dBASE for Windows Debugger

The dBASE for Windows Debugger is a full-featured debugger for watching program flow, tracking values, and trapping errors. You can launch the Debugger from within dBASE for Windows or run it as a stand-alone application.

Debugger Concepts and Tasks

Choose from the following topics for information about using the Debugger:

Using the Debugger - Overview

Debugger Tasks

Debugger Tools

The Debugger has several windows, menus, SpeedMenus, and a SpeedBar. Choose from the following topics for more information.

Windows	About the Module, Break, Watch, Stack, File, and Inspect windows

SpeedBar	Descriptions of the Debugger SpeedBar buttons

Menus	List and descriptions of the Debugger menus

SpeedMenus	List and descriptions of the SpeedMenus in each Debugger window


 Using the Debugger - Overview

See Also

Use the dBASE for Windows Debugger to debug and fix your source code.

In particular, use the Debugger to:

Control program execution. By using commands in the Run menu, you can control how the program executes. Each Debugger window displays a different aspect of the program execution.

Trap errors The Debugger traps errors and lets you choose how to continue.

Debug objects You can use the Debugger to debug and execute code attached to an object.

Fix bugs Use the Text Editor to fix errors.

Using the Debugger Windows

Use the Debugger windows to examine your source code, set breakpoints, watch expressions, follow calls to other modules or procedures, and inspect items. The Debugger always displays these windows (unless you close or minimize them):

Module window Shows the source code for the program module you are debugging

Break window Shows all breakpoints set in the current module and lets you add, edit, and remove breakpoints

Watch window Shows the values of specified expressions

Stack window Shows any calls the module you are debugging makes to other modules, procedures, and user-defined functions

You can also choose to display the following windows:

File window Shows the contents of an ASCII file

Inspect window Shows the value of an expression you inspect

Note:	Inspecting and watching items are different. You can inspect an item only after it is initialized. However, you can watch an item at any time. You can inspect arrays and objects. You cannot watch them.


See Also

Debugger Windows

Differences Between Inspect and Watch


 Debugger Tasks

Choose from the following list for information about how to use the Debugger:

Starting the Debugger

Loading Program Files

Loading Subroutines

Controlling Program Execution

Debugging Event Handlers

Trapping Errors

Fixing Bugs

Module Window Tasks

Using the Pointer in the Module Window

Viewing Files in the Module Window

Break Window Task

Setting Breakpoints

Watch Window Task

Setting Watch Points

Stack Window Task

Opening a Module from the Stack Window

Inspect Window Task

Inspecting Items


 Starting the Debugger

Language

You can start the Debugger from dBASE for Windows or as a standalone program from the Windows Program Manager.

In dBASE for Windows:

Type the DEBUG command in the Command window.

Include the DEBUG command in a program file.

Choose Program|Debug or click [image] when the Command window is active.

Choose Program|Debug or click [image] when the Text Editor is active with a program file loaded.

Choose Debug... in the Program Error dialog box when a run-time error occurs in your program.

In the Windows Program Manager:

Double-click the Debugger icon.

Using dBASE IV Debugging Commands

In dBASE IV, debugging commands activate the debugger and perform other debugging tasks. In dBASE for Windows, you perform all debugging tasks in the Debugger. Consequently, some dBASE IV debugging commands have no effect in dBASE for Windows, while others open the Debugger.

For example, in dBASE for Windows, issuing any of the following dBASE IV debugging commands opens the Debugger:

SET ECHO ON

SET STEP ON


Language

DEBUG

SET ECHO

SET STEP


Loading Program Files (Debugger)
 Loading Program Files

See Also	Language

You can load a program file when you start the Debugger or after you open the Debugger.

To load a file when you start the Debugger, do one of the following:

Type DEBUG <filename> in the Command window, where <filename> is the program file to debug.

Type a DEBUG statement in the place in the program file where you want to start the Debugger.

Choose Program|Debug or click [image] when the Command window is active. A dialog box prompts you for a file to debug.

Choose Program|Debug or click [image] when the Text Editor is active with a program file loaded.

Choose Debug in the Program Error dialog box when a run-time error occurs in your program.

To load a file after you open the Debugger,

Choose File|New from the Debugger menu and specify the program file to debug in the Select Application dialog box.

When you load a program file in the Debugger, the Debugger automatically starts dBASE for Windows, if it is not already running, and uses it to run your program.

Screen Display Changes

The screen display changes when you load a program in the Debugger:

The source code for the program appears in the Module window, and the first line to execute is selected.

The program name replaces "No Module" as the title of the Module window.

Program Execution

After you load a program in the Debugger, the program does not execute until you explicitly start execution. Controlling Program Execution describes how to run and control your programs in the Debugger.


See Also

Loading Subroutines


Language

DEBUG


Loading Subroutines (Debugger)
 Loading Subroutines

See Also

When you debug a program that calls a procedure file, the Debugger loads the procedure file automatically when the call occurs. However, you can also load a procedure file before the call is made.

From the Debugger menu:

1.	Choose File|New to open the main module if it is not already open.

2.	Choose File|Load Module.

3.	In the Select Module dialog box, specify the procedure file you want to load.

From the Module window:

1.	Choose File|New to open the main module if it is not already open.

2.	Right-click the Module window to display the Module window SpeedMenu.

3.	Choose Load Module.

4.	In the Select Module dialog box, specify the procedure file you want to load.

Do not use File|New to load a procedure file after a module is loaded. If you choose File|New when a module is already loaded in the Debugger, dBASE for Windows asks if you want to terminate the current debugging session.


See Also

Loading Program Files


Controlling Program Execution (Debugger)
 Controlling Program Execution

When you run a program in the Debugger, you can control how the source code executes. By following program execution precisely, you can learn which lines contain or cause errors and how the program flows.

You can control program execution in the Debugger in the following ways:

Animate	Executes source lines continually, pausing at each command line and updating the Watch, Stack, and Break windows. You determine the relative amount of time for each pause by setting the Animation Speed.

Step Over	Executes a program one line at a time, stepping over procedures while executing them as a single unit.

Trace Into	Executes a program one line at a time, tracing into procedures and following the execution of each line.

Run	Runs the current program without pausing at each line. This is equivalent to running a program outside the Debugger.

Stop	Temporarily stops the execution of a running program.

Add Breakpoints	Specifies places in your source code for program execution to stop.

The Debugger provides three ways to run a program:

Conventional	Runs the loaded program until you interrupt execution with Run|Stop.

Until Return	Runs the loaded program until control returns to a calling routine.

To Cursor	Runs the loaded program to the location of the cursor in the Module window.


 Debugging Event Handlers

Language

You can use the Debugger to debug event handling code attached to forms and controls. You can set breakpoints and watchpoints in this code, and you can inspect items in this code.

Here is an example of Debugging an event handler:

1.	Load the file containing the event handler code in the Debugger.

2.	Add a breakpoint in the event handler code.

3.	Run the program.

4.	When the form displays, interact with the form to cause the event handler to execute. For example, if the event handler is assigned to the OnClick event of a pushbutton, click the pushbutton.

Note	To make switching between the Debugger and the form easier, click [image] to shrink the Debugger application window. To restore the Debugger, click [image].

5.	The event handler code displays in the Module window at the line containing the breakpoint. You can then trace or animate the code, or perform other debugging tasks, such as inspecting variables.


Language

OPEN FORM


Trapping Errors (Debugger)
 Trapping Errors

When an error occurs while you are running a program, dBASE for Windows automatically traps it and opens the Program Error dialog box. The program stops executing at the point where the error occurred.

When a run-time error occurs, you have the following choices:

Cancel the program.

Fix the problem by editing the program, starting at the line where the error occurred.

Ignore the erroneous line and continue running the program at the next line.

Suspend the program to initiate some other action.

Debug the program, starting at the erroneous line.

About the dBASE IV SET TRAP ON Command

dBASE for Windows does not support the dBASE IV SET TRAP ON command. Issuing SET TRAP ON does nothing.


Fixing Bugs (Debugger)
 Fixing Bugs

Use the Text Editor to fix errors that you find while debugging. To end the debugging session and automatically load your program in the Text Editor at the erroneous line, follow these steps:

1.	In the Module window, move the cursor to the erroneous line of source code.

2.	Right-click the Module window to display the Module window SpeedMenu.

3.	Choose Fix. The Text Editor opens.


Viewing Files in the Module Window (Debugger)
 Viewing Files in the Module Window

See Also

The Debugger treats each file, such as a .PRG or .WFM file, as a single program module. The file that appears in the Module window is the module you are currently debugging.

If your application calls a subroutine that is in a separate file, the Debugger automatically loads the file in the Module window.

If your application calls a subroutine that is elsewhere in the same file, the Debugger automatically moves to the appropriate line of the subroutine in the Module window.

Using the Stack Window

The module or subroutine that is active in the Module window is listed at the top of the Stack window. Previously called modules and subroutines are listed sequentially below the active routine in the Stack window. If you double-click any item in the Stack window, the Debugger loads that item in the Module window.

Loading a Subroutine

After you load a module in the Debugger, you can load a subroutine that is in a separate module without waiting for your program to call it. You can then set breakpoints and watchpoints in that module. Use File|Load Module to load a subroutine that is in a separate module.

When you open another module, you do not terminate the current application, and you do not change the next line of code to execute.

Do not use File|New to load a subroutine unless you want to terminate the active module.


See Also

Loading Subroutines

Module Window


Using the Pointer in the Module Window (Debugger)
 Using the Pointer in the Module Window

See Also

Selecting Code

You can select code in the Module window. For example, if you want to watch or inspect a variable, you can select it in the Module window and then choose Module SpeedMenu|Watch or Module SpeedMenu|Inspect. By default, selected code appears green in the Module window.

You cannot cut, copy, paste, or perform other editing tasks in the Module window. Choose Module SpeedMenu|Fix to open the Text Editor and edit your source code.

Setting Breakpoints

You can also set breakpoints in the Module window. Move the pointer to the left end of the line where you want to set a breakpoint, and click when the pointer changes to a stop sign.


See Also

Break Window

Inspect Window

Module Window

Watch Window


Setting Breakpoints (Debugger)
 Setting Breakpoints

See Also

Setting a Breakpoint for a Specific Line

To set a breakpoint that interrupts execution at a specific line in your program, do any of the following:

In the Module window, move the pointer to the left end of the line where you want to set a breakpoint, and click when the pointer changes to a stop sign.

In the Module window, place the cursor in the the line where you want to set a breakpoint and do any of the following:

Click the Toggle Breakpoint SpeedBar button.

Choose Break|Toggle On/Off.

Press F2.

Setting a Breakpoint for a Condition or Expression

To set a breakpoint for a condition or expression, or to specify an action that occurs at the breakpoint, do any of the following:

Choose Break|Add and enter the required information in the Add Breakpoint dialog box.

Right-click the Break window, choose Add, and enter the required information in the Add Breakpoint dialog box.

Double-click an existing breakpoint line in the Break window, and enter the required information in the Edit Breakpoint dialog box.

Breakpoints Appear in Red

The line marked as a breakpoint appears red in the Module window.


See Also

Break|Add or Edit

Break Window

Module Window


Setting Watch Points (Debugger)
 Setting Watch Points

See Also

To add a watchpoint for an expression that is in the Module window, either select the expression in the Module window or place the cursor in the expression and do any of the following:

Right-click the expression and choose Watch from the Module window SpeedMenu.

Choose Watch|Add from the Debugger menu.

Press Ctrl+W.

The Add Watchpoint dialog box appears listing the expression you specified.

To add a watchpoint without specifying an expression in the Module window, do any of the following:

Right-click the Watch window and choose Watch from the SpeedMenu.

Choose Watch|Add from the Debugger menu.

Press Ctrl+W.

The Add Watchpoint dialog box appears with no watchpoints listed. Enter the expression you want to watch. To save watchpoints, Choose Options|Defaults, then check the Watchpoints checkbox in the Defaults dialog box.


See Also

Module Window

Watch|Add or Edit

Watch Window


Opening a Module from the Stack Window (Debugger)
 Opening a Module from the Stack Window

You can open any of the modules listed in the Stack window. The module then appears in the Module window. You can then set breakpoints and watchpoints in that module.

When you open a module from the Stack window, you do not terminate the current application, and you do not change the next line of code to execute.

To open a module from the list in the Stack window, do one of the following:

Double-click the module in the Stack window.

Select the module in the Stack window, right-click to display the SpeedMenu, then click Go to Source Line.


See Also

Stack Window


Setting Inspection Points (Debugger)
 Inspecting Items

See Also

To inspect a variable, field, array, or object that you specify in the Module window, either select the item in the Module window or place the cursor in the item and do any of the following:

Right-click the item and choose Inspect from the Module window SpeedMenu.

Choose Program|Inspect from the Debugger menu.

Press Ctrl+I.

The Inspect dialog box appears and lists the item you specified.

To inspect a variable, field, array, or object without specifying it in the Module window, do any of the following:

Choose Program|Inspect from the Debugger menu. (You can also right-click the Module window and choose Inspect from the SpeedMenu.)

Press Ctrl+I.

The Inspect dialog box appears with no item listed. Enter the variable, field, array, or object that you want to inspect.


See Also

Module Window

Program|Inspect


 Debugger Windows

See Also

When you first start the Debugger, it displays the following windows:

Module window	Shows the source code for the program module you are debugging and is the main window in the Debugger

Break window	Shows all breakpoints set in the current module and lets you add, edit, and remove breakpoints

Watch window	Shows the values of expressions you choose to watch

Stack window	Shows any calls the module you are debugging makes to other modules, procedures, and UDFs

In addition, the Debugger can display the following windows:

File window	Shows the contents of an ASCII file

Inspect window	Shows the value of an expression you inspect

The Module window is the main window in the Debugger. It contains the source code for the module that you are debugging and also keeps track of the source code line that is executing. The additional Debugger windows keep track of values and calls to procedures.

SpeedMenus

Each Debugger window has a SpeedMenu to help you perform debugging tasks that are specific to that window. To display the SpeedMenu for any window, right-click the window.

In addition, you can use the commands on the Debugger menu to perform tasks in each window. All the SpeedMenu commands are also available on the Debugger menu, and many are available on the SpeedBar.


See Also

Debugger Menus

Debugger SpeedMenus


Module Window (Debugger)
 Module Window

See Also

Shows the source code for the program module you are debugging.

The Module window is the main window in the Debugger. When you load a module in the Debugger, its name appears as the title of the Module window. If you do not load a module automatically when you start the Debugger, you can load one with File|New. Loading a module automatically is described in Loading Program Files.

When you load a module, the first command line to execute is selected in the Module window. As you run a program in the Debugger, the next command to execute is selected.

You can scroll through the Module window without affecting program execution. Program execution is controlled by the commands on the Run menu.


See Also

Module Window Colors

Module Window Commands

Using the Pointer in the Module Window

Viewing Files in the Module Window


Module Window Colors (Debugger)
 Module Window Colors

See Also

The Module window displays information in three colors. The default colors are as follows (the colors on your system might be different):

The next command line to execute is blue.

A line marked as a breakpoint is red.

A section of code that you select, for example to define a watchpoint, is green.

Following is an example of a typical Module window:

The previous example shows the following:

The next command line to execute is DO WHILE Counter < 50.

The variable A is selected.

The line Counter = Counter + 1 contains a breakpoint.


See Also

Module Window


Module Window Commands (Debugger)
 Module Window Commands

See Also

Use commands on the Module window SpeedMenu or the Debugger menu to perform the following tasks in the Module window:

Inspect a variable, field, array, or object to examine its value.

Watch an expression to see how its value changes as your program executes.

Load another module into your program.

Move the cursor to its previous line.

Go to any line in your program.

Go to a procedure or UDF within the same file or another file.

Return the cursor to the origin, or calling procedure, after using the Go to Proc command.

Find any string in your program.

Find the next occurrence of any string in your program.

Fix any bugs that you find in your source code.


Break Window (Debugger)
 Break Window

See Also

Shows all breakpoints set in the current module and lets you add, edit, and remove breakpoints.

A breakpoint is a place in your program where execution temporarily stops. When the Debugger reaches a breakpoint, it interrupts your program and optionally executes an action that you specify. You can specify any number of breakpoints in your code.

When you set a breakpoint, it appears in a list in the Break window. The following example shows a typical Break window:

The previous example shows the following:

A global breakpoint is set for the condition X = 5 is TRUE. Execution is interrupted when the variable X evaluates to 5 in any module of the program you are debugging.

Line 109 of the module Animals.prg contains a program-specific breakpoint.


See Also

Break Window Commands

Breakpoint Basics

Setting Breakpoints


Breakpoint Basics (Debugger)
 Breakpoint Basics

See Also

You can create two types of breakpoints:

Program-specific breakpoints that affect a single program file

Global breakpoints that affect all program files

Within a single program file, you can specify any of the following as a program-specific breakpoint:

A condition, when it evaluates to True

A program line number

A pass count expression

You can specify any of the following as a global breakpoint:

A condition, when it evaluates to True

An expression, when its value changes

A pass count expression


See Also

Break Window


Break Window Commands (Debugger)
 Break Window Commands

See Also

Use commands on the Break window SpeedMenu to perform the following tasks in the Break window:

Add a breakpoint to the current line in the Module window.

Delete a breakpoint from the Module window.

Edit a breakpoint in the Module window.

Remove All breakpoints from the Module window.

Go to a breakpoint in the Module window.

Toggle a breakpoint on and off in the Module window.


Watch Window (Debugger)
 Watch Window

See Also

Shows the values of expressions you choose to watch.

When you debug a program, you can watch expressions to see what they evaluate to throughout the program. For example, you can watch the value of a variable in a loop to see if it iterates properly.

You can watch any expression in the Watch window: the expression can be undefined and does not have to occur in the program. The Debugger displays the expression in the Watch window along with its current value in parentheses. When the value of the expression changes, the Debugger updates the value in the Watch window.

The following example shows a typical Watch window:

The previous example shows:

The value of Firstrec is False.

The value of Savearea is 1.

The value of WinAnimals is undefined.


See Also

Differences Between Inspect and Watch

Setting Watch Points

Watch Window Commands


Watch Window Commands (Debugger)
 Watch Window Commands

See Also

Use commands on the Watch window SpeedMenu to perform the following tasks in the Watch window:

Add a watchpoint.

Delete a watchpoint.

Edit a watchpoint.

Remove All watchpoints.

Change... the value of an expression you previously specified as a watchpoint.


See Also

Watch Window


Stack Window (Debugger)
 Stack Window

See Also

Shows any calls the module you are debugging makes to other modules, procedures, and UDFs.

The Debugger keeps track of all program calls to other modules, procedures, and UDFs and displays this information in the Stack window.


See Also

Opening a Module from the Stack Window

Stack Window Basics

Stack Window Commands


Stack Window Basics (Debugger)
 Stack Window Basics

See Also

The Stack window displays the following information about modules, procedures, and UDFs you are debugging:

The line number of the subroutine call

The name and file name of the calling module

The name and file name of the subroutine

The line number of the next source code line to execute

The most recently called subroutine is listed at the top of the Stack window. Other subroutines are listed in the order in which they were called.

The following example shows a typical Stack window:

The previous example shows:

Line number 55 of the procedure Animals called the subroutine Animals.qbe.

Animals.qbe is the most recently called subroutine.

The subroutine Animals.qbe is in the file ANIMALS.QBE.

The next line to execute is line number 2 of the Animals.qbe subroutine.


See Also

Stack Window


Stack Window Commands (Debugger)
 Stack Window Commands

See Also

Use the Stack window SpeedMenu to perform the following task in the Stack window:

Go to the source code for a selected routine.


File Window (Debugger)
 File Window

See Also

Displays an ASCII file.

The File window displays the contents of any ASCII file that you select. You can use the File window to view source code without debugging it; you cannot select text or edit in the File window. Do not confuse the File window with the Module window, which displays the source code for the program you are debugging.

dBASE for Windows does not automatically display the File window when you start the Debugger. To display the File window, choose File|Open Text File and select a file from the Select File dialog box. (For general information about choosing files, see Open or Save File dialog box.) Do not choose File|New, which terminates the active application and starts a new debugging session by displaying source code in the Module window.


See Also

File Window Commands


File Window Commands (Debugger)
 File Window Commands

See Also

Use commands on the File window SpeedMenu or the Debugger menu to perform the following tasks in the File window:

Go to any line number in the file you are viewing.

Find any string in the file you are viewing.

Find the next occurrence of any string in the file you are viewing.

Display the file you are viewing as ASCII characters.

Display the file you are viewing as hexadecimal characters.

Replace the file in the current File window with another file.


See Also

File Window


Inspect Window (Debugger)
 Inspect Window

See Also

Shows the value of an expression you inspect.

When you run a program in the Debugger, you can inspect an item to see its value at a specific point in the program. The value appears in an Inspect window. For example, if you inspect a variable in a procedure, the Inspect window displays the value of the variable at the time the inspection occurred.

When you inspect an array or object, the Inspect window displays its value and the value of all its elements or properties. You can inspect an item only after it is initialized.

The following example shows a typical Inspect window:

The previous example shows:

TestArray is a two-dimensional array containing four elements.

The values of the array elements are 10, 20, 30, and 40.


See Also

Differences Between Inspect and Watch

Inspect Window Commands

Inspecting Items


Differences Between Inspect and Watch (Debugger)
 Differences Between Inspect and Watch

See Also

The following descriptions summarize the differences between inspect and watch.

Inspect

You can inspect an item only after it is initialized.

Inspect provides information about arrays and objects.

Watch

You can watch at any time.

Watch does not provide information about arrays and objects.

The following example shows an Inspect and a Watch window for the same item:

In the example, notice that you can watch both an individual array element and an array; however, the Watch window only indicates that the array is an object and does not display other information about it.


See Also

Inspect Window

Watch Window


Inspect Window Commands (Debugger)
 Inspect Window Commands

See Also

Use commands on the Inspect window SpeedMenu or the Debugger menu to perform the following tasks in the Inspect window:

Set an upper and lower range of values for the inspected item.

Change the value of the inspected item.

Place an inspected item in its own window.

Descend into the layers of an object.

Display the hexadecimal value of binary string variables.

Clear any values in the current Inspect window and inspect a new expression.


See Also

Inspect Window


 Debugger SpeedBar

See Also

The SpeedBar is a row of buttons located beneath the menu bar in the Debugger. Each button represents a menu command or similar action in the Debugger. Use the SpeedBar by clicking the button that represents the command you want to execute.

By default, the SpeedBar is displayed horizontally under the Debugger menu. To change its orientation, choose Options|Defaults, then select the option you want from the Defaults dialog box.

Button	Action	Menu Equivalent
	Locates and opens a file	File|New
	Exits the Debugger	File|Exit
	Runs or continues the current program	Run|Run
	Stops a running program temporarily	Run|Stop
	Reloads the current program	Run|Reset
	Executes, tracing into procedures	Run|Trace Into
	Executes, stepping over procedures	Run|Step Over
	Inspects the specified item	Program|Inspect
	Evaluates or modifies the specified item	Program|Evaluate/Modify
	Displays the full Debugger window	Options|Defaults
	Displays the menu bar and SpeedBar only	Options|Defaults
	Displays the SpeedBar as a vertical palette	Options|Defaults


See Also

Options|Defaults


 Debugger Menus

See Also

The Debugger has the following menus:

File Menu

Program Menu

Run Menu

Watch Menu

Break Menu

Options Menu

Window Menu

Help Menu


See Also

Debugger SpeedMenus


 Debugger SpeedMenus

See Also

The Debugger has the following SpeedMenus:

Module SpeedMenu

Watch SpeedMenu

Break SpeedMenu

Stack SpeedMenu

File SpeedMenu

Inspect SpeedMenu


See Also

Debugger Menus


 File Menu (Debugger)

Use the Debugger File menu to start debugging a program, attach the Debugger to an active program, change directories, get information about the current debugging session, and exit the Debugger.

The Debugger File menu contains the following commands:

New...

Load Module...

Open Text File...

Change Dir...

Attach...

Exit


File|New... (Debugger)
File | New...

See Also

Opens a file in the Module window for debugging.

If a file is not already loaded in the Module window, this command displays the Select Application dialog box from which you can choose the file. The default file-name extension is .PRG. (For general information about choosing files, see Open or Save File dialog box.)

If a file is already loaded in the Module window, the Debugger asks if you want to terminate the current module before continuing.

After you load a module in the Debugger, you can debug a subroutine that is in a separate module without waiting for your program to call it. Use File|Load Module to debug a subroutine that is in a separate module. Do not use File|New to load a subroutine unless you want to terminate the active module.

When you load a program in the Debugger, its name replaces "No Module" as the title of the Module window, and the current command line is highlighted.

Shortcuts

SpeedBar:


See Also

File|Load Module...

Module Window


Open or Save File Dialog Box (Debugger)

See Also

Opens or saves a file that you specify. This dialog box appears with different names in the Debugger when you select any of the following commands:

File|New (Select Application dialog box)

File|Load Module (Select Module dialog box)

File|Open Text File (Select File dialog box)

Options|Save Options (Save Configuration dialog box)

Options|Restore Options (Restore Configuration dialog box)

Select a drive and directory, then specify the file name in that directory to open or the name under which you want to save the current file. Once you choose a file, dBASE loads or saves the file.

Dialog Box Options

File Name

Specifies the name of the file to open or save. Type the name or choose it from the File Name list box.

Directories

Specifies the full path and directory where the current list of files resides. Select the path and directory from which to open the file or where you want to save the file.


See Also

File|New

File|Load Module

File|Open Text File

Options|Save or Restore Options


File|Load Module... (Debugger)
File | Load Module...

See Also

Loads another module of the current program in the Module window.

If a file is not already loaded in the Module window, this command displays the Select Module dialog box from which you can choose the file. The default file-name extension is .PRG. (For general information about choosing files, see Open or Save File dialog box.)

After you open a program in the Debugger with File|New, you can set breakpoints, watchpoints, and inspection points in a subroutine that is in a separate module without waiting for your program to call it.

Use File|Load Module to load a subroutine that is in a separate module. Do not use File|New to load a subroutine unless you want to terminate the active module.

When you load a new subroutine in the Debugger:

The new subroutine appears in the Module window.

The module that was active when you selected File|Load Module remains the current module in the Debugger.

The Stack window displays the name of the module that was active when you selected File|Load Subroutine as the current module in the Debugger.

To return to the module that was active before you selected File|Load Subroutine, double-click its name in the Stack window.

Shortcuts

SpeedMenu:	Load Module... (Module window)


See Also

File|New...

Module Window


File|Open Text File... (Debugger)
File | Open Text File...

See Also

Displays a text file in the File window.

This command displays the Select File dialog box from which you can choose a file to open:

If a File window is not open, this command displays the file you select in a File window.

If a File window is already open, this command displays the file you select in a new File window.

For general information about choosing files, see Open or Save File dialog box.


See Also

File Window


File|Change Dir... (Debugger)
File | Change Dir...

See Also

Changes the directory for the current Debugger session.

Use this command to specify a directory as the default directory for loading files.

In addition to changing the directory for the current Debugger session, you can also change the default directory for future sessions. Choose Options|Source File Paths to change the default directory for future sessions.

Dialog Box Options

New Directory

Specifies the new default directory. Enter the new directory. Use the drop-down button to choose from a history of previously selected directories.


See Also

Options|Source File Paths...


File|Attach... (Debugger)
File | Attach...

Attaches the current application to another instance of dBASE for Windows.

Use this command to attach the current application in the Debugger to another instance of dBASE for Windows.

If you start the Debugger from dBASE for Windows, the Debugger automatically attaches to the instance of dBASE for Windows that started it.

If you have multiple instances of dBASE for Windows, you can run different applications in those different instances and specify which application in which instance to attach the Debugger to.

Dialog Box Options

Active Applications

Lists the active applications. Choose the application you want to attach to.


File|Exit (Debugger)
File | Exit

Exits the Debugger.

If an application is active, dBASE for Windows asks if you want to terminate the application before exiting.

Shortcuts

SpeedBar:


 Program Menu (Debugger)

Use the Debugger Program to navigate within modules, fix your source code, and inspect, evaluate, or modify variables, fields, arrays, or objects.

The Debugger Program menu contains the following commands:

Go to Line...

Previous Line

Find...

Find Next...

Origin

Go to Procedure...

Fix

Inspect...

Evaluate/Modify...


Program|Go to Line... (Debugger)
Program | Go to Line...

See Also

Moves to a specified line number in the current source code.

Shortcuts

SpeedMenu:	Go to Line... (Module window)
Go to... (File window)

Dialog Box Options

Line Number

Specifies the line number to move to. Enter the line number. Use the drop-down button to choose from a history of previously selected line numbers.


See Also

Program|Previous Line


Program|Previous Line (Debugger)
Program | Previous Line

See Also

Returns the cursor to its previous position.

You can move the cursor to each previous position by continuing to choose Previous. When you reach the initial cursor position, Previous does nothing.

Shortcuts

SpeedMenu:	Previous Line... (Module window)


See Also

Program|Go to Line...


Program|Find... (Debugger)
Program | Find...

See Also

Searches for the specified text string in the current source code.

The search begins from the current cursor position, and the search is case-insensitive. If dBASE for Windows finds the text string, the Module window scrolls to the line containing it, and the cursor moves to the beginning of the text string.

Shortcuts

SpeedMenu:	Find... (Module window)
Find... (File window)

Dialog Box Options

Search String

Specifies the string to search for. Enter the string to search for. Use the drop-down button to choose from a history of previously selected strings.


See Also

Program|Find Next


Program|Find Next (Debugger)
Program | Find Next

See Also

Finds the next occurrence of the string specified in Program|Find or Module or File SpeedMenu|Find.

Shortcuts

SpeedMenu:	Find Next (Module window)
Find Next (File window)


See Also

Program|Find...


Program|Origin (Debugger)
Program | Origin

See Also

Returns the cursor to the calling command after using Program|Go to Proc.

Shortcuts

SpeedMenu:	Origin (Module window)


See Also

Program|Go to Proc...


Program|Go to Procedure... (Debugger)
Program | Go to Procedure...

See Also

Moves to a procedure or UDF in the current source code or the source code of another program file.

If dBASE for Windows finds the procedure or UDF definition, it moves the cursor to the beginning of the definition. If the definition is in a separate procedure file, dBASE for Windows opens the file in the Module window.

If dBASE for Windows cannot find the procedure or UDF, the cursor remains in the current source code.

To find a procedure or UDF definition in a procedure file, a command such as SET PROCEDURE TO must open the procedure file before the procedure or UDF call occurs.

Shortcuts

SpeedMenu:	Go to Procedure... (Module window)

Dialog Box Options

Procedure Name

Specifies the name of the procedure or UDF to go to. Enter the name of the procedure or UDF. Use the drop-down button to choose from a history of previously selected procedures and UDFs.


See Also

Program|Origin


Program|Fix (Debugger)
Program | Fix

Closes the Debugger and opens the current file in the Text Editor  with the cursor on the line that was current in the Debugger.

You cannot edit source code in the Debugger. Use this command to make changes to source code.

Shortcuts

SpeedMenu:	Fix (Module window)


Program|Inspect... (Debugger)
Program | Inspect...

See Also

Displays the value of a variable, field, array, or object in the Inspect window.

The Inspect window also displays the values of all associated array elements and object properties.

The value displayed in the Inspect window is the value of the variable, field, array, or object at the time of inspection. Unlike the display in the Watch window, the display in the Inspect window is not updated as values change.

Shortcuts

SpeedBar:

SpeedMenu:	Inspect... (Module window)
Inspect New Expression... (Inspect window)

Keyboard:	Ctrl+I

Mouse:	Double-click an inspectable item in the Inspect window

Dialog Box Options

Name to Inspect

Specifies the expression to inspect. Enter the expression to inspect. Use the drop-down button to choose from a history of previously selected items.


See Also

Inspect SpeedMenu

Inspect Window

Watch Window


Program|Evaluate/Modify... (Debugger)
Program | Evaluate/Modify...

Evaluates or changes the value of the specified variable, field, array, object, or expression.

You can perform two tasks with this command:

Evaluate a specified variable, field, array, object, or expression. To evaluate one of these items, specify the item in the Expression text box and choose Evaluate. The value of the item is displayed in the Result text box.

Change the value of a specified variable, field, or array element. To change the value of the specified item, enter a value in the New Value text box and choose Modify. The new value is displayed in the Result text box.

Shortcuts

SpeedBar:

SpeedMenu:	Evaluate/Modify... (Module window)

Dialog Box Options

Expression

Specifies the variable, field, array, or object to evaulate or modify. Enter the variable, field, array, or object to evaluate or modify.

Result

Displays the value of the item specified in the Expression text box after you choose Evaluate or Modify.

New Value

Assigns a new value to the item specified in the Expression text box. Enter a new value for the item if you want to change its value.


 Run Menu (Debugger)

Use the Debugger Run menu to execute a program in the Debugger and to control the way a program executes.

The Debugger Run menu contains the following commands:

Run

Stop

Go to Cursor

Until Return

Animate

Trace Into

Step Over

Reset

Terminate

Parameter Arguments...


Run|Run (Debugger)
Run | Run

See Also

Runs the current program without pausing at each line.

Using Run|Run is equivalent to running a program outside the Debugger. The program continues running until it reaches a breakpoint, or until you stop the execution temporarily with Run|Stop.

You can run a subset of the current program without pausing at each line by using the following commands:

Run|Until Return runs the loaded program until control returns to a calling routine.

Run|Go to Cursor runs the loaded program up to the location of the cursor in the Module window.

You can control the line-by-line execution of a program within the Debugger by using the following commands:

Run|Animate executes source lines continually, pausing at each command line and updating the Watch, Stack, and Break windows.

Run|Trace Into executes a program one line at a time,  tracing into procedures and following the execution of each line.

Run|Step Over executes a program one line at a time, stepping over procedures while executing them as a single unit.

Shortcuts

SpeedBar:

Keyboard:	F9


See Also

Run|Animate

Run|Go to Cursor

Run|Step Over

Run|Stop

Run|Trace Into

Run|Until Return


Run|Stop (Debugger)
Run | Stop

See Also

Temporarily stops execution of a running program.

The next line of the program to execute is selected in the Module window, the program remains in memory, and the status bar continues to display the message "Running." Use a Run menu command to continue execution.

In addition to temporarily stopping a program running in the Debugger, you can also stop a program and release it from memory. Use Run|Terminate to stop a running program and release it from memory.

Shortcuts

SpeedBar:


See Also

Run|Run

Run|Terminate


Run|Go to Cursor (Debugger)
Run | Go to Cursor

See Also

Runs the loaded program up to the location of the cursor in the Module window.

You can also run a program using these commands:

Use Run|Run to run a program continuously.

Use Run|Until Return to run a single subroutine.

Shortcuts

Keyboard:	F4


See Also

Run|Run

Run|Until Return


Run|Until Return (Debugger)
Run | Until Return

See Also

Runs the loaded program until control returns to a calling routine.

You can also run a program using these commands:

Use Run|Run to run a program continuously.

Use Run|Go to Cursor to run the loaded program up to the location of the cursor in the Module window.


See Also

Run|Run

Run|Go to Cursor


Run|Animate (Debugger)
Run | Animate

See Also

Executes source lines continually, pausing at each command line and updating the Watch, Stack, and Break windows.

Use Run|Animate to view the line-by-line execution of your program in an automated way. Before each source line executes, it is selected in the Module window. You can control the amount of time each line of code is selected before execution by choosing Options|Animation Speed.

In addition to using Run|Animate, you can control the line-by-line execution of your program with the following commands:

Run|Trace Into executes a program one line at a time, tracing into procedures and following the execution of each line.

Run|Step Over executes a program one line at a time, stepping over procedures while executing them as a single unit.

You can run the current program without pausing at each line by using the following commands:

Run|Run runs the current program continuously without pausing at each line.

Run|Until Return runs the loaded program until control returns to a calling routine.

Run|Go to Cursor runs the loaded program up to the location of the cursor in the Module window.


See Also

Module Window

Options|Animation Speed

Run|Go to Cursor

Run|Run

Run|Step Over

Run|Trace Into

Run|Until Return


Run|Trace Into (Debugger)
Run | Trace Into

See Also

Executes a program one line at a time, tracing into procedures and following the execution of each line.

In addition to tracing into procedures, you can step over them, executing each procedure as a single unit. Use Run|Step Over to execute procedures as a single unit.

Using Run|Trace Into

Run|Trace Into and Run|Step Over are the primary commands you use to isolate bugs in individual lines of code.

For example, if you know that a program fails in a specific module, you can set a breakpoint in that module and then use Run|Run to execute the program up to the breakpoint. When the program reaches the breakpoint, execution stops and the problem area of code, at and following the breakpoint, is loaded in the Module window.

You can then use Run|Trace Into and Run|Step Over to investigate what happens when each line of code executes. You can inspect or watch as many values as you want, and then use Run|Trace Into and Run|Step Over repeatedly, examining the watchpoints and inspection points as each line of code executes.

Shortcuts

SpeedBar:

Keyboard:	F7


See Also

Run|Run

Run|Step Over


Run|Step Over (Debugger)
Run | Step Over

See Also

Executes a program one line at a time, stepping over procedures while executing them as a single unit.

In addition to stepping over procedures, you can trace into them, following the execution of each line. Use Run|Trace Into to execute each line of a procedure.

Using Run|Step Over

Run|Trace Into and Run|Step Over are the primary commands you use to isolate bugs in individual lines of code.

For example, if you know that a program fails in a specific module, you can set a breakpoint in that module and then use Run|Run to execute the program up to the breakpoint. When the program reaches the breakpoint, execution stops and the problem area of code is loaded in the Module window.

You can then use Run|Trace Into and Run|Step Over to investigate what happens when each line of code executes. You can inspect or watch as many values as you want, and then use Run|Trace Into and Run|Step Over repeatedly, examining the watchpoints and inspection points as each line of code executes. If necessary, you can also change the values of variables or objects.

Shortcuts

SpeedBar:

Keyboard:	F8


See Also

Run|Run

Run|Trace Into


Run|Reset (Debugger)
Run | Reset

See Also

Reloads the current program into memory.

Use this command to reload a program if it is finished executing, or if you have used Run|Terminate to end a program.

If a program is running, Run|Reset stops execution and clears the program from memory before reloading it.

Shortcuts

SpeedBar:


See Also

Run|Stop

Run|Terminate


Run|Terminate (Debugger)
Run | Terminate

See Also

Ends the current program and releases it from memory.

Run|Terminate does not exit the Debugger or remove the current module from the Module window It only terminates program execution.

You must reload the program into memory before running it again. Use Run|Reset to reload the program into memory.

In addition to terminating program execution, you can stop program execution temporarily. Use Run|Stop to temporarily halt the execution of a program without releasing it from memory.


See Also

Run|Reset

Run|Stop


Run|Parameters... (Debugger)
Run | Parameter Arguments...

See Also	Language

Specifies parameters to pass to a program you are debugging.

If the program you are debugging can accept parameters when you run it, enter those parameters using this command before you run the program. See the PARAMETERS and DO commands for additional information about passing parameters at the time you run a program.

Dialog Box Options

Arguments

Specifies the parameters to use when you run the program. Enter the parameters. If more than one parameter is used, separate the parameters with spaces.


See Also

Run|Run


Language

DO

PARAMETERS


 Watch Menu (Debugger)

See Also

Use the Watch menu to add, edit, delete, and change watchpoints in a debugging session.

You can watch an expression in the Watch window to learn what it evaluates to at different points in the program, such as in a subroutine or a loop.

The Watch menu contains the following commands:

Add...

Delete

Edit...

Remove All

Change...


See Also

Watch Window


Watch|Add or Edit... (Debugger)
Watch | Add or Edit...

See Also

Places an expression in the Watch window, if you are adding a watchpoint, or changes the expression you are currently watching if you are editing a watchpoint.

You watch an expression to see its value at different places in your program. Use this command to enter or edit an expression you want to watch.

In addition to changing the watchpoint itself, you can change the value of a watchpoint. Use Watch|Change to change the value of a watchpoint.

Shortcuts

Keyboard:	Ctrl+W

SpeedMenu:	Add... (Watch window)
Edit... (Watch window)
Watch (Module window)

Dialog Box Options

Expression

Specifies the expression to watch. Enter or edit the expression you want to watch. Use the drop-down button to choose from a history of previously selected expressions.


See Also

Watch|Change...

Watch Window


Watch|Delete (Debugger)
Watch | Delete

See Also

Deletes the selected watchpoint from the Watch window.

Shortcuts

SpeedMenu:	Delete (Watch window)


See Also

Watch|Remove All

Watch Window


Watch|Remove All (Debugger)
Watch | Remove All

See Also

Removes all watchpoints from the Watch window.

Shortcuts

SpeedMenu:	Remove All (Watch window)


See Also

Watch|Delete

Watch Window


Watch|Change (Debugger)
Watch | Change...

See Also

Changes the value of a variable, field, object, or property selected in the Watch window. Choosing this command displays the Changing <item> dialog box, where you can specify a new value.

This command affects the value of the variable globally. For example, if you change the value of a global variable in a subroutine, you also change the value of the variable in the calling program.

In addition to changing the value globally, you can change the value within the scope of the inspection only. Use Inspect SpeedMenu|Change to change the value of a variable within a specific scope.

Shortcuts

SpeedMenu:	Change (Watch window)


See Also

Inspect SpeedMenu|Change...


 Break Menu (Debugger)

See Also

Use the Break menu to add, edit, remove, and navigate between breakpoints in a debugging session.

You can create a breakpoint for a single program file or for all program files.

The Break menu contains the following commands:

Add...

Delete

Edit...

Remove All

Toggle On/Off

Go To


See Also

Break Window


Break|Add or Edit... (Debugger)
Break | Add or Edit...

See Also

Adds a breakpoint to the list in the Break window or changes an existing breakpoint.

You can set two types of breakpoints in the Debugger:

A global breakpoint interrupts program execution when a condition you specifiy occurs anywhere in your program.

A program-specific breakpoint interrupts program execution in one of the following situations:

When a condition you specify occurs in a specific module in your program

When a line number you specify executes a certain number of times

Use this command to specify where you want a breakpoint to occur:

To create a program-specific breakpoint based on a condition, enter a value for Location, Condition, and optionally Action.

To create a program-specific breakpoint based on the number of times a line executes, enter a value for Location, Line #, Pass Count, and optionally Action.

To create a global breakpoint, check Global, enter a value for Condition/Expression, turn on either Expression True or Expression Changed, and optionally enter a value for Action.

Shortcuts

SpeedMenu:	Add... (Break window)
Edit... (Break window)

Dialog Box Options

Location

Specifies a program-specific breakpoint to set or change. Enter the name of the program file for the breakpoint. Use the drop-down button to choose from a history of previously selected program files.

To set or change a global breakpoint, check Global. The Location text box disappears.

Condition

Specifies a condition or expression to stop program execution. Program execution stops when the condition evaluates to True or when the expression changes.

If you are creating a program-specific breakpoint, enter a condition to stop program execution.

If you are creating a global breakpoint, enter either a condition or an expression to stop program execution.

Action

Specifies an action when the program reaches the breakpoint. Enter the action to occur. For example, you can reset the value of an expression when the program reaches a breakpoint.

Line #

Sets or changes the line number for a program-specific breakpoint. Enter or change the line number for the breakpoint. If you check Global, the Line # text box disappears.

Pass Count

Stops program execution at a certain line number after a specified number of passes. Enter the number of passes. You must also specify the line number in the Line # text box.

Global

Specifies if the breakpoint is a global breakpoint. If you check Global:

The Location text box and the Line # text box disappear.

The Expression True and Expression Changed buttons appear.

Expr(ession) TRUE

Specifies a condition to stop program execution. Choose Expression True and enter the condition in the Condition text box.

For example, enter a condition such as "Quantity=5". When the value of the variable Quantity is 5, program execution stops.

The Expression True button is available only if you check Global.

Expr(ession) Changed

Specifies an expression to stop program execution. Choose Expression Changed and enter the expression in the Expression text box.

For example, enter an expression such as "a+b". Regardless of the present value of a+b, program execution stops when the value of a+b changes.

The Expression Changed button is available only if you check Global.


See Also

Break Window


Break|Delete (Debugger)
Break | Delete

See Also

Removes the breakpoint from the selected line in the Module window.

In addition to removing one breakpoint, you can remove all breakpoints in the current session. Choose Break|Remove All to remove all breakpoints in the current session.


See Also

Break|Remove All

Break Window


Break|Remove All (Debugger)
Break | Remove All

See Also

Removes all breakpoints in the current session.

In addition to removing all breakpoints, you can remove the breakpoint from the selected line in the Module window. Use Break|Delete to remove a single breakpoint.

Shortcuts

SpeedMenu:	Remove All (Break window)


See Also

Break|Delete

Break Window


Break|Toggle (Debugger)
Break | Toggle On/Off

See Also

Adds or removes a breakpoint in the current line of the Debugger.

If the current line does not have a breakpoint, dBASE for Windows adds one.

If the current line has a breakpoint, dBASE for Windows deletes it.

Shortcuts

Keyboard:	F2

SpeedMenu:	Toggle On/Off (Break window)


See Also

Break Window


Break|Goto (Debugger)
Break | Go To

Moves to the selected breakpoint in the Module window.

In the Break window, select the breakpoint that you want to move to. Then use Break|Go To to scroll the Module window to display that breakpoint. If the breakpoint is in another module, the Debugger loads that module in the Module window.

Shortcuts

SpeedMenu:	Go to (Break window)


 Options Menu (Debugger)

Use the Options menu to customize and save the Debugger configuration, or to restore a previously saved configuration.

The Options menu contains the following commands:

Defaults...

Animation Speed...

Display Font...

Source File Path...

Save Options...

Restore Options...


Options|Defaults... (Debugger)
Options | Defaults...

See Also

Sets Debugger environment options and controls the display of the SpeedBar.

Use this command to perform two tasks:

Specify the orientation of the SpeedBar for the present debugging session.

Specify the options that are saved in a .CFG file for use in future sessions. Choose Options|Save Options to save the options in a .CFG file.

Use checkmarks in the Config Options panel to specify the environment options that the Options|Save Options command saves. Use the SpeedBar radio buttons to specify the orientation of the SpeedBar for the current debugging session.

Dialog Box Options

Config Options

Sets Debugger environment options that are saved in the .CFG configuration file using Options|Save Options.

Desktop

Specifies that Options|Save Options will save the current arrangement of the Debugger windows and the placement of the SpeedBar.

Application

Specifies that Options|Save Options will save the current application as the default application for the Debugger.

Breakpoints

Specifies that Options|Save Options will save the breakpoints currently listed in the Break window.

Watchpoints

Specifies that Options|Save Options will save the watchpoints currently listed in the Watch window.

SpeedBar

Controls the position and display of the Debugger SpeedBar.

Normal

Displays the SpeedBar in its normal position at the top of the Debugger window.

Popup

Displays the SpeedBar as a floating palette.

Reduced

Reduces the size of the Debugger window so that only the menu and SpeedBar appear.

Vertical

Displays the SpeedBar in a vertical position.


See Also

Options|Save Options...


Options|Animation Speed... (Debugger)
Options | Animation Speed...

See Also

Determines the speed at which Run|Animate executes.

You can use this command before animating a program to set the animation speed, or you can use it to change the speed interactively while the Debugger is animating a program.

Dialog Box Options

Sets the animation speed. Move the slider to the left for a slower animation speed and to the right for a faster animation speed.


See Also

Run|Animate


Options|Display Fonts... (Debugger)
Options | Display Font...

Changes the display font that the Debugger uses.

This command displays the Font dialog box where you can specify the font, style, and size.


Options|Source File Path... (Debugger)
Options | Source File Path...

See Also

Specifies a default drive and directory from which to load files into the Debugger.

The path that you specify is set only for the present Debugger session. You cannot save it for future sessions with the Options|Save Options command.

Dialog Box Options

Path for Sources

Specifies the default path for Debugger files. Enter the full path to use.


See Also

Options|Save Options...


Options|Save or Restore Options... (Debugger)
Options | Save or Restore Options...

See Also

Saves or restores the configuration settings specified by Options|Defaults.

To save configuration settings for use in future sessions, first choose Options|Defaults to specify the environment settings you want to save.

Then choose Options|Save Options to display the Save Configuration dialog box, where you can specify a path and file name. The default file-name extension is .CFG.

To restore a previously saved configuration, choose Options|Restore Options to display the Restore Configuration dialog box, from which you can choose the file. The default file-name extension is .CFG.

(For general information about opening or saving files, see Open or Save File dialog box.)


See Also

Options|Defaults...

Options|Source File Paths


 Window Menu (Debugger)

Use the Window menu to arrange and open the Debugger windows.

The Window menu contains the following commands:

Tile

Cascade

Arrange Icons

Break Window

Watch Window

Stack Window

Module Window


Window|Tile (Debugger)
Window | Tile

See Also

Tiles all open Debugger windows.

If a window is minimized as an icon, this command has no effect on it.


See Also

Window|Cascade

Window|Arrange Icons


Window|Cascade (Debugger)
Window | Cascade

See Also

Cascades all open Debugger windows.

If a window is minimized as an icon, this command has no effect on it.


See Also

Window|Tile

Window|Arrange Icons


Window|Arrange Icons (Debugger)
Window | Arrange Icons

See Also

Arranges all Debugger windows that are minimized as icons.


See Also

Window|Cascade

Window|Tile


Window|Break Window (Debugger)
Window | Break Window

See Also

Displays the Break window, which shows all breakpoints set in the current module and lets you add, edit, and remove breakpoints.


See Also


Window|Watch Window(Debugger)
Window | Watch Window

See Also

Displays the Watch window, which shows the values of expressions you choose to watch.


See Also


Window|Stack Window (Debugger)
Window | Stack Window

See Also

Displays the Stack window, which shows any calls the module you are debugging makes to other modules, procedures, or UDFs.


See Also


Window|Module Window (Debugger)
Window | Module Window

See Also

Displays the Module window, which shows the source code for the program module you are debugging.


See Also


 Help Menu (Debugger)

Use the Help menu to display various types of online Help and version information for dBASE for Windows.

Choose from the following commands:

Contents

Search...

Language...

How to Use Help

About...


 Module SpeedMenu (Debugger)

Use the Module SpeedMenu to open other program modules, navigate within modules, fix your source code, inspect, evaluate, or modify variables, fields, arrays, or objects, and add watchpoints.

The Module SpeedMenu contains the following commands:

Load Module...

Go to Line...

Previous Line

Find...

Find Next

Origin

Go to Procedure...

Fix

Inspect

Evaluate/Modify...

Watch


 Watch SpeedMenu (Debugger)

Use the Watch SpeedMenu to add, edit, delete, and change watchpoints.

The Watch SpeedMenu contains the following commands:

Add...

Delete

Edit...

Remove All

Change


 Break SpeedMenu (Debugger)

Use the Break SpeedMenu to add, delete, edit, and navigate between breakpoints.

The Break SpeedMenu contains the following commands:

Add...

Delete

Edit...

Remove All

Go to

Toggle On/Off


 Stack SpeedMenu (Debugger)

Use the Stack SpeedMenu to navigate to different modules.

The Stack SpeedMenu contains the following command:

Go to Source Line


Stack SpeedMenu|Go to Source Line (Debugger)
Stack SpeedMenu | Go to Source Line

Displays the source code for a selected routine.

The Stack window keeps track of any calls the program you are debugging makes to other programs, procedures, or UDFs. When you select a call in the Stack window and use Go to Source Line, the Module window displays the source code for the selected call.


 File SpeedMenu (Debugger)

Use the File SpeedMenu to navigate within the file you are viewing, display the file as ASCII or as hexadecimal.

The File SpeedMenu contains the following commands:

Go To...

Find...

Find Next

Display ASCII

Display Hex

New File...


File SpeedMenu|Display ASCII (Debugger)
File SpeedMenu | Display ASCII

See Also

Displays the contents of the current File window in ASCII.


See Also

File SpeedMenu|Display Hex


File SpeedMenu|Display Hex (Debugger)
File SpeedMenu | Display Hex

See Also

Displays the contents of the current File window in hexadecimal.


See Also

File SpeedMenu|Display ASCII


File SpeedMenu|New File (Debugger)
File SpeedMenu | New File...

See Also

Replaces the source code in the current File window with the source code in another file.

Do not confuse this command with File|Open Text File, which opens another File window.


See Also

File|Open Text File...


 Inspect SpeedMenu (Debugger)

Use the Inspect SpeedMenu to provide a range for an item you are inspecting, change the inspection point, inspect additional elements, descend into objects or arrays, view the item you are inspecting in hexadecimal characters, and enter new items to inspect.

The Inspect SpeedMenu contains the following commands:

Range...

Change...

Inspect Alone

Descend

Hex Expand

Inspect New Expression...


Inspect SpeedMenu|Range (Debugger)
Inspect SpeedMenu | Range...

Sets an upper and lower limit for the inspected item.

Use this command to specify a temporary upper and lower boundary for the inspected item while the program is executing. The inspected item does not exceed this range until you close the Inspect window.

Dialog Box Options

Lower Limit

Specifies the lower limit. Enter a value for the lower limit.

Upper Limit

Specifies the upper limit. Enter a value for the upper limit.


Inspect SpeedMenu|Change (Debugger)
Inspect SpeedMenu | Change...

See Also

Changes the value of the inspected variable, field, or array element. Choosing this command displays the Changing <item> dialog box, where you can specify a new value.

This command affects the value of the inspected item only within the scope of the inspection. For example, if you change the value of a global variable in a subroutine, you do not affect the value of the variable in the calling program.

In addition to changing the value within the scope of inspection, you can change the value globally. Choose Change... from the Watch window SpeedMenu to change the value of a variable globally.


See Also

Watch|Change...


Changing <item> Dialog Box

See Also

Changes value of a variable, field, or array element that you are inspecting, or changes the value of a variable, field, object, or property selected in the Watch window. This dialog box is displayed for an inspected item when you choose Change... from the Inspect window SpeedMenu, and it is displayed for a watched item when you select Watch|Change.

Dialog Box Option

New Value

Specifies a new value for the inspected or watched item. Enter the new value in the text field, or use the drop-down button to choose from a history of previously selected values.

If you specify a character value, enter the value in quotes, such as "Birthday". Enter date values enclosed in braces, such as {01/19/64}.


See Also

Inspect SpeedMenu|Change

Watch|Change


Inspect SpeedMenu|Inspect Alone (Debugger)
Inspect SpeedMenu | Inspect Alone

See Also

Inspects the specified item again and displays its value in a separate Inspect window.

The value displayed in the Inspect window is the value of the variable, field, array, or object at the time of inspection. Unlike the display in the Watch window, the display in the Inspect window is not updated as values change.


See Also

Inspect SpeedMenu|Descend


Inspect SpeedMenu|Descend (Debugger)
Inspect SpeedMenu | Descend

See Also

Displays the highlighted item in a new Inspect window.

Use this command to descend into objects and arrays. For example, if you inspect an object, the values of all its properties are displayed in the Inspect window. If one of the properties is an object, you can inspect that object in its own Inspect window with this command.


See Also

Inspect SpeedMenu|Inspect Alone


Inspect SpeedMenu|Hex Expand (Debugger)
Inspect SpeedMenu | Hex Expand

Displays the hexadecimal value of binary string variables.


Help Contents
 dBASE for Windows Help Contents

Welcome to dBASE for Windows Help. Select an item from the list below. Choose Help|How to Use Help if Windows Help is new to you.
	Basics: Overview of features and tools; introduction to new concepts; information for dBASE IV users; how to register and obtain technical support.
	Views and Tools: Information about working with the interactive views and tools, including menus, dialog boxes, SpeedBars, designers, palettes, and inspectors.
	Debugger:  Information about working in the Debugger.
	Language Reference: Descriptions of the language elements, in categorical and alphabetical order.
	Keyboard Shortcuts: Lists, descriptions, and menu equivalents of available keystrokes.
	Glossary: Definitions of terms, in alphabetical order.
	Error Messages: Lists of error messages, in alphabetical and numerical order.


Search Dialog Box

The Search dialog box gives you a comprehensive index to the topics in dBASE for Windows Help. Use it to look up specific topics or categories of topics.

1.	Open the Search dialog box using one of the following methods.

Click the Search button on the Help button bar.

Press Alt+S.

Select Search... from the dBASE for Windows Help menu.

2.	Type the topic or category in the input box under "Type a word."

If the item is indexed in Help, it appears in the upper list box.

If the item is not indexed, you see the item that most closely matches.

3.	Choose an item from the list, then press Enter or choose Show Topics. A list of 1 or more Help topics appears in the lower "Select a topic" list box.

4.	Choose a topic from the list, then press Enter or choose Go To. The Help topic appears.


Search Dialog Box

The Search dialog box gives you a comprehensive index to the topics in dBASE for Windows Help. Use it to look up specific topics or categories of topics.

1.	Open the Search dialog box using one of the following methods.

Click the Search button on the Help button bar.

Press Alt+S.

Select Search... from the dBASE for Windows Help menu.

2.	Type the topic or category in the input box under "Type a word."

If the item is indexed in Help, it appears in the upper list box.

If the item is not indexed, you see the item that most closely matches.

3.	Choose an item from the list, then press Enter or choose Show Topics. A list of 1 or more Help topics appears in the lower "Select a topic" list box.

4.	Choose a topic from the list, then press Enter or choose Go To. The Help topic appears.


Moving from the dBASE IV Control Center

If you are familiar with the dBASE IV Control Center, this topic helps you find corresponding commands, tools, and features in dBASE for Windows. You can view information on each Control Center menu command and the dBASE IV screens.

Control Center Menus

Click a menu name in the list below to view the main Control Center menu commands and their dBASE for Windows equivalents.

Catalog Menu

Tools Menu

Exit Menu

dBASE IV Screens

Click the name of a dBASE IV screen from the list below to view information about each screen, its menus, and the dBASE for Windows equivalents.

Create/Modify Structure Screen

Browse/Edit Screen

Queries Design Screen

Forms Design Screen

Reports Design Screen

Labels Design Screen

Applications Screen


dBASE IV Control Center - Catalog Menu

See Also

In dBASE for Windows, the Catalog Window and other features replace the Catalog menu commands in the Control Center. Choose from the following list for information on the dBASE for Windows features and commands.

dBASE IV Catalog Menu	dBASE for Windows Equivalent
Use a different catalog	File|Open
Modify catalog name	Windows File Manager
Edit description of catalog	Catalog Window Components
Add file to catalog	Catalog|Add Item
Remove highlighted file from catalog	Edit|Delete
Change description of highlighted file	Catalog Item Description box, See Catalog Window Components
Open custom utility	Not applicable


dBASE IV Control Center - Tools Menu

See Also

Choose from the following list for information on the dBASE for Windows equivalent commands for the Control Center Tools menu.

dBASE IV Tools Menu	dBASE for Windows Equivalent
Macros	Windows Recorder
Import	File|Import or Table|Table Utilities|Append Records from File
Export	Table|Table Utilities|Export Records
DOS utilities	Windows File Manager
Protect data	Not supported in this release.
Settings
Options	Properties|Desktop
Display	Windows Control Panel


dBASE IV Control Center - Exit Menu

See Also

Choose from the following list for information on the dBASE for Windows equivalent commands for the Control Center Exit menu.

dBASE IV Exit Menu	dBASE for Windows Equivalent
Exit to dot prompt	Command Window
Quit to DOS	File|Exit


dBASE IV Control Center - Create/Modify Structure Screen

See Also

In dBASE for Windows, use the Table Designer, Table Records Window, and Manage Indexes Dialog Box as the equivalent tools for the dBASE IV Create/Modify Structure screen.

dBASE IV Data Screen (Create/Modify Structure)

Click a menu name in the list below to view the Create/Modify Structure menu commands and their dBASE for Windows equivalents.

Layout Menu

Organize Menu

Append Menu

Go To Menu

Exit Menu


dBASE IV Control Center - Layout Menu (Create/Modify Structure Screen)

See Also

In dBASE for Windows, use the Table Designer as the equivalent feature for the Layout menu commands in the Create/Modify Structure screen. Choose from the following list for information on the dBASE for Windows commands.

dBASE IV Layout Menu	dBASE for Windows Equivalent
Print database structure	File|Print
Edit database description	Catalog Item Description box, See Catalog Window Components
Save this database file structure	File|Save


dBASE IV Control Center - Organize Menu (Create/Modify Structure Screen)

See Also

In dBASE for Windows, use the Manage Indexes Dialog Box, the Table Records Window, and the dBASE language as the equivalent features for the Organize menu commands in the Create/Modify Structure screen. Choose from the following list for information on the dBASE for Windows commands.

dBASE IV Organize Menu	dBASE for Windows Equivalent
Create new index	Structure|Manage Indexes,  Create Index Dialog Box
Modify existing index	Structure|Manage Indexes,  Modify Index Dialog Box
Order records by index	Manage Indexes Dialog Box
Activate .NDX index file	USE or SET INDEX in Command Window
Include .NDX index file	SET INDEX in Command Window
Remove unwanted index tag	Manage Indexes dialog box
Sort database on field list	Table|Table Utilities|Sort Records
Unmark all records	Table|Table Utilities|Recall Records
Erase marked records	Table|Table Utilities|Pack Records


dBASE IV Control Center - Append Menu (Create/Modify Structure Screen)

See Also

In dBASE for Windows, use the Table Records Window as the equivalent feature for the Append menu commands in the Create/Modify Structure screen. Choose from the following list for information on the dBASE for Windows commands.

dBASE IV Append Menu	dBASE for Windows Equivalent
Enter records from keyboard	Table|Add Records
Append records from dBASE file	Table|Table Utilities|Append Records from File
Copy records from non-dBASE file	Table|Table Utilities|Append Records from File


dBASE IV Control Center - Go To Menu (Create/Modify Structure Screen)

See Also

In dBASE for Windows, use the Table Designer as the equivalent feature for the Go To menu commands in the Create/Modify Structure screen. Choose from the following list for information on the dBASE for Windows commands.

dBASE IV Go To Menu	dBASE for Windows Equivalent
Top field	Table Designer Components
Last field	Table Designer Components
Field number	Structure|Go to Field Number


dBASE IV Control Center - Exit Menu (Create/Modify Structure Screen)

See Also

In dBASE for Windows, use the following commands as the equivalent commands for the Exit menu commands in the Create/Modify Structure screen.

dBASE IV Exit Menu	dBASE for Windows Equivalent
Save changes and exit	File|Save and Close
Abandon changes and exit	File|Abandon and Close


See Also

Control Center - Create/Modify Structure Screen

Table Designer

Manage Indexes Dialog Box

Table Records Window

Moving from the dBASE IV Control Center


dBASE IV Control Center - Browse/Edit Screen

See Also

In dBASE for Windows, use the Table Records Window as the equivalent tool for the dBASE IV Browse/Edit screen.

dBASE IV Data Screen (Browse/Edit)

Click a menu name in the list below to view the Browse/Edit menu commands and their dBASE for Windows equivalents.

Records Menu

Organize Menu

Fields Menu

Go To Menu

Exit Menu


dBASE IV Control Center - Records Menu (Browse/Edit Screen)

See Also

In dBASE for Windows, use the Table Records Window as the equivalent tool for the Records menu commands in the Browse/Edit screen. Choose from the following list for information on the dBASE for Windows commands.

dBASE IV Records Menu	dBASE for Windows Equivalent
Undo change to record	Edit|Undo
Add new records	Table|Add Records
Mark record for Deletion/ Clear deletion mark	Table|Delete or Recall Selected Record
Blank record	Table|Blank Selected Record
Record lock	Table|Lock Selected Record
Follow record to new position	Properties|Table Records Window,  Records Properties


dBASE IV Control Center - Organize Menu (Browse/Edit Screen)

See Also

In dBASE for Windows, use the Table Records Window as the equivalent tool for the Organize menu commands in the Browse/Edit screen. Choose from the following list for information on the dBASE for Windows commands.

dBASE IV Organize Menu	dBASE for Windows Equivalent
Create new index	Table|Table Utilities|Manage Indexes, Create Index Dialog Box
Modify existing index	Table|Table Utilities|Manage Indexes, Modify Index Dialog Box
Order records by index	Manage Indexes Dialog Box
Activate .NDX index file	USE or SET INDEX in Command Window
Include .NDX index file	SET INDEX in Command Window
Remove unwanted index tag	Manage Indexes Dialog Box
Sort database on field list	Table|Table Utilities|Sort Records
Unmark all records	Table|Table Utilities|Recall Records
Erase marked records	Table|Table Utilities|Pack Records


dBASE IV Control Center - Fields Menu (Browse/Edit Screen)

See Also

In dBASE for Windows, use the Table Records Window as the equivalent tool for the Fields menu commands in the Browse/Edit screen. Choose from the following list for information on the dBASE for Windows commands.

dBASE IV Fields Menu	dBASE for Windows Equivalent
Lock fields on left	Properties|Table Records Window,  Window Properties
Blank field	Edit|Select All then Edit|Delete
Freeze field	Properties|Table Records Window,  Window Properties
Size field	Properties|Table Records Window,  Fields Properties,  Field Properties Dialog Box


dBASE IV Control Center - Go To Menu (Browse/Edit Screen)

See Also

In dBASE for Windows, use the Table Records Window as the equivalent tool for the Go To menu commands in the Browse/Edit screen. Choose from the following list for information on the dBASE for Windows commands.

dBASE IV Go To Menu	dBASE for Windows Equivalent
Top record	Table|Top Record
Last record	Table|Bottom Record
Record number	Table|Go To  Record Number
Skip	Table|Next Record and Table|Previous Record
Index key search	Table|Find Records
Forward search	Table|Find Records
Backward search	Table|Find Records
Match capitalization	Table|Find Records


dBASE IV Control Center - Exit Menu (Browse/Edit Screen)

See Also

In dBASE for Windows, use the Table Records Window as the equivalent tool for the Exit menu commands in the Browse/Edit screen. Choose from the following list for information on the dBASE for Windows commands.

dBASE IV Exit Menu	dBASE for Windows Equivalent
Exit	File|Save Record and Close
Transfer to Query Design	Table|Create Query


See Also

Control Center - Browse/Edit Screen

Moving from the dBASE IV Control Center


See Also

Moving from the dBASE IV Control Center


dBASE IV Control Center - Queries Design Screen

See Also

In dBASE for Windows, use the Query Designer to design views and queries, and the Table Records Window to perform update queries. Use these tools as the equivalent tools for the Control Center Queries Design Screen menu commands.

dBASE IV Queries Design Screen

Click a menu name in the list below to view the Queries Design menu commands and their dBASE for Windows equivalents.

Layout Menu

Fields Menu

Condition Menu

Update Menu

Exit Menu


dBASE IV Control Center - Layout Menu (Queries Design Screen)

See Also

In dBASE for Windows, use the Query Designer as the equivalent tool for the Layout menu commands in the Queries Design screen. Choose from the following list for information on the dBASE for Windows commands.

dBASE IV Layout Menu	dBASE for Windows Equivalent
Add file to query	Query|Add Table
Remove file from query	Query|Remove Selected Table
Create link by pointing	Query|Set Relation
Write view as database file	Query|Copy Results to New Table
Edit description of query	Catalog Item Description box, See Catalog Window Components
Save this query	File|Save As
Invoke layout program	Not applicable


dBASE IV Control Center - Fields Menu (Queries Design Screen)

See Also

In dBASE for Windows, use the Query Designer as the equivalent tool for the Fields menu commands in the Queries Design screen. Choose from the following list for information on the dBASE for Windows commands.

dBASE IV Fields Menu	dBASE for Windows Equivalent
Add field to view	Selecting Fields to Display in a View
Remove field from view	Selecting Fields to Display in a View
Edit field name	Not supported in this release.
Create calculated field	Query|Create Calculated Field
Delete calculated field	Query|Delete Selected Calculated Field
Sort on this field	Specifying Record Order in a Query
Include indexes	Properties|Query Designer
Keep speedup indexes	Query|Manage Indexes (automatic)
Filter method	Setting Filter Conditions in a Query (automatic)
Load field program	Not applicable


dBASE IV Control Center - Condition Menu (Queries Design Screen)

See Also

In dBASE for Windows, use the Query Designer as the equivalent tool for the Condition menu commands in the Queries Design screen. Choose from the following list for information on the dBASE for Windows commands.

dBASE IV Condition Menu	dBASE for Windows Equivalent
Add condition box	Query|Add Conditions
Delete condition box	Query|Remove Conditions
Show condition box	Not supported in this release.


dBASE IV Control Center - Update Menu (Queries Design Screen)

See Also

In dBASE for Windows, you perform update queries in the Table Records Window. Use this tool for the Update menu commands in the Queries Design screen. Choose from the following list for information on the dBASE for Windows commands.

dBASE IV Update Menu	dBASE for Windows Equivalent
Perform the update	See below.
Specify update operation	See below.
Replace values in	Table|Replace Records
Append records to	Table|Table Utilities|Append Records from File or File|Import
Mark records for deletion	Table|Table Utilities|Delete Records
Unmark records in	Table|Table Utilities|Recall Records


dBASE IV Control Center - Exit Menu (Queries Design Screen)

See Also

In dBASE for Windows, use the Query Designer as the equivalent tool for the Exit menu commands in the Queries Design screen. Choose from the following list for information on the dBASE for Windows commands.

dBASE IV Exit Menu	dBASE for Windows Equivalent
Save changes and exit	File|Save and Close
Abandon changes and exit	File|Abandon and Close


See Also

Control Center - Queries Design Screen

Query Designer

Table Records Window

Moving from the dBASE IV Control Center


dBASE IV Control Center - Forms Design Screen

See Also

In dBASE for Windows, use the Form Designer to design data entry forms, dialog boxes, and application windows. Use this tool for the Control Center Forms Design screen menu commands.

dBASE IV Forms Design Screen

Click a menu name in the list below to view the Forms Design menu commands and their dBASE for Windows equivalents.

Layout Menu

Fields Menu

Words Menu

GoTo Menu

Exit Menu


dBASE IV Control Center - Layout Menu (Forms Design Screen)

See Also

In dBASE for Windows, use the Form Designer as the equivalent tool for the Layout menu commands in the Forms Design screen. Choose from the following list for information on the dBASE for Windows commands.

dBASE IV Layout Menu	dBASE for Windows Equivalent
Quick layout	Help|Experts|Form Expert
Box	View|Controls, Control Palette
Line	View|Controls, Control Palette
Use different database file or view	View|Object Properties then Data Linkage Properties
Edit description of form	Catalog Item Description box, See Catalog Window Components
Save this form	File|Save
Invoke layout program	Not applicable


dBASE IV Control Center - Fields Menu (Forms Design Screen)

See Also

In dBASE for Windows, you add a control to a form using the Control Palette, then link the control to a table field or a calculation using Data Linkage Properties. You can also use tools for picture functions and templates. You attach dBASE code to controls using the Procedure Editor. Use these tools for the Fields menu commands in the Forms Design screen. Choose from the following list for information on the dBASE for Windows commands.

dBASE IV Fields Menu	dBASE for Windows Equivalent
Add field	View|Controls, Control Palette
Remove field	Select the field then Edit|Delete
Modify field	Select the field then View|Object Properties
Insert memory variable	View|Object Properties then Data Linkage Properties


dBASE IV Control Center - Words Menu (Forms Design Screen)

See Also

In dBASE for Windows, use the Form Designer as the equivalent tool for the Words menu commands in the Forms Design screen. Choose from the following list for information on the dBASE for Windows commands.

dBASE IV Words Menu	dBASE for Windows Equivalent
Style	View|Object Properties then Font Properties
Display	View|Object Properties then Visual Properties
Position	View|Object Properties then Position Properties
Modify ruler	Properties|Form Designer
Hide ruler	Properties|Form Designer
Enable automatic indent	Properties|Procedure Editor
Add line	Press Enter or Ctrl+N or Ctr+Enter
Remove line	Select the line then Edit|Delete
Insert page break	Not applicable
Write/read text file	Edit|Insert from File or Edit|Copy to File


dBASE IV Control Center - Go To Menu (Forms Design Screen)

See Also

In dBASE for Windows, use the Form Designer as the equivalent tool for the Go To menu commands in the Forms Design screen. Choose from the following list for information on the dBASE for Windows commands.

dBASE IV Go To Menu	dBASE for Windows Equivalent
Go to line number	Edit|Search|Go to Line Number
Forward search	Edit|Search|Find Text
Backward search	Edit|Search|Find Text
Replace	Edit|Search|Replace Text
Match capitalization	Edit|Search|Find Text


dBASE IV Control Center - Exit Menu (Forms Design Screen)

See Also

In dBASE for Windows, use the Form Designer as the equivalent tool for the Exit menu commands in the Forms Design screen. Choose from the following list for information on the dBASE for Windows commands.

dBASE IV Exit Menu	dBASE for Windows Equivalent
Save changes and exit	File|Save and Close
Abandon changes and exit	File|Abandon and Close


See Also

Control Center - Forms Design Screen

Form Designer

Using the Form Designer - Overview

Moving from the dBASE IV Control Center


dBASE IV Control Center - Reports and Labels Design Screen

See Also

In dBASE for Windows, you create and edit report and label designs using Crystal Reports for dBASE. See the following topics for information.

About Reports and Labels

Designing Reports and Labels

Using Reports and Labels


dBASE IV Control Center - Applications Screen

See Also

In dBASE for Windows, tools such as the Query Designer and Form Designer generate dBASE code automatically. You typically use these tools in combination to create an entire application. You can edit the generated code using the Text Editor. In the Form Designer, you use the Procedure Editor to write and structure code that defines the form and its behavior.

You can also write your own programs from scratch using the Text Editor. Use this tool as the equivalent tool for the Control Center Applications menu commands when editing a dBASE program.

dBASE IV Applications Screen

Click a menu name in the list below to view the Applications menu commands and their dBASE for Windows equivalents.

Layout Menu

Words Menu

GoTo Menu

Print Menu

Exit Menu


dBASE IV Control Center - Layout Menu (Applications Screen)

See Also

In dBASE for Windows, use the Text Editor as the equivalent tool for the Layout menu commands in the Applications screen. Choose from the following list for information on the dBASE for Windows commands.

dBASE IV Layout Menu	dBASE for Windows Equivalent
Modify a different program	File|Open
Edit description of program	Catalog Item Description box, See Catalog Window Components
Save this program	File|Save


dBASE IV Control Center - Words Menu (Applications Screen)

See Also

In dBASE for Windows, use the Text Editor as the equivalent tool for the Words menu commands in the Applications screen. Choose from the following list for information on the dBASE for Windows commands.

dBASE IV Words Menu	dBASE for Windows Equivalent
Hide ruler	Not supported in this release.
Enable automatic indent	Properties|Program or Text Editor
Add line	Press Enter or Ctrl+N or Ctr+Enter
Remove line	Select the line then Edit|Delete
Insert page break	Not applicable
Write/read text file	Edit|Insert from File or Edit|Copy to File


dBASE IV Control Center - Go To Menu (Applications Screen)

See Also

In dBASE for Windows, use the Text Editor as the equivalent tool for the Go To menu commands in the Applications screen. Choose from the following list for information on the dBASE for Windows commands.

dBASE IV Go To Menu	dBASE for Windows Equivalent
Go to line number	Edit|Search|Go to Line Number
Forward search	Edit|Search|Find Text
Backward search	Edit|Search|Find Text
Replace	Edit|Search|Replace Text
Match capitalization	Edit|Search|Find Text


dBASE IV Control Center - Print Menu (Applications Screen)

See Also

In dBASE for Windows, you print and control printing options with File|Print and File|Printer Setup. In addition, the Windows Control Panel has options for setting up printers on your system. See your Windows documentation for more information.


dBASE IV Control Center - Exit Menu (Applications Screen)

See Also

In dBASE for Windows, use the File menu to exit programs and to open programs. The Debugger is the tool for debugging programs. Choose from the following list for information on the dBASE for Windows commands.

dBASE IV Exit Menu	dBASE for Windows Equivalent
Save changes and exit	File|Save and Close
Abandon changes and exit	File|Abandon and Close
Run program	Program|Do
Debug program	Program}Debug


See Also

Control Center - Applications Screen

Moving from the dBASE IV Control Center


Error Messages

The following topics show all the dBASE for Windows error messages. Choose a topic to display the messages and their corresponding numbers alphabetically or numerically.

When the alphabetical list is displayed, click Numerical List beneath the title to display the messages numerically. When the numerical list is displayed, click Alphabetical List to display them numerically.

Error Messages - Alphabetical List

Error Messages - Numeric List

Trapping Errors

You can use the ON ERROR command to designate a subroutine as an error handler. This subroutine is automatically executed when an error condition occurs during runtime. The subroutine can use the following functions to trap errors:

ERROR( ) returns a dBASE error number.

MESSAGE( ) returns a dBASE error message.

DBERROR( ) returns an IDAPI error number.

DBMESSAGE( ) returns an IDAPI error message.

SQLERROR( ) returns a server error number.

SQLMESSAGE( ) returns a server error message.

LINENO( ) returns the number of the line at which the error occurred.

PROGRAM( ) returns the name of the program, procedure, or user-defined function in which the error occurred.

The error-handler subroutine can use these returned values to make branching decisions or provide information to the user.

The CERROR( ) function returns the number of an error that occurs at compile time.


Error Messages - Alphabetical List

Numerical List

A

248	Access denied

180	ALIAS already in use

178	Alias not found

251	Already in printjob

281	Attempt to access released object

151	Attempt to free a bad memory block

152	Attempt to load a bad icode block

257	Attempting to call a method as a function

B

25	Bad field name

26	Bad field type

135	Bars already defined for popup

136	Bars must have a positive value.

186	Beginning of table encountered

310	BINARY field not allowed here

C

249	Can only change draft mode on page boundaries

250	Can only change page orientation on page boundaries

272	Cannot activate object.OLE server is busy

270	Cannot Copy selection

319	Cannot create directory:

197	Cannot execute this command when DESIGN is off

145	Cannot have more than one window object with the same name

266	Cannot load print driver:

271	Cannot Package file:

267	Cannot paste more than one file

269	Cannot Paste selection

275	Cannot perform operation on static object

212	Cannot redefine active menu

139	Cannot release active

245	Cannot UPDATE a table with itself

273	Cannot update linked object

344	Class does not exist

201	Command not functional in dBASE for Windows

110	Command requires exclusive use of table

55	Command too large

200	Command will never be reached

298	Constant is already #defined

191	CONTINUE without previous LOCATE

41	Cyclic RELATION not allowed

D

163	Data type mismatch.Expecting <type>

232	Database already open

241	Database not opened

304	DLL does not support Multiple Instances:

206	Drive not ready: <drive>

28	Duplicate field name

E

4	End of table encountered

84	ENDCASE encountered without preceding CASE

88	ENDCLASS/MEMBER command encountered without previous CLASS command

76	ENDDO encountered without preceding WHILE

74	ENDIF encountered without preceding IF

86	ENDPRINTJOB command encountered without previous PRINTJOB command

80	ENDSCAN encountered without preceding SCAN

90	ENDTEXT command encountered without previous TEXT command

3	Error closing file

276	Error connecting to OLE server

1	Error creating file

313	Error creating palette

305	Error loading DLL:

2	Error opening file

268	Error pasting file:

6	Error positioning in file

187	Error reading file

342	Error reading from binary field

309	Error Saving VBX

224	Error unlocking file

29	Error writing file

154	Expanded macro variable does not return a valid identifier

228	Expecting #endif

56	Expression expected

57	Expression too large

306	Extern:

202	Extra characters ignored at end of command

F

198	Feature not currently available

51	Field must be a binary field

50	Field must be a memo field

299	Field must be an OLE field:

40	Field not found

8	File already exists

9	File already open

7	File does not exist

114	Filename space exhausted

335	First class in .WFM file is not derived from FORM

341	Form already open

262	Form cannot be MDI

G - I

239	IDAPI Error

185	Illegal file name

32	Illegal key

169	Illegal Opcode

158	Illegal value

157	Illegal work area number or alias

108	In use by another

230	Include file not found

327	#includes nested too deeply

316	Incomplete link specification

328	Index expressions not allowed for INTEGRITY rules

339	Index file does not exist

237	Index is not open

260	Internal Exception Error

149	Internal runtime's buffer overflow

146	Internal stack overflow

147	Internal stack underflow

150	Internal string buffer overflow

246	Invalid Catalog

104	Invalid CLASS name

277	Invalid command verb for OLE object

12	Invalid COV file

210	Invalid directory

211	Invalid disk drive

243	Invalid file Handle

340	Invalid file privileges

103	Invalid FUNCTION or PROCEDURE name

323	Invalid key label

14	Invalid label file

105	Invalid MEMBER name

16	Invalid memory variable file

71	Invalid name character

48	Invalid order number

247	Invalid password

321	Invalid preprocessor identifier

196	Invalid printer redirection

17	Invalid PRO / FMO file

18	Invalid query file

19	Invalid report file

193	Invalid subscript reference

320	Invalid table name

242	Invalid value for convert size (8-24)

21	Invalid view file

22	Invalid window file

J - K

334	Key already exists in parent

98	Keyword Repeated

L

94	Loop stack overflow

M

153	Macros cannot expand flow of control commands

227	Maximum #ifdef nesting exceeded

176	Maximum number of active keyboard macros exceeded

175	Maximum number of DO or UDF parameters exceeded

36	Maximum number of fields reached

222	Maximum number of locked records exceeded

172	Maximum number of nested FOR NEXT loops exceeded

179	MEMO field not allowed here

338	Memo file does not exist

190	Memory variable already defined - cannot make PUBLIC

111	Memory variable space exhausted

127	Menu already active

258	Method is not available on object

85	Missing ENDCASE

89	Missing ENDCLASS

77	Missing ENDDO

75	Missing ENDIF

87	Missing ENDPRINTJOB

81	Missing ENDSCAN

91	Missing ENDTEXT

79	Missing NEXT

83	Missing UNTIL

343	Must convert report before modifying

N

78	NEXT encountered without preceding FOR

134	No bars defined for popup/pulldown

49	No fields were found to process

332	No matching parent record

254	No pads defined for

116	No PARAMETERS statement found

219	No previous DO WHILE/SCAN/PRINTJOB/FOR to match this command

253	No print driver selected

259	No Records Selected

119	No such bar

293	No such form

126	No such form object

214	No such listbox

120	No such menu

121	No such pad

122	No such popup

31	No such record in index

124	No such window

125	No such window

34	No table in use in area

30	Not a valid dBASE table

325	Not a valid table

168	Not an array

112	Not enough memory for DOS

107	Not enough memory for this operation

289	Not member of Class or Base class

156	Numbers are not allowed in the CURRENCY symbol

O

244	Idapi Not Initialized

280	OLE BLOB field data is from an incompatible version

279	OLE BLOB field is corrupted

314	OLE Error

311	OLE field not allowed here

278	OLE object error

295	OLE: cannot create link

315	Only 1 dimensional array is allowed in this operation

283	Only 1 or 2 dimensional array is allowed in this operation

324	Only allowed in function or procedure scope

115	Only valid in program files

333	Operation not allowed across different databases or table types

234	Operation not allowed in transaction

286	Operation not allowed on read-only fields

24	Operation not allowed on read-only files

287	Operation not allowed on read-only tables

236	Operation not allowed on this table

164	Out of range

P

303	Parameter type '...' can only be used with CDECL calling convention

70	PARAMETERS command must be at top of function or procedure

308	Parent is not a PAGETEMPLATE or BANDBODY

307	Parent is not a REPORT

128	Popup already active

312	Popup too small

326	Port not configured for a printer

301	Position not in window

229	Preprocessor expansion too large

189	Printer error

131	Printer is either not connected or turned off

182	Procedure not found

181	Processing would exceed maximum allowed string length

118	Program not SUSPENDed

106	Program too big to compile

203	Program was previously compiled with SET COVERAGE OFF

140	Prompt cannot be MEMO

282	Property is read only

285	Property not found

Q - R

109	Record is in use by another

337	Record is in use by another

5	Record out of range

329	Related records still exist in alias

336	Relation expression and active index expression must be the same

45	Relation expression memory exhausted

331	Relation using CONSTRAIN

322	RELEASE DLL: DLL not Loaded:

284	Report Engine Error

265	Resource not found

199	Restricted command: not allowed in this context

S

317	Selected tables cannot be related

240	Server Error

218	SET FIELDS space exhausted

330	SET KEY active in alias

223	Sharing buffers are full

67	Something is missing.Expecting

11	Structure invalid

290	SUPER not allowed when THIS is undefined

217	Symbol table space exhausted. Increase to <n>

63	Syntax error

T

231	Table already open

35	Table is not indexed

53	Tag not found

294	The system registry does not contain an OLE server for a file

58	Too few arguments.Expecting at least <n>

59	Too many arguments.Expecting at most <n>

101	Too many dimensions

209	Too many files open

47	Too many index files

221	Too many nested DO/UDF

95	Too many nested FOR loops

96	Too many nested SCAN loops

44	Too many RELATIONs in this chain

318	Too many symbols in this module

102	Too many UDF/PROCEDUREs defined in program

U

100	UDF must return a value

159	UDF or procedure already exists

207	UDF or PROCEDURE not found

292	Unable to create control

160	Unable to execute DOS

291	Unable to open form

10	Unable to rename file

97	Unallowed phrase/keyword in command

62	Unbalanced parentheses

188	Unexpected type

274	Unknown error saving window contents

68	Unknown keyword

225	Unmatched #else

226	Unmatched #endif

117	Unmatched parameters

54	Unrecognized command verb

61	Unterminated string

82	UNTIL encountered without preceding DO

V

192	Value out of range

167	Variable undefined

W

215	Window not active

132	Window out of range

42	Work area already used in relation

252	Wrong version of IDAPI01.DLL

X - Z

(none)


Error Messages - Numerical List

Alphabetical List

1 - 49

1	Error creating file

2	Error opening file

3	Error closing file

4	End of table encountered

5	Record out of range

6	Error positioning in file

7	File does not exist

8	File already exists

9	File already open

10	Unable to rename file

11	Structure invalid

12	Invalid COV file

14	Invalid label file

16	Invalid memory variable file

17	Invalid PRO / FMO file

18	Invalid query file

19	Invalid report file

21	Invalid view file

22	Invalid window file

24	Operation not allowed on read-only files

25	Bad field name

26	Bad field type

28	Duplicate field name

29	Error writing file

30	Not a valid dBASE table

31	No such record in index

32	Illegal key

34	No table in use in area

35	Table is not indexed

36	Maximum number of fields reached

40	Field not found

41	Cyclic RELATION not allowed

42	Work area already used in relation

44	Too many RELATIONs in this chain

45	Relation expression memory exhausted

47	Too many index files

48	Invalid order number

49	No fields were found to process

 50 - 99

50	Field must be a memo field

51	Field must be a binary field

53	Tag not found

54	Unrecognized command verb

55	Command too large

56	Expression expected

57	Expression too large

58	Too few arguments.Expecting at least <n>

59	Too many arguments.Expecting at most <n>

61	Unterminated string

62	Unbalanced parentheses

63	Syntax error

67	Something is missing.Expecting

68	Unknown keyword

70	PARAMETERS command must be at top of function or procedure

71	Invalid name character

74	ENDIF encountered without preceding IF

75	Missing ENDIF

76	ENDDO encountered without preceding WHILE

77	Missing ENDDO

78	NEXT encountered without preceding FOR

79	Missing NEXT

80	ENDSCAN encountered without preceding SCAN

81	Missing ENDSCAN

82	UNTIL encountered without preceding DO

83	Missing UNTIL

84	ENDCASE encountered without preceding CASE

85	Missing ENDCASE

86	ENDPRINTJOB command encountered without previous PRINTJOB command

87	Missing ENDPRINTJOB

88	ENDCLASS/MEMBER command encountered without previous CLASS command

89	Missing ENDCLASS

90	ENDTEXT command encountered without previous TEXT command

91	Missing ENDTEXT

94	Loop stack overflow

95	Too many nested FOR loops

96	Too many nested SCAN loops

97	Unallowed phrase/keyword in command

98	Keyword Repeated

100 - 149

100	UDF must return a value

101	Too many dimensions

102	Too many UDF/PROCEDUREs defined in program

103	Invalid FUNCTION or PROCEDURE name

104	Invalid CLASS name

105	Invalid MEMBER name

106	Program too big to compile

107	Not enough memory for this operation

108	In use by another

109	Record is in use by another

110	Command requires exclusive use of table

111	Memory variable space exhausted

112	Not enough memory for DOS

114	Filename space exhausted

115	Only valid in program files

116	No PARAMETERS statement found

117	Unmatched parameters

118	Program not SUSPENDed

119	No such bar

120	No such menu

121	No such pad

122	No such popup

124	No such window

125	No such window

126	No such form object

127	Menu already active

128	Popup already active

131	Printer is either not connected or turned off

132	Window out of range

134	No bars defined for popup/pulldown

135	Bars already defined for popup

136	Bars must have a positive value.

139	Cannot release active

140	Prompt cannot be MEMO

145	Cannot have more than one window object with the same name

146	Internal stack overflow

147	Internal stack underflow

149	Internal runtime's buffer overflow

150 - 199

150	Internal string buffer overflow

151	Attempt to free a bad memory block

152	Attempt to load a bad icode block

153	Macros cannot expand flow of control commands

154	Expanded macro variable does not return a valid identifier

156	Numbers are not allowed in the CURRENCY symbol

157	Illegal work area number or alias

158	Illegal value

159	UDF or procedure already exists

160	Unable to execute DOS

163	Data type mismatch.Expecting <type>

164	Out of range

167	Variable undefined

168	Not an array

169	Illegal Opcode

172	Maximum number of nested FOR NEXT loops exceeded

175	Maximum number of DO or UDF parameters exceeded

178	Alias not found

179	MEMO field not allowed here

180	ALIAS already in use

181	Processing would exceed maximum allowed string length

182	Procedure not found

185	Illegal file name

186	Beginning of table encountered

187	Error reading file

188	Unexpected type

189	Printer error

190	Memory variable already defined - cannot make PUBLIC

191	CONTINUE without previous LOCATE

192	Value out of range

193	Invalid subscript reference

196	Invalid printer redirection

197	Cannot execute this command when DESIGN is off

198	Feature not currently available

199	Restricted command: not allowed in this context

200 - 249

200	Command will never be reached

201	Command not functional in dBASE for Windows

202	Extra characters ignored at end of command

203	Program was previously compiled with SET COVERAGE OFF

206	Drive not ready: <drive>

207	UDF or PROCEDURE not found

209	Too many files open

210	Invalid directory

211	Invalid disk drive

212	Cannot redefine active menu

214	No such listbox

215	Window not active

217	Symbol table space exhausted. Increase to <n>

218	SET FIELDS space exhausted

219	No previous DO WHILE/SCAN/PRINTJOB/FOR to match this command

221	Too many nested DO/UDF

222	Maximum number of locked records exceeded

223	Sharing buffers are full

224	Error unlocking file

225	Unmatched #else

226	Unmatched #endif

227	Maximum #ifdef nesting exceeded

228	Expecting #endif

229	Preprocessor expansion too large

230	Include file not found

231	Table already open

232	Database already open

234	Operation not allowed in transaction

236	Operation not allowed on this table

237	Index is not open

239	IDAPI Error

240	Server Error

241	Database not opened

242	Invalid value for convert size (8-24)

243	Invalid file Handle

244	Idapi Not Initialized

245	Cannot UPDATE a table with itself

246	Invalid Catalog

247	Invalid password

248	Access denied

249	Can only change draft mode on page boundaries

250 - 299

250	Can only change page orientation on page boundaries

251	Already in printjob

252	Wrong version of IDAPI01.DLL

253	No print driver selected

254	No pads defined for

257	Attempting to call a method as a function

258	Method is not available on object

259	No Records Selected

260	Internal Exception Error

262	Form cannot be MDI

265	Resource not found

266	Cannot load print driver:

267	Cannot paste more than one file

268	Error pasting file:

269	Cannot Paste selection

270	Cannot Copy selection

271	Cannot Package file:

272	Cannot activate object.OLE server is busy

273	Cannot update linked object

274	Unknown error saving window contents

275	Cannot perform operation on static object

276	Error connecting to OLE server

277	Invalid command verb for OLE object

278	OLE object error

279	OLE BLOB field is corrupted

280	OLE BLOB field data is from an incompatible version

281	Attempt to access released object

282	Property is read only

283	Only 1 or 2 dimensional array is allowed in this operation

284	Report Engine Error

285	Property not found

286	Operation not allowed on read-only fields

287	Operation not allowed on read-only tables

289	Not member of Class or Base class

290	SUPER not allowed when THIS is undefined

291	Unable to open form

292	Unable to create control

293	No such form

294	The system registry does not contain an OLE server for a file

295	OLE: cannot create link

298	Constant is already #defined

299	Field must be an OLE field:

300 - 349

301	Position not in window

303	Parameter type '...' can only be used with CDECL calling convention

304	DLL does not support Multiple Instances:

305	Error loading DLL:

306	Extern:

307	Parent is not a REPORT

308	Parent is not a PAGETEMPLATE or BANDBODY

309	Error Saving VBX

310	BINARY field not allowed here

311	OLE field not allowed here

312	Popup too small

313	Error creating palette

314	OLE Error

315	Only 1 dimensional array is allowed in this operation

316	Incomplete link specification

317	Selected tables cannot be related

318	Too many symbols in this module

319	Cannot create directory:

320	Invalid table name

321	Invalid preprocessor identifier

322	RELEASE DLL: DLL not Loaded:

323	Invalid key label

324	Only allowed in function or procedure scope

325	Not a valid table

326	Port not configured for a printer

327	#includes nested too deeply

328	Index expressions not allowed for INTEGRITY rules

329	Related records still exist in alias

330	SET KEY active in alias

331	Relation using CONSTRAIN

332	No matching parent record

333	Operation not allowed across different databases or table types

334	Key already exists in parent

335	First class in .WFM file is not derived from FORM

336	Relation expression and active index expression must be the same

337	Record is in use by another

338	Memo file does not exist

339	Index file does not exist

340	Invalid file privileges

341	Form already open

342	Error reading from binary field

343	Must convert report before modifying

344	Class does not exist


dBASE for Windows Basics

dBASE for Windows is a complete database management system that is both a development environment and a collection of interactive tools for managing data.

dBASE for Windows moves the dBASE language and user interface into the event-driven, visual environment of Microsoft Windows, while retaining compatibility with previous versions of dBASE. You can work interactively with visual tools, such as menus and dialog boxes, or directly with the dBASE language.

Choose from the following topics to orient yourself to dBASE for Windows, to learn important underlying concepts, and to learn how to use tools that are available throughout the product.

Introduction to the Views and Tools

About Sessions

About the DBASEWIN.INI Initialization File

About SpeedFilters

File Extensions Supported in dBASE for Windows

How to Use Help in dBASE for Windows

Using the Interactive Tutors

Choose this topic if you are familiar with the dBASE IV Control Center and you want to use that knowledge to help you learn dBASE for Windows quickly:

Moving from the dBASE IV Control Center

Choose this topic for information on how to register your software and how to get technical support:

Software Registration and Technical Support


Basics: Introduction to the Views and Tools
Introduction to the Views and Tools

See Also

dBASE for Windows provides views and tools for organizing your work, working with the dBASE language, designing items, and displaying the results of what you design.

Choose from the following topics for more information:

About the View Model in the User Interface

About Design and Run Modes

Working with Design and Run Modes

About the System-Wide Views and Tools

Introduction to the dBASE Navigator

Introduction to the Catalog Window

Introduction to the Command Window

Introduction to the Expression Builder

Introduction to the Text Editors

About the Tool Button

About SpeedBars and SpeedMenus

About the Status Bar

About Properties Inspectors

About Object Inspectors

About Tabbed Dialog Boxes

About the File-Specific Views and Tools

About the Debugger

Basics: How the User Interface and the Language Are Related


See Also

Basics: About Sessions

Views and Tools - Contents


Basics: About the View Model in the User Interface
About the View Model in the User Interface

See Also

The dBASE for Windows user interface is structured around views. A view is the unique working environment for accomplishing related tasks. For example, there are different views for designing tables, queries, and forms.

Each view contains tools such as menus, dialog boxes, SpeedBars, and  SpeedMenus for accomplishing the tasks specific to the view.

When you switch from one view to the next, certain aspects of the working environment change. For example:

Menus, menu commands, and SpeedBar buttons appear or are removed, according to what is appropriate for the view.

Different windows, design surfaces, and other tools become available, according to what is appropriate for the view.

Different SpeedMenus become available, according to what is appropriate for the window or design surface.

For example, in this illustration, the Command window has focus, and you can see the Query Designer behind it:

	Menu SpeedBar Command window
In this illustration, focus has switched to the Query Designer:

	The menu is different. Some SpeedBar buttons    are different. The Query Designer now    has focus.


See Also

Basics: Introduction to the Views and Tools

Views and Tools - Contents


Basics: About Design and Run Modes
About Design and Run Modes

See Also

For several dBASE file types, you must design them to specify their features, then run them to see (or hear) and manipulate them. dBASE for Windows provides Design and Run modes to accommodate this. First you design the item (in Design mode), then you run it by switching to a different view, which is the Run mode for the item.

The basic dBASE file types that have Design and Run modes are shown below.

	Design	Run
Tables	Table Designer	Browse layout Columnar layout Form layout
Queries	Query Designer	(Same three views as for tables, above)
Forms	Form Designer	Form
Reports	Crystal Reports for dBASE	Reports
Labels	Crystal Reports for dBASE	Labels
Programs	Program Editor	Application (or anything else you can program in dBASE)
dBASE for Windows tables can include sounds and images. These objects also have Design and Run modes. The Design mode of a sound is a sound recorder, if you have one. The Run mode is the sound itself. The Design mode of an image is a drawing or painting program. The Run mode is the image displayed in the Image viewer.


See Also

Basics: Introduction to the Views and Tools

Views and Tools - Contents


Basics: Working with the Design and Run Modes
Working with Design and Run Modes

See Also

There are several ways to open designers, run files, and switch between Design and Run modes.

To design a file from the Navigator or a Catalog window, do one of the following:

Click an icon in the right pane of the window to select the file. Then choose the design command from the Navigator or Catalog menu. The wording of the command changes according to the type of file selected. For example:

File type	Navigator or Catalog menu command

Table 	New Table

Design Table Structure

Form 	New Form

Design Form

Right-click a file  icon, then choose the design command from the SpeedMenu. This command varies according to file type, as described above.

Click a file  icon to select it,  then click [image] on the SpeedBar.

Double-right-click a file icon.

To run a file from the Navigator or a Catalog window, do one of the following:

Click an icon in the right pane of the window to select the file. Then choose the run command from the Navigator or Catalog menu. The wording of the command changes according to the type of file selected. For example:

File type	Navigator or Catalog menu command

Table 	Edit Records

Add Records

Form 	Run Form

Right-click a file  icon, then choose the run command from the SpeedMenu. This command varies according to file type, as described above.

Click a file  icon to select it, then click [image] on the SpeedBar.

Double-left-click a file  icon.

To switch between Design and Run modes when a file is already open, do one of the following:

Choose a design or run command from the View menu. The wording of these commands changes according to the file type (as determined by the view in which you are working). For example,

From this view...	Choose this command to switch modes

Query Design	View|Query Results

Query Run	View|Query Design

Table Design	View|Table Records

Table Run	View|Table Structure

Click one of these buttons on the SpeedBar:

 	Switches to Design mode for the current item

 	Switches to Run mode for the current item


See Also

Basics: Introduction to the Views and Tools

Views and Tools - Contents


Basics: About the System-Wide Tools
About the System-Wide Tools

See Also

Some views and tools are provided for working with particular file types. Others are available for more global purposes, such as managing files and working with the language. Some tools are shared by different views for accomplishing the same or similar tasks. This provides consistency and predictablity throughout the product.

Choose from the following list for more information about the system-wide views and tools:

Introduction to the dBASE Navigator

Introduction to the Catalog Window

Introduction to the Command Window

Introduction to the Expression Builder

Introduction to the Text Editors

About the Tool Button

About SpeedBars and SpeedMenus

About the Status Bar

About Properties Inspectors

About Object Inspectors

About Tabbed Dialog Boxes


See Also

Basics: Introduction to the Views and Tools

Views and Tools - Contents


Basics: Introduction to the dBASE Navigator
Introduction to the dBASE Navigator

See Also

The dBASE Navigator is a window that organizes and displays files according to type and location (within subdirectories). Each file type is represented by a different icon, which makes it easier to see what kinds of files are available.

File types		Files in the current directory or path for the selected file type(s)
Use the Navigator to:

Display lists of files and details about them. You can display dBASE, Paradox, and SQL tables, and you can display SQL databases and Paradox aliases.

Open and run files.

Open designers and other tools for modifying files.

Change directories and the search path.

Mouse Operations in the Navigator

 Double-left-click a file  icon to run the file, for example to display a table or play a sound.

 Double-right-click a file  icon to design it, for example to design a query or lay out a form.

You can also drag a file icon to the Command window to run the file, and you can drag a file icon to a Catalog window to add the file to the catalog.


See Also

Basics: Introduction to the Views and Tools

Basics: Introduction to the Catalog Window

Views and Tools - Contents

Using the dBASE Navigator

Using the Command Window

Using the Catalog Window


Basics: Introduction to Catalog Windows
Introduction to the Catalog Window

See Also

A Catalog window is similar to the Navigator except that it shows the files referenced by a Catalog file. Catalogs provide a way for you to organize files apart from their organization within subdirectories.

The Catalog window can also show dependencies between files. For example, if a form is based on a query, the Catalog window shows a line linking the .WFM file and the .QBE file.

File types		Files in the current catalog file for the selected file type(s). You can also show dependencies among files.


See Also

Basics: Introduction to the Views and Tools

Basics: About the System-Wide Tools

Basics: Introduction to the dBASE Navigator

Views and Tools - Contents

Using the Catalog Window

Using the dBASE Navigator

Using the Command Window


Basics: Introduction to the Command Window
Introduction to the Command Window

See Also

The Command window is the counterpart of the dot prompt in previous versions of dBASE. You can type commands directly into the window and execute them immediately to see the results. The Command window also shows commands that execute when you perform actions through the user interface.

The Command window has two panes which can be placed side-by-side or one on top of the other:

Input pane: Type commands here (or see the commands issued by actions in the user-interface).		Results pane: See results of typed commands here.


See Also

Basics: Introduction to the Views and Tools

Basics: About the System-Wide Tools

Views and Tools - Contents

Using the Command Window


Basics: Introduction to the Expression Builder
Introduction to the Expression Builder

See Also	Language

The Expression Builder helps you construct a valid dBASE expression. It displays lists of constants, fields, functions, operators, and variables from which you can use to build the expression. The Expression Builder uses visual cues to guide you through the process. You can evaluate the expression at any time to check that it is valid and to show its current value.

Select expression elements from these lists		Type or paste expression elements in this window.
You can paste the expression from the Expression Builder into the Command window, into a program you are editing, or anywhere else that accepts an expression.

The Expression Builder is available for fields whenever an expression is allowed. In these cases, the Tool button [image] appears next to the entry field. You can also display it directly from the Command window or call it from within a program with the GETEXPR( ) function.


See Also

Basics: Introduction to the Views and Tools

Basics: About the System-Wide Tools

Views and Tools - Contents

Using the Expresssion Builder


Language

GETEXPR( )


Basics: Introduction to the Text Editors
Introduction to the Text Editors

See Also

Various forms of the Text Editor are available, depending on what you need to do. You can write and edit programs, text files, and memo fields in tables.

When you are working with program code, the Text Editor (called the Program Editor in this context) uses color to denote literal values and comments. You can also work with auto-indenting and .a variety of fonts.

Program Editor


See Also

Basics: Introduction to the Views and Tools

Basics: About the System-Wide Tools

Views and Tools - Contents

Editing Text


Basics: About the Tool Button
About the Tool Button

See Also

In some places in the .user interface, you can enter a value directly, or you can display a dialog box from which you can select a value (or otherwise construct or specify a value). In these places, a button is provided for displaying the dialog box that is appropriate for the context. The button is called the Tool button and looks like this:

For example, there are options in several dialog boxes that require an expression. You can type the expression directly in the entry field, or you can click [image] to display the Expression Builder, where you can construct the expression.

The Tool button is available for several properties when they appear in the Object Inspector. For example, you can click [image] when it appears next to the ColorNormal property to display the Choose Color dialog box.


See Also

Basics: Introduction to the Views and Tools

Basics: About the System-Wide Tools


Basics: About SpeedBars and SpeedMenus
About SpeedBars and SpeedMenus

See Also

The menu bar in each view contains menus with the commands you need to work with the items in the view. Some of these commands are also available on SpeedBars and SpeedMenus.

About SpeedBars

SpeedBars are located below the title bar of each view. A SpeedBar is composed of buttons that execute commands when clicked. These commands are equivalent to menu commands on the menu bar. SpeedBars are provided as a convenient way to execute frequently used commands.

When you pass the mouse pointer over a button on the SpeedBar, the status bar at the bottom of the screen displays a short description of the SpeedBar button.

About SpeedMenus

A SpeedMenu is a menu that is displayed when you right-click within most design surfaces or windows in a view. A SpeedMenu makes frequently used commands readily available while working in the window. The commands on a SpeedMenu are equivalent to commands on the menu bar for the view.


See Also

Basics: Introduction to the Views and Tools

Basics: About the System-Wide Tools


Basics: About the Status Bar
About the Status Bar

See Also

The status bar is a bar at the bottom of the screen that displays message and system information. For example, the current record number appears on the status bar when you browse a table.

The status bar also contains hints about items in the user interface. When you pass the mouse pointer over menu items and SpeedBar buttons, a short description of the item appears in the status bar.


See Also

Basics: Introduction to the Views and Tools

Basics: About the System-Wide Tools


Basics: About Properties Inspectors
About Properties Inspectors

See Also

Properties inspectors are dialog boxes where you can set the properties for the current view or window. For example, you can set default fonts for the Command window, set the scope of records to display in the Table Records window, and set the grid size on the Form Designer design surface.

In several cases, an inspector is a tabbed dialog box. For example, the inspector for the Table Records window looks like this:

Saving Settings

When you set the options in a Properties inspector and choose OK, the settings are permanent until you redisplay the inspector and reset the options. These settings are saved in the DBASEWIN.INI file, which stores dBASE configuration settings.

Displaying Inspectors

You can always display the Properties inspector for the current environment by choosing the name of the inspector from the Properties menu. The name on the menu is different for each context. For example, the menu item in the Table Records view is Properties|Table Records Window, and the name in the Query Designer view is Properties|Query Designer.

You can also display the Properties inspector by right-clicking a window to display a SpeedMenu. Choose the name of the inspector from the menu.

About the Desktop Properties Inspector

The Desktop Properties inspector sets global properties that affect the environment in all views. Choose Properties|Desktop in any view to display the Desktop Properties dialog box (inspector).

Most items in the Desktop Properties dialog box correspond to a SET command in the dBASE language.


See Also

Basics: Introduction to the Views and Tools

Basics: About the System-Wide Tools

Basics: About Object Inspectors

Views and Tools - Contents

Properties|Command Window

Properties|Desktop

Properties|Form Designer

Properties|Navigator

Properties|Procedure Editor

Properties|Query Designer

Properties|Selected File or Catalog Item

Properties|Table Records Window

Properties|Table Structure Window


Basics: About Object Inspectors
About Object Inspectors

See Also

An Object Inspector is a window that displays the properties, events, and methods for the current object.

The properties, events, and methods are displayed on separate tabbed pages. Click the tab at the bottom of the inspector to display the page whose name is on the tab. Or use the Tab key to give focus to the tab at the bottom of the page, and then use the Right or Left arrow keys to select a different page.

When you create a form in the Form Designer, use the Object Inspector interactively to view and change the values of properties and to link code blocks and methods to events.

You can also display an Object Inspector when you create an object with a DEFINE command or the NEW operator. Use the INSPECT( ) function to display the Object Inspector.

You can display more than one Object Inspector when you use the INSPECT( ) function, but you can display only one when you work in the Form Designer.


See Also

Basics: Introduction to the Views and Tools

Basics: About the System-Wide Tools

Basics: About Properties Inspectors

Views and Tools - Contents

Using the Form Designer - Overview

Object Inspector


Language

INSPECT( )


Basics: About Tabbed Dialog Boxes
About Tabbed Dialog Boxes

See Also

Some dialog boxes are divided into pages that group related options together. The pages in the dialog box are indicated by tabs along the bottom of the dialog box. For example, the Table Records Properties dialog box contains the tabs for Fields, Records, and Window:

Click a tab to display the page named by the tab. Or use the Tab key to give focus to the tab at the bottom of the page, and then use the Right or Left arrow keys to select a different page.


See Also

Basics: Introduction to the Views and Tools

Basics: About the System-Wide Tools

Views and Tools - Contents


Basics: About the File-Specific Views and Tools
About the File-Specific Views and Tools

See Also

dBASE for Windows provides unique views and tools for working with the different types of files. You can create, modify, and use tables, queries, forms, reports, labels, images, and sounds. (Special hardware is required to record sound.)

Each file type has a Design and Run mode. See About Design and Run Modes for information about the different modes for each file type.

See Views and Tools - Contents for a list of all the Help topics about these views and tools.


See Also

Basics: Introduction to the Views and Tools

Basics: About the System-Wide Tools


Basics: The dBASE for Windows Debugger
About the Debugger

See Also	Language

dBASE for Windows includes a complete debugger. Use the Debugger to:

Control program execution

Watch and inspect the values of variables, fields, arrays, objects and expressions

View the subroutines the main program calls and see when they are called

Stop program execution at any point

You can run the Debugger from within dBASE, or you can launch it as a separate application from Windows.


See Also

dBASE for Windows Debugger


Language

DEBUG


Basics: How the User Interface and the Language Are Related
How the User Interface and the Language Are Related

See Also

Watching Commands in the Command Window

In most cases, when you initiate actions with menus, dialog boxes, SpeedBar buttons, or other interactive tools, you are executing dBASE commands. If the Command window is open, you can see the commands appear there whenever you initiate an action.

You can use this feature as an unobtrusive tutor to help you learn the dBASE language and to understand the relationship between the interactive tools and the language.

Two-Way Tools: About Code Generated from dBASE Designers

You can use the Query Designer, Form Designer, and Menu Designer to create queries, forms, and menus with little or no programming. When you save your design from one of these designers, it is saved as dBASE code in a program file.

You can edit and modify this code directly by editing it in the program file. Then you can open the file again in the appropriate designer and continue to use the interactive tools to continue designing the item visually.

After designing a query, form, or menu, you run the file to see the results. You can run the program file from within the designer (by clicking [image], for example). Or you can use the DO command to run the program from the Command window or from within another program.

This feature is called Two-Way Tools, because you can create, modify, and save your work both in a designer and using the language, with complete compatibility between them.


See Also

Basics: Introduction to the Views and Tools

Basics: About Design and Run Modes

Basics: About Sessions

Basics: Introduction to the Command Window

Using the Command Window

Designing Queries

About Form (.WFM) Files

Using the Form Designer - Overview

Language Reference


Basics: About Sessions
About Sessions

See Also	Language

Sessions is an environment setting that determines how dBASE makes items available to certain operations and how certain settings apply to those items. Sessions affect how you can work with multiple open files and with the same file open multiple times. Within a session, you can change environment settings, define a transaction, open tables and indexes, and navigate records, all without affecting the operation of other sessions open at the same time.

When Sessions is on (the default), dBASE behavior follows standard Windows conventions. When Sessions is off, dBASE behaves more like previous versions of dBASE.

To turn Sessions on or off,

1.	Choose Properties|Desktop to display the Desktop Properties dialog box.

2.	Click the Files tab to display the Files page.

3.	Click the Sessions check box to toggle the setting on or off. When the check box is checked, Sessions is on; when it is unchecked, Session is off.

About Sessions and SET Environment Variables

Certain SET environment variables affect the current session only. See the reference topic for CREATE SESSION for a list of SET commands that affect only the current session.

About Sessions and Memory Variables

Sessions do not affect memory variables. A public memory variable maintains its value across sessions. CLEAR MEMORY clears all memory variables in all sessions.

About Sessions and the Command Window

When Sessions is on, the Command window is always in its own session.

Whether Sessions is on or off, you can see commands echoed to the Command window from actions performed on items in other windows. But when Sessions is on, commands typed in the Command window cannot affect items in windows that belong to other sessions. For example, when Sessions is on, you cannot open a table from the Navigator and then type commands in the Command window to work with that table. But if you open the table with the USE command in the Command window, you can continue to use the Command window to type other commands that will affect the table.

About Sessions and Tables

When Sessions is on, and a table is open in multiple sessions, the table is treated the same as if it were opened by multiple users in a multiuser environment. That is, if one session locks a table or record, another session cannot obtain a lock on the same table or record until the first lock is released. When a table is updated in one session, it is not updated in another session until that session becomes current again.

When Sessions is on and a table is displayed in a window, closing the window also closes the table. If the table appears in more than one window, the table is closed when the last window is closed. When Sessions is off, closing a window never closes the table. You must close the table explicitly, for example by choosing Table|Table Utilities|Close Table.

When Sessions is on, opening a table through the user interface (for example by double-clicking its icon in the Navigator) always opens it in its own session.

About Sessions and Work Areas

Each session has its own set of work areas. This allows you to open files multiple times in multiple sessions without work area conflicts. For example, the first table in a query always uses work area 1. With Sessions on, you can run the query multiple times (using different tables, for example) and each session opens the first table in a different work area 1. This also allows you to run programs and forms without worrying about conflicts with other tables open in work areas that are specified in the program or form.

When Sessions is off, there is only a single set of work areas.

About Sessions and Queries

When you start to create a query with Sessions on, you are prompted to choose a table to query, even if a table is already open. That is because the query is in its own session and therefore does not have access to the table open in a different session. If you create a query with Sessions off, and any tables are open, you are not prompted to choose a table. The table skeletons for any open tables appear on the Query Designer design surface.

When Sessions is on, opening a query through the user interface (for example by double-clicking its icon in the Navigator) always opens it in its own session.

About Sessions and Forms

The Form Designer does not automatically create a session for a form. However, if you create a form that uses a table or tables, it is a good idea to add a CREATE SESSION command to the Header section of the form's program code (in the .WFM file). When the form exists in its own session, any actions performed on the table in another session, such as reindexing, do not affect the table used with the form.

About Sessions and Reports and Labels

Reports and labels always have their own unique sessions. This allows you to run multiple reports simultaneously.


See Also

Basics: Introduction to the Views and Tools


Language

CREATE SESSION


Basics: About the DBASEWIN.INI Initialization File
About the DBASEWIN.INI Initialization File

See Also

The dBASE for Windows initialization file is called DBASEWIN.INI. This file stores many of the properties of dBASE and its components, as well as settings for user interface objects such as windows, palettes, and dialog boxes.

Many of the global settings that affect the dBASE working environment are determined by the choices you make in the Desktop Properties dialog box. Those settings are stored in DBASEWIN.INI.

DBASEWIN.INI is constantly updated as you work in dBASE. Its state when you exit the program determines many of the settings of the dBASE user interface the next time you start the program.

Although this file is a text file, it is strongly recommended that you not edit it. For more information about this file, see Getting Started and the User's Guide.


See Also

Basics: About Properties Inspectors

Properties|Desktop


About SpeedFilters

See Also	Language

dBASE uses a filter optimization process called SpeedFilters to increase access speed when selecting a subset of records from a table or tables. Speed is enhanced for both "global" filter conditions (SET FILTER TO) and "local" filter conditions (a FOR clause). SpeedFilter optimization occurs automatically when certain conditions are met, as described below.

In cases where the filter can be fully optimized, you will see the benefits immediately. In other cases, the SpeedFilter is constructed the first time a command is processed, so the benefit occurs the second and subsequent times you work with the data (see the examples below).

Optimum performance occurs when the data is indexed using an expression that corresponds to the filter condition. Whether or not the data is indexed, the search speed increases the more you work with the data, because dBASE retains the results of previous operations.

The filter optimization works with operations involving related tables as well as single tables.

Optimizable Commands

Filter optimization works for any command that contains an expression with a FOR clause and with a SCOPE clause of ALL (the default) or NEXT.  When you use these clauses, the following commands execute more quickly:

AVERAGE	LIST

CALCULATE	LOCATE

CHANGE	RECALL

COPY TO	REPLACE

COPY TO ARRAY	REPORT

COUNT	SCAN

DELETE	SORT TO

EDIT	SUM

EXPORT TO	TOTAL ON

LABEL FORM

Full Optimization

The following conditions are examples of full optimization:

The table is in natural order and the filter condition corresponds to an open index or order.

The table is indexed and the filter condition corresponds to the master index.

The table is indexed on a complex character expression (such as firstname+lastname+address), and the filter condition corresponds to a subset of the expression (for example, firstname or firstname+lastname).

Optimization Examples

The following examples list expressions within different types of optimization.

Full Optimization

INDEX ON State TAG State
SET FILTER TO State="CA" .OR. State="TN"

INDEX ON State+Zip TAG Statezip
SET FILTER TO State+Zip="CA95059"
SET FILTER TO State="WA"

INDEX ON State TAG State
SET FILTER TO .NOT. State="NY"

INDEX ON Lastname TAG Lastname
INDEX ON Year(Date_hired) TAG Year_hired
LIST FOR Year(Date_hired)=1993 .AND. Lastname="Smith"

INDEX ON STR(OrderNo,6)+STR(StockNo,6) TAG LineKey
LIST FOR STR(OrderNo,6)="10001"

Partial the first time, Full subsequent times

SET FILTER TO State="CA"  &&  no index

SET FILTER TO State="CA" .OR. State="TN"   && no index

INDEX ON Lastname TAG Lastname
SET ORDER TO Firstname
SET FILTER TO Lastname="SMITH"

Partial the first time, Full subsequent times (Country is not indexed)

INDEX ON Lastname TAG Lastname
LIST FOR Country="USA" .AND. Lastname="Smith"

Partial for COUNT (it is the first operation); Full for SUM (uses the result of the previous operation)

SET FILTER TO "Fred" $ Lastname
COUNT
SUM

None

SET FILTER TO FOUND(2)

Any function

Multiuser Issues

Filter optimization is effective in a multiuser environment. However, if another user modifies a shared table while your application has an active filter on the same table, the filter condition must be reprocessed, and optimization is lost. In a busy multiuser environment, the delays can be significant. One way to avoid delays is to gain exclusive access to the table by using SET EXCLUSIVE ON or  FLOCK().


In many cases, when you select a set of records from a table or tables, dBASE automatically uses a filter optimization process that increases processing speed. This process uses temporary filters, called SpeedFilters, that speed up the search under certain conditions, described below.


See Also

About Tables


Language

FLOCK()

INDEX

SET FILTER

SET EXCLUSIVE


File Extensions Supported in dBASE for Windows

The following table is an alphabetical list of the file extensions supported in dBASE for Windows.

Note the following about file extensions:

Although the standard dBASE table file extension is .DBF, it is not required. However, the table file extension cannot end in X or T, which are reserved for production index files and memo files. If you create a table called TABLE.ABC that includes an index and a memo field, dBASE automatically creates an index file called TABLE.ABX and a memo file called TABLE.ABT.

Do not use the letter O as the last character in the file extension of any file that can be compiled. (Any text file that contains dBASE program code can be compiled.) When you compile, dBASE automatically replaces the last character of the source file extension with an O. For example, the compiled version of the program file PROGRAM.PRG is called PROGRAM.PRO. If you use an O as the last character in the file extension of the source file, the compilation process will overwrite the source file.

Extension	Description

.BAK	Command or procedure backup file

.BAT	DOS batch file

.BFM	Binary form file for VBX controls

.BMP	Windows bitmap file

.CAT	Catalog file

.CC	dBASE for Windows custom control file

.CO	Compiled dBASE for Windows custom control (.CC) file

.COM	DOS command file

.COV	File containing program coverage information

.CRR	Crystal Reports for dBASE registration file

.CVT	dBASE table with change detection field

.DB	Paradox table file

.DBF	dBASE table file

.DBK	dBASE table backup file

.DBT	dBASE table memo file

.DLL	Windows dynamic-link library file

.EXE	Executable program file

.FMO	Compiled format (.FMT) file

.FMT	dBASE III+/IV format files; can be converted to .WFM with dBASE Component Builder

.FNF	Expression Builder database file

.FR3	Renamed old dBASE III PLUS report form (.FRM) file

.FRG	dBASE IV generated report form file; from .FRM file

.FRM	dBASE III PLUS report form file; can be converted to .RPT with dBASE Component Builder. For dBASE IV, run the corresponding .FRG file.

.FRO	Compiled report form (.FRG) file

.GRP	Windows group file

.H	Header (Include) file

.HDX	Help keyword index file

.HLP	Windows-format Help file

.ICO	Windows icon file

.INI	Initialization file

.LB3	Renamed old dBASE III PLUS label form (.LBL) file

.LBG	dBASE IV generated label form file; from .LBL file

.LBL	dBASE III PLUS label form file; can be converted to .RPL with dBASE Component Builder. For dBASE IV, run the corresponding .LBG file.

.LBO	Compiled label form (.LBG) file

.MB	Paradox BLOB/memo file

.MBK	Multiple index backup file

.MDX	Multiple index file

.MEM	Memory file

.MNO	Compiled menu (.MNU) file

.MNU	dBASE for Windows menu file

.NDX	Single index file

.PCX	PC Paintbrush format bit image file

.PIF	Windows program information file for DOS applications

.PRF	Print form file

.PRG	dBASE program file

.PRO	Compiled program (.PRG) file

.PRT	Printer output file

.PX	Paradox primary key file

.QBE	dBASE for Windows, dBASE IV query file

.QBO	Compiled query (.QBE ) file

.QRY	dBASE III PLUS query/filter file

.RPC	Crystal Reports for dBASE cross-tab report file

.RPL	Crystal Reports for dBASE label file

.RPT	Crystal Reports for dBASE report file

.SCN	Image of the results pane of the Command window saved to a file

.TBK	dBASE table memo backup file

.TXT	Text file

.UPD	QBE update query file

.VAL	Paradox validity check file

.VBX	VBX custom control file

.VUE	dBASE III+/IV query/view files

.WAV	Sound file

.WB1	Quattro Pro for Windows notebook file

.WFK	dBASE for Windows form backup file

.WFM	dBASE for Windows form file

.WFO	Compiled dBASE for Windows form (.WFM) file

.WIN	dBASE IV window save file

.WK1	Lotus 1-2-3 Version 2 file

.Xnn	Secondary single-field index for a Paradox table, numbered

.Ynn	Secondary single-field index for a Paradox table, numbered

.XGn	Secondary multiple-field index for a Paradox table, numbered

.YGn	Secondary multiple-field index for a Paradox table, numbered


How to Use Help in dBASE for Windows

See Also

You can get online help in dBASE for Windows in several ways. You can:

Display context-sensitive help for the current item, such as a menu, dialog box, or window. You can also display context-sensitive help for language elements in the Expression Builder, for classes of controls in the Form Designer, and for properties, events, and methods in Object Inspectors.

Navigate through the Help topics, using the structure of the Help system as a guide for finding related informaton.

Search for Help topics using the Search dialog box.

Use the HELP command in the Command window.

Choose from the following topics for instructions:

Displaying Context-Sensitive Help for User Interface Items

Displaying Help for Language Elements in Lists

Displaying Help for Controls in a Form Design

Navigating Through dBASE for Windows Help

Displaying Related Help Topics

Searching for Help Topics

Displaying Help Using the HELP command

Copying Syntax and Examples from Help


See Also

Getting Online Help in the Expression Builder

Getting Context-Sensitive Online Help in the Form Designer


Displaying Context-Sensitive Help for User Interface Items

See Also

This topic describes how to display Help topics for the interactive controls in the dBASE for Windows user interface.

To display context-sensitive Help for a dialog box,

1.	Display the dialog box.

2.	Press F1 or click the Help button in the dialog box.

For tabbed dialog boxes, click the tab of the page for which you want help, then press F1 or click the Help button.

To display context-sensitive Help for a menu,

1.	Click the name of the menu on the menu bar to open the menu.

2.	Press Escape. The menu closes, but the menu name remains selected. You can press the Right and Left arrow keys to select other menu names on the menu bar.

3.	Press F1 to display Help for the menu. This Help topic usually just lists the menu items and provides jumps to their Help topics.

To display context-sensitive Help for a menu item,

1.	Select a menu from the menu bar or display a SpeedMenu, in one of the following ways:

Click the name of a menu on the menu bar to open the menu.

Right-click in a window to display the SpeedMenu for the window.

2.	Press the Down arrow key until the menu item is selected.

3.	Press F1 to display Help for the menu item. If choosing this menu item displays a dialog box, the Help topic includes Help for that dialog box (or provides a jump to help for the dialog box).

An alternative way to select Help for a menu item is as follows:

1.	Click to display a menu from the menu bar or right-click to display a SpeedMenu (as described in step 1, above) and drag the mouse pointer to the item you want. Do not release the mouse button.

2.	Press F1 to display Help for the menu item.

To display context-sensitive Help for a window or a design surface,

1.	Select the window. For example, click the Command window or the Query Designer design surface.

2.	Press F1 to display Help for the menu item.


See Also

How to Use Help in dBASE for Windows

Getting Online Help in the Expression Builder

Getting Context-Sensitive Online Help in the Form Designer


Displaying Context-Sensitive Language Reference Help

See Also

The Expression Builder and Object Inspectors provide lists of language elements. In the Expression Builder, you can choose from these lists to construct an expression. In an Object Inspector, you can review, edit, and use properties, events, and methods.

Display reference Help topics for these language elements by selecting the item and pressing F1. The topic that is displayed is complete reference information for the item from the dBASE Language Reference.

Expression Builder	Select a language element from this list, and press F1 to display the Language Reference topic.
Object Inspector		Select a property, event, or method from the appropriate page, and press F1 to display the Language Reference topic.


See Also

How to Use Help in dBASE for Windows

Getting Online Help in the Expression Builder

Getting Context-Sensitive Online Help in the Form Designer


Displaying Help for Controls in a Form Design

See Also

One of the things you do when creating a form in the Form Designer is to place controls on the design surface. A control is defined by a class, and all the standard dBASE controls are defined by classes in the dBASE language.

To display the Help topic in the Form Designer for a control's class,

1.	Place a control on the design surface.

2.	If the control is not already selected, select it by clicking it.

2.	Press F1 to display Help for the class that defines the selected control.


See Also

How to Use Help in dBASE for Windows

Getting Online Help in the Expression Builder

Getting Context-Sensitive Online Help in the Form Designer


Navigating Through dBASE for Windows Help

See Also

dBASE for Windows Help is organized in a hierarchy, descending from the main Help Contents screen.

Using the Contents Screen

The Contents screen lists the main areas of Help. Click one of these items to display another topic that displays further choices for that area.

Display the Contents from within the main product by choosing Help|Contents or by pressing Shift+F1.

Display the Contents from within any Help topic by pressing the Contents button below the menu bar.

Using the Signposts

Every main area in the Help system is identified by an icon. These icons appear in the main Contents topic and in the Views and Tools contents topic (which is one level below the main Contents). They also appear next to the title in most topics in that area of Help, serving as "signposts" to show where you are in the Help system.

For example, this icon identifies the Debugger:

It appears on the Contents screen, where you can click it to display the main contents for the Debugger. It also appears next to the title for most Debbugger topics.

When you are looking at a topic, and a signpost appears in the title, you can click it to return to the main contents for that area of Help. For example, if you are looking at the topic "Setting Breakpoints," and you click the Debugger signpost in the title, the main contents for the Debugger Help topics appears.

Signposts do not appear on the Help topics for menus, menu items, or dialog boxes (because these topics can appear in many contexts). They also do not appear on Language Reference topics.

Using the Standard Windows Help Navigation Controls

Windows Help has a standard set of controls for navigating. See How to Use Help for general information about using Windows Help. Click the Back button to return to this topic.


See Also

How to Use Help in dBASE for Windows

dBASE for Windows Help Contents

Views and Tools - Contents


Displaying Related Help Topics

See Also

Beneath the title of nearly every Help topic, above the line that separates the title from the body of the topic, is one or more underlined items. For example, the one in this topic says "See Also."

You can click these items to display pop-up lists of related items, display a pop-up window with other information about the current topic, or jump directly to a related topic.

The following paragraphs describe the different items that can appear in the non-scrolling region.

In User Interface Help Topics

See Also	Displays a pop-up list of related topics dealing with other user-interface items, tasks, and conceptual or overview information.

Language	Displays a pop-up list of dBASE language elements related to the current topic.

In Language Help Topics

See Also	Displays a pop-up list of dBASE language elements related to the current one.

Example	Displays a window containing examples that use the language element described in the current topic.

Portability	Displays a pop-up list with information about the compatibility of the current item with dBASE III PLUS and dBASE IV.

(Category name)	Jumps you to the overview topic for the category of the language to which the current language element belongs.

This item includes names such as Fields and Records, Disk and File Utilities, and Colors and Fonts.

Forms	Displays a pop-up list of Help topics about working with forms.

This item appears in Help topics about classes, properties, event properties, and methods.

Other

This non-scrolling region beneath the title can also contain other items, in special circumstances. For example, the categorical list of language elements contains an item for displaying the alphbetical list, and the alphabetical list contains an item for displaying the categorical list.


See Also

How to Use Help in dBASE for Windows


Searching for Help Topics

See Also

Use the standard dBASE for Windows Search dialog box to search for topics in dBASE for Windows Help.

To display the Search dialog box from dBASE for Windows,

Choose Help|Search.

To display the Search dialog box from within Help,

Click the Search button.

See How to Use Help for general information about using Windows Help. Click the Back button to return to this topic.


See Also

How to Use Help in dBASE for Windows


Displaying Help Using the HELP Command

See Also	Language

The HELP command searches for Help topics using the same keywords that appear in the top box in the Help Search dialog box. These keywords serve as the index to the Help system.

To search for a topic using the HELP command,

In the Command window, type HELP followed by the word or words to identify the help topic.

This command is especially useful when you are working in the Command window and you want help on a command or other language element. For example, type HELP DEFINE WINDOW for the reference topic on the DEFINE WINDOW command.

If the word or words you type do not exactly match a keyword for a topic, the Search dialog box is displayed, with the topic highlighted whose identifying keyword is closest to the one(s) you typed. The Search dialog box is also displayed if a keyword is used by more than one topic. All the topics that use the keyword appear in the list at the bottom of the dialog box.

Note: Display the Search dialog box by choosing Help|Search from the dBASE for Windows menu or by clicking the Search button in a Help topic.


See Also

How to Use Help in dBASE for Windows


Language

HELP


Copying Syntax and Examples from Help

See Also

To paste syntax or code examples from the Help window to the Text Editor or Command window,

1.	Display the Help topic containing the syntax or code example.

2.	Choose Edit|Copy or click the Copy button. A dialog box appears.

3.	Select the text you want to copy using the mouse or keyboard.

4.	Click the Copy button or press Alt+C.

5.	Return to the Text Editor or Command window, and position the insertion point in the correct location.

6.	Choose Edit|Paste.


See Also

How to Use Help in dBASE for Windows


Using the Interactive Tutors

See Also

Interactive Tutors teach you how to use dBASE for Windows while working with real data to accomplish real tasks. Tutors walk you through tasks, step by step. You can use your own data, or you can use sample data provided by the tutors.

To display a list of tutors and to choose a tutor,

1.	Choose Help|Interactive Tutors, or click [image] on the SpeedBar. The main tutor list appears:

Subject areas		List of tutors for the selected subject area
2.	Click a subject area on the left side of the screen. A list of tutors related to that subject area appears on the right side.

3.	Click the button next to the tutor you want, listed on the right side. The first window of the lesson appears.

Navigating Through the Tutors

Click the buttons at the bottom of the window to navigate through the Tutors:

	Displays the next window in the lesson.
	Displays the previous window in the lesson.
	Cancels the current lesson and redisplays the main tutor list.
When you complete a tutor, a check mark appears beside that tutor in the list. To specify whether to save or erase the check marks, click the Options button at the bottom of the main tutor list to display the Options dialog box.


See Also

How to Use Help in dBASE for Windows


Software Registration and Technical Support

The Borland Assist program offers a range of technical support plans to fit the different needs of individuals, consultants, large corporations, and developers. To recieve help with this product, send in the registration card and select the Borland Assist plan which best suits your needs. North American customers can register by phone 24 hours a day by calling 1-800-845-0147. For additional details on these and other Borland services, see the Borland Assist Support and Services Guide included with this product.


Interactive Tutors - Main Tutor List

See Also

The main tutor list divides the tutors into groups by subject area. These subject areas are listed on the left side of the window. Titles pertaining to the selected topic appear on the right side.

Subject areas		List of tutors for the selected subject area
To start an Interactive Tutor,

1.	Click a subject area on the left side of the screen. A list of tutors appears on the right side.

2.	Click the button next to the tutor you want. The first window of the tutor appears.

Navigating Through the Tutors

Click the buttons at the bottom of the window to navigate through the Tutors:

	Displays the next window in the lesson.
	Displays the previous window in the lesson.
	Cancels the current lesson and redisplays the main tutor list.
Main Tutor List Buttons

Options

When you complete a tutor, a check mark appears on the button for that lesson on the main tutor list. Click the Options button to display a dialog box where you can set options that determine when the check marks are saved or removed.

The options in the dialog box are listed below.

Save main tutor list Checkmarks

Check this option to save the check marks when you exit dBASE for Windows.

Clear main tutor list Checkmarks

Check this option to clear the check marks when you exit dBASE for Windows.

Clear current Checkmarks

Check this option to clear the check marks immediately.

Quit

Click this button to close the Interactive Tutors


See Also

How to Use Help in dBASE for Windows


Glossary

A

active window

alias (table)

animate

ANSI

append

application

application window

argument

array

array element

ascending order

ASCII

automem variables

B

binary field

blank

bookmark

breakpoint

browse control

Browse layout

C

calculated field

calculated field skeleton

catalog

Catalog window

character data

check box

child table

class

client

Clipboard

codeblock

code page

collision

Columnar layout

combo box

command

Command window

comparison operator

complex index

composite key

concatenation

condition

Conditions box

constant

containership

constructor

Control-menu box

controls

coverage analysis

coverage file

D

database

database alias

data type

DBASEWIN.INI file

DDE

deadlock

delimiter

derivation

descending order

design

Design mode

design surface

Desktop

dialog box

DLL

dot operator

E

editor control

encapsulation

entry field

event

event handler

exclusive use

expression

Expression Builder

F

field

field name

field type

file association

file-name skeleton

file server

filter

filter condition field

flow-of-control commands

focus

font

form

Form layout

function

function keys

function pointer

G

global breakpoint

global variable

H

handles

header file

I - J

IBM extended codes

IDAPI.CFG

IDAPI Configuration Utility

import

index

index tag

inheritance

input pane

insert

inspect

inspector

Inspect window

instance

integrity

internal language driver name

K

key expression

key field

keyword

L

language driver

library file

link

linking field

list box

local variable

lock

logical data

logical operator

loops

lvalue

M

many-to-many relation

master index

member

memo field

memory variable

MDI (Multiple Document Interface)

MDI form

.MDX index file

menu

menu bar

message

method

mnemonic key

modal window

modeless window

module

Multiple Document Interface (MDI)

N

natural order

Navigator

.NDX index file

network control file

O

object

Object Inspector

Object Linking and Embedding (OLE)

one-to-many relation

one-to-one relation

operator

order box

P

pack

parameter

parent table

pass count

pixel

polymorphism

precedence

primary index

private variable

procedure

production index

program file

properties

public variable

pushbutton

Q

query

Query Results window

R

radio button

raster operation

recall

record

record lock

record number

record pointer

relation

relational database

relational operator

report

reserved words

results pane

rollback

run

Run mode

run-time error

S

scope (memory variables)

scope (records)

server

session

skeleton (file)

skeleton (table or view)

sort order

soundex

source

SpeedBar

SpeedMenu

spin box

SQL

statement

static variable

step over

streaming output

structure

Structured Query Language (SQL)

subclass

subroutine

substring

superclass

syntax

syntax error

system memory variable

T

tabbed dialog box

tabbing order

table

table lock

Table Records Window

table type

Text Editor

trace

transaction

U

UDF

unique index

user-defined function

V

variable

VBX control

view (query)

view (user interface)

W

watch

watchpoint

While condition

wildcard

Windows API

work area

X - Z

zap

z-order


active window, definition
active window

The window that has focus. Multiple windows can be open at one time, but only one window has focus at a given time.


alias (of table), definition
alias

An alternate name of 1 to 30 characters for an open table. Aliases make source code more readable by substituting meaningful names for cryptic file names or work area numbers and letters. You can use the alias name in place of the actual name when referring to a table.


animate, definition
animate

Animating is a debugging technique that executes source lines in a program slowly. In the Debugger, animating executes a line, displays the result, then executes the next line, and so on. Animating displays program flow and helps you locate bugs.


ANSI, definition
ANSI

American National Standards Institute. The ANSI character set is a sequence of eight-bit codes that defines 256 standard letters, numbers, and symbols. The Windows environment uses the ANSI character set.


append, definition
append

The process of adding a record to the end of a table.


application, definition
application

A set of programs and other source code files that work together to perform tasks. In dBASE for Windows, you use the Form Designer to create the forms that make up an application.


application window, definition
application window

The main window that appears when an application is launched. The application menu bar and status bar are part of the application window. Application windows can contain other windows. For example, the dBASE for Windows application window contains the Navigator and Command windows.


argument, definition
argument

The part of a command line that you supply, such as a memory variable or a field name. Arguments are presented in command line syntax as a word or sequence of words enclosed in angle brackets, such as <scope>.


array, definition
array

An object that consists of multiple elements in which data can be stored. Multi-dimensional arrays are tables of values stored in memory. Items in an array are designated by subscripts enclosed in square brackets. For example, ar[1] and ar[2] are the first two items of an array named ar.


array element, definition
array element

An individual item in an array. Elements can be referred to by the element subscript or the element number.


ascending order, definition
ascending order

An indexing and sort order that goes from lowest to highest for numbers (1 through 10, for example), from A to Z for characters, and from earliest to latest for dates. The default order is ascending.


ASCII, definition
ASCII

American Standard Code for Information Interchange. The ASCII character set is a sequence of seven-bit codes that defines 128 standard letters, numbers, and symbols. The IBM PC extends this code to eight bits (ANSI) to include some special graphic characters. Windows products use the ANSI character set.


automem variable, definition
automem variables

Memory variables that have the same names as the fields in a table and that temporarily store the contents of the current record. dBASE for Windows provides several commands, such as STORE AUTOMEM, for working with automem variables.


binary field, definition
binary field

A field type that contains data stored in binary format, such as bitmap images or sounds. You can store any binary data in binary fields, and you can also add user-defined binary formats.


blank, definition
blank

The state of a field, memory variable, or expression that has an empty value. Each data type has its own blank value. For instance, false is a blank value for logical data, and zero is a blank value for numeric data.


bookmark, definition
bookmark

A value representing a specific row in a specific table. You place bookmarks with BOOKMARK( ) and return to that position by specifying the bookmark value with other commands, such as GOTO. Bookmarks are especially useful for Paradox and SQL tables, which do not have record numbers.


breakpoint, definition
breakpoint

A specified location in a program where execution suspends. Setting breakpoints is a debugging technique. In the Debugger, you set a breakpoint at a specific location, and (optionally) specify a condition that, when met, suspends execution of the program and highlights the line that caused the break. Breakpoints can help locate bugs by identifying the point at which a value is incorrect.


browse control, definition
browse control

A control for viewing and editing records in a table. Data is presented in one of three layouts: Tabular, Form, or Columnar. When a browse control is linked to a table, the user can display and change the contents of the table when the form is run.


Browse layout, definition
Browse layout

A display mode in a browse object (or the Table Records window) where multiple records are arranged in a grid of rows (records) and columns (fields).


calculated field, definition
calculated field

A user-defined field based on a specified expression. Typically, calculated fields combine or perform calculations on fields in a table. LASTNAME+FIRSTNAME, and SUBTOTAL+TAX, are examples of expressions that define calculated fields.


calculated field skeleton, definition
calculated field skeleton

A template in the Query Designer for creating a calculated field.


catalog, definition
catalog

A file (with a .CAT extension) containing a list of files that you specify. Use catalogs to group related files together, such as those for a particular project or job. The Catalog window displays the files listed in a given catalog.


Catalog window, definition
Catalog window

A window that represents a catalog, which is a group of related files. The Catalog window shows associations, or dependencies, between files. In every other way, it works like the Navigator window.


character data, definition
character data

Data consisting of letters, numbers, punctuation marks, and any other symbols, including spaces. dBASE treats character data as strings of symbols; consequently, character fields or memory variables are often called "strings" or "string data."


check box, definition
check box

A control that offers two choices, such as yes or no, on or off, and true or false. Check boxes are sometimes referred to as toggles.


child table, definition
child table

One of two tables in a relation. When two tables are related, the table you link to is the child table, and the table you create the link from is the parent table. The key field (the field in the child table that you use for the link) must be indexed. In most parent-child relations there are no duplications of key field values in the parent table, while there might be many such duplications in the child table.


class, definition
class

A specification, or template, for creating instances of a particular object. Form and Entryfield are examples of standard classes that dBASE provides. You can declare your own classes with the CLASS...ENDCLASS command.


client, definition
client

A Windows application that initiates DDE links and requests information from a DDE server application. A dBASE application can be a client, a server, or both. dBASE for Windows provides several commands and functions for creating and maintaining DDE client and server applications.

The word client also refers to a workstation attached to a file server.


Clipboard, definition
Clipboard

A temporary area used by Windows applications to copy and paste information from one location to another.


codeblock, definition
codeblock

A data type for storing small nameless groups of commands or expressions. Codeblocks let you work with program code as if it were data; you can assign codeblocks to memory variables or properties of objects. A codeblock is delimited by braces ({ }).


code page, definition
code page

The set of characters available to DOS. The code page determines which characters are used by non-Windows applications running in a window, and affects file names that use extended characters.


collision, definition
collision

An error condition that occurs when two users attempt to change the same data at the same time in a multiuser environment. Collisions can be avoided by placing locks on data and displaying error messages when a user tries to change locked data.


Columnar layout, definition
Columnar layout

A display mode in a browse object (or the Table Records window) where one record at a time is displayed, with the fields arranged vertically. The field names are displayed on the left and the data is displayed on the right.


combo box, definition
combo box

A control that lets users select a value from a list by entering initial characters in a text box or by selecting the value directly from the list. A list box is similar to a combo box; however, a list box does not have a text box for entering characters.


command, definition
command

A verb that tells dBASE to perform an action. USE, SET DEFAULT, and COMPILE are examples of commands.


Command window, definition
Command window

A window in which you can enter and execute commands. The Command window consists of an input pane (for entering commands) and a results pane (to view the results).


comparison operator, definition
comparison operator

An operator such as =, >, or < that compares two values. Expressions that use comparison operators return logical values, true (.T.) or false (.F.).


complex index, definition
complex index

An index based on an expression containing two or more key fields or an expression that uses dBASE functions and operators.


composite key, definition
composite key

A Paradox index that uses two or more key fields.


concatenation, definition
concatenation

The joining of two or more strings to form a single string. The concatenation operators are a plus (+) sign and a minus sign (-).


condition, definition
condition

An expression that defines the conditions that records must meet to be processed by subsequent dBASE commands.


Conditions box, definition
Conditions box

A component of the Query Designer for specifying conditions that records must meet to be processed by dBASE commands. You can combine multiple conditions in a single expression using standard dBASE expression syntax.


constant, definition
constant

A literal value that you assign to a field or memory variable.


constructor, definition
constructor

Program code in a CLASS...ENDCLASS statement that executes when an object of that class is created. Constructor code can contain any dBASE commands, although it typically contains only property and method assignment statements.


containership, definition
containership

When an object has a property that references a second object, the first object is said to contain the second object. The most common example of containership is a form object that contains controls such as spin boxes or entry fields. When the container object is released from memory the contained object is released automatically.


Control-menu box, definition
Control-menu box

An icon at the upper left corner of a window. The Control-menu box opens the Control menu when you double-click it. The Control menu and the Control-menu box are standard Windows features.


controls, definition
controls

Objects that are displayed on a form, such as menus, pushbuttons, and list boxes.


coverage analysis, definition
coverage analysis

A way of determining which logical blocks of a program execute. Perform coverage analysis with the SET COVERAGE, DISPLAY COVERAGE, and LIST COVERAGE commands.


coverage file, definition
coverage file

A file containing the results of coverage analysis. A coverage file has the same name as its program and an extension of .COV.


database, definition
database

A collection of related tables and their associated files. In prior versions of dBASE, a single table is called a database file.


database alias, definition
database alias

A name that identifies an SQL database, a directory on the hard disk, or a file server where dBASE tables are stored.


data type, definition
data type

A classification for data stored in a field or memory variable. Each data type has rules governing how you work with the data and what the field or variable can contain. For example, logical variables can contain only true (.T.) or false (.F.) values, while numeric variables can contain only numbers.


DDE, definition
DDE

Dynamic Data Exchange. DDE is a Windows protocol for exchanging information and instructions between applications. Programs that support DDE can pass data to each other through links that you establish.


DBASEWIN.INI file, definition
DBASEWIN.INI file

A text file that stores attributes of dBASE and its components, as well as settings for tools such as windows, palettes, and dialog boxes. DBASEWIN.INI is constantly updated as you work and retains the new settings each time you exit dBASE. When you start dBASE again, the same settings are in effect.


deadlock, definition
deadlock

An error condition that can occur in a multiuser environment when two users repeatedly attempt to lock the same record or file.


delimiter, definition
delimiter

A special character that encloses or separates data items in expressions. For example, you delimit character literals with single quotation marks ( ' ), double quotation marks ( " ), or brackets ([ ]). Always use the same delimiter on either side of the literal expression.


derivation, definition
derivation

The declaration of a new class (a subclass) that is based on another class (a superclass). Programmers build hierarchies of classes by deriving one from another.


descending order, definition
descending order

An indexing and sort order that goes from highest to lowest for numbers (10 through 1, for example), from Z to A for characters, and from latest to earliest for dates. The default order is ascending.


Desktop, definition
Desktop

The area within the application window between the SpeedBar and status bar. Many windows, including the Navigator, Command window, and Table Records window, cannot be moved outside the Desktop.


design, definition
design

The process of creating or changing the structure or characteristics of tables, queries, forms, reports, and other dBASE items.


design mode, definition
Design mode

The mode in which you use design tools. For example, you can create or modify a form with the Form Designer when dBASE is in Design mode.


design surface, definition
design surface

The main window of a design tool such as the Form Designer or the Query Designer. You work with design surfaces when dBASE is in Design mode.


dialog box, definition
dialog box

A window that displays a message or prompts the user for information before proceeding with other tasks. Most dialog boxes have options and controls that collect information or choices from the user.


DLL, definition
DLL

Dynamic Link Library. DLLs are files containing compiled program code that Windows applications load and execute at run time. The program code can be routines such as functions and procedures, or resources such as bitmaps, icons, and menus.


dot operator, definition
dot operator

An operator ( . ) that accesses an object property through an object reference. Place the object reference on the left side of the dot operator, and place the property name on the right of the operator. Command syntax containing the dot operator is commonly called dot notation.


editor control, definition
editor control

A control for viewing and editing memo fields, large character fields, or text files. An editor control uses either the dBASE Text Editor or another text editor you specify on the Files page of the Desktop Properties dialog box.


encapsulation, definition
encapsulation

Combining memory variables and procedures to form a new structure called an object. Encapsulation is an important concept in object-oriented programming. Encapsulating variables and procedures within an object separates them from data with the same names elsewhere in the application. Encapsulation also enhances reusability by grouping related data together.


entry field, definition
entry field

A control in which the user enters a single value. An entry field can be linked to any field type except memo, binary, and OLE. Entry fields correspond to GETs in prior versions of dBASE.


event, definition
event

An occurrence such as a keypress or a mouse click. Most events are user actions; however, some events are actions performed by a program or the operating system. In forms, you can write event handlers (program code) that execute in response to events.


event handler, definition
event handler

A subroutine that executes automatically when an event occurs. Use the Procedure Editor to write event handlers for forms and controls.


exclusive use, definition
exclusive use

A way of opening a table so that no other user can open the table. Exclusive use is required for actions that make structural changes to a table, such as adding or deleting fields, reindexing, or removing records.


expression, definition
expression

A combination of one or more fields, literals, memory variables, operators, and functions. An expression evaluates to a single value of a given data type, such as character or numeric. Use expressions to provide values for arguments in a command statement.


Expression Builder, definition
Expression Builder

A tool that helps you build expressions. Access the Expression Builder through the Command window, the Text Editor, or with the GETEXPR( ) function.


field, definition
field

One item of information in a table. A set of fields makes up one record, which is equivalent to a row in a table. In a table structure, records are the rows and fields are the columns.


field name, definition
field name

The name of a field in a table. You refer to specific fields in a table by their field names. The table type, such as dBASE, Paradox, or SQL, determines the rules for creating field names.


field type, definition
field type

The kind of information (data type) that can be entered into a field of a table. You specify the field type when adding a new field to a table.


file association, definition
file association

When one file, such as a form file (.WFM), is based on another file, such as a table file, the two files are associated. Other file associations include queries (.QBE) and tables, and reports (.RPT) and queries. File associations are represented graphically in the Catalog window.


file-name skeleton, definition
file-name skeleton

A template for selecting files according to their names and extensions. For example, the file-name skeletons for table files are *.DBF (for dBASE tables) and *.DB (for Paradox tables).


filter, definition
filter

A command that restricts the records processed by subsequent commands. Filters make queries more useful by excluding unnecessary information. Filters can contain conditions that must be met before records can be processed.


filter condition field, definition
filter condition field

A text box in the Query Designer where you enter a filter condition for a single field.


flow-of-control commands, definition
flow-of-control commands

Commands that control the flow of program execution. Flow-of-control commands (also called control structures), such as IF...ENDIF and DO WHILE...ENDDO, branch to other commands or loop through a series of commands repeatedly.


focus, definition
focus

A control or window has focus when the user selects (highlights) it. In an event-driven interface, where many windows and controls appear onscreen, only one at a time can have focus. When an object has focus, you can choose an action to perform on the object.


font, definition
font

A set of letters, numbers, punctuation marks, and symbols of a given size and style.


form, definition
form

A window containing controls for displaying or editing data. Create forms visually with the Form Designer.


Form layout, definition
Form layout

A display mode in a browse object (or the Table Records window) where records are displayed one at a time with fields arranged horizontally and contiguously.


function, definition
function

A subroutine that returns a value. Functions consist of a keyword followed by parentheses, which can contain arguments.


function keys, definition
function keys

The 12 keys across the top of the keyboard labeled F1 through F12. (Some keyboards have 10 keys at the far left of the keyboard).


function pointer, definition
function pointer

A data type for storing references to procedures or functions. For example, when you assign a procedure to the OnClick property of an object, the data type of the property is a function pointer. When the user clicks the object, the procedure executes.


global breakpoint, definition
global breakpoint

A breakpoint you specify in the Debugger that stops program execution when a condition becomes true or the value of an expression changes. Global breakpoints affect all program files and are not linked to a specific line of code.


handles, definition
handles

In the Form Designer, handles (small black squares) appear on the borders of the control that has focus. Use the mouse to drag control handles to resize the control.

Handles are also integer values provided by DOS to identify a file or DOS device.


header file, definition
header file

A program file that you insert into another program file at compile time using the #include directive. Header files typically have .H extensions and are especially useful for inserting global constant definitions created with #define.


IBM extended codes, definition
IBM extended codes

Keys or key combinations that do not correspond to any of the standard ASCII character codes. Extended codes have special extended code numbers between -1 and -132.


IDAPI, definition
IDAPI

Integrated Database Application Programming Interface. IDAPI allows dBASE to access data in different formats, such as Paradox for Windows, and SQL servers (InterBase, ORACLE, SYBASE, and Informix).


IDAPI.CFG, definition
IDAPI.CFG

A configuration file for IDAPI (Integrated Database Application Programming Interface). IDAPI.CFG stores dBASE system and program settings.


IDAPI Configuration Utility, definition
IDAPI Configuration Utility

The Integrated Database Application Programming Interface configuration utility. Use this utility to change system settings for files such as language drivers, database aliases, and network control files.


import, definition
import

The process of bringing data into an open table from a different type of file. Importing data allows you to share data with other applications.


index, definition
index

An ordered set of keys that identifies specific records in a table. An index organizes data for rapid retrieval and ordered display. dBASE stores indexes in single index files (.NDX) or multiple index files (.MDX). Unlike sorting, indexing does not rearrange records in a separate file. Create an index using the Table Designer or the Manage Indexes dialog box, or use the INDEX command.


index tag, definition
index tag

A single index in a multiple index file (.MDX). A multiple index file can have up to 47 index tags. Use the Table Designer or the Manage Indexes dialog box to create an index tag. The TAG keyword of the INDEX command also creates a tag.


inheritance, definition
inheritance

When you derive a class (a subclass) from another class (a superclass), the subclass inherits all the properties and methods of the superclass. Inheritance is an important concept in object-oriented programming because it makes program code easy to reuse. When you need to modify part of a class, you can derive a subclass, and then modify only the properties or methods that need to change.


input pane, definition
input pane

The pane in the Command window where you enter dBASE commands. When you perform tasks with the user interface (such as choosing a menu item), dBASE automatically echoes the corresponding commands in the input pane.


insert, definition
insert

The process of adding a record to a table at the location of the record pointer instead of the end of the table.


inspect, definition
inspect

The process of displaying the properties of an object in the Object Inspector.


inspector, definition
inspector

A tabbed window that displays property settings for an object. To display the Object Inspector, right-click the object and select Object Properties from the Form Designer SpeedMenu.


Inspect window, definition
Inspect window

A window in the Debugger that you use to display the value of a variable, field, array, or object. For example, if you inspect a variable in a procedure, the Inspect window displays the value of the variable at the time the inspection occurred.


instance, definition
instance

An object created from a class. For example, a form is an instance of the Form class (or a custom class derived from the Form class).


integrity, definition
integrity

The accuracy and consistency of the data in tables.


internal language driver name, definition
internal language driver name

Each language driver has an internal driver name, which is required when you change language drivers using the IDAPI Configuration Utility. For IDAPI, internal driver names are case-sensitive. Enter all letters in uppercase.


key expression, definition
key expression

One field name, or a combination of one or more field names, functions, or operators used for complex indexes.


key field, definition
key field

When you index on a single field in a table, it becomes a key field. Your index will order that table according to the key field.


keyword, definition
keyword

A word that is part of the dBASE language, such as USE or EXCLUSIVE. A keyword should not be used as the name of a variable, array, or procedure.


language driver, definition
language driver

A file that determines the character set available on your computer and how characters sort.


library file, definition
library file

A file where you store procedures and functions for use by other programs. Programmers typically create library files that contain commonly used subroutines.


link, definition
link

With Dynamic Data Exchange (DDE), a link is a mechanism that passes information between DDE-type applications. A client application initiates the link and a server application responds. The Initiate( ) property of a DDELink object creates a DDE link.


linking field, definition
linking field

A field used to create a relation between two or more tables.


list box, definition
list box

A control where the user chooses from a list of values. A list box differs from a combo box in that a list box only lets the user choose from a displayed list; it does not accept typed-in values the way a combo box does.


local variable, definition
local variable

A memory variable that is automatically released when the subroutine that declared it finishes executing. Declare local variables with LOCAL.


lock, definition
lock

A mechanism for preventing two users from editing a record at the same time in a multiuser environment. A lock can prevent a second user from reading or editing a record and can prevent access to an entire table.


logical field, definition
logical data

A data type that accepts either/or values, such as true/false, yes/no (T, t, Y, y, F, f, N, n).


logical operator, definition
logical operator

One of the three operators (AND, OR, or NOT) that can be used on logical data. For example, an AND between two logical values results in a logical value of True if both the original values are also True. Also known as Boolean operators.


loops, definition
loops

Control structures that repeat a series of commands until a certain condition is met.


lvalue, definition
lvalue

Something that occurs on the left side of an equal sign in an expression. For example, variables, fields, and array elements can be lvalues.


many-to-many relation, definition
many-to-many relation

A relation in which multiple records in the parent table are linked with multiple records in the child table. A many-to-many relationship occurs when both the parent table and the child table have duplicated values in the linking field. For example, customers often buy from multiple sales representatives, and sales representatives often sell to multiple customers.


master index, definition
master index

The controlling index. This index determines the current order of records in the table. You can have many indexes open, but just one is the master index. Set a master index by using the Manage Indexes dialog box, or by typing SET ORDER in the Command window.


MDI form, definition
MDI form

A Multiple Document Interface window containing the standard MDI Windows features, including a window title, a Control-menu box, maximize and minimize buttons, and menus. MDI windows are moveable and sizable.


.MDX index file, definition
.MDX index file

A multiple index file. Each index has a name, called a tag, that uniquely defines the index in the .MDX file.


member, definition
member

A variable in an object that has a name. For example, MyObj.Item is the member name for the Item property.


memo field, definition
memo field

A field type that typically contains text of varying length. dBASE stores memo fields in a memo file (.DBT), separate from the table (.DBF). APPEND MEMO imports data into a memo field.


memory variable, definition
memory variable

A named location in memory where you store values, such as strings, numbers, and dates. Programmers create memory variables (also called variables) to temporarily store values for calculations and other operations. The STORE command assigns values to memory variables.


menu, definition
menu

A user interface element for displaying the tasks or actions available to the user.


menu bar, definition
menu bar

A user interface element that displays the titles of currently available menus. Most applications have a File menu, an Edit menu, and a Help menu, in addition to menus specific to the active window.


message, definition
message

A character expression displayed in the status bar.


method, definition
method

A function, procedure, or codeblock associated with an object. Methods performs actions on objects. For example, to close a form, call the Close() method for the form.


mnemonic key, definition
mnemonic key

The underlined letter in the menu title that users can press on the keyboard to select an item when the menu is open. This is different from a shortcut key, which activates a command even when the menu is closed. This is also called a "pick" key.


modal window, definition
modal window

A window that, when active, takes control of the user interface. The user cannot switch to another window without exiting the modal window. A dialog box is an example; when it is open, you cannot take any other actions outside the dialog box until it is closed.


modeless window, definition
modeless window

A window that does not require exclusive interaction from the user. A user can open more than one modeless window and switch between them in an application.


module, definition
module

In the Debugger, a module is a program file that you view in the Module window.


Multiple Document Interface (MDI), definition
Multiple Document Interface (MDI)

A Windows standard that allows an application to manage multiple windows or multiple views of the same document within the main application window. In dBASE, you can have multiple windows (Command window, Navigator, Table Designer, and so on) open at the same time.


natural order, definition
natural order

The order in which records are added to a table. Natural order is the sequence in which the record pointer moves through a table when you do not specify a master index. Indexing can change the sequence of the record pointer, but it does not change the natural order. Only the SORT command changes the natural order of records in a table.


Navigator, definition
Navigator

The dBASE Navigator is the window that displays the primary dBASE file types, such as tables, queries, and forms, and the icons representing files of those types.


.NDX index file, definition
.NDX index file

A single index file. The single index file is comparable to a single tag in an .MDX file. Single index files provide compatibility with earlier versions of dBASE.


network control file, definition
network control file

A Paradox file that keeps track of users on the network and controls table sharing on the network.


object, definition
object

The user interface contains objects, which are graphical interface elements and Windows controls. Menus, pushbuttons, and check boxes are examples of objects, also known as controls. You can move objects, size them, and assign properties to them, which affects their appearance and behavior. Programmers work with objects as collections of memory variables, where each variable represents a property of the object.


object inspector, definition
Object Inspector

A window that displays the property settings for objects. To open the Object Inspector, execute the INSPECT( ) function or choose the Object Properties command from the View menu or SpeedMenu.


OLE, definition
OLE

Object Linking and Embedding. OLE is a Windows protocol for integrating data from different applications into a single compound document. dBASE for Windows supports OLE as a way to store and read different kinds of data, such as binary data, in tables.


one-to-many relation, definition
one-to-many relation

A relation where individual records in a parent table are linked with multiple records in the child table. A one-to-many relationship occurs when the parent table has unique values in the linking field and the child table has duplicated values in the linking field.


one-to-one relation, definition
one-to-one relation

A relation where individual records in a parent table are linked with individual records in the child table. A one-to-one relationship occurs when the both the parent table and the child table have unique values in the linking field.


operator, definition
operator

A symbol that represents the kind of operation to be performed on a value or values. For example, the + operator specifies addition, and the * operator specifies multiplication.


order box, definition
order box

In the Query Designer, a button you select that displays options for ordering records, including ascending, descending, and natural (the default) orders.


pack, definition
pack

The process of permanently removing records that have been marked for deletion from a .DBF table. Packing a table also updates any open indexes. Once you pack a table, you cannot recover the deleted records.


parameter, definition
parameter

A literal value, or reference to a memory variable containing a value, that you pass to a procedure or user-defined function (UDF).


parent table, definition
parent table

One of two tables in a relation, the other being the child table. When a key field value in the parent table matches a key field value in the child table, the child record pointer moves to the matching record. As you select a record in the parent table, you see the corresponding child record or records.


pass count, definition
pass count

The number of times a program passes a breakpoint during a debugging session. Program execution stops after the breakpoint occurs the specified number of times.


pixel, definition
pixel

A unit of measure. Pixel stands for "picture element" and is the smallest addressable element on the display device, such as a monitor. The physical size of a pixel varies between display devices.


polymorphism, definition
polymorphism

The process of giving a class in a hierarchy of classes the ability to implement an action that is common to all classes in the hierarchy, in whatever way is most appropriate for that class. Polymorphism (literally, "having many shapes"), is an important concept in object-oriented programming.

dBASE for Windows supports polymorphism by allowing programmers to derive one class from another class and override a property or method of the new class with a different value or subroutine. The overridden property or method shares the same name in both classes but takes a different "shape" in each class.


precedence, definition
precedence

The order in which dBASE applies the operators contained in an expression. For example, logical operators are applied in the following order of precedence: NOT, AND, and OR. You can override precedence by grouping with parentheses.


primary index, definition
primary index

The main index in a Paradox table. It consists of one or more consecutive fields, starting with the first field in the table.


private variable, definition
private variable

A memory variable that is automatically released when the creating routine terminates. Declare private variables with PRIVATE. Previously declared variables become hidden when you declare a private variable with the same name.


procedure, definition
procedure

A named group of commands beginning with PROCEDURE. You can reduce program size and improve modularity by consolidating often-used command sequences into procedures.


production index, definition
production index

An index file associated with a dBASE table that opens automatically when you open the table. Each table can have one production index with the same file name as the table and an .MDX extension.


program-file, definition
program file

A text file containing dBASE commands. Program files have .PRG extensions by default. You can create programs with any text editor or with the dBASE Text Editor. MODIFY COMMAND also creates programs.


properties, definition
properties

The attributes of an object. You can view and change object properties with the Object Inspector. To open the Object Inspector, execute the INSPECT( ) function or choose the Object Properties command from the View menu or SpeedMenu.


public variable, definition
public variable

A memory variable that is available to all subroutines in an application. Declare public memory variables with PUBLIC. Public variables are sometimes called global variables.


pushbutton, definition
pushbutton

A control where the user carries out dBASE commands with a single action. For example, when the user makes changes to a table through a settings dialog box, pressing the OK pushbutton commits those changes.


query, definition
query

A question you ask about information in a table. Create a query by using the Query Designer to build a model of the information you want - which table or tables you want, which records from those tables, and which fields from those records. Then you run the query to create a view of the data. When you run the query, dBASE generates and executes the code necessary to select and arrange the information as you requested it. When you save a query, the dBASE commands are stored in a .QBE file.


Query Results window, definition
Query Results window

The view where you see the data you have requested. The data that is displayed is the result of whatever fields and records you specified in your query. Use the Query Results window (view) as you do the Table Records window in Browse layout.


radio button, definition
radio button

A control where the user selects a single choice from a set of alternatives. Radio buttons are part of a group of at least two or more. If you select one radio button in the group, all other radio buttons are unselected.


raster operation, definition
raster operation

An operation that specifies how colors are blended on the screen.


recall, definition
recall

The process of recovering records that have been marked for deletion. When you delete a record, dBASE does not remove the record from the table until you pack the table. You can unmark, or recall, marked records until you pack the table. This applies only to .DBF tables.


record, definition
record

A group of fields containing information about a single person, place, or thing. In a table structure, records are the rows and fields are the columns.


record lock, definition
record lock

A restriction applied to a record that prevents other users from changing that record. Record locks are typically used when dBASE is running in a multiuser environment.


record number, definition
record number

A unique number that represents the current record in a table. dBASE tables have record numbers, which are assigned consecutively as you add records. Paradox and SQL records do not have fixed record numbers; identify these records with bookmarks.


record pointer, definition
record pointer

A pointer in memory representing or "pointing to" the current record in an open .DBF table. When a record is highlighted, the record is the current record. You do not actually move records, you move the record pointer. Commands that move to a different record in a table, such as SKIP and GOTO, change the position of the record pointer. Use RECNO() to determine the position of the record pointer.


relational database, definition
relational database

A database design in accordance with a set of principles called the relational model. Data in a relational database is represented by values in tables.


relational operator, definition
relational operator

An operator, such as >, <, =, used in comparison expressions that return logical values, true (.T.) or false (.F.).


relation, definition
relation

A link between two tables based on a key expression, usually a field. When key fields in both tables contain the same information, their associated records are related. Relations provide a way to synchronize the movement of the record pointer in two tables containing similar information. Set a relation using the Query Designer or the SET RELATION command.


report, definition
report

Information from tables printed on paper or previewed onscreen.


reserved words, definition
reserved words

The names of commands, keywords, functions, system variables, and operators. These words may not be used as variables or array names.


results pane, definition
results pane

The pane in the Command window that displays the results of many commands that you enter in the input pane. It is also where dBASE III+/IV programs run, except for programs that open their own windows.


rollback, definition
rollback

The process of reversing changes (or a transaction) before committing them to the database. If the transaction is not successful, you can reverse, or roll back, your changes.


run, definition
run

The process of using an object. When you run a table, you open it in Browse layout where you can edit the data. When you run a query, you view the data from the tables that you selected for the query. When you run a form, the controls become active.


Run mode, definition
Run mode

The mode in which you use an object. For example, running a table opens it for browsing. Running a program executes the program.


run-time error, definition
run-time error

An error that occurs when a syntactically valid statement cannot be carried out in the current context.


scope (memory variables), definition
scope (memory variables)

The availability of a memory variable. dBASE for Windows supports the following memory variable scopes: private, public, local, and static. For example, a local variable exists only as long as the subroutine that created it is running, and it is available only within that subroutine.


scope (records), definition
scope (records)

A condition specifying the set of records that a given command processes. dBASE for Windows supports the following scope options: ALL, NEXT, REST, or RECORD.


server, definition
server

A Windows application that communicates with Dynamic Data Exchange (DDE) client applications. A dBASE application can be a DDE server, a client, or both.

The word server also refers to a computer that stores shared files on a network.


session, definition
session

A feature that lets you simulate a multiuser environment. When you run an application in a session, the session manages its own set of work areas. No other form or application can interfere with the environment in the session. For example, if an application running in another session issues CLOSE ALL, the files in the current session are not affected. Or, you can turn sessions on and off in the Desktop Properties dialog box.


shortcut key, definition
shortcut key

A combination of keyboard keys, such as Ctrl+O, that activates a command even when the menu is closed. For example, pressing Ctrl+O displays the Open File dialog box even when the File menu is closed. This differs from a mnemonic key, which is an underlined letter that activates a command only when the menu is open.


skeleton (file), definition
skeleton (file)

A template for selecting names. Combine literal characters with wildcard characters (* for any number of characters, and ? for any single character) to create a pattern to match one or more names from a set of names, such as file names or procedure names. For example, the skeleton "Cust*.dbf" matches the file names CUST1.DBF, CUST2.DBF, and CUST1A.DBF.


skeleton (table or view), definition
skeleton (table or view)

A framework representation of the table structure in the Query Designer window. The skeleton shows the table name and the name of each field. As you add more tables to the query, their skeletons appear in the Query Designer window.


sort order, definition
sort order

The sequence in which data is arranged. Sort order is affected by the language driver in use. dBASE for Windows provides several language drivers for data in different languages.


soundex, definition
soundex

A four-character code that represents the phonetic value of a character expression or memo field. Use SOUNDEX() to generate soundex codes.


source code, definition
source code

Commands or statements in a human-readable form. Program files (.PRG) are an example of source code. Programmers write source code and compile it into machine-readable object code. Use MODIFY COMMAND to create source code files.


SpeedBar, definition
SpeedBar

The set of buttons and tools for frequently performed tasks. The SpeedBar is below the menu bar and changes according to the window you are using.


SpeedMenu, definition
SpeedMenu

A menu that you access within a window. SpeedMenus contain commands specific to the windows in which they appear; for example, the Module window in the Debugger has a SpeedMenu that provides debugging options. To display the SpeedMenu for a window, right-click within the window.


spin box, definition
spin box

A control where the user enters number or date values by increasing or decreasing the current value incrementally using Up and Down arrows, or by typing in the values. Spin boxes can be linked to numeric, float, and date fields.


static variable, definition
static variable

A memory variable that continues to exist when the subroutine that declared it finishes executing. It is not available unless you call the subroutine again. Declare static variables with STATIC.


statement, definition
statement

A complete executable command line, including all arguments and options. Statements contain language elements such as commands, functions, preprocessor directives, and memory variables.


step over, definition
step over

Stepping is a debugging technique that executes source lines one at a time in a program without individually executing the source lines in UDFs and procedures. Set up step handling with the Debugger or with the SET STEP and ON STEP commands. In the Debugger, the Step Over command executes a line, displays the results, and stops. If a line contains a procedure or UDF call, the line executes as if it were a single command. In contrast, the Trace Into command steps through the source lines in procedures and UDFs individually.


streaming output, definition
streaming output

Text that is displayed on the current or next available line. Streaming output flows in lines from left to right, top to bottom and is not controlled by formatting commands such as @...SAY. Text output commands other than @... commands, such as ? and ??, generate streaming output.


structure, definition
structure

The specifications and arrangement of fields in a table. The information for a table structure includes the name and type of the table, and the name, width, and data type of each field in the table.


Structured Query Language (SQL), definition
Structured Query Language (SQL)

A unified language for defining, querying, modifying, and controlling the data in a relational database. dBASE for Windows provides access to SQL tables.


subclass, definition
subclass

A class derived from another class (known as a superclass). A subclass inherits the properties of the superclass.


subroutine, definition
subroutine

A group of commands that performs a specific task. Programmers create subroutines to organize and increase the modularity of their code. Subroutines include procedures, user-defined functions (UDFs), and codeblocks.


substring, definition
substring

Any part of a character string. For example, "niel" is a substring of "Nathaniel." Use SUBSTR() to extract a substring from a character string.


superclass, definition
superclass

A class you use to derive another class (known as a subclass). The subclass inherits all properties of the superclass.


syntax, definition
syntax

The rules of the dBASE language regarding the usage of language elements such as commands, functions, preprocessor directives, and system memory variables.


syntax error, definition
syntax error

An error in a command statement. Examples of syntax errors are misspelled keywords, incorrect data types of arguments, or missing arguments. Most syntax errors are detected when a program is compiled.


system memory variable, definition
system memory variable

A predefined memory variable. System memory variables are typically used to specify environmental and printer settings, and to control the format of printed and screen output. System memory variable names begin with an underscore (_) to distinguish them from other memory variables.


tabbed dialog box, definition
tabbed dialog box

A dialog box that contains two or more pages with tabs at the bottom of each page. Click the tabs to move from one page to another.


tabbing order, definition
tabbing order

The order in which controls receive focus when the user presses the Tab key. The tabbing order is associated with the z-order of the controls. That is, when the z-order changes, so does the tabbing order.


table, definition
table

A file structured into rows (records) and columns (fields) of information. dBASE tables have .DBF extensions. In earlier versions of dBASE, a table is called a database file.


table lock, definition
table lock

An instruction that prevents more than one user at a time from accessing a table.


Table Records window, definition
Table Records window

The window that lets you view and edit the contents of a table. The Table Records window provides three layout options: Browse, Form, and Columnar.


table type, definition
table type

Through the Borland Database Engine, dBASE supports several different types of tables, including dBASE, Paradox, and SQL.


Text Editor, definition
Text Editor

The component of dBASE for Windows used to create and edit dBASE programs and memo fields.


trace, definition
trace

Tracing is a debugging technique that executes the source lines in a program one at a time. In the Debugger, the Trace Into command executes a line, displays the results, and stops. Trace Into executes source lines in procedures and UDFs individually; Step Over executes them as if they were a single command. By tracing through a program, you can analyze the results of each source line before executing the next one.


transaction, definition
transaction

A group of related changes to a table. The whole group of changes must be successfully completed for the transaction to be committed to the database. Otherwise, you can roll back your changes; they will not be committed to the database. Use the BEGINTRANS() function to mark the beginning of a transaction.


unique index, definition
unique index

A Paradox term, primary indexes require unique values - they do not permit duplicate key values.


user-defined function, definition
user-defined function

A function you create with FUNCTION that contains other commands or functions. You can reduce program size and improve reliability by consolidating often-used command sequences into user-defined functions (UDFs).


user interface, definition
user interface

The parts of an application that users see onscreen and interact with. For example, the dBASE for Windows user interface includes menus, dialog boxes, windows, palettes, and many other graphical elements.


VBX control, definition
VBX control

A user interface object written in C or Pascal, with a .VBX extension. Like dBASE custom controls, VBX controls usually enhance the appearance or extend the functionality of other controls used in forms. dBASE for Windows supports VBX Version 1 controls.


view (query), definition
view (query)

An organized selection of data from one or more tables. The details of a view are defined in a query. The details of a query include field order, record order, record selection, and certain calculations. When a query is run, the data appears in the Table Records window where the data can be viewed and in many cases edited. A view is a virtual table. That is, it exists in memory only and is removed from memory when the query is closed.


view (user interface), definition
view (user interface)

A unique working environment for accomplishing related tasks. For example, there are different views for designing tables, queries, and forms. Each view contains tools such as menus, dialog boxes, SpeedBars, and SpeedMenus for accomplishing the tasks specific to the view.


watch, definition
watch

To monitor the value of an expression while a program executes. In the Debugger, you specify the expressions to watch by creating watchpoints. The values of the expressions appear in the Watch window.


watchpoint, definition
watchpoint

A variable, field, array element, object, or expression that you are viewing in the Watch window of the Debugger. Every time your program pauses during a debugging session, dBASE for Windows evaluates the watchpoint and displays its current value. Watchpoints help locate bugs in a program by displaying values you do not ordinarily see.


While condition, definition
While condition

An expression that instructs dBASE to process records as long as a condition is true. Unlike FOR conditions, which process all records meeting the condition, a WHILE condition begins processing at the current record and stops when the condition becomes false.


wildcard, definition
wildcard

A special character that DOS uses to match patterns in file names. The asterisk (*) matches any number of characters in a file name. The question mark (?) matches any single character.


Windows API, definition
Windows API

The Windows Application Programming Interface is a library of C functions built into the Windows environment that programmers use to develop Windows applications. dBASE for Windows provides access to the Windows API through the EXTERN command. You might call a Windows API function to retrieve system-level information, such as the percentage of resources free.


work area, definition
work area

An area of memory reserved for a table and its associated files, such as indexes and format files. Identify work areas by number, letter, or alias name. You can open several different files in different work areas, but only one work area is current. Fields you reference need to be in the current work area, unless you use qualified field names, which specify the work area.


zap, definition
zap

To permanently remove all records from a table, even if they are not marked for deletion. You cannot recover records after zapping them.


z-order, definition
z-order

The visual layering of controls on a form. This indicates the z-axis (or depth) of the layout. The z-order determines which controls are in front of other controls. This affects the tabbing order - the order in which controls receive focus when the user presses the Tab key.


Keyboard Shortcuts

dBASE provides keyboard shortcuts for actions that otherwise require you to use the mouse. Where these keystrokes are equivalent to a menu command, they appear in the menu following the command name. In many cases there are three ways to do something. For example, to display the Open File dialog box, you can do any of the following:

Choose File|Open with the mouse.

Press Alt+F to display the menu, and then press O to execute the command.

Press Ctrl+O (the keyboard shortcut).

Choose from the following lists of tables for information about these topics:

System-wide Keystrokes

Text Editing Keystrokes

Table Editing Keystrokes

Query Editing Keystrokes

Form Editing Keystrokes

Navigator and Catalog Window Keystrokes

Command Window dBASE III+/IV Compatibility Keystrokes


System-wide Keystrokes

See Also

The following table lists the keystrokes that are in effect at all times. Most of these are standard Windows keyboard shortcuts. The second table in this topic lists keystrokes available in dialog boxes.

Menu Command	Keystroke	Description
	Alt	Activates the menu bar.
	F10	Activates the menu bar.
	Alt+<letter>	Displays the menu containing the underlined letter.
	<letter>	When a menu is open, executes the command containing the underlined letter.
	Alt+Spacebar	Opens the Control menu of the main application window or a dialog box.
	Alt+hyphen	Opens the active window's Control menu.
	Ctrl+F4	Closes the active window (MDI).
	Alt+F4	Closes the application or the current non-MDI window.
	Esc	First press closes the Control menu but leaves the Control menu box active; second press deacitivates the Control menu box.
	Esc	Closes a menu.
Edit|Undo	Ctrl+Z	Undoes the last reversible action.
Edit|Cut	Ctrl+X, Shift+Del	Cuts the selected item to the Clipboard.
Edit|Copy	Ctrl+C, Ctrl+Ins	Copies the selected item to the Clipboard.
Edit|Paste	Ctrl+V, Shift+Ins	Pastes the contents of the Clipboard to the current insertion point or cursor position.
Edit|Delete	Del	Deletes the selected item. It is not placed on the Clipboard.
Help|Contents	Shift+F1	Displays the Contents screen for online Help.
Window|Tile Vertically	Shift+F4	Tiles the open windows vertically.
Window|Cascade	Shift+F5	Cascades the open windows.
File|Open	Ctrl+O	Displays the Open File dialog box.
	Alt+Esc	Activates the next application in the Windows Task List.
	Ctrl+Esc	Displays the Windows Task List.
	Alt+Tab	Cycles forward through the list of active applications. To switch to that application, release the Alt key.
	Alt+Shift+Tab	Cycles backwards through the list of active applications.
	Ctrl+Tab Ctrl+F6	Activates the next child window.
	Ctrl+Shift+Tab Ctrl+Shift+F6	Activates the previous child window.

This table describes the keystrokes available when a dialog box is open.

Keystroke	Description
Esc	Closes the dialog box without its settings taking effect.
Spacebar	Toggles the state of a selected check box or executes the pushbutton with focus.
Enter	Executes the pushbutton with focus or, if no pushbutton has focus, the default pushbutton.
Alt+<letter>	Moves focus to the option containing the underlined letter. If the option is a pushbutton, it is executed.
Tab/Shift+Tab	Moves focus to the next/previous option or group of options.
Up arrow/ Down arrow	Moves focus within a grouped set of check boxes.
Up arrow/ Down arrow	Changes the selection within a grouped set of radio buttons or in a combo box drop-down list.
Alt+Down arrow	Displays a combo box drop-down list.


See Also

Keyboard Shortcuts

Text Editing Keystrokes

Table Editing Keystrokes

Query Editing Keystrokes

Form Editing Keystrokes

Navigator and Catalog Window Keystrokes

Command Window dBASE III+/IV Compatibility Keystrokes


Text Editing Keystrokes

See Also

This table describes the text editing keystrokes that are available in the text editors, Table Records and Table Structure windows, and generally anywhere you can edit text.

Menu Command	Keystroke	Description
	Right arrow/Left arrow	Moves the insertion point to the next/previous character.
	Ctrl+Right arrow/ Left arrow	Moves the insertion point to the next/previous word or entry field.
	Home/End	Moves the insertion point to the beginning/end of the line or entry field.
	PgUp/PgDn	Moves the insertion point up/down one screen.
Edit|Search|Top Line Edit|Search|Bottom Line	Ctrl+PgUp/PgDn Ctrl+Home/End	Moves the insertion point to the beginning/end of the file.
Edit|Search|Go to Line Number	Ctrl+G	Moves the insertion point to the specified line number in a file or memo field.
	Ctrl+T	Deletes from the insertion point to the beginning of the next word.
	Ctrl+Backspace	Deletes from the insertion point to the beginning of the current word or, if the insertion point is on a space, to the beginning of the previous word.
	Ctrl+Y	Deletes the line containing the insertion point.
	Ctrl+N	Breaks the line at the insertion point.
	Shift+Right arrow/ Left arrow	Selects the character to the left or right.
	Shift+Up arrow/ Down arrow	Selects to the same position in the previous or next line.
	Shift+Ctrl+Right arrow/Left arrow	Selects the previous/next word.
	Shift+Home/End	Selects to the beginning/end of the line.
	Shift+click	Selects from the insertion point to the point at which you clicked.
	Shift+PgUp/PgDn	Selects up/down one screen from the insertion point.
	Shift+Ctrl+PgUp/ PgDn Shift+Ctrl+Home/ End	Selects from the insertion point to the beginning/end of the file.
Edit|Select All		Selects all text in the file or memo field.
Edit|Search|Find Text	Ctrl+F	Displays the Find Text dialog box.
Edit|Search|Find Next Text	Ctrl+K	Searches for the next occurrence of the text specified in the Find Text dialog box.
Edit|Search|Replace Text	Ctrl+R	Displays the Replace Text dialog box.
	Ctrl+Enter	Adds a new command line without executing the current line; places the insertion point on the new line (Command window only).
	Ctrl+N	Adds a new command line without executing the current line; the insertion point does not move (Command window only).


See Also

Keyboard Shortcuts

System-wide Keystrokes

Table Editing Keystrokes

Query Editing Keystrokes

Form Editing Keystrokes

Navigator and Catalog Window Keystrokes

Command Window dBASE III+/IV Compatibility Keystrokes


Table Editing Keystrokes

See Also

This table describes the keystrokes available in the Table Records window.

Menu Command	Keystroke	Description
File|Save Record	Ctrl+S	Saves the current record.
File|Save And Close	Ctrl+W	Saves the current record and closes the Table Records window.
File|Abandon Record And Close	Ctrl+Q	Abandons changes to the current record and closes the Table Records window.
File|Close	Ctrl+F4	Closes the Table Records window. If changes have not been saved, you are prompted to save them.
File|Print	Ctrl+P	Prints the current record or table.
View|Table Records	F2	Displays the Table Records window from the Table Structure window.
View|Table Structure	Shift+F2	Displays the Table Structure window from the Table Records window.
View|Browse Layout View|Form Layout View|Columnar Layout	F2	In the Table Record window, toggles between Browse layout, Form layout, and Columnar layout.
View|Field Contents	F9	Displays the contents of a memo, OLE, or binary field in the appropriate editor.
Table|Find Records	Ctrl+F	Displays the Find Record dialog box.
Table|Replace Records	Ctrl+R	Displays the Replace Record dialog box.
Table|Add Records	Ctrl+A	Inserts a blank record at the end of the table.
Table|Delete Selected Record	Ctrl+U	Deletes the current record. No confirmation is requested.
Table|Lock Selected Record	Ctrl+L	Locks the current record.
Table|Go to Record Number	Ctrl+G	Moves the record pointer to the specified record number.
	Tab/Enter	Moves the selection to the next field in the record.
	Shift+Tab	Moves the selection to the previous field in the record.
	Up arrow/ Down arrow	Moves the selection to the previous/next field in the record (Form and Columnar layouts only).
	Ctrl+Home/End	Moves the selection to the first/last field in the current record.
Table|Previous Record/ Next Record	Up arrow/ Down arrow	Moves the record pointer to the previous/next record in the table (Browse layout only).
Table|Previous Page/ Next Page	PgUp/PgDn	Moves the record pointer to the top of the previous/next page of the table (Browse layout only).
Table|Previous Record/ Next Record	PgUp/PgDn	Moves the record pointer to the previous/next record in the table (Form and Columnar layout only).
Table|Top Record/ Bottom Record	Ctrl+PgUp/PgDn	Moves the record pointer to the first/last record in the table.

This table describes the keystrokes available in the Table Structure window.

Menu Command	Keystroke	Description
	End	Moves the insertion point to the end of the current field.
	Home	Moves the insertion point to the beginning of the current field.
	Enter	Moves the selection to the next record.
	Esc	Closes the Table Structure window.
	Tab/Enter	Moves the selection to the next cell in the field definition.
	Shift+Tab	Moves the selection to the previous cell in the field definition.
	Up arrow/ Down arrow	Moves the selection to the same position in the previous/next row of the table structure. If the selection is in a list box, the arrow keys scrolls through the options in the list box.
	Ctrl+PgUp/PgDn	Moves the selection to the same position in the first/last row of the table structure.
File|Save	Ctrl+S	Saves the current table structure.
File|Save And Close	Ctrl+W	Saves the current table structure and closes the Table Structure window.
File|Abandon Record And Close	Ctrl+Q	Abandons changes to the current table structure and closes the Table Structure window.
File|Close	Ctrl+F4	Closes the Table Structure window. If changes have not been saved, you are prompted to save them.
File|Print	Ctrl+P	Prints the current table structure.
View|Table Records	F2	Switches to the Table Records window for the current table.
Structure|Add Field	Ctrl+A	Adds a new field at the end of the table structure.
Structure|Insert Field	Ctrl+N	Inserts a new field above the field containing the insertion point.
Structure|Delete Selected Field	Ctrl+U	Deletes the field containing the insertion point.
Structure|Go To Field Number	Ctrl+G	Moves the selection to the first cell of the specified field number.


See Also

Keyboard Shortcuts

System-wide Keystrokes

Text Editing Keystrokes

Query Editing Keystrokes

Form Editing Keystrokes

Navigator and Catalog Window Keystrokes

Command Window dBASE III+/IV Compatibility Keystrokes


Query Editing Keystrokes

See Also

This table describes the keystrokes available in the Query Designer.

Menu Command	Keystroke	Description
File|Save	Ctrl+S	Saves the current query.
File|Save And Close	Ctrl+W	Saves the current query and closes the Query Designer window.
File|Abandon Record And Close	Ctrl+Q	Abandons changes to the current query and closes the Query Designer window.
File|Close	Ctrl+F4	Closes the Query Designer window. If changes have not been saved, you are prompted to save them.
File|Print	Ctrl+P	Prints the current query.
View|Query Results	F2	Runs the query and displays the results.
Query|Add Table	Ctrl+A	Displays the Open Table Required dialog box so you can add a table to the query.
	Tab/Shift+Tab	Moves the selection to the next/previous field in the query skeleton.
	Ctrl+Home/End	Moves the selection to the first/last field in the query skeleton.
	F3/F4	Moves the selection to the previous/next table in the query skeleton.
	F5	Toggles the check in the current field of the query skeleton.
	Ctrl+F5	Toggles the check in all fields of the query skeleton.
	F6	Cycles through the sort order options for the current field.

The keystrokes for the Query Results window are the same as those for the Table Records window, with one exception: Shift+F2 displays the Query Designer instead of the Table Structure window. Its menu command equivalent is View|Query Design. See Table Editing Keystrokes for information on keystrokes in the Query Results window.


See Also

Keyboard Shortcuts

System-wide Keystrokes

Text Editing Keystrokes

Table Editing Keystrokes

Form Editing Keystrokes

Navigator and Catalog Window Keystrokes

Command Window dBASE III+/IV Compatibility Keystrokes


Form Editing Keystrokes

See Also

This table describes the keystrokes available in the Form Designer and the Form window.

Menu Command	Keystroke	Description
File|Save	Ctrl+S	Saves the current form.
File|Save And Close	Ctrl+W	Saves the current form and closes the Form Designer window.
File|Abandon Record And Close	Ctrl+Q	Abandons changes to the current form and closes the Form Designer window.
File|Close	Ctrl+F4	Closes the Form Designer window. If changes have not been saved, you are prompted to save them.
File|Print	Ctrl+P	Prints the current form.
View|Form	F2	Runs the form.
View|Form Design	Shift+F2	Displays the Form Designer for the current form.


See Also

Keyboard Shortcuts

System-wide Keystrokes

Text Editing Keystrokes

Table Editing Keystrokes

Query Editing Keystrokes

Navigator and Catalog Window Keystrokes

Command Window dBASE III+/IV Compatibility Keystrokes


Navigator and Catalog Window Keystrokes

See Also

This table describes the keystrokes available in the Navigator and Catalog window.

Menu Command	Keystroke	Description
	Home/End	Moves the selection to the first/last item in the file list or file icon box.
	PgUp/PgDn	Moves the selection up/down one screen in the file list or file icon box.
	Spacebar	Displays the SpeedMenu for the selected item.
Navigator|Edit Records Navigator|Run Query Navigator|Run Form Navigator|Run Report Navigator|Run Labels Navigator|Do Navigator|Display Image Navigator|Play Sound	F2	Performs the appropriate action depending on the selected file type. When the active window is the Catalog window, the menu title is Catalog (for example, Catalog|Edit Records).
Navigator|Design <file type>	Shift+F2	Switches to Design mode for the selected file type.
Navigator|New Catalog	Shift+F2	When the selected file type is Catalogs, displays the Create Catalog dialog box.


See Also

Keyboard Shortcuts

System-wide Keystrokes

Text Editing Keystrokes

Table Editing Keystrokes

Query Editing Keystrokes

Form Editing Keystrokes

Command Window dBASE III+/IV Compatibility Keystrokes


Command Window dBASE III+/IV Compatibility Keystrokes

See Also

When the Command window is active, dBASE for Windows supports the following keystrokes for compatibility with the dot prompt in dBASE III+/IV.

Key	Command

F3	LIST

F4	DIR

F5	DISPLAY STRUCTURE

F6	DISPLAY STATUS

F7	DISPLAY MEMORY

F8	DISPLAY

F9	APPEND


See Also

Keyboard Shortcuts

System-wide Keystrokes

Text Editing Keystrokes

Table Editing Keystrokes

Query Editing Keystrokes

Form Editing Keystrokes

Navigator and Catalog Window Keystrokes


Views and Tools - Contents
Views and Tools

See Also

Choose from the following topics for information about using the dBASE for Windows interactive views and tools. These topics include descriptions of menus, dialog boxes, SpeedBars, designers, palettes, and inspectors, along with instructions for accomplishing specific tasks.

System-Wide Views and Tools

	dBASE Navigator	Window that lists files in the current directory (and optionally in a directory path) or in a database
	Command Window	Window where you type dBASE commands and see the results
	Expression Builder	Tool for building dBASE expressions
File-Specific Views and Tools

	Tables	Views for creating the structure of a table and for displaying and editing the data in a table
	Queries	Views for defining a query and for displaying and (in some cases) editing the data in the table or tables used by the query
	Forms	Views for laying out and defining the properties and behavior of a form; also, the form itself, with controls for displaying and manipulating data or values presented by the form
	Reports and Labels	Views for creating and running reports and labels
	Programs, Memo Fields, and Text	Windows for writing and editing programs, table memo fields, and text files
	Images	Views for creating and displaying an image
	Sounds	Tools for recording (if the appropriate hardware and software are present) and playing a sound
	Catalog Window	Window that lists files from a catalog (.CAT) file


See Also

Introduction to the Views and Tools


Help Menu

Use the Help menu to display various types of online Help and version information for dBASE for Windows.

Choose from the following commands:

Contents

Search...

Views and Tools

Language

Keyboard

Experts

Interactive Tutors

How to Use Help

About...


Help | Contents

See Also

Opens the Help window on the dBASE for Windows Help Contents topic. The Contents topic lists the main areas covered in online Help. From the Contents topic, you can navigate through Help to find the information you need.

From within the Help window, press Alt+C or choose the Contents button to return to the Contents topic.

To get context-sensitive help on a certain area in the product, press F1 from within that area.

Shortcuts

Keyboard:	Shift+F1


See Also

Help Menu


Help|Search
Help | Search...

See Also

Opens the Help window and displays the Search dialog box. The Search dialog box lists all the keywords in the online Help.

From within the Help window, press Alt+S or choose the Search button to open the Search dialog box.


See Also

Help Menu


Help | Views and Tools

See Also

Opens the Help window and displays the Views and Tools topic. Views and Tools is the main topic for describing the user interface of dBASE for Windows. This topic describes each window, menu command, dialog box, and SpeedBar.


See Also

Help Menu


Help | Language

See Also

Opens the Help window and displays the Language Reference topic. The Language Reference topic provides information about the dBASE language elements and supporting information.

To look up a specific language element quickly, use the Search dialog box or the Language Alphabetic list.


See Also

Help Menu


Help | Keyboard

See Also

Opens the Help window and displays the Keyboard Shortcuts topic. The Keyboard Shortcuts topic lists all the topics in online Help containing tables of keystrokes that perform special tasks.

In addition, keyboard shortcuts for each menu command are listed on the individual menu command topics.


See Also

Help Menu


Help | Experts

See Also

Displays a cascading menu. From the menu, choose Form Expert.

An expert is a tool that walks you through the process of building a file.

Shortcuts

SpeedBar:


See Also

Help Menu

Help|Interactive Tutors


Help | Experts | Form Expert

See Also

Displays the Form Expert window, which prompts you through the steps for building a form.

Shortcuts

SpeedBar:


See Also

Help Menu

File|New|Form

Designing Forms

Help|Interactive Tutors


Help | Interactive Tutors...

See Also

Opens the Interactive Tutors window listing all the available tutors. Tutors are short lessons on how to do certain tasks in dBASE for Windows.

You can choose a lesson from the tutor catalog, or click the Index button to search for a keyword in the topic.

For each tutor you complete, a checkmark appears next to its title in the tutor catalog.

For more information about tutors, see Using the Interactive Tutors.

Shortcuts

SpeedBar:


See Also

Help Menu


Help | How to Use Help

See Also

Opens the Help window and displays information on how to use the Help system.

If Windows help is new to you, you can press F1 from within the Help window to open the Windows help file.

For information about using online Help in dBASE for Windows, see How to Use Help in dBASE for Windows.


See Also

Help Menu


Help|About dBASE for Windows
Help | About...

See Also

Displays a dialog box with version and copyright information about this product.


See Also

Help Menu


Window Menu

Use the Window menu to arrange, open, or activate the windows in the dBASE for Windows Desktop.

Choose from the following commands:

Cascade

Tile Horizontally

Tile Vertically

Arrange Icons

Close All Windows

Navigator

Command

(open window list)


Window | Cascade

See Also

Rearranges all open windows on the Desktop in overlapping layers. The top line of each window is displayed so you can see the name.

If a window is minimized, this command has no effect on it.

Shortcuts

Keyboard:	Shift+F5


See Also

Window Menu


Window | Tile Horizontally

See Also

Displays all open windows on the Desktop without overlapping them. When possible, the windows are sized equally on the screen.

Depending on how many windows you have open and how large your Desktop is, Tile Horizontal attempts to place the windows on top of each other. If you have more windows open than will fit horizontally, Tile Horizontal functions the same as Tile Vertical.

If a window is minimized, this command has no effect on it.


See Also

Window Menu


Window | Tile Vertically

See Also

Displays all open windows on the Desktop without overlapping them. When possible, the windows are sized equally on the screen.

Depending on how many windows you have open and how large your Desktop is, Tile Vertical attempts to place the windows next to each other. If you have more windows open than will fit vertically, Tile Vertical functions the same as Tile Horizontal.

If a window is minimized, this command has no effect on it.

Shortcuts

Keyboard:	Shift+F4


See Also

Window Menu


Window | Arrange Icons

See Also

Aligns the icons from minimized windows at the bottom of the Desktop.

This command has no effect on open windows.


See Also

Window Menu


Window | Close All Windows

See Also

Closes or minimizes all the windows on the Desktop. The Navigator and Command window minimize rather than close.

When windows are closed, their names are removed from the open window list (Window menu) and added to the closed file list (File menu). However, the Navigator and Command window are always available in the open window list.

If you had open tables or Catalog windows, this command does not close the files associated with those windows.


See Also

Window Menu

Window|(open window list)

File|Close

File|(closed file list)


Window | Navigator

See Also

Displays the dBASE Navigator window.

If the Navigator window is minimized, this command restores it.

A checkmark appears next to the current window.

Shortcuts

SpeedBar:


See Also

Window Menu

Using the dBASE Navigator


Window | Command or Program

See Also

Displays the Command window.

If the Command window is minimized, this command restores it.

If you run a dBASE program that does not use a predefined or user-defined window, the program runs in the results pane of the Command window. In this case, the Window menu and the title of the Command window display "Program" and the name of the program.

A checkmark appears next to the current window.

Shortcuts

SpeedBar:


See Also

Window Menu

Using the Command Window


Window | (open window list)

See Also

Displays a list of available windows. Each window is numbered. Choosing a window from the list makes it current. A checkmark appears next to the current window.

If the window is open, this command makes it current.

If the window is minimized, this command opens it and makes it current.

This command lists both visible and minimized windows. When you choose to reopen a minimized window, it appears on the Desktop as if you had restored it using the icon's Control menu.

Dialog Box Options

Window List

Lists the open windows on the dBASE for Windows Desktop. Double-click a window, or select it and choose OK to make it current.

Navigator and Command (or Program) are always available in the window list.

When more than nine windows are open, the menu command More Windows appears. Choose More Windows then pick a window from the Select Window dialog box.


See Also

Window Menu


Using the Command Window

Use the Command window to type dBASE language commands, without writing a program, and see the results immediately.

Shortcuts

SpeedBar:

Command Window Concepts and Tasks

Choose from the following list for information about using the Command window:

Using the Command Window - Overview

Command Window Tasks

System-wide Keystrokes

Text Editing Keystrokes

Command Window dBASE III+/IV Compatibility Keystrokes

Command Window Tools

The Command window has menus and a SpeedBar associated with it. Choose from the following list for more information about these topics:

Components	Description of the Command window

Menus	Lists and descriptions of all Command window menu commands

SpeedBar	Descriptions of the Command window SpeedBar options

SpeedMenu	List and description of the Command window SpeedMenu


Using the Command Window - Overview

See Also

The Command window is an ideal tool for learning the dBASE language. As you use the menu commands and dialog boxes in dBASE for Windows, the Command window echoes the corresponding dBASE language commands. You see the commands, the correct syntax, and the results, and you can start to learn how to use the language. For example, when you choose File|New|Form, the CREATE FORM command is executed in the Command window, and the Form Designer appears. In the future, you might choose to type CREATE FORM rather than use the menu command.

You can also use the Command window if you simply prefer typing commands. Once you learn some dBASE commands, you will find it is sometimes faster and easier to type commands than to use the menus.

Interactive dBASE

The Command window is similar to the dot prompt in dBASE IV and dBASE III PLUS. It provides a way to interact with the dBASE language on a command-by-command basis. For example, you can declare some variables, then use different functions in the language to calculate a complex formula. Once the formula is correct, you can paste it into a program.

Online Help

As you start to learn different commands in the language, refer to the online Help for more detailed information. For example, type HELP CREATE FORM to learn more about the CREATE FORM command. As you learn more about the language, you will find a wealth of commands and functions available to help you create sophisticated database applications.

Programs

From the Command window, you can write, test, compile, and debug dBASE programs using the Program menu commands. For more information on working with programs, see Compiling Programs.


See Also

Command Window Components

Basics: Introduction to the Command Window

How to Use Help in dBASE for Windows

Text Editor Window Components


Command Window Tasks

See Also

To open the Command window, click [image] or choose Window|Command.

Choose from the following list for more information about how to use the Command window:

Opening and Closing the Command Window

Clearing the Command Window Panes

Changing the Appearance of the Command Window

Executing Multiple Commands

Analyzing Program Coverage

Running Files from the Command Window


See Also

Text Editor Tasks


Opening and Closing the Command Window

See Also

To open the Command window, do one of the following:

Choose Window|Command.

Click [image].

Double-click the Command window icon.

Click the Command window icon and choose Restore.

To minimize the Command window, do one of the following:

Choose File|Close.

Press Ctrl+F4.

Click the minimize button.

Choose Minimize from the Command window Control menu.

When you exit dBASE for Windows, the last size, location, and state of the Command window is saved to the DBASEWIN.INI file.


See Also

Command Window Tasks

Clearing the Command Window Panes

Changing the Appearance of the Command Window

File|Close

Opening and Closing the Text Editor

Window|Command


Clearing the Command Window Panes

See Also

To clear the text from the results pane,

1.	Select or open the Command window.

2.	Choose Edit|Clear Results.

To clear the text from the input pane,

1.	Select or open the Command window.

2.	Choose Edit|Select All.

3.	Choose Edit|Delete or press Del.

Note:	The text is not permanently cleared from the input pane. The next command executed in the Command window refreshes the input pane with all previous commands.


See Also

Command Window Tasks

Changing the Appearance of the Command Window

Opening and Closing the Command Window

Opening and Closing the Text Editor


Changing the Appearance of the Command Window

See Also

Use the Command Window Properties dialog box to change the relative position of the two panes and their fonts. Choose Properties|Command Window to view the Command Window Properties dialog box. Alternatively, you can right-click anywhere in the input pane and choose Command Window Properties from the SpeedMenu.

To change the Command window fonts,

1.	Choose Properties|Command Window.

2.	Click [image] next to either Input Pane or Results Pane.

3.	Choose a Font from the Font dialog box. Since some commands, such as DISPLAY STATUS, display output in rows and columns, a monospaced font, such as Terminal or Courier, makes the output easier to read in the results pane.

To change the position of the Command window panes,

1.	Choose Properties|Command Window.

2.	Choose one of the Input Pane positions:

Top displays the input pane above the results pane.

Bottom displays the input pane below the results pane.

Left displays the input pane to the left of the results pane.

Right displays the input pane to the right of the results pane.

By default, the input pane appears above the results pane.


See Also

Command Window Tasks

Clearing the Command Window Panes

Opening and Closing the Command Window

Opening and Closing the Text Editor


Executing Multiple Commands

See Also

To execute multiple commands, do one of the following:

Enter each command on a separate line, pressing Enter to execute each one in succession.

Select a group of previously entered command lines in the input pane and press Enter or choose Edit|Execute Selection.

Separate each command with a semicolon and string them together on one command line. For example,

? REPLICATE("-",8); ? DATE(); ? REPLICATE("-",8)

Paste a block of commands from the Clipboard, then select the commands and press Enter or choose Edit|Execute Selection.

Type multiple command lines by pressing Ctrl+Enter at the end of each line. The commands do not execute. Then select the block of commands and press Enter or click [image].


See Also

Command Window Tasks

Compiling Programs

Copying, Cutting, and Pasting Text Between Windows


Analyzing Program Coverage

See Also

To use coverage analysis,

1.	Set the coverage feature on. Choose Properties|Desktop. Choose the Programming page. Check Coverage, then click OK.

2.	From the Command window or Text Editor, compile and run the program with Program|Do.

3.	View the results with Program|Display Coverage.

4.	Repeat steps 2 and 3 as many times as necessary.


See Also

Command Window Tasks

Compiling Programs

Executing Multiple Commands


Running Files from the Command Window

See Also

You can run any of the primary dBASE file types by dragging and dropping them into the input pane of the Command window.

To run a file,

1.	Open the Navigator, Catalog window, or Windows File Manager.

2.	Select the file, then drag and drop it into the input pane of the Command window.


See Also

Command Window Tasks

Compiling Programs

Differences between the Navigator and Catalog window

Running the Primary dBASE File Types


Command Window Components

See Also	Language

The Command window consists of three areas: input pane, center divider, and results pane, as follows:

Input Pane

By default, the upper part of the window is the input pane. Use the input pane to type dBASE commands. When you press Enter after typing a command, dBASE executes the command.

When you use the menu commands, SpeedBars, SpeedMenus, and dialog boxes, the corresponding dBASE language commands appear in the input pane and are executed immediately.

The input pane retains a list of commands you have run. You can use the arrow keys to move up and down in the list. To execute any command line in the list, move the insertion point to it and press Enter. You can also execute a selected block of commands by pressing Enter. To insert a command between others, press Ctrl+N or Ctrl+Enter, then type the new command.

Results Pane

By default, the lower part of the window is the results pane. Use the results pane to see the results of some dBASE commands. Commands that do not have a specialized window display their output in the results pane. For example, the DISPLAY STRUCTURE command sends its results to the results pane, whereas the BROWSE command opens its own window.

You can change the position of the input and results panes in the Command Window Properties dialog box. See Changing the Appearance of the Command Window.

Center Divider

Between the input and output panes is a center divider line. Drag the divider line up or down, or left or right to increase the size of one of the panes. Double-click the divider line to return it to the center of the window.

Maximum Lengths

The maximum length of a command line in the input pane is 4096 characters.

The maximum number of lines stored in the input pane is 1000.

For information about clearing the input and results pane, see Clearing the Command Window Panes.

The maximum length of a line in the results pane depends on the command. For DOS programs, the screen output size is typically 80 characters. For other commands, the output wraps to fit the width of the Command window. You can drag the border of the Command window to resize it to the width you want.

The maximum number of lines in the results pane depends on your video driver. A typical maximum value is 25. You can run dBASE IV and dBASE III PLUS programs in the results pane, and they appear similar to their native DOS appearance. You can increase or decrease the number of lines stored in the results pane with the SET DISPLAY command.

Text Selection

Text selection in the input pane is like most word processors. If you select text over multiple lines, the end-of-line character is included in the selection.

Text selection in the results pane is different from the input pane. The results pane assumes you want to select a box of text. The box starts where you start dragging, and ends where you stop dragging. If you drag through multiple lines of text, the end-of-line characters are not automatically included in the selection.

If you select text in both windows then choose Edit|Copy or Edit|Cut, the input pane takes priority, and the text selected in the input pane is copied or removed.

Status Bar

The status bar displays the status of the Insert key:

Ins if you can insert characters in front of others

Blank if you will overwrite characters

The status bar also displays information about the current table, if any. See Table Records Window Components for information.


See Also

Changing the Appearance of the Command Window

Clearing the Command Window Panes

Command Window Tasks

Text Editing Keystrokes

System-wide Keystrokes

Command Window dBASE III+/IV Compatibility Keystrokes

Opening and Closing the Command Window

Text Editor Window Components

Using the Command Window - Overview

Table Records Window Components


Language

Language Reference

Alphabetic List

Categorical List

Classes

Properties


Command Window Menus

The Command window has the following menus:

File Menu

Edit Menu

Program Menu

Table Menu

Properties Menu

Window Menu

Help Menu


Command Window SpeedBar

See Also

The SpeedBar is the row of buttons beneath the menu bar. Each button represents a menu command. Click the button representing the command you want to execute.

Button	Action	Menu Equivalent
	Creates a new dBASE-related file	File|New
	Opens a dBASE-related file	File|Open
	Removes the selected text/object and places it on the Clipboard	Edit|Cut
	Copies the selected text, object, or record onto the Clipboard	Edit|Copy
	Inserts the text, object, or record onto the active window	Edit|Paste
	Executes the selected text	Edit|Execute Selection
	Executes the statements in a dBASE program	Program|Do
	Compiles, then debugs the selected program	Program|Debug
	Switches to the Navigator window	Window|Navigator
	Switches to the Command window	Window|Command
	Opens the Form Expert	Help|Experts|Form Expert
	Opens the Interactive Tutors	Help|Interactive Tutors


See Also

Text Editor SpeedBar


Command Window SpeedMenu

See Also

Use the Command window SpeedMenus to quickly perform a common operation on the Command window. The Command window has two SpeedMenus, one for the input pane, one for the results pane.

To use the input pane SpeedMenu, right-click in the input pane of the Command window.

Choose from the following commands:

Command Window Properties...

Cut

Copy

Paste

Build Expression...

Execute Selection

To use the results pane SpeedMenu, right-click in the results pane of the Command window.

Choose from the following commands:

Command Window Properties...

Copy

Clear Results


See Also

File Types and SpeedMenus

Program SpeedMenu


Edit Menu (Command Window)

See Also

Use the Edit menu to perform editing operations and to copy or remove text.

The Edit menu works differently in each of the windows. The most common use of the Edit menu is to work with text, for example, to move text around or to delete text. For information about using the Edit menu in different windows, see Where the Edit Menu Works.

You can cut, copy, or paste text using the Clipboard. The Clipboard is a temporary storage area for information you want to move or copy from one location to another.

Choose from the following commands:

Undo or Redo

Cut

Copy

Paste

Delete

Select All

Clear Results

Insert from File...

Copy to File...

Search

Build Expression...

Execute Selection


See Also

Edit Menu (Text Editor)

Program Menu (Command Window)


Edit | Clear Results

See Also

Erases the contents of the results pane of the Command window. This command does not copy the text to the Clipboard.

For information about using the Edit menu in different windows, see Where the Edit Menu Works.


See Also

Edit|Cut

Edit|Select All


Edit | Insert from File...

See Also	Language

Inserts text from a text file into the active window.

Use this command to insert program code or information from other files to reuse in your current file or window.

Specify the name and location of the file to insert in the Insert from File dialog box.

If you are editing a program, the dialog box displays files with the file extension .PRG.

If you are editing a memo field, text file, or command lines in the Command window, the dialog box displays all files.

To insert a file with a different extension, such as .DAT, enter the file-name skeleton in the File Name text box, for example, *.DAT. For general information about choosing files, see Open File dialog box.

The intended use of this command is to insert text-only files. If you specify a nontext file, dBASE inserts the file character-by-character until a Ctrl+Z (ASCII 26) or null (ASCII 0) character is found.

You can insert a text file of any size, until the active window reaches the limit of your computer memory. The Text Editor built into dBASE for Windows supports a line length of 32,767 characters. However, the maximum line length recognized in a dBASE for Windows program is 4096. You can choose your own text editing tool with the Program Editors option on the Files page in the Desktop Properties dialog box. See Properties|Desktop for more information.


See Also

Edit|Build Expression

Edit|Copy to File

Edit|Paste

Saving Text and Text Files


Language

COPY FILE

REPLACE

REPLACE MEMO


Edit | Copy to File...

See Also	Language

Copies all or selected text to a text file.

Use this command to copy program code or information to another file so you can reuse it later or separate it into smaller files.

To select text, click and drag the mouse over it or use Shift and the arrow keys to move the insertion point through the text. If no text is selected, dBASE copies the contents of the entire active window.

This command asks you to specify the name and location of the text file in the Copy to File dialog box. The default file extension depends on what type of file you are editing.

If you are editing a memo field, text file, or command lines in the Command window, and you do not specify a file extension, the file is saved with no file extension.

If you are editing a program and you do not specify a file extension, the file is saved with the file extension .PRG.

To specify a different file extension, type the file name including extension in the File Name text box. For general information about saving files, see Save As dialog box.

If you choose an existing file name, a dialog box appears, asking if you want to replace the existing file:

To replace the file, choose Yes.

To return to the Copy to File dialog box without replacing the file, choose No.


See Also

Copying, Cutting, and Pasting Text Between Windows

Edit|Build Expression

Edit|Insert from File

Edit|Paste


Language

COPY FILE

COPY MEMO

SET SAFETY


Edit | Search

Displays a cascading menu. From the menu, choose a command to search for text and optionally replace it with other text.

Choose from the following commands:

Find Text...

Find Next Text

Replace Text...


Edit | Search | Find Text...

See Also	Language

Searches for an occurrence of the specified text in the active window.

You can search for text in the Command window or in the Text Editor window. If you select text in the window before choosing the command, it appears in the Find What text box.

Specify the text to find and the search options, then choose Find. If the text is found, it is selected. Press the Find button until you find the text you want, then choose Close. If the end of the window is encountered and you did not start the search from the beginning of the window, dBASE asks if you want to continue searching from the top of the window.

Settings you make in this dialog box are temporarily saved. You can choose Edit|Search|Find Next Text or press Ctrl+K to repeat the last Find Text command.

Shortcuts

SpeedBar:

SpeedMenu:	Find Text...

Keyboard:	Ctrl+F

Dialog Box Options

Find What

Specifies the text to look for. By default, the word the insertion point is on or the currently selected text appears in the Find What text box.

Match Whole Words

Searches for the text as a group of characters surrounded by, but not including spaces or punctuation. When the Match Whole Words option is off, the search finds the text within longer words. For example, if Match Whole Words is on, this command finds "MODI" only if it is a word, not if it is the beginning of "MODIFY". By default, Match Whole Words is off.

Match Case

Differentiates between uppercase and lowercase letters when searching. For example, "Company Name" is different from "company name" when Match Case is on. By default, Match Case is off.

Direction

Specifies which way to search. The default is Down.

Up

Searches from the current position to the beginning of the file or selected text.

Down

Searches from the current position to the end of the file or selected text.


See Also

Edit|Search

Edit|Find Next Text

Edit|Replace Text...

Table|Find Record...

Table|Replace Record...


Language

AT( )

FIND

MODIFY COMMAND

MODIFY FILE


Edit | Search | Find Next Text

See Also

Repeats the last Edit|Search|Find Text operation, using the same settings as you last used in the Find Text dialog box.

This command does not display the Find Text dialog box, but uses its last settings. If you choose Edit|Search|Find Text again, the settings are reset to the default values.

Find Next Text is unavailable if you have not performed a Find Text operation.

Shortcuts

SpeedMenu:	Find Next Text

Keyboard:	Ctrl+K


See Also

Edit|Search

Edit|Find Text

Edit|Replace Text...


Edit | Search | Replace Text...

See Also	Language

Searches for an occurrence of the specified text in the active window and replaces it with other text.

You can search and replace text in the Command window or in the Text Editor window. If you select text in the window before choosing the command, it appears in the Find What text box.

Specify the text to find, the replacement text, and the search options, then choose Find. If the text is found, it is selected. Then do one of the following:

Choose Replace to replace the text and find the next occurrence of the text.

Choose Find to skip to the next occurrence of the text.

At any time, you can choose Replace All to replace all occurrences of the text. Choose Close to close the dialog box.

If the end of the window is encountered and you did not start the search from the beginning of the window, dBASE asks if you want to continue searching from the top of the window.

Shortcuts

SpeedBar:

SpeedMenu:	Replace Text...

Keyboard:	Ctrl+R

Dialog Box Options

Find What

Specifies the text to look for. By default, the word the insertion point is on or the currently selected text appears in the Find What text box.

Replace With

Specifies the replacement text.

Match Whole Words

Searches for the text as a group of characters surrounded by, but not including spaces or punctuation. When the Match Whole Words option is off, the search finds the text within longer words. For example, if Match Whole Words is on, this command finds "MODI" only if it is a word, not if it is the beginning of "MODIFY". By default, Match Whole Words is off.

Match Case

Differentiates between uppercase and lowercase letters when searching. For example, "Company Name" is different from "company name" when Match Case is on. By default, Match Case is off.

Direction

Specifies which way to search. The default is Down.

Up

Searches from the current position to the beginning of the file or selected text.

Down

Searches from the current position to the end of the file or selected text.


See Also

Edit|Search

Edit|Find Text

Edit|Find Next Text

Table|Find Record

Table|Replace Record


Language

MODIFY COMMAND

MODIFY FILE

REPLACE


Edit | Build Expression...

See Also	Language

Opens the Expression Builder.

Use the Expression Builder to construct a dBASE expression and insert it into the active window. The expression then appears at the current insertion point position.

This command is unavailable when you are editing memo fields.

Shortcuts

SpeedBar:

SpeedMenu:	Build Expression...

Keyboard:	Ctrl+E


See Also

About dBASE Expressions

Building an Expression in the Expression Builder - Overview

Opening the Expression Builder


Language

GETEXPR( )


Edit | Execute Selection

See Also	Language

Executes the current command line or selected text as if it were typed in sequence from the Command window.

To select multiple command lines, click and drag the mouse over them, or use Shift and the arrow keys to move the insertion point through the text. Press Enter or choose Edit|Execute Selection to run the commands. Each command line runs in sequence. If any line contains a syntax error, none of the command lines run.

This command is unavailable when you are editing memo fields or text files.

Shortcuts

SpeedBar:

SpeedMenu:	Execute Selection

Keyboard:	Enter


See Also

Program|Compile...

Program|Do...


Language

COMPILE

DO


File Menu (Command Window)

Use the File menu to create new files, open and run existing files, print files, and exit dBASE for Windows.

The New and Open commands manipulate the primary file types, such as tables, queries, and forms. The New command displays a menu allowing you to choose the type of file you want to create. The Open command lets you run or design an existing file.

You can open as many files as you like, and each appears in its own window. However, the Navigator and Command windows are unique and cannot be opened more than once.

Choose from the following commands:

New

Open...

Close

Import...

Exit

(closed file list)


Program Menu (Command Window)

Use the Program menu to run, compile, debug, and analyze your programs.

Choose from the following commands:

Do...

Compile...

Debug...

Display Coverage...


Program | Do...

See Also	Language

Executes the statements in a dBASE program.

Use Do to run a program. If you invoke this command from the Text Editor, the program in the active window runs. If you invoke this command from the Command window, you must specify the name and location of the program in the Execute Selection dialog box. Program files are displayed by default and have the file type "Programs (*.PRG, *.WFM, *.PRO)." To open a file with a different extension, enter the file-name skeleton in the File Name text box. For example, you could enter *.FMT to view format files. For general information about opening files, see Open File dialog box.

If necessary, this command compiles the .PRG file into a .PRO file. .PRO is the file extension of dBASE object files. An object file is a file ready to be linked to libraries and resources to create a target file, such as an executable file (.EXE) or dynamic link library (.DLL).

Note:	If you use a different file extension from .PRG for your programs, avoid ending the file extension with the letter O. Object files have the same file extension as the program file, except the last character is O. If the program file extension ends in O, the object file extension is the same as the program file, and the program file is overwritten.

When you run a program with Program|Do, if Ensure Compilation is checked in the Desktop Properties dialog box, dBASE compares the date and time of .PRG and .PRO files to see if recompilation is necessary. If Ensure Compilation is unchecked, the .PRG is not recompiled unless no .PRO file exists.

To compile a program without running it, choose Program|Compile.

If your program contains errors, the Program Alert dialog box appears. It displays the error, file, routine, and line number and asks how you want to handle the error.

If your program calls other programs, or procedures and user-defined functions in another file, these are also compiled and run. To compile a single program but not all its called programs, procedures, and user-defined functions, use Program|Compile.

Shortcuts

Menu:	Navigator|Do (from selected program)
Catalog|Do (from selected program)

SpeedBar:
 (from selected program in Navigator or Catalog window)

SpeedMenu:	Do (from selected program in Navigator or Catalog window)

Keyboard:	Ctrl+D
F2 (from selected program in Navigator or Catalog window)

Mouse:	Double-click program file in Navigator or Catalog window.
Drag program file from Navigator or Catalog window onto the Desktop or Command window.


See Also

Program Menu (Command window)

Program Menu (Text Editor)

Compiling Programs

Edit|Execute Selection

Program|Compile

Program|Debug

Program|Display Coverage

Properties|Desktop

Running Files in the Command Window


Language

COMPILE

DO

SET DEVELOPMENT

SET PROCEDURE


Program Alert Dialog Box

See Also	Language

Displays an error message and supplies several ways to handle it.

This dialog box appears when you compile or run a program containing syntax or run-time errors. dBASE stops compiling when a syntax error is encountered, and does not create an object file.

Dialog Box Options

Error

States the error that occurred. See Error Messages for information on dBASE for Windows error messages.

File

Displays the program path and file name in which the error occurred.

Routine

Displays the procedure or user-defined function in which the error occurred. If the error occurred in the main program, the Routine is the same name as the file.

Line

Displays the line number on which the error occurred.

Fix

Opens the program file in the Text Editor and places the insertion point on the line with the error.

Ignore

Disregards a syntax or run-time error. If you ignore a run-time error, the program continues running. If you ignore a syntax error at run time, the program stops running. If you ignore a syntax error at compile time, the program stops compiling.

Suspend

Suspends execution of the program at the line where a run-time error occurred and returns you to the Text Editor or Command window. You can then check and change the status of files, memory variables, or the dBASE environment. Type RESUME to continue the program. Type CANCEL to cancel the program.

Debug

Opens the dBASE for Windows Debugger, where you can debug the program line by line. This option is available only for run-time errors.

Cancel

Stops running or compiling the program, and returns to the Text Editor or Command window. If it is a syntax error, no object file is created. If it is a run-time error, the object file remains on the disk.


See Also

Program|Compile

Program|Debug

Program|Do

Error Messages


Language

CANCEL

COMPILE

DO

ERROR( )

MESSAGE( )

MODIFY COMMAND

RESUME

SET PROCEDURE

SUSPEND


Program | Compile...

See Also	Language

Compiles a dBASE program (.PRG) into an object file (.PRO).

If you invoke this command from the Text Editor, the program in the active window is compiled. If you invoke this command from the Command window, you must specify the name and location of the program in the Compile Program dialog box. Program files are displayed by default and have the file type "Programs (*.PRG, *.WFM)." To open a file with a different extension, enter the file-name skeleton in the File Name text box. For example, you could enter *.FMT to view format files. For general information about opening files, see Open File dialog box.

This command compiles the .PRG file into a .PRO file. .PRO is the file extension of dBASE object files. An object file is a file ready to be linked to libraries and resources to create a target file, such as an executable file (.EXE) or dynamic link library (.DLL).

This command recompiles the program, whether or not the program file has changed since the last time you compiled.

A Compilation Status dialog box displays the status as the file is compiled.

Note:	If you use a different file extension from .PRG for your programs, avoid ending the file extension with the letter O. Object files have the same file extension as the program file, except the last character is O. If the program file extension ends in O, the object file extension is the same as the program file, and the program file is overwritten.

To compile a program, if necessary, and run it, choose Program|Do.

If your program contains errors, the Program Alert dialog box appears. It displays the error, file, routine, and line number and asks how you want to handle the error.

If your program calls other programs, or procedures and user-defined functions in another file, these are not compiled. To compile a program and all its called programs, procedures, and user-defined functions, use Program|Do.


See Also

Program Menu (Command window)

Program Menu (Text Editor)

Compiling Programs

Edit|Execute Selection

Program|Debug

Program|Display Coverage

Program|Do

Running Files in the Command window


Language

COMPILE

DO

SET DEVELOPMENT

SET PROCEDURE


Compilation Status Dialog Box

See Also	Language

Displays the status as your program is compiled.

The Compilation Status dialog box appears when you choose Program|Compile.

To disable the Compilation Status dialog box, set Talk off in the Desktop Properties dialog box. Choose the Programming page, then uncheck Talk.

The information displayed includes:

Current File Name	The name of the program source file
Line	The line number being compiled
Executable Lines	The number of nonblank lines
Warnings	The number of warnings given for this program
Routines	The number of subroutines (programs, procedures, or functions) compiled
Total Lines	The number of lines in the program source files
Total Executable Lines	The number of nonblank lines compiled
Total Files	The number of files compiled, including called subroutines in other files
Total Errors	The number of errors found in the files
Total Warnings	The number of warnings given
Total Routines	The number of subroutines counted and compiled, including the main program
Set Coverage	States whether coverage files will be created when the program runs


See Also

Program|Display Coverage

Properties|Desktop


Language

DISPLAY COVERAGE

COMPILE

DO

SET COVERAGE

SET TALK


Program | Debug...

See Also	Language

Compiles the selected program, if necessary, then opens it in the dBASE for Windows Debugger.

If you invoke this command from the Text Editor, the program in the active window is opened in the Debugger. If you invoke this command from the Command window, you must specify the name and location of the program in the Debug Program dialog box. Program files are displayed by default and have the file type "Programs (*.PRG, *.WFM, *.PRO)." To open a file with a different extension, enter the file-name skeleton in the File Name text box. For example, you could enter *.FMT to view format files. For general information about opening files, see Open File dialog box.

With the Debugger, you can find logical errors in the program or errors that occur when the program is running. This command does the following:

Opens the Debugger with a blank Module window.

Recompiles the source file, if necessary, to create a valid object file. If syntax errors are found, the Program Alert dialog box appears, and you must correct the errors before using the Debugger.

Loads the program into the Module window and selects the first line. Use the Debugger commands to run the program line by line, inspect variables, and set breakpoints.

Shortcuts

Menu:	Navigator|Debug (from selected program)
Catalog|Debug (from selected program)

SpeedBar:

SpeedMenu:	Debug (from selected program in Navigator or Catalog window)


See Also

Program Menu (Command window)

Program Menu (Text Editor)

Program|Compile...

Program|Display Coverage...

Program|Do...


Language

CANCEL

DEBUG

RESUME

SUSPEND


Program | Display Coverage...

See Also	Language

Displays the contents of a coverage file in the results pane of the Command window.

Display Coverage displays the binary file resulting from the coverage analysis tool. The file contains information on how many times dBASE enters and exits each logical block of a program. Coverage analysis is a technique you can use to determine which program lines have executed and which lines have not executed and therefore still need to be tested. The coverage file identifies each logical block by its program line number.

To use coverage analysis, check Coverage in the Desktop Properties dialog box, then compile and run the program.

If you invoke this command from the Text Editor, the coverage file corresponding to the program in the active window appears. If you invoke this command from the Command window, you must specify the name and location of the coverage file in the Display Coverage dialog box. Coverage files are displayed by default and have the file type "Coverage (*.COV)." For general information about choosing files, see Open File dialog box.


See Also

Program Menu (Command window)

Program Menu (Text Editor)

Analyzing Program Coverage

Properties|Desktop


Language

DISPLAY COVERAGE

SET COVERAGE


Properties Menu (Command Window)

Use the Properties menu to change the characteristics of the dBASE for Windows Desktop and the Command window.

Choose from the following commands:

Desktop...

Command Window...


Properties | Command Window...

See Also

Changes the characteristics of the Command window.

Use the Command window to

Enter and see the results of dBASE commands.

View commands as the user interface sends them to the input pane.

Run dBASE IV and dBASE III PLUS programs.

dBASE records the choices you make in this dialog box in the DBASEWIN.INI file.

Shortcuts

SpeedMenu:	Command Window Properties...

Dialog Box Options

Input Pane Position

Sets how the panes in the Command window are displayed.

Top

Displays the input pane above the results pane.

Bottom

Displays the input pane below the results pane.

Left

Displays the input pane to the left of the results pane.

Right

Displays the input pane to the right of the results pane.

Fonts

Sets the fonts used to display information in the two panes of the Command window.

Input Pane

Specifies the font to use for the input pane. Click [image] to open the Font dialog box, then choose a font, style, size, effects, and color.

Results Pane

Specifies the font to use for the results pane. Click [image] to open the Font dialog box, then choose a font, style, size, effects, and color.

Reset Fonts

Sets the font selections for the input pane and the results pane to their default values.


See Also

Properties Menu (Command Window)

Changing the Appearance of the Command Window

Clearing the Command Window Panes

Command Window Components


Table Menu (Command Window)

See Also

Use the Table menu to find and replace records, access table utilities, append, delete, lock, and blank records, and navigate in the table.

Choose from the following commands:

Find Records...

Replace Records...

Table Utilities

Edit Records

Add Records


See Also

Table Menu (Table Records window)


Using the Expression Builder

Use the Expression Builder to construct a dBASE expression and paste it into the current field or window.

Expression Builder Concepts and Tasks

Choose from the following list for information about expressions and about using the Expression Builder:

What You Can Do with the Expression Builder

About dBASE Expressions

Getting Online Help in the Expression Builder

Expression Builder Tasks

Expression Builder Components

Click the names next to the following illustration for information about each part.

	Expression box and the Safety Net Undo, Group, and Evaluate buttons information panel  Element list boxes information panel  OK, Cancel, and Help buttons


What you Can Do with the Expression Builder

See Also

Use the Expression Builder to build a dBASE expression and paste it into the current field or window.

You can type an expression or parts of an expression directly into the Expression box. Or, you can choose expression elements from the list boxes and paste them into the Expression box, thereby building the expression from its constituent parts.

The Safety Net is a feature that prevents you from constructing an illegal expression. It also helps you accomplish certain tasks, such as grouping elements to establish precedence.

With the Safety Net on or off, you can use the lists and hints in the Expression Builder to remind you what you can use to build an expression and to remind you of the correct syntax for the elements.

Use the Evaluate button to evaluate an expression before you paste it into place. You can use this feature to try out expressions and to calculate results from an expression, even if you do not plan to paste the expression anywhere else.


See Also

About the Expression Box and the Safety Net

Building an Expression in the Expression Builder- Overview

Opening the Expression Builder

Turning the Safety Net On or Off

Using the List Boxes to Add Elements to an Expression

Selecting and Deleting Items in the Expression Box

Editing Placeholders in the Expression Box

Editing Constants in the Expression Box

Grouping Elements to Establish Precedence

Evaluating Expressions in the Expression Builder

Pasting Expressions from the Expression Builder


About dBASE Expressions

See Also

An expression is one or more dBASE elements that evaluate to a single value. These are some examples of expressions:

UPPER(TRIM(LName) + ", " + UPPER(FName))

Mfilesize = (RECCOUNT() * RECSIZE()) + 2000)

120000 / 3

Elements that can be used in an expression are:

Field names

Constants

Functions

Operators

Memory variables

Array elements

An expression must evaluate to a single data type (character, date, logical, or numeric). You can create an expression from elements of different data types, but you must use one or more data-type conversion functions so that all the elements are converted into the same data type. When you use a comparison operator, the expressions on either side of the operator must be the same data type, and the comparison operator always turns the expression into a logical expression. See Language Reference for more information about data-type conversion functions.

In the dBASE language, the different expressions types are represented by these placeholders:

<expC>	Character

<expD>	Date

<expL> or <condition>	Logical

<expN>	Numeric

<exp> 	An expression of any type

Single-element Expressions

A single element can be an expression. For example, the field name YTD_SALES, the memory variable PassCnt, the date {09/01/94}, and the constant 16 are all expressions:

YTD_SALES evaluates to the value of the YTD_SALES field in the current record

PassCnt evaluates to its current value, for example 12.

{09/01/94} evaluates to itself, the date 09/01/94

16 evaluates to itself, the numeric value 16

Expressions Using Functions and Operators

More complex expressions are constructed of one or more of the following:

A function or functions used to transform a value (or another expression)

An operation consisting of two or more values (or expressions) that are compared or calculated using one or more operators

For example,

MDY({09/01/94}) evaluates to September 01, 94

17 + (8 * 3) evaluates to 41

UPPER(LName) + ", " + UPPER(FName) + ":  " + STR(Salary) evaluates to (for example) AMBERSON, FAY:  34,500

See Language Reference for more information about functions. See Language Reference for more information about operators.

Difference Between Commands and Expressions

Commands are the verbs of the dBASE language. An expression represents a value and thus does not contain a command. A complete language statement is usually made up of a command and one or more expressions.

The Expression Builder does not create whole command statements. It only creates expressions. For example, to enter the statement SET FILTER TO ZIP_POSTAL>"9000" in the Command Window, type  "SET FILTER TO" (the command portion of the statement) and then open the Expression Builder to create the expression ZIP_POSTAL>"9000". When you press OK in the Expression Builder, the expression is pasted into place in the Command Window.


See Also

Using the Expression Builder


Getting Online Help in the Expression Builder

See Also

There are two kinds of context-sensitive online Help available in the Expression Builder:

Explanations and instructions on how to use the Expression Builder. You are reading part of that Help right now.

Language Reference Help for the functions, operators, and other elements you can use to build an expression.

To display the main Help topic for the Expression Builder, do one of the following:

Click the Help button at the bottom of the Expression Builder.

Press F1 when the Safety Net check box, the Expression box, or any of the buttons have focus.

To display Help for one of the categories of expression elements, do one of the following:

Click the item in the Category list box, and press F1.

Click any of the items in the Type list box for a category, and press F1.

Exception: When you press F1 after clicking one of the types of functions in the Type list box for Functions, a Help topic for that type of function is displayed.

To display Language Reference Help for an expression element,

Click the element in the Paste list box, and press F1.

Language Reference Help is displayed for these elements:

Functions

Operators

System memory variables

Exception: When you press F1 after clicking a constant, field, or user variable in the Paste list box, a general topic describing the type of element is displayed.


See Also

Using the Expression Builder

About dBASE Expressions


Expression Builder Tasks

See Also

For information about how to use the Expression Builder, choose from the following tasks:

Building an Expression in the Expression Builder- Overview

Opening the Expression Builder

Turning the Safety Net On or Off

Using the List Boxes to Add Elements to an Expression

Selecting and Deleting Items in the Expression Box

Editing Placeholders in the Expression Box

Editing Constants in the Expression Box

Grouping Elements to Establish Precedence

Evaluating Expressions in the Expression Builder

Pasting Expressions from the Expression Builder

Adding User-Defined Function to the Expression Builder Lists


See Also

Using the Expression Builder

About dBASE Expressions


Building an Expression in the Expression Builder- Overview

See Also

These steps do not have to be followed in exactly this order, except that steps #1 (starting the Expression Builder) is first and #7 (pasting the expression into the window or field) is last.

To build an expression using the Expression Builder,

1.	Open the Expression Builder. See Opening the Expression Builder.

2.	Turn the Safety Net on or off. See:

About the Expression Box and the Safety Net

Turning the Safety Net On or Off.

3.	Select elements from the list boxes and paste them in to the Expression box.

See Using the List Boxes to Add Elements to an Expression.

4.	Edit placeholders and constants (if any) in the Expression box. See:

Selecting and Deleting Items in the Expression Box

Editing Placeholders in the Expression Box

Editing Constants in the Expression Box

5.	If desired, group elements to establish precedence, that is, the order in which the parts of the expression will be evaluated. See Grouping Elements to Establish Precedence.

6.	If desired, click the Evaluate button to evaluate the expression. See Evaluating Expressions in the Expression Builder.

7.	Click OK to paste the expression into the current window or field, that is, wherever the cursor was when you launched the Expression Builder. See Pasting Expressions from the Expression Builder.


See Also

Using the Expression Builder

About dBASE Expressions

Getting Online Help in the Expression Builder

Opening the Expression Builder

Turning the Safety Net On or Off

Using the List Boxes to Add Elements to an Expression

Selecting and Deleting Items in the Expression Box

Editing Placeholders in the Expression Box

Editing Constants in the Expression Box


Opening the Expression Builder

See Also

To open the Expression Builder, do one of the following:

Click [image] on the SpeedBar when you are in the Text Editor.

Choose Edit|Build Expression or press Ctrl-E when you are in the Command window or Text Editor.

Type GETEXPR() in the Command window, or include GETEXPR() in a program. To assign the value returned by the expression to a variable, type or include:

 <variable name> = GETEXPR()

where <variable name> is the name of the variable.

For more information about the GETEXPR() function, see GETEXPR() in the Language Reference.

Click [image] when it appears next to a field where you can enter an expression. For example, this button appears next to the Key Expression and For fields in the Create Index Tag dialog box.

Opening the Expression Builder with Existing Text

If you select text in a window or field and then open the Expression Builder, the selected text appears in the Expression box of the Expression Builder. (Select text by clicking and dragging across it or by double-clicking between two spaces.)

Opening the Expression Builder with a Required Data Type

When you open the Expression Builder from a location that requires a certain data type, the Expression Builder automatically checks that the expression evaluates to the correct data type. For example, a For or While field requires a logical expression. When you open the Expression Builder from a For or While field in a dialog box, the Expression Builder checks to ensure that the expression is a logical expression.

When a certain data type is required, the required data type is specified in a message that appears to the left of the OK button.

When a certain data type is required, you cannot paste the expression unless it evaluates to the correct data type.


See Also

Using the Expression Builder

About dBASE Expressions


Working with the Safety Net (Expression Builder)
Turning the Safety Net On or Off

See Also

To turn the Safety Net on,

 	Check the Safety Net check box.

The Expression box becomes gray (or another color, depending on your Windows color settings), and you cannot type directly in it. You must paste items into it by double-clicking elements in the Paste list box.

Note: You cannot turn the Safety Net on if the expression in the Expression window contains placeholder elements. You must replace the placeholders with real values before you can switch the Safety Net on.

To turn the Safety Net off,

 	Uncheck the Safety Net check box.

The Expression box becomes white (or another color, depending on your Windows color settings), and you can type directly in it. You can still also paste items into it by double-clicking elements in the Paste list box. You can also cut, copy, and paste items with the Windows clipboard commands (Ctrl+X to cut, Ctrl+C to copy, and Ctrl+V to paste).

You cannot turn the Safety Net off unless the Expression box is blank or it contains a valid expression.


See Also

Using the Expression Builder

About dBASE Expressions

About the Expression Box and the Safety Net

Using the List Boxes to Add Elements to an Expression

Selecting and Deleting Items in the Expression Box

Editing Placeholders in the Expression Box

Editing Constants in the Expression Box


Constructing Expressions from the Expression Builder List Boxes
Using the List Boxes to Add Elements to an Expression

See Also

You build expressions, in part, by adding expression elements to the Expression box. You can type elements directly into the Expression box when the Safety Net is off. Or you can paste elements into it whether the Safety Net is on or off.

Use the list boxes in the lower half of the Expression Builder to select the elements to paste into the Expression box.

Choosing Elements from the List Boxes

Work from left to right to narrow down the choices. Then choose an element from the Paste list on the right to paste it into the Expression box. The following illustration shows this process:

       Expression box

Categories (most general)	Types or Fields (subcategories)	Paste (most specific)
1) Click a category to display its subcategories in the Types or Fields list box.	2) Click the subcategory to display its elements in the Paste list box.	3) Paste one of these expression elements into the Expression box (as described below).
To paste an element from the Paste list box, do one of the following:

Double-click the element.

Select the element by clicking it once (or by clicking anywhere in the Paste list box and pressing the arrow keys to reach it). Then press the Spacebar.

Drag the element to the Expression box and release the mouse button.

The element is pasted into the current position, as described below. The only exception to this is when you drag an operator onto an "Op" placeholder. In that case, the current position, as indicated by the insertion point, is ignored. The operator replaces the placeholder onto which it was dropped.

About the Current Position in the Expression Box

The current position, also called the "insertion point,"  is indicated by a blinking or nonblinking vertical bar. The current position can be one of the following:

Between two adjacent elements

To specify this position, click between the elements. When you paste the new element, it is pasted between the two adjacent elements. When the Safety Net is on and the insertion point is touching a placeholder for a value or an operator, the entire placeholder is replaced by the new element.

At the end of all the elements already in the Expression box

To specify this position, click to the right or below all the elements. If you have added elements to the Expression box and have not moved the insertion point, this last position is the current position.

When you drag an element from the Paste list box into any empty area in the Expression box, the element is pasted into the last position in the Expression box, if you have not specified a different insertion point.

A selected sequence of characters

To specify this position, select the sequence of characters by clicking and dragging or by double-clicking between two spaces.

When you paste an element from the Paste list box into this position, all of the selected characters or elements are replaced.

About the Different List Boxes

See these topics for more information about the categories of expression elements and their list boxes:

Category List Box

Expression Element Lists: Constants

Expression Element Lists: Fields

Expression Element Lists: Functions

Expression Element Lists: Operators

Expression Element Lists: Variables


See Also

Using the Expression Builder

About dBASE Expressions

Selecting and Deleting Items in the Expression Box


Selecting and Deleting Items in the Expression Box

See Also

Selecting Items

Select items in the Expression Box in the same way you select them in fields and the Text Editor:

To select a sequence of characters, click where you want to start selecting. Hold the mouse button down and drag until the entire selection is highlighted. Release the mouse button.

To select all the characters between two spaces (for example, a word or a date), double-click anywhere on the sequence of characters.

Deleting Items

To delete an item, select it, then do one of the following:

Press Delete.

Start typing new text to replace the selected item(s).

Select and paste a new element to replace the selected item(s).


See Also

Using the Expression Builder

About dBASE Expressions

Turning the Safety Net On or Off

Using the List Boxes to Add Elements to an Expression

Editing Placeholders in the Expression Box

Editing Constants in the Expression Box


Editing Placeholders in the Expression Box

See Also

In many cases, when you paste elements into the Expression box, placeholders are pasted in positions where you must supply values. For example, when you double-click the INT() function in the Paste list box, INT(expN) is pasted into the Expression box. You must replace expN with a number constant or a numeric expression.

How Placeholders Look with the Safety Net On

When the Safety Net is on, placeholders appear in color.

A placeholder for an expression appears in yellow, for example

The placeholder for an operator is "Op," and it appears in white, for example

To edit placeholders when the Safety Net is off,

Select the placeholder, for example expN, and type a constant or other expression. You can also select it and then paste a constant or build another expression from the Paste list box. The expression must be the type indicated by the placeholder. For example, if the placeholder is expN, you must use a valid numeric expression.

To edit placeholders when the Safety Net is on,

Select the placeholder, for example expN, and paste a constant from the Paste list box, or build another expression using the list boxes. The expression must be the type indicated by the placeholder.


See Also

Using the Expression Builder

About dBASE Expressions

Turning the Safety Net On or Off

Using the List Boxes to Add Elements to an Expression

Selecting and Deleting Items in the Expression Box

Editing Constants in the Expression Box


Editing Constants in the Expression Box

See Also

Typically, when you paste a constant into the Expression box, you will want to change the value of the constant. For example, you always must paste 0 if you want to add a number. To use a number other than zero, you must replace the zero with that number.

To edit constants when the Safety Net is off,

Select the part of the constant you want to replace and type the new value.

If you select any delimiters such as quotation marks (""), slashes (/), or curly braces ({}), you must type them back in when you type the new value.

For logical values, type .f., .F., .t., .T., .n., .N., .y., or .Y.

To edit constants when the Safety Net is on, do one of the following:

Double-click the constant to select it, and type a new value.

When you start typing, an entry field opens beneath the constant. You do not have to type the delimiters for character or date constants. Quotation marks are added for character strings, and curly braces are provided for dates.

Right-click the constant.

For character, date, and numeric values, the existing value appears in an entry field beneath the constant. To replace the entire constant, type the new value. To replace only part of the value, select the part you want to replace, and type the new value.

When you right-click a logical value, the value is toggled from true to false or from false to true.


See Also

Using the Expression Builder

About dBASE Expressions

Turning the Safety Net On or Off

Using the List Boxes to Add Elements to an Expression

Selecting and Deleting Items in the Expression Box

Editing Placeholders in the Expression Box


Grouping Expression Elements to Establish Precedence

See Also

Place parentheses around expression elements to establish the order in which they will be evaluated. Elements within parentheses are always evaluated first. For example, (3 + 4) * 2 evaluates to 14, but 3 + (4 * 2) evaluates to 11.

To group elements with the Safety Net on,

Select the elements and click Group. Parentheses are placed around the selected elements.

To group elements with the Safety Net off,

Click where you want to start the group and type an open parenthesis. Then click where you want to end the group, and type a close parenthesis.


See Also

Using the Expression Builder

About dBASE Expressions

Turning the Safety Net On or Off

Selecting and Deleting Items in the Expression Box


Evaluating Expresssions in the Expression Builder
Evaluating Expressions in the Expression Builder

See Also

To evaluate an expression means to perform the calculations and comparisons specified in the expressions. For example, when you evaluate 2 + 5, the result is 7. When you evaluate "Tom" = "Rita" the result is .F. (false).

You can evaluate an expression before pasting it from the Expression Builder into a field or window. That way, you can check the result before placing the expression in a context in the field, window, or program.

To evaluate an expression,

Click Evaluate, in the upper right corner of the Expression Builder. The result is displayed in the information panel beneath the Expression box.


See Also

Using the Expression Builder

About dBASE Expressions


Pasting Expressions from the Expression Builder

See Also

Click OK to paste the expression from the Expression box into the location from which you opened the Expression Builder. The expression is pasted at the insertion point in the field or window from which you opened the Expression Builder.

If the expression is not valid, for example if the syntax is wrong, the OK button is dimmed when you click it. You must correct the expression before you can paste it.

Opening the Expression Builder with a Required Data Type

When you open the Expression Builder from a location that requires a certain data type, the Expression Builder automatically checks that the expression evaluates to the correct data type. For example, a For or While field requires a Logical expression. When you open the Expression Builder from a For or While field in a dialog box, the Expression Builder checks to ensure that the expression is Logical.

When a certain data type is required, the required data type is specified in a message that appears to the left of the OK button.

When a certain data type is required, you cannot paste the expression unless it evaluates to the correct data type.


See Also

Using the Expression Builder

About dBASE Expressions


Adding User-Defined Functions to the Expression Builder Lists

See Also

A user-defined function (or UDF) is a custom function created with the dBASE FUNCTION command. You can add these UDFs to the list boxes in the Expression Builder so you can paste them into the Expression box, just like any other expression element.

The information for the UDFs is stored in the DBASEWIN.FNF file. This file is installed in the same directory as the DBASEWIN.EXE file, which is the DBASEWIN\BIN directory when you accept the suggested directories during installation. DBASEWIN.FNF contains the following fields:

Field name	Description
NAME	Name of the function, for example, TAGCOUNT
NAME_EXT	One or more dots (periods) to indicate that there are alternative versions of this function. Most of the time this field will be blank.
PURPOSE	A description of the function.
ARGUMENTS	Comma-delimited list of arguments for the function in the NAME field.
CATEGORIES	Comma-delimited list of language element types that are displayed in the Type list box for functions.
When you click a function in the Paste list box, information from the DBASEWIN.FNF table is displayed in the information panel beneath the list boxes.

The first line in the message panel is constructed from:

The name in the NAME field

Open parenthesis

The arguments from the ARGUMENTS field

Close parenthesis

The second line in the message panel contains the text from the PURPOSE field.

To add UDFs to the Expression Builder lists,

1.	Open DBASEWIN.FNF by typing USE DBASEWIN.FNF in the Command window. (You cannot open it from the Navigator because it does not have a .DBF extension.)

2.	Add the information for the function to the table, as described in the table above.

The function can appear in more than one category. Separate category names with commas. You can also create a new category by entering its name in the Category field.

You cannot change the field names listed in the table. You can add other fields, but they are ignored by the Expression Builder. All fields are Character data type. You can change the size of the fields.

3.	Save and close the table.


See Also

Using the Expression Builder

About dBASE Expressions

FUNCTION


The Expression Box and the Safety Net
About the Expression Box and the Safety Net

See Also

The Expression box is the area at the top of the Expression Builder where you type expressions or build them by pasting elements from the Expression Builder list boxes. Directly below the Expression box is a panel that displays information about the expression you are building.

	Expression box Safety Net check box information panel
About the Safety Net

The Safety Net is a feature that allows or prevents typing directly in the Expression box. It is called a safety net, because when it is on, it helps you avoid mistakes as you build an expression.

When the Safety Net is on,

You cannot type directly in the Expression box.

Placeholders are identified with color, so you can readily see what you need to add to complete the expression.

The message panel beneath the Expression box reports how many placeholders you must fill in.

You can use the Group button to enclose selected items with parentheses to indicate precedence. (The Group button is available when you select all or part of a formula.)

When the Safety Net is off, you can type an expression directly in the Expression box. Use this feature if you know how to create an expression. You can still use all the other features in the Expression Builder to select and paste elements into the box.

Turning the Safety Net On and Off

To turn the Safety Net on, check the Safety Net check box. The Expression box turns gray (or another color, depending on your Windows color settings).

To turn the Safety Net off, uncheck the check box. The Expression box turns white (or another color, depending on your Windows color settings).


See Also

Using the Expression Builder

About dBASE Expressions

Turning the Safety Net On or Off

Using the List Boxes to Add Elements to an Expression

Selecting and Deleting Items in the Expression Box

Editing Placeholders in the Expression Box

Editing Constants in the Expression Box


Undo, Group, and Evaluate Buttons

See Also

The Undo and Group buttons are available only when the Safety Net is on.

Undo

Use the Undo button to undo the last action, that is, revert to the state in the Expression box before your last paste, edit, or delete.

Group

Use the Group button to group elements in the expression in order to specify precedence. Precedence is the order in which the elements in the expression are evaluated. For example, (3 + 4) * 2 evaluates to 14, but 3 + (4 * 2) evaluates to 11. To group elements with the Safety Net on, select the elements and then click Group. Parentheses are placed around the selected elements. (The Group button is available only when items are selected.)

Evaluate

Use the Evaluate button to evaluate the expression in the Expression box before pasting it into the field or window from which you call the Expression Builder. When you click Evaluate, the result appears in the message panel beneath the Expression box.


See Also

Using the Expression Builder

About dBASE Expressions

Turning the Safety Net On or Off

Grouping Elements to Establish Precedence

Evaluating Expressions in the Expression Builder


OK, Cancel, and Help Buttons (Expression Builder)
OK, Cancel, and Help Buttons

See Also

OK

Click OK to paste the expression in the Expression box into the location from which you opened the Expression Builder. The expression is pasted at the insertion point in the field or window from which you opened the Expression Builder.

If the expression is not valid, for example if the syntax is wrong, the OK button is dimmed when you click it. You must correct the expression before you can paste it.

Cancel

When you choose Cancel in the Expression Builder, the Expression Builder is closed. Any expression in the Expression box is lost.

Help

Displays Help for the Expression Builder (the topic you are reading is one of those Help topics).


See Also

Using the Expression Builder

Getting Online Help in the Expression Builder

Pasting an Expression from the Expression Builder


About the Expression Builder Expression Element Lists

See Also

The Expression Builder list boxes organize the elements you can use to build an expression.

The Category list on the left shows the main categories of elements that can be used to construct an expression. The elements in this list never change. When you click one of these, the middle box displays subcategories of the item you clicked. When you click one of the items from the middle list, the Paste list on the right displays the elements you can use in an expression. Double-click one of those items to paste it into the Expression box.

The information panel beneath the Expression box displays information about any function or system memory variable that has focus in the Paste list box.


See Also

Using the Expression Builder

About dBASE Expressions

Using the List Boxes to Add Elements to an Expression

Category List Box

Expression Element Lists: Constants

Expression Element Lists: Fields

Expression Element Lists: Functions

Expression Element Lists: Operators

Expression Element Lists: Variables


Category List Box

See Also

The Category list box on the left of the Expression Builder lists the categories of elements that can be used to construct an expression. Unlike the other list boxes in the Expression Builder, the content of this list does not change. It always contains Constant, Field, Function, Operator, and Variable.

Choose from the following list for more information about any of the categories:

Expression Element Lists: Constants

Expression Element Lists: Fields

Expression Element Lists: Functions

Expression Element Lists: Operators

Expression Element Lists: Variables


See Also

Using the Expression Builder

About dBASE Expressions

Using the List Boxes to Add Elements to an Expression


Expression Element Lists: Constants

See Also

When you choose Constant from the Category list box on the left of the Expression Builder, these items are displayed in the Type list box in the middle:

When you choose one of these items from the Type list box, a list of constants and delimiters appears in the Paste list box on the right. Double-click any of the items in the Paste list box to paste them into the Expression box.

Constants: Types and Elements

The Paste list of constants does not (and could not) contain all possible constants. It contains examples of certain constants along with delimiters and placeholders you can use to specify your own.

The following paragraphs show the types of constants you can choose in the Type list box, along with what appears in the Paste list for that type.

Character

"double quotes"

'single quotes'

[brackets]

Choose one of these items if you want to insert a character string into the expression. These items are the three kinds of delimiters available for enclosing a string. When you double-click one of these, the delimiters you chose (both the open and close delimiters) are pasted into the Expression box. Type the characters you want between the delimiters. (When the Safety Net is on, you must right-click the delimeters, then type the characters.)

Date

LastWeek	{MM/DD/YY}

NextWeek	{MM/DD/YY}

Today	{MM/DD/YY}

Tomorrow	{MM/DD/YY}

Yesterday	{MM/DD/YY}

Choose the appropriate item if you want to paste the actual date of a week ago today, a week from today, or to paste today's, tomorrow's, or yesterday's date. If you want to enter any other date, paste any one of these into the Expression box and edit it in place.

Logical

.F.

.T.

Choose .T. for True or .F. for False.

If the Safety Net is off, you can also type these alternative forms of logical values: .f., .t., .Y., .y., .N., and .n.

Numeric

0

Choose this item for any numeric value. If you want zero, you can paste this in without modification. For any other numeric value, paste this in and then edit it in place.


See Also

Using the Expression Builder

About dBASE Expressions

Using the List Boxes to Add Elements to an Expression

Expression Element Lists: Fields

Expression Element Lists: Functions

Expression Element Lists: Operators

Expression Element Lists: Variables


Expression Element Lists: Fields (in Open Tables)

See Also

When you choose Fields from the Category list box on the left of the Expression Builder, the names of the tables that are open in the current work area are displayed in the Table list box in the middle:

When you choose one of these tables from the Table list box, the fields in that table appear in the Paste list box on the right. Double-click any of those fields to paste it into the Expression box.


See Also

Using the Expression Builder

About dBASE Expressions

Using the List Boxes to Add Elements to an Expression

Expression Element Lists: Constants

Expression Element Lists: Functions

Expression Element Lists: Operators

Expression Element Lists: Variables


Expression Element Lists: Functions

See Also

When you choose Function from the Category list box on the left of the Expression Builder, these items are displayed in the Type list box in the middle:

This is a list of the types of dBASE functions. Each item in the list describes a group of related functions. When you choose one of these items from the Type list box, that group of functions appears in the Paste list box on the right. Double-click any of those functions to paste it into the Expression box.

The names of the functions in the list do not show the open and close parentheses that all functions have. For example, DATE() appears in the list as DATE. Many functions appear in the list more than once, followed by dots. See Choosing Alternate Syntax for a Function, below, for more information about the multiple entries.

Specifying Function Arguments

When you paste a function that can or must take one or more arguments, the placeholders for the arguments are pasted into the Expression box along with the function. For example, if you double-click FLOOR in the Paste list box, FLOOR(expN) is pasted into the Expression box. You must then replace the placeholder expN (which stands for "numeric expression") in the Expression box with a numeric expression.

When you click a function in the Paste list box, the information panel beneath the Expression box shows the syntax for the function, along with a short description of the function, for example:

FLOOR(expN)

Returns nearest integer less than or equal to specified number

Choosing Alternate Syntax for a Function

Often, a function can take different arguments to perform different actions. For example, ALIAS() returns the alias name of the current work area, while ALIAS(3) returns the alias name of work area 3. The syntax for the first form of the function is simply ALIAS(). The syntax of the second is ALIAS(database alias), where "database alias" is an alias number.

When alternate syntax forms exist for a function, those different forms appear as separate items in the Paste list box. The first form appears simply as the name of the function. The second form appears followed by a single dot. For example, the two forms of ALIAS appear like this:

ALIAS

ALIAS.

Each new syntax form is followed by another dot, for example:

DESCENDING

DESCENDING.

DESCENDING..

DESCENDING...

Click any item once to display syntax and a description in the information panel beneath the Expression box.

The description that appears for a function whose name is followed by a dot in the Paste list box (as described above) may use a + to indicate that the description builds on or adds to a previous one. For example, see the following:

Function as listed in Paste box	Description below the Expression box
DESCENDING	DESCENDING(index expN) Tests if specified index was created with DESCENDING keyword
DESCENDING.	DESCENDING(.MDX filename expC, index expN) DESCENDING + specifies multiple index (.MDX) file
Read the description of DESCENDING. (that is, the second item above) as "Tests if specified index was created with DESCENDING keyword and specifies multiple index (.MDX) file."


See Also

Using the Expression Builder

About dBASE Expressions

Using the List Boxes to Add Elements to an Expression

Expression Element Lists: Constants

Expression Element Lists: Fields

Expression Element Lists: Operators

Expression Element Lists: Variables


Expression Element Lists: Operators

See Also

When you choose Operator from the Category list box on the left of the Expression Builder, these items are displayed in the Type list box in the middle:

This is a list of the types of dBASE operators. When you choose one of these items from the Type list box, that group of operators appears in the Paste list box on the right. Double-click any of those operators to paste it into the Expression box.

Categories of dBASE Operators

The lists of operators that appear in the Paste list box are not complete lists of all the operators in the dBASE language; they are the most common ones. The following lists show the operators you can choose from the Paste list box:

Type	Operator	Explanation
All		(All the operators listed below)
Character	+	Concatenate two character expressions to form one.
	-	Concatenate two character expressions, and trim trailing spaces from the expression to the left of the operator.
Logical	.AND.	Both expressions must be True for the whole expression to evaluate to True.
	.OR.	One or the other expression must be True for the whole expression to evaluate to True.
	<>	Not equal The value of the first expression must be different from the value of the second for the entire expression to evaluate to True.
	=	Equal The value of the first expression must be equal to the value of the second for the entire expression to evaluate to True.
Numeric	*	Multiply
	+	Add
	-	Subtract
	/	Divide
	^	Exponentiation Carry the value to the left of this operator to the power of the value to the right of this operator, for example 2^2=4 and 2^3=8.
Relational	$	Substring compare
	<	Less than
	<=	Less than or equal to
	<>	Not equal to
	=	Equal to
	>	Greater than
	>=	Greater than or equal to


See Also

Using the Expression Builder

About dBASE Expressions

Using the List Boxes to Add Elements to an Expression

Expression Element Lists: Constants

Expression Element Lists: Fields

Expression Element Lists: Functions

Expression Element Lists: Variables


Expression Element Lists: Variables

See Also

When you choose Variable from the Category list box on the left of the Expression Builder, these items are displayed in the Type list box in the middle:

System

These are all the system memory variables in the dBASE language.

User

This is a list of any user-defined variables currently in memory.


See Also

Using the Expression Builder

About dBASE Expressions

Using the List Boxes to Add Elements to an Expression

Expression Element Lists: Constants

Expression Element Lists: Fields

Expression Element Lists: Functions

Expression Element Lists: Operators


No Help for Current Function (Expression Builder)
No Help Found

No Help is available for this item.


Working with Programs, Memo Fields, and Text Files

Editing Text

Running Programs


Running Programs

See Also

Use the menu bar, SpeedBar, Navigator, or Catalog window to run a program.

To run a program, do one of the following:

Choose File|Open, select the File Type "Program Source (*.PRG)," select a program file, choose Do, then click OK.

Double-click the program file from the Navigator or Catalog window.

Right-click the program file in the Navigator or Catalog window, then choose Do.

Select the program file in the Navigator or Catalog window, then choose Navigator|Do or Catalog|Do.

Click [image] from the Command window or Text Editor, select a program or form, then click OK.

The menus, SpeedBar, and window you see while running a program can vary depending on how the program was written. When a program uses any of the windows built into dBASE for Windows, these windows control the user interface. The built-in windows are those designed to work with the primary dBASE file types, such as tables, queries, and forms.

While running a program, the user might see the following:

A predefined window and its menu bar and SpeedBar. For example, if the program displays table data in the Table Records window, the user starts the program and sees the Table Records window, menu bar, and SpeedBar.

An entirely new menu bar, SpeedBar, and window. For example, if the program displays an invoice form for data entry and calculates complex financial formulas, the user starts the program and sees the form window, with a specialized menu bar and buttons to perform calculations.

When a program does not use a form or any of the windows built into dBASE for Windows, the program runs in the Command window. Screen output from dBASE IV and dBASE III PLUS programs that define their own windows and menus appears in the Command window. While the program is running, the title of the Command window displays "Program" and the name of the program. The dBASE for Windows menu bar and SpeedBar remain the same, except the Window menu changes to display the name of the program running.

dBASE IV programs that have user-defined menus can be converted to use dBASE for Windows menus. dBASE IV and dBASE III PLUS screen formats, and programs that create screens, can be converted to use dBASE for Windows forms. Both of these conversions are possible using the Component Builder. See the Component Builder help for more information about the Component Builder.


See Also

Editing Text

Compiling Programs

Opening and Closing the Text Editor

Window|Command or Program

Using Forms

Component Builder Overview


Editing Text

See Also

Use the dBASE for Windows Text Editor to create and edit dBASE programs and text files, and to edit memo fields in tables. In dBASE for Windows, the text editing tool is named both "Text Editor" and "Program Editor." Online Help uses the term "Text Editor" globally to refer to the Memo Editor, the Program Editor, and the Text Editor.

Text Editor Concepts and Tasks

Choose from the following list for information about using the Text Editor:

Text Editor Tasks

System-Wide Keystrokes

Text Editing Keystrokes

Text Editor Tools

The Text Editor has menus and a SpeedBar associated with it. Choose from the following list for more information about these topics:

Components	Description of the Text Editor

Menus	Lists and descriptions of all Text Editor menu commands

SpeedBar	Descriptions of the Text Editor SpeedBar buttons

SpeedMenu	List and description of the Text Editor SpeedMenu


See Also

Running Programs


Text Editor Tasks

See Also

Choose from the following tasks for more information about how to use the Text Editor:

Opening and Closing the Text Editor

Saving Text and Text Files

Copying, Cutting, and Pasting Text Between Windows

Indenting Text

Text File Defaults

Compiling Programs


See Also

Command Window Tasks


Opening and Closing the Text Editor

See Also	Language

You can edit programs, memo fields, and text files with the Text Editor. To start editing, open the Text Editor and access the data or file you want to edit. Once you open the Text Editor, edit the text by typing and using the standard text editing keystrokes. When you are done editing, close the window and save your changes.

Use the following tasks to open and close the Text Editor window.

To open a memo field, open the table in the Table Records window, select the memo field, then do one of the following:

Double-click the memo field icon.

Choose View|Field Contents or press F9.

To create a new program, do one of the following:

Choose File|New|Program.

Choose the Programs file type in the Navigator or Catalog window, then do one of the following:

Double-click the Untitled file.

Right-click the Untitled file, then choose New Program.

Select the Untitled file, then choose Navigator|New Program or Catalog|New Program or press Shift+F2.

Select the Untitled file, then click [image].

To change an existing program, do one of the following:

Choose File|Open, change the File Type to "Program Source (*.PRG)" or enter your own file-name skeleton, choose the program file you want, click Design Program, then click OK.

Choose the Programs file type in the Navigator or Catalog window, then do one of the following:

Double-right-click the correct file.

Right-click the correct file, then choose Design Program.

Select the correct file, then choose Navigator|Design Program or Catalog|Design Program or press Shift+F2.

Select the correct file icon, then click [image].

You can open the same text file or program in more than one Text Editor window. Thus you can have two views of the same file. Changes you make in one window are automatically reflected in the other when you make that window active.

To create a new text file,

1.	Choose File|New|Program.

2. Type the text.

3.	Choose File|Save As.

4.	Save the file with the .TXT file extension. By naming the file with .TXT, the next time you open it, dBASE will recognize it as a plain text file and use the Text Editor defaults for text files.

To edit an existing text file,

1.	Choose File|Open.

2.	Type *.TXT in the File Name text box then press Enter.

3.	Select the correct text file from the file list box, then click OK.

To close the Text Editor, do one of the following:

Choose File|Save and Close, or press Ctrl+W.

Choose File|Abandon and Close, or press Ctrl+Q. This closes the file without warning and without saving the changes.

Choose File|Close or press Ctrl+F4. If the file has unsaved changes, dBASE asks if you want to save your changes.

Double-click the Control-menu box in the upper left corner of the Text Editor window. If the file has unsaved changes, dBASE asks if you want to save your changes.

Programs are saved with the file extension .PRG by default. Text files are saved with the file extension .TXT by default. Memo fields are saved with the table and do not have a file extension.


See Also

Text Editor Tasks

Opening and Closing the Table Records Window

Copying, Cutting, and Pasting Text Between Windows

Indenting Text

Saving Text and Text Files

Text File Defaults

System-wide Keystrokes

Text Editing Keystrokes

File|Abandon and Close

File|Close

File|New|Program

File|Open

File|Save and Close

View|Field Contents

Catalog Menu

Navigator Menu


Language

CREATE COMMAND

CREATE FILE

MODIFY COMMAND

MODIFY FILE

SET EDITOR

SET WP


Saving Text and Text Files

See Also

To save changes you have made to a file in the Text Editor, do one of the following:

Choose File|Save or press Ctrl+S.

Choose File|Save As.

Choose File|Save and Close or press Ctrl+W.

Double-click the Control-menu box in the upper left corner of the Text Editor window. If the file has unsaved changes, dBASE asks if you want to save your changes.

To save a portion of the text to a file,

1.	Select the text.

2.	Choose Edit|Copy to File. In the dialog box that appears, specify the file name and location.

You can edit the same text file in more than one Text Editor window. If the file has unsaved changes, dBASE prompts you to save the file when you close the last window displaying the file.


See Also

Text Editor Tasks

Opening and Closing the Text Editor

Edit|Copy to File

File|Save

File|Save As

File|Save and Close


Copying, Cutting, and Pasting Text Between Windows

See Also

You can open more than one Text Editor window. This allows you not only to view different text files or different parts of the same text file, but to copy and paste text between windows.

To cut or copy  text:

1.	Select the text by clicking at the beginning of the text, holding down the left mouse button,  and dragging to the end of the text. You can also press Shift plus the direction keys.

2.	Choose Edit|Cut or press Ctrl+X to remove the text, or choose Edit|Copy or press Ctrl+C to copy the text to the Clipboard.

Note:	Choose Edit|Delete or press Del to remove the text without placing it on the Clipboard. You can restore the text with Edit|Undo.

To paste text into a different window:

1.	Select the window by clicking it or by choosing it from the open window list at the bottom of the Window menu.

2.	Position the insertion point where you want the text to start.

3.	Choose Edit|Paste or press Ctrl+V.

Note:	If you want to replace existing text with the text on the Clipboard, select the existing text before you choose Edit|Paste.

You can also copy syntax or examples from the dBASE for Windows online Help. See Copying Syntax and Examples from Help for more information.


See Also

Text Editor Tasks

Indenting Text

Opening and Closing the Text Editor

Saving Text and Text Files

Text File Defaults

Edit|Copy

Edit|Cut

Edit|Delete

Edit|Paste

Edit|Undo

Window|(open window list)


Indenting Text

See Also

Use the Text Editor Auto Indent feature to align indented lines of program code automatically. You control the Auto Indent feature with the Auto Indent and Spacing options in the Editor Properties dialog box. By default, Auto Indent is on for programs, off for memo fields and text files.

To indent and unindent text if Auto Indent is on,

Press Tab at the beginning of the line to insert spaces.

Press Shift+Tab to remove the spaces inserted from the last Tab.

Press Enter to begin a new line indented with the same number of spaces as the previous line.

You can start a line with spaces or spaces and tabs. Auto Indent works for:

Tabs alone

Spaces alone

Tabs and spaces

To indent text if Auto Indent is off,

Press Tab at the beginning of the line to insert a true tab character.

Press Shift+Tab to move the insertion point back one tab stop.

Press Enter to begin a new line at the left margin.

Note:	Shift+Tab does not unindent text when Auto Indent is off.

To set the tab width of true tab characters if Auto Indent is off,

1.	Click [image] to open the Command window.

2.	Enter a command similar to the following:

_tabs = "5,10,15,20,25"

This sets the tab stops to every five spaces. You can reset the tabs to their default length of eight by entering the following command:

_tabs=""

3.	Open or switch to a Text Editor window with Auto Indent off. The tabs are reset to the new tab stops.

To insert a tab after the first nonspace or nontab character in the line,

If insert mode is on, use Tab anywhere past the first nonspace character in a line to insert a tab character. This is useful for aligning program comments at the end of several command lines.

If insert mode is off, use Tab and Shift+Tab anywhere past the first nonspace character to move the insertion point to the next or previous tab stop without moving the text.


See Also

Text Editor Tasks

Compiling Programs

Copying, Cutting, and Pasting Text Between Windows

Opening and Closing the Text Editor

Saving Text and Text Files

Text File Defaults

Properties|Program or Text Editor


Text File Defaults

See Also

The following table lists the default settings in the Editor Properties dialog box for editing memo fields, text files, and programs in the Text Editor. To change these settings, choose Properties|Program or Text Editor.

Text Source	Word Wrap	Auto Indent	Auto Colors
Memo fields	On *	Off	Off
Programs (PRG)	Off	On, 3 spaces	On
Text Files (nonPRG)	Off	Off	Off
* By default, lines in memo fields wrap at the width of the window.


See Also

Text Editor Tasks

Opening and Closing the Text Editor

Properties|Program or Text Editor

Text Editor Window Components


Compiling Programs

See Also

To compile a program file,

1.	From the Command window, choose Program|Compile.

2.	Specify a program file. It is then compiled whether or not it has changed since the last compile operation. Any subroutines it calls are not compiled.

To fully recompile a program and its subroutines, type COMPILE * in the Command window.

When you run a program with Program|Do, if Ensure Compilation is checked in the Desktop Properties dialog box, dBASE compares the date and time of .PRG and .PRO files to see if recompilation is necessary. Use Ensure Compilation while developing an application. When you finish the application, you can uncheck Ensure Compilation to improve performance because dBASE assumes the .PROs are current.


See Also

Text Editor Tasks

Command Window Components

Program|Compile

Program|Do

Properties|Desktop


Text Editor Window Components

See Also	Language

Use the Text Editor to edit the contents of programs, text files, and memo fields.

Insertion Point

As you type, characters appear at the insertion point, also known as the cursor or text cursor.

Maximum Length

The Text Editor has a maximum line length of 32,767 characters. However, the maximum line length recognized in a dBASE for Windows program is 4096.

Colors

The Text Editor displays colors in programs to denote literal values and comments. See the Editor Properties dialog box for more information.

Status Bar

The status bar displays the following information about your text editing session:

Row and column position

Status of the Insert key: Ins if you can insert characters in front of others, blank if you will overwrite characters

If you are editing a memo field, the status bar also displays information about the current table, if any. See Table Records Window Components for information.

OEM Font

The default font in the Text Editor is an OEM (Original Equipment Manufacturer) font. An OEM font has the same characters in its character set as a DOS-based font. If you have DOS programs with graphics characters over ASCII 128, they look correct in an OEM font. See the Programmer's Guide for more information on character sets.


See Also

Command Window Components

System-wide Keystrokes

Text Editing Keystrokes

Properties|Program or Text Editor


Language

Language Reference

Alphabetic List

Categorical List

Classes

Properties


Text Editor Menus

The Text Editor has the following menus:

File Menu

Edit Menu

Program Menu	(not available for memo fields and text files)

Properties Menu

Window Menu

Help Menu


Text Editor SpeedBar

See Also

The SpeedBar is the row of buttons beneath the menu bar. Each button represents a menu command. Click the button representing the command you want to execute.

Button	Action	Menu Equivalent
	Creates a new dBASE-related file	File|New
	Opens a dBASE-related file	File|Open
	Saves the current file or memo field	File|Save
	Prints the information in the active window	File|Print
	Removes the selected text, object, or record and places it on the Clipboard	Edit|Cut
	Copies the selected text, object, or record onto the Clipboard	Edit|Copy
	Inserts the text/object into the active window	Edit|Paste
	Searches for specified text	Edit|Search|Find Text
	Searches for and replaces specified text	Edit|Search|Replace Text
	Opens the Expression Builder (programs only)	Edit|Build Expression
	Executes the selected text (programs only)	Edit|Execute Selection
	Executes the statements in a dBASE program (programs only)	Program|Do
	Compiles then debugs the selected program (programs only)	Program|Debug
	Switches to the Navigator window	Window|Navigator
	Switches to the Command window	Window|Command
	Opens the Form Expert	Help|Experts|Form Expert
	Opens the Interactive Tutors	Help|Interactive Tutors


See Also

Command Window SpeedBar


Text Editor SpeedMenu

See Also

Use the Text Editor SpeedMenu to quickly perform a common operation in the Text Editor.

To use the SpeedMenu, right-click in the Text Editor window.

Choose from the following commands:

Program or Text Editor Properties...

Cut

Copy

Paste

Find Text...

Find Next Text

Replace Text...

Build Expression...	(not available for memo fields and text files)


See Also

File Types and SpeedMenus

Program SpeedMenu


Edit Menu (Text Editor)

See Also

Use the Edit menu to perform editing operations and to copy or remove text.

The Edit menu works differently in each of the windows. The most common use of the Edit menu is to work with text, for example, to move text around or to delete text. For information about using the Edit menu in different windows, see Where the Edit Menu Works.

You can cut, copy, or paste text using the Clipboard. The Clipboard is a temporary storage area for information you want to move or copy from one location to another.

Choose from the following commands:

Undo or Redo

Cut

Copy

Paste

Delete

Select All

Insert from File...

Copy to File...

Search

Convert Case

Join Text Lines

Build Expression...	(not available for memo fields and text files)

Execute Selection	(not available for memo fields and text files)


See Also

Edit Menu (Command Window)

Program Menu (Text Editor)


Edit | Search

See Also

Displays a cascading menu. From the menu, choose a command to search for text and optionally replace it with other text.

Choose from the following commands:

Find Text...

Find Next Text

Replace Text...

Go to Line Number...

Top Line

Bottom Line


See Also

Edit Menu (Text Editor)


Edit | Search | Go to Line Number...

See Also

Moves the insertion point to the beginning of a specified line.

The status bar in the Text Editor displays the current position of the insertion point as follows:

Pos: row, column

This command repositions the insertion point at the beginning of a specified row.

Shortcuts

Keyboard:	Ctrl+G

Dialog Box Options

Line

Specifies the line number to move the insertion point to. Use the Up arrow button or Down arrow button to increase or decrease the number. These buttons limit the number you can enter to the actual number of lines in the file or memo field. If you manually enter a number exceeding the number of lines in the file or memo field, an error message appears.


See Also

Edit Menu (Text Editor)

Edit|Search|Find Text...

Edit|Search|Find Next Text

Edit|Search|Replace Text...

Edit|Search|Top Line

Edit|Search|Bottom Line


Edit | Search | Top Line

See Also

Moves the insertion point to the beginning of the first line in the file or memo field.

Shortcuts

Keyboard:	Ctrl+Home, Ctrl+PgUp


See Also

Edit Menu (Text Editor)

Edit|Search|Find Text...

Edit|Search|Find Next Text

Edit|Search|Replace Text...

Edit|Search|Go to Line Number...

Edit|Search|Bottom Line


Edit | Search | Bottom Line

See Also

Moves the insertion point to the end of the last line in the file or memo field.

Shortcuts

Keyboard:	Ctrl+End, Ctrl+PgDn


See Also

Edit Menu (Text Editor)

Edit|Search|Find Text...

Edit|Search|Find Next Text

Edit|Search|Replace Text...

Edit|Search|Go to Line Number...

Edit|Search|Top Line


Edit | Convert Case

See Also

Displays a cascading menu. From the menu, choose a command to convert the selected text to all capital letters, all small letters, or a combination where the first letter of each word is capitalized and the remaining letters are small.

Choose from the following commands:

Uppercase

Lowercase

Initial Capitals


See Also

Edit Menu (Text Editor)


Edit | Convert Case | Uppercase

See Also

Changes all the selected text to uppercase (capital) letters.

For example, the selected text "Borland International" would be converted to "BORLAND INTERNATIONAL."

This command is not available if no text is selected.


See Also

Edit Menu (Text Editor)

Edit|Convert Case|Lowercase

Edit|Convert Case|Initial Capitals


Edit | Convert Case | Lowercase

See Also

Changes all the selected text to lowercase (small) letters.

For example, the selected text "Borland International" would be converted to "borland international."

This command is not available if no text is selected.


See Also

Edit Menu (Text Editor)

Edit|Convert Case|Uppercase

Edit|Convert Case|Initial Capitals


Edit | Convert Case | Initial Capitals

See Also

Changes the first letter of each word in the selected text to a capital letter and the remaining letters in each word to small letters.

For example, the selected text "borland INTERNATIONAL" would be converted to "Borland International."

This command is not available if no text is selected.


See Also

Edit Menu (Text Editor)

Edit|Convert Case|Uppercase

Edit|Convert Case|Lowercase


Edit | Join Text Lines

See Also

Changes the hard carriage returns in the selected text to soft carriage returns.

This command is available if text is selected and Word Wrap is on.

If Word Wrap is on in the Editor Properties dialog box, text automatically wraps to the next line when it nears the right margin, and a soft carriage return is inserted at the end of the wrapped line. When you add or delete text from the paragraph, it is reformatted. A hard carriage return is inserted when you press Enter.

To combine several lines of text into one paragraph, select the text and choose Join Text Lines. dBASE replaces each hard carriage return with a soft carriage return and adds a space, if necessary, to separate the sentences.

This command leaves a hard carriage return at the end of a line or paragraph in the following cases:

The next line begins with spaces.

The next line begins with tabs.

The next line is blank.

This command is particularly useful if you insert text containing hard carriage returns from another text file.


See Also

Edit Menu (Text Editor)

Properties|Program or Text Editor


File Menu (Text Editor)

Use the File menu to create new files, open and run existing files, print files, and exit dBASE for Windows.

The New and Open commands manipulate the primary file types, such as tables, queries, and forms. The New command displays a menu from which you choose the type of file you want to create. The Open command lets you run or design an existing file.

You can open as many files as you like, and each appears in its own window. However, the Navigator and Command windows are unique and cannot be opened more than once.

Choose from the following commands:

New

Open...

Save

Save As...

Save and Close

Abandon and Close

Close

Print...

Printer Setup...

Exit

(closed file list)


Program Menu (Text Editor)

Use the Program menu to run, compile, debug, and analyze your programs.

Note:	This menu is not available when you edit memo fields and text files.

Choose from the following commands:

Do

Compile

Debug

Display Coverage


Properties Menu (Text Editor)

Use the Properties menu to change the characteristics of the dBASE for Windows Desktop and the Text Editor.

Choose from the following commands:

Desktop...

Program or Text Editor...


Properties | Program or Text or Procedure Editor...

See Also	Language

Changes the characteristics of the Text Editor.

Use the dBASE for Windows Text Editor to edit programs, text files, memo fields, and form procedures. The Text Editor has different default behaviors for each of these file types. The Editor Properties dialog box displays these defaults and lets you change them. For programs, the dialog box is called Program Editor Properties. For memo fields and text files, the dialog box is called Text Editor Properties.

Changes you make in this dialog box are saved in DBASEWIN.INI. Settings for memo fields, programs, and text files are saved separately. For example, when you are editing a memo field and you set the right margin to 65, this setting is saved for all memo fields. If you are editing a program and set the Auto Indent to two, this setting is saved for all programs.

Shortcuts

SpeedMenu:	Program or Text Editor Properties...

Procedure Editor Properties...

Dialog Box Options

Word Wrap

Determines if dBASE automatically adds a soft carriage return when the number of characters in a line exceeds the limit specified in Right Margin. If a paragraph contains soft carriage returns, you can add or delete text in the paragraph, and the lines reformat automatically to Right Margin. The default is on (checked) for memo fields, off (unchecked) for programs and text files.

If you enter some text with Word Wrap off, then set Word Wrap on again, previously entered text is reformatted to wrap at the right margin. If the lines of text end in hard carriage returns, you can convert them to soft carriage returns with Edit|Join Text Lines.

Auto Indent

Determines if new lines are automatically indented to the level of the previous line.

If Auto Indent is on (checked),

When you press Enter, the new line is indented with the same number of spaces as the previous line. This makes structured programs easier to read.

If you press Tab, dBASE inserts a group of spaces equal to the value specified in Spacing. Each time you press Tab, an additional group of spaces is inserted. To move the insertion point back one level of indentation, press Shift+Tab.

When you press Tab at the beginning of a line, spaces (ASCII decimal 32) are inserted, rather than a true tab character (ASCII decimal 9).

If Auto Indent is off (unchecked),

When you press Enter, the new line of text begins at the left margin.

If you press Tab, dBASE inserts a true tab character, equal to eight average-width characters. To move the insertion point back one tab stop, press Backspace.

You can configure the tab character width with _tabs. For example, in the Command window, enter _tabs="4,8,12,16,20" to set the tabs four characters wide. In this example, you can Tab five times per line. To reset the tab width to the default, enter _tabs="".

Other Tab behaviors include the following:

If Insert is on and you press Tab after the first nonspace character, a true tab character is inserted. This is useful for aligning comments in your code.

If Insert is off and you press Tab after the first nonspace character, the insertion point moves to the next tab stop without moving text. Shift+Tab moves to the previous tab stop.

The default for Auto Indent is off (unchecked) for memo fields and text files, on (checked) for programs.

Auto Colors

Determines if programming comments and literal values appear in different colors.

If Auto Colors is on, comments appear gray. Comment lines can begin with *, NOTE, or &&. You can also put comments at the end of a line by typing && followed by the comment.

If Auto Colors is on, literal values appear blue. The value appears red if it is not fully delimited, denoting a probable syntax error. Literals include:

Strings surrounded by single quotation marks ('), double quotation marks ("), or brackets ([ ]), for example 'dBASE', "dBASE", or [dBASE]

Dates surrounded by braces ({ }), for example {02/21/94}

Numbers, for example 32

Hexadecimal numbers, for example HTOI("32FA")

Scientific notation numbers, for example .6E+23

Logicals surrounded by periods (.), for example .T.

The default is off (unchecked) for memo fields and text files, on (checked) for programs.

Font

Specifies the font to use in the Text Editor. The font applies to all text in the window. Click [image] to open the Font dialog box, then choose a font, style, size, effects, and color. For program files, a monospaced font, such as Terminal or Courier, makes the code easier to read.

Right Margin

Sets the right margin to use for wordwrapping, if Word Wrap is on. The default is 0, which means words wrap at the width of the window. A nonzero value specifies the width in average-width characters where a wordwrap occurs. A vertical line appears in the window at the right margin. The range for the right margin is 0 to 999.

If Word Wrap is off, the Right Margin value is dimmed, and the default command-line length is 32,767 characters. However, the maximum line length recognized in a dBASE for Windows program is 4096.

Spacing

When Auto Indent is on, sets the number of spaces to insert if you press Tab at the beginning of a line. If Auto Indent is off, the Spacing value is dimmed, and pressing Tab inserts a true tab character (ASCII decimal 9). The default spacing for Auto Indent is three characters.


See Also

Properties Menu (Text Editor)

Edit|Join Text Lines

Indenting Text

Text File Defaults

Text Editor Window Components


Language

*

&&

_tabs

HTOI( )

ITOH( )

NOTE


Font Dialog Box

See Also	Language

Selects a typeface, style, and size for text.

This dialog box appears whenever you can specify the font used to display text in a window, such as the Command window or Text Editor. When you choose OK, dBASE records your choices and returns the following information:

Font name, also called the typeface

Type size in points

Bold, if it was selected

Italic, if it was selected

Underline, if it was selected

Strikeout, if it was selected

Dialog Box Options

Font

Specifies the typeface. Click a typeface and view it in the Sample box.

Font Style

Specifies the treatment of the font. Examples are Regular, Bold, Italic, and Bold Italic.

Size

Specifies the point size of the text. A point is a measure of type equal to 1/72 of an inch. Printed correspondence typically has a size of 10 or 12 points.

Effects

Sets special effects for text.

Strikeout

Determines if text appears with a line drawn through it. The line extends to the width of the window.

Underline

Determines if text appears with a line drawn under it. The line extends to the width of the window.


See Also

Color Dialog Box


Language

GETCOLOR( )

GETFONT( )


Using the Catalog Window

See Also

Use the Catalog window to group files needed for a particular project or application. The files can be stored anywhere; they are simply organized into a list, the catalog file, and displayed in the Catalog window.

Catalog Window Concepts and Tasks

Choose from the following list for information about using the Catalog window:

Using the Catalog Window - Overview

Catalog Window Tasks

File Types and SpeedMenus

Differences between the Navigator and Catalog window

Catalog Differences between dBASE IV and dBASE for Windows

Catalog Window Tools

The Catalog window has menus and a SpeedBar associated with it. Choose from the following list for more information about these topics:

Components	Description of the Catalog window

Menus	Lists and descriptions of all Catalog window menu commands

SpeedBar	Descriptions of the Catalog window SpeedBar options

SpeedMenu	List and description of the Catalog window SpeedMenu


See Also

Using the dBASE Navigator


Using the Catalog Window - Overview

See Also

A Catalog window is a visual representation of a catalog file. A catalog is a file that stores information about the files necessary for a particular purpose or application so they can be conveniently accessed when needed.

A file can be listed in as many catalogs as it applies to. For example, a table containing postal abbreviations for the United States could apply to several applications and could be listed in several catalogs.

You can have as many catalogs as you need. One purpose of catalogs is to reduce the number of files you see. In the Navigator, you see all files in one or more directories. Catalogs hide extraneous files from your working environment, letting you concentrate on the files you need.

CATALOG.CAT

In each directory that you create catalogs, dBASE for Windows maintains a catalog file called CATALOG.CAT. Unlike regular catalog files, CATALOG.CAT does not store the names of tables, queries, and so on. It stores the names of other catalog files you have used or created in that directory.

When you create a new catalog file, its name, location, and description are added to the CATALOG.CAT file in the current directory. If the current directory does not have a CATALOG.CAT file, a new one is created.

Since CATALOG.CAT is not a regular catalog file, but is a dBASE for Windows internal file, it is not displayed in the Navigator.

Contents of a Catalog File

A catalog file includes the following information:

Path name	The full path name of the file
File name	The name of the file, including its extension
Alias name	Usually the same name as the file, unless you manually assign another
File type	The file extension that identifies the type of file
Description	A description of the file (80-characters or less)
Code	A number representing the file type and association
Tag	Not used
Note:	The Catalog window looks similar to the Navigator but displays files differently. The Navigator displays files stored in specified directories on the disk. The Catalog window displays files you list in the catalog file.

File Types Supported in the Catalog Window

Both the Navigator and the Catalog window support the primary dBASE file types. When you choose Catalog|Add Item, you can choose from these file types:

.DBF	dBASE table	.DB	Paradox table
.QBE	Query by example	.QBO	Compiled QBE
.VUE	View	.QRY	dBASE III PLUS query
.WFM	Form	.WFO	Compiled form
.FMT	dBASE III+/IV screen format	.FMO	Compiled screen format
.RPT	Report	.RPC	Cross-tab report
.FRG	dBASE IV report	.FRO	Compiled dBASE IV report
.FRM	dBASE III+/IV report	.RPL	Label
.LBG	dBASE IV label	.LBO	Compiled dBASE IV label
.LBL	dBASE III+/IV label form	.PRG	Program
.PRO	Compiled program
Each time you add a file to an open catalog, you can type a description of the file. This description appears at the bottom of the Catalog window when the file is selected. With this feature, the Catalog window acts like a documentation tool for your applications. As you use different files in the Catalog window, you can read the description for information on when or how to use the file.

Tables from an SQL database (nonstandard) or local database (standard) cannot be added to a dBASE catalog. For information about standard and nonstandard databases, see Navigator Components.

Associated Files

The Catalog window visually shows file associations. File association indicates some sort of dependency between the files. For example, a form might be associated with a query because the data in the form depends on the settings and options in the query. Choose View|Associations to show associated files.

If you run or design a form, report, or label file while a catalog is active, it is added to the active catalog. The query or table it depends on is also added to the active catalog. These files are then associated.

Structure of the Catalog File

A catalog file is actually a dBASE table. It has a file name with the file extension .CAT. The information for each file in a catalog is stored in a different record in the catalog file. Associated files have the same numeric value in the Code field of the catalog file.

The catalog file (table) has the following structure:

Field Name	Type	Length  Dec  Index

Path	Character	70	N

File_Name	Character	12	N

Alias	Character	8	N

Type	Character	3	N

Title	Character	80	N

Code	Numeric	3	N

Tag	Character	4	N


See Also

Navigator Components

File|New|Catalog...


Catalog Window Tasks

See Also

Choose from the following list for more information about how to use the Catalog window:

Organizing Files with a Catalog

Adding Files to a Catalog

Deleting Items from a Catalog

Running a File from the Catalog Window or Navigator

Associating Files in a Catalog


See Also

Using the dBASE Navigator

Navigator Tasks


Adding Files to a Catalog

See Also

When you add a file to a catalog, you are creating a reference to the file inside the catalog file. The file itself does not move on the disk.

To add a file to a catalog using the menu,

1.	Click the Catalog window to make it active.

2.	Choose Catalog|Add Item.

3.	Select a file from the Add Catalog Item dialog box. The file type defaults to the current file type in the Catalog window. The file is added to the active catalog.

To add a file to a catalog automatically,

1.	Click the Catalog window to make it active.

2.	Choose File|New or File|Open to create or open a file. You could also switch to the Navigator or Command window, without closing the Catalog window, and open a file from there. The file you open is added to the active catalog.

To add a file by dragging and dropping,

1.	Open the Catalog window.

2.	Switch to the window that lists the file you want to add. This can be the Navigator, another Catalog window, or the Windows File Manager.

3.	Select, drag, and drop the file into the open Catalog window. The file is added to the catalog, and the Catalog window refreshes to display the new file.


See Also

Using the Catalog Window - Overview

Catalog Window Tasks


Deleting Items from a Catalog

See Also

To delete a file from the catalog,

1.	Click the Catalog window to make it active.

2.	Select a file to remove from the catalog.

3.	Press Del or choose Edit|Delete. You are asked first to confirm that you want to delete the file from the catalog. Then you are asked if you also want to delete it from the disk.

Use caution when deleting a file from the disk. Even if it is not useful in the active catalog, it might be used in another catalog or application.

You cannot delete the Untitled icons from the Navigator or Catalog window.

Note:	In dBASE IV, the file had to be closed before you could remove it from a catalog. Closing the file first is not necessary in dBASE for Windows.


See Also

Using the Catalog Window - Overview

Catalog Window Tasks


Running a File from the Catalog Window or Navigator

See Also

To open and run a file by dragging and dropping it, select, drag, and drop the file into the Desktop or Command window.


See Also

Using the Catalog Window - Overview

Catalog Window Tasks


Associating Files in a Catalog

See Also

To associate a new form, report, or label with an existing table or query,

1.	Open or create a catalog.

2.	Create a new form, report, or label.

3.	Specify the table or query to base the new file on.

4.	After working with the new file, save it with File|Save or File|Save As.

5.	Specify a file description in the Catalog Item Description dialog box.

dBASE adds the new file to the catalog and associates it with the table or query it is based on.

To associate an existing form, report, or label with an existing table or query,

1.	Add the existing form, report, or label to the catalog with Catalog|Add Item or by dragging and dropping it from the Navigator to the Catalog window.

2.	Specify a file description in the Catalog Item Description dialog box.

dBASE adds the file to the catalog. When you run or design the form, report, or label, dBASE checks which table or query it is based on, adds the table or query to the catalog, and associates the file with the table or query.


See Also

View|Associations

File|New|Form

File|New|Report

File|New|Labels

File|Save

File|Save As

Catalog Window Components

Catalog|Add Item...


Differences Between the Navigator and Catalog Window

See Also

The Catalog window and Navigator are both used to organize files, but in different ways.

The current or search path directory and the selected file type determine the file icons that appear in the Navigator. The files can be totally unrelated. Other than changing directories or selecting a different file type, you cannot control the file icons that appear in the Navigator. If you delete a file from the Navigator, it is also deleted from the disk.

The current catalog file determines what appears in the Catalog window. A catalog file is simply a list of file names that you select. Typically, these files are related in some way, usually as part of a project of some kind. If you delete a file from a catalog, you only remove its name from the list; you do not delete it from the disk. You can still display its icon in the Navigator or use the file in another catalog.

Dragging and Dropping Files

You can drag and drop a file from the Windows File Manager into a Catalog window, but not into the Navigator.

File Types

The Catalog window does not support sounds, images, custom files, and other catalogs. Use the Navigator or File menu to work with these file types. See Using the dBASE Navigator for information on sounds, images, and custom files.


See Also

Using the Catalog Window - Overview

Catalog Window Tasks

Catalog Differences between dBASE IV and dBASE for Windows


Catalog Differences Between dBASE IV and dBASE for Windows

See Also

dBASE for Windows catalog files are dBASE IV compatible, in that they have the same structure. However, dBASE for Windows supports new file types, and it handles other file types differently than dBASE IV.

dBASE for Windows catalogs support the following file types that dBASE IV does not:

.DB Paradox tables

.QRY filters

.WFM form code

.WFO compiled form code

.FMT generated form code

.FMO compiled form code

.LBG generated label code

.FRG generated report form code

.PRO compiled programs

.RPT reports

.RPC cross-tab reports

.RPL labels

dBASE for Windows catalogs do not support update query files (.UPD, .UPO), screen form files (.SCR), dBASE SQL programs (.PRS), compiled dBASE IV programs (.DBO), Applications Generator files (.APP), and external programs (.COM, .EXE).


See Also

Using the Catalog Window - Overview

Catalog Window Tasks

Differences between the Navigator and Catalog window

Moving from the dBASE IV Control Center


Catalog Window Components

See Also	Language

The Catalog window displays the primary dBASE file types, such as tables, queries, and forms, and icons representing files of those types.

You can use simple commands to view or modify any file displayed in the Catalog window. When you open a file, it appears in a window corresponding to the action you requested. For example, if you open a program in Design mode, it appears in the Text Editor window. dBASE for Windows supports opening several files at once, each in a separate window.

File Types and File-Name Skeletons

The primary file types appear on the left side of the window. Each file type has a predefined file-name skeleton, such as *.QBE and *.WFM, which appears above the file list. The file-name skeleton defines which files appear for each file type. For more information about the file-name skeletons, see File Types and SpeedMenus.

Any file of the selected type in the catalog appears in the file list on the right side of the Catalog window. The files are represented by icons that indicate the file type. The file name for the currently selected file appears in the status bar. To see detailed information about each file, choose Properties|Selected File Item or View|Details.

Active and Inactive Catalogs

You can open several Catalog windows, each displaying a different catalog. When you select a Catalog window, the window and the catalog in it become active. When you select a non-Catalog window, the last selected catalog remains active, even though its window is no longer active. When you create or open a file supported in a catalog, it is automatically added to the active catalog.

You can see which Catalog window is active, even if none are selected, by looking for the Active Catalog icon.

Specifies the active catalog

Specifies an inactive catalog

Catalog Description

When you create a catalog, dBASE asks for a description of the catalog in the Catalog Item Description dialog box. Type a description of 80 characters or less. The description appears at the top of the Catalog window. Also displayed in the dialog box are the master Catalog Name, CATALOG.CAT, and the current Catalog Item Name, your new file. CATALOG.CAT is a list of all catalogs you have created and their descriptions.

Once in the new Catalog window, you can edit the description at any time by clicking in the Catalog Description text box and editing the text.

Item Description

When you add a file to a catalog, dBASE asks for a description of the file in the Catalog Item Description dialog box. Type a description of 80 characters or less. The description appears at the bottom of the Catalog window when the file is selected. The dialog box also displays the Catalog Name you are adding the file to, and the current Catalog Item Name, the file you are adding.

You can edit the file description at any time by clicking in the Item Description text box and editing the text.

You can also edit the description and see other attributes about the file in the Catalog Item Properties dialog box. Select the file, then choose Properties|Selected Catalog Item.


See Also

Using the Catalog Window - Overview


Language

SET TITLE


Catalog Window Menus

The Catalog window has the following menus:

File Menu

Edit Menu

View Menu

Catalog Menu

Properties Menu

Window Menu

Help Menu


Catalog Window SpeedBar

The SpeedBar is the row of buttons beneath the menu bar. Each button represents a menu command. Click the button representing the command you want to execute.

Button	Action	Menu Equivalent
	Creates a new dBASE-related file	File|New
	Opens a dBASE-related file	File|Open
	Removes the selected text/object and places it on the Clipboard	Edit|Cut
	Copies the selected text, object, or record onto the Clipboard	Edit|Copy
	Inserts the text, object, or record into the active window	Edit|Paste
	Opens and runs the selected file	See Catalog Menu
	Opens the selected file for design	See Catalog Menu
	Adds a file to the active catalog	Catalog|Add Item
	Deletes the selected file from the catalog	Edit|Delete
	Switches to the Navigator window	Window|Navigator
	Switches to the Command window	Window|Command
	Opens the Form Expert	Help|Experts|Form Expert
	Opens the Interactive Tutors	Help|Interactive Tutors


Catalog Window SpeedMenu

Use the Catalog window SpeedMenu to quickly perform a common operation on the Catalog window.

To use the SpeedMenu, right-click anywhere in the Catalog window except in the file list.

Choose from the following commands:

Catalog Window Properties...

Cut

Copy

Paste


Catalog Menu (Catalog Window)

See Also

Use the Catalog menu to perform operations on the selected item in the Catalog window.

In the Catalog window, choose from the list of file types, and then select a file in the file list on the right side of the window. Once you select a file, you can manipulate it in one of four ways:

Choose a menu command on the Catalog menu.

Double-click the file to run it, or double-right-click the file to design it.

Choose a SpeedMenu command. To view the SpeedMenu, right-click the file or press Spacebar.

Click [image] to run the file. Click [image] to design the file.

The Catalog menu changes for each file type, and within each file type, for titled and untitled files. Add Item... always appears. The file-specific menu commands are the following:

Tables	Reports
New Table	New Report
Edit Records	Run Report
Add Records	Design Report
Design Table Structure	Edit as Program
Queries	Labels
New Query	New Labels
Run Query	Run Labels
Design Query	Design Labels
Edit as Program	Edit as Program
Forms	Programs
New Form	New Program
Run Form	Do
Design Form	Debug
Edit as Program	Design Program
Note:	The Catalog menu corresponds to the SpeedMenu for each file type. In addition, the SpeedMenu offers choices for viewing the file properties and deleting the file. See Properties|Selected Catalog Item and Edit|Delete for information.


See Also

File Types and SpeedMenus


Catalog | Add Item...

See Also

Adds a file to the active catalog.

You can add all the primary dBASE file types to a catalog. The file types you cannot add are images, sounds, menus, other catalogs, and custom files. For information about the primary dBASE file types, see View|All. For information about the file types supported in the Catalog window, see Using the Catalog Window - Overview.

Specify the name and location of the file in the Add Catalog Item dialog box. dBASE tables are displayed by default. For general information about choosing files, see Open File dialog box.

dBASE for Windows looks in the catalog for duplicate files. Any files in the catalog without a full path name are assumed to be in the current directory. See Using the Catalog Window - Overview for information about the contents of catalog files.

Shortcuts

SpeedBar:

Keyboard:	Ctrl+A


See Also

Catalog Menu

Using the Catalog Window - Overview

Catalog Differences between dBASE IV and dBASE for Windows

Edit|Delete


Edit Menu (Catalog Window)

Use the Edit menu to perform editing operations and to copy or remove text.

The Edit menu works differently in each of the windows. The most common use of the Edit menu is to work with text, for example, to move text around or to delete text. For information about using the Edit menu in different windows, see Where the Edit Menu Works.

You can cut, copy, or paste text using the Clipboard. The Clipboard is a temporary storage area for information you want to move or copy from one location to another.

Choose from the following commands:

Undo or Redo

Cut

Copy

Paste

Delete

Select All


File Menu (Catalog Window)

Use the File menu to create new files, open and run existing files, and exit dBASE for Windows.

The New and Open commands manipulate the primary file types, such as tables, queries, and forms. The New command displays a menu allowing you to choose the type of file you want to create. The Open command lets you run or design an existing file.

You can open as many files as you like, and each appears in its own window. However, the Navigator and Command windows are unique and cannot be opened more than once.

Choose from the following commands:

New

Open...

Close

Import...

Exit

(closed file list)


Properties Menu (Catalog Window)

Use the Properties menu to change the characteristics of the dBASE for Windows Desktop, the Catalog window, and specific files.

Choose from the following commands:

Desktop...

Catalog Window...

Selected Catalog Item...


Properties | Catalog Window...

See Also

Changes the characteristics of the Catalog window.

In the Associations view, the X and Y spacing settings in this dialog box are ignored. The icon spacing is predetermined to accommodate the association lines.

Settings you make in this dialog box are also reflected in the Navigator Properties dialog box.

dBASE records the choices you make in this dialog box in the DBASEWIN.INI file.

Shortcuts

SpeedMenu:	Catalog Window Properties...

Dialog Box Options

Large Icons

Specifies the horizontal (x) and vertical (y) spacing of large file icons. Set the view to large icons by using View|Large Icons.

Small Icons

Specifies the horizontal (x) and vertical (y) spacing of small file icons. Set the view to small icons by using View|Small Icons. This is the default view.

Details

Specifies the vertical (y) spacing of detailed file icons; you cannot alter the horizontal spacing. Set the view to show file details by using View|Details. The Details view is unavailable when you are viewing catalog associations.

X Spacing

Sets the amount of space in pixels between columns of file icons. A pixel is a single dot on your computer screen.

Y Spacing

Sets the amount of space in pixels between rows of file icons. A pixel is a single dot on your computer screen.

Reset

Changes the X and Y spacing text boxes to their default values.


See Also

Properties Menu (Catalog window)

View|Associations

Properties|Navigator


View Menu (Catalog Window)

See Also

Use the View menu to change the category of file types displayed in the Catalog window and set how files are displayed. For example, View|Queries opens the Queries file type and displays query files.

A checkmark indicates which category of file types is currently displayed. By default, the Tables file type is displayed.

Another way to choose a file type is to click it with the mouse in the Catalog window.

Choose from the following commands:

All

Tables

Queries

Forms

Reports

Labels

Programs

Associations

Sort

Large Icons

Small Icons

Details


See Also

View Menu (Navigator)


View | Associations

See Also

Draws lines connecting associated files in the Catalog window. You can toggle Associations on or off by checking or unchecking this menu command.

In a catalog, you store a group of related files, but the relationship between them might not be obvious. Use Associations to view the relationship between dependent files. A dependent file is a form, report, or label that depends on a table or query for its data. Programs are independent file types and do not depend on a table or query.

This command works for files that are marked as associated in a catalog. For more information, see Associating Files in a Catalog.

The Associations view changes slightly for each file type in the Catalog window. In each case a line appears connecting the table or query with the associated form, report, or label.

When All is selected,

Untitled icons appear at the top of the list.

Tables and associated files appear next.

Queries and associated files appear next.

Unassociated tables and queries appear last.

Unassociated forms, reports, and labels do not appear.

Programs do not appear.

When Tables or Queries is selected, a line appears connecting the table or query name with its associated forms, reports, and labels. Unassociated tables or queries appear last in alphabetical order.

When Forms, Reports, or Labels is selected, a line appears connecting the associated table or query name with the forms, reports, or labels. Unassociated forms, reports, or labels appear last in alphabetical order. Other files associated with the same table or query do not appear. To see a complete list of associated files, use the All file type.

When Programs is selected, the list of programs appears in alphabetical order.

When Associations is off (unchecked), file names appear in alphabetical order similar to the way they appear in the Navigator.


See Also

View Menu (Catalog Window)

Associating Files in a Catalog


Using the dBASE Navigator

Use the dBASE Navigator to work with the primary file types supported in dBASE for Windows, including tables and associated files, queries, forms, reports, catalog (project) files, and programs.

Shortcuts

SpeedBar:

Navigator Concepts and Tasks

Choose from the following list for information about using the Navigator:

Navigator Tasks

File Types and SpeedMenus

Navigator Tools

The Navigator has menus and a SpeedBar associated with it. Choose from the following list for more information about these topics:

Components	Description of the Navigator

Menus	Lists and descriptions of all Navigator menu commands

SpeedBar	Descriptions of the Navigator SpeedBar options

SpeedMenu	List and description of the Navigator SpeedMenu


Navigator Tasks

To open the Navigator, click [image] or choose Window|Navigator.

Choose from the following list for more information about how to use the Navigator:

Choosing a Directory

Opening Files

Running a file from the Catalog window or Navigator

Running the Primary dBASE File Types

Designing the Primary dBASE File Types

Organizing Files with a Catalog


Choosing a Directory

See Also	Language

dBASE searches for files in one or more directories you specify. By default, the Current Directory text box is available from the Navigator. The Search Path text box is optional. Choose Properties|Navigator and check Use Supplemental Search Path to display the Search Path text box.

Current Directory	The main directory to search in. By default, only the Current Directory text box appears in the Navigator.

Search Path	One or more additional directories to search in. Separate multiple directories with a semicolon (;), comma (,), or space. For example, C:\FILES\TABLES;C:\FILES\OTHER

You can type the directory names directly in the Current Directory and Search Path text boxes. Or you can click the folder button next to the text box to display the Choose Directory dialog box from which you can select a directory.

Note:	The Current Directory is one directory. The Search Path is one or more directories. To specify multiple directories, you must type them.

After changing a directory name, press Enter. dBASE updates the file list to display an icon for any file in the new directory with a file extension specified in the file-name skeleton.


See Also

Navigator Components


Language

SET DIRECTORY

SET PATH


Choose Directory Dialog Box

Specifies a directory.

Use the Choose Directory dialog box to choose a directory for the Navigator. When you choose OK, the directory you chose appears in the Current Directory text box or the Search Path text box.

Dialog Box Options

Directory Name

Displays the current drive and directory name.

Directories

Lists the directories on the selected drive. A closed folder icon indicates that no subdirectories are showing. An open folder icon indicates that subdirectories under the selected directory, if any, are showing.

Files

Lists the files in the selected directory. The file-name skeleton is *.*, meaning all files. Use the Files list box to verify that you chose the correct directory. The file names are dimmed because this dialog box chooses only a directory, not a file.

Drives

Lists the logical drives your system can use. Use the drop-down button to see a list of available drives. If you have network drives, they appear in the list. When you select a drive, the Directories list is automatically updated to the new drive.


Opening Files

See Also

Once you have chosen the file type and directories you want, click a file icon to select the file. Once the file is selected, you can perform several operations. You can run or design the file, or choose other options. To see a SpeedMenu that lists the specific operations you can perform on a file, right-click the file icon or press Spacebar. For information about each file SpeedMenu, see File Types and SpeedMenus.

To create a new file, double-click the Untitled file icon, or use File|New.

To run a specific file, select the file, then do any of the following:

Click the Navigator menu, then choose the appropriate command (usually the first command on the menu).

Click [image].

Press F2.

Double-click the file.

Drag the selected file into the Desktop or Command window.

To design a specific file, select the file, then do any of the following:

Click the Navigator menu, then choose the appropriate command (usually the second or third command on the menu).

Click [image].

Press Shift+F2.

Double-right-click the file.


See Also

Running the Primary dBASE File Types

Designing the Primary dBASE File Types


Running the Primary dBASE File Types

See Also

The following table lists the main dBASE file types, file extensions, and a description of the action that occurs when you run a file. Running means displaying data or objects in a window so you can use them to do real-world tasks. For example, running a table means displaying the data in it so you can evaluate it, change it, calculate it, and so on.

Running a form, report, or label that is based on a table or query automatically opens the table or query. If a different table or query is currently active, dBASE asks you to confirm before opening the new table or query.

You can limit the file types that appear in the Navigator by unchecking Older File Types on the Files page of the Desktop Properties dialog box.

File Type	Extension	Description
Table	.DBF, .DB	Opens the table for display and modification of the data
Query	.QBE, .VUE, .QRY	Sets up tables, indexes, and relationships and displays the resulting data
Form	.WFM, .FMT	Displays the objects and data in the form
Report	.RPT, .RPC, .FRM, .FRG	Displays and prints table data in a tabular or cross-tab format
Label	.RPL, .LBL, .LBG	Displays table data in a label format
Program	.PRG	Executes the commands in the program
Image	.BMP, .PCX	Displays the image
Sound	.WAV	Plays the sound
Catalog	.CAT	Opens the catalog for display and modification


See Also

Displaying and Editing Table Records

Running Queries

Using Forms

Using Reports and Labels

Running Programs

Displaying Images

Playing Sounds

Using the Catalog Window


Designing the Primary dBASE File Types

See Also

The following table lists the primary dBASE file types, file extensions, the name of the window they are designed in, and a description of the action that occurs when you design a file. Designing means using a tool to create and lay out a file so you can use it later for real-world tasks. For example, designing a table means laying out the types of data the table will contain.

You can limit the file types that appear in the Navigator by unchecking Older File Types on the Files page of the Desktop Properties dialog box.

File Type	Extension	Window Name	Description
Table	.DBF, .DB	Table Designer	Defines the type and structure of the table.
Query	.QBE	Query Designer	Defines how to organize, sort, and select data from one or more tables.
	.VUE, .QRY	not applicable	Available only for running.
Form	.WFM	Form Designer	Defines screen displays, such as data entry forms and dialog boxes.
	.FMT	Text Editor	Defines the screen display of data. You can use the Component Builder to convert to .WFM then use the Form Designer to define the screen display.
Report	.RPT, .RPC	Report Designer	Defines a tabular or cross-tab format for displaying table data.
	.FRM, .FRG	not applicable	You can use the Component Builder to convert to .RPT, then use the Report Designer to define the format.
Label	.RPL	Report Designer	Displays table data in a label format.
	.LBL, .LBG	not applicable	You can use the Component Builder to convert to .RPL, then use the Report Designer to define the format.
Program	.PRG	Text Editor	Edits the program. You can use the Component Builder to convert to .WFM or .MNU, then use the Form Designer or Menu Designer to define the format.
Image	.BMP, .PCX	External graphics application	Edits the image.
Sound	.WAV	External sound application	Edits the sound.
Catalog	.CAT	Catalog window	Opens the catalog for display and modification.


See Also

Component Builder Overview

Designing Table Structures

Designing Queries

Designing Forms

Designing Reports and Labels

Editing Text

Designing Menus

Editing Images

Editing Sounds

Using the Catalog Window


Component Builder Overview

The Component Builder is a utility for translating code generated by the dBASE IV design tools into the format used by the dBASE for Windows design tools. Running these files through the Component Builder lets you enhance them with standard Windows controls such as pushbuttons and list boxes.

With the Component Builder, you can move dBASE IV format, report, and label files into the Windows environment. The Component Builder translates the following file types:

.FMT Screen format files

.FRM Report form files

.LBL Label form files

.PRG Programs containing user-defined menus or screen formats

After you run the Component Builder, load the generated code into the dBASE for Windows design tools such as the Form Designer and Menu Designer.

The Component Builder program is installed in the UTILITY subdirectory. To run it, double-click the dBASE for Windows Component Builder icon from the Windows Program Manager. You can also execute the program file, CB.PRO, from within dBASE for Windows. For instructions on using the Component Builder, see its online Help.


Organizing Files with a Catalog

You can view dBASE files by organizing them into projects, or catalogs. A catalog is a file that contains a list of related files. You choose which files are in the catalog, and this file list appears in the Catalog window. See Using the Catalog window for information about creating a catalog.

Note:	The Navigator displays files stored on your disk. The Catalog window displays only files listed in a catalog file.

Once you have created and opened a catalog, all files you create or use are automatically added to the open catalog and appear in the Catalog window. You can also add files directly to the catalog by dragging them to the Catalog window from the Navigator or from another Catalog window.

Select a file in the Navigator window, then drag it to the open Catalog window. dBASE adds the file to the catalog and displays it in the Catalog window in the appropriate file type.

See Adding Files to a Catalog for more information.


File Types and SpeedMenus

Each of the file types in the Navigator and Catalog window has a predefined file-name skeleton. For example, the file-name skeletons for the Tables file type are *.DBF and *.DB. Any file ending with one of the predefined extensions appears in the file list.

In the Navigator, the file list reflects what files are on the disk. You can refresh this list using Navigator|Refresh Items.

In the Catalog window, the file list reflects what files are in the catalog file.

A SpeedMenu is a short menu that appears next to a file. To view the SpeedMenu for a file in the file list, select the file and then right-click or press Spacebar. The SpeedMenu commands provide a quick way to perform common commands pertaining to the file type. For example, a table file has SpeedMenu commands to edit the table, add records to the table, or change the table structure.

Choose a file type in the following table to get help on the predefined file-name skeleton for that file type. The All file type describes all the file-name skeletons used in the Navigator or Catalog window.

Choose a SpeedMenu in the following table to get a list of the SpeedMenu commands for each file type.

File Types	SpeedMenus
All
Tables	Table File SpeedMenu
Queries	Query File SpeedMenu
Forms	Form File SpeedMenu
Reports	Report File SpeedMenu
Labels	Label File SpeedMenu
Programs	Program File SpeedMenu
Images	Image File SpeedMenu	Not available in the Catalog window
Sounds	Sound File SpeedMenu	Not available in the Catalog window
Catalogs	Catalog File SpeedMenu	Not available in the Catalog window
Custom	Custom File SpeedMenu	Not available in the Catalog window


Navigator Components

See Also	Language

The Navigator window displays the primary file types used in dBASE for Windows, such as tables, queries, and forms, and icons representing files of those types.

You can use simple commands to view or modify any file displayed in the Navigator. When you open a file, it appears in a window corresponding to the action you requested. For example, if you open a program in Design mode, it appears in the Text Editor window. dBASE for Windows supports opening several files at once, each in a separate window. However, the Navigator is a window that can appear only once.

File Types and File-Name Skeletons

The primary file types appear on the left side of the window. Each file type has a predefined file-name skeleton, such as *.QBE and *.WFM, which appears above the file list. The file-name skeleton defines which files appear for each file type. For more information about the file-name skeletons, see File Types and SpeedMenus.

Any file in the Current Directory or Search Path with the extension specified in the file-name skeleton appears on the right side of the Navigator window in the file list. The files are represented by icons that indicate the file type. The file name for the currently selected file appears in the status bar. To see detailed information about each file, choose Properties|Selected File Item or View|Details.

Directories

Current Directory is the main directory to search in.

Search Path is one or more optional additional directories to search in. Choose Properties|Navigator to set whether or not the Search Path text box appears. Separate multiple directories with a semicolon (;), comma (,), or space. For example, C:\FILES\TABLES;C:\FILES\OTHER

To select a directory interactively, click the folder button next to Current Directory or Search Path. The Choose Directory dialog box appears.

Tables from ...

If you use SQL or local databases on your system, you see two additional options: Tables from Directory and Tables from Database.

Tables from Directory

By default, Tables from Directory is selected. This option searches for tables in the directories specified by Current Directory and Search Path.

Tables from Database

This option searches for tables in the database specified in Current Database. When you choose Tables from Database, Current Directory and Search Path are replaced by Current Database.

Note:	Tables from Database and Current Database appear if All or Tables is selected in the Navigator. If any other file type is selected, Current Directory and the optional Search Path appear.

Current Database is the name of the active database. By default, <None> appears. Click the drop-down button to display a list of available databases.

This option is for accessing two types of databases, standard and nonstandard.

A standard database is a dBASE or Paradox database, specified by a DOS path in the IDAPI configuration file. All the tables found in the DOS directory you specify are considered part of the database.

A nonstandard database is an SQL database, such as an InterBase database, stored on a database server. Access to an SQL database requires SQL Links for dBASE for Windows. The SQL database must be listed as a database alias in the IDAPI.CFG file.

To open a database, choose it from the list. If you choose a nonstandard database, you must enter your user name and password in the Open Database dialog box. Once you are logged on to the database server and the database is open, the tables in the database appear in the Navigator file list.


See Also

Basics: About Design and Run Modes

Choosing a Directory


Language

CD

OPEN DATABASE

SET DATABASE

SET DIRECTORY

SET PATH

USE


Open Database Dialog Box

Logs you on to the database server and opens a database.

This dialog box appears the first time you open a database. You can open multiple databases, then switch between them without logging on again. To switch between them, choose the database name from the Current Database list in the Navigator, or specify the database in the Open Table dialog box.

Dialog Box Options

Database

Specifies the name of the database server you are attempting to log on to.

Username

Specifies the computer name of the user to use this database. You can enter a user name of 31 characters in length or less.

Password

Specifies the password corresponding to the specified Username. You can enter a password 31 characters in length or less. To protect your password, the characters appear as asterisks (*).


Navigator Menus

The Navigator has the following menus:

File Menu

Edit Menu

View Menu

Navigator Menu

Properties Menu

Window Menu

Help Menu


Navigator SpeedBar

See Also

The SpeedBar is the row of buttons beneath the menu bar. Each button represents a menu command. Click the button representing the command you want to execute.

Button	Action	Menu Equivalent
	Creates a new dBASE-related file	File|New
	Opens a dBASE-related file	File|Open
	Removes the selected text/object and places it on the Clipboard	Edit|Cut
	Copies the selected text, object, or record to the Clipboard	Edit|Copy
	Inserts the text, object, or record into the active window	Edit|Paste
	Opens and runs the selected file	See Navigator Menu
	Opens the selected file for design	See Navigator Menu
	Deletes the selected file from the disk	Edit|Delete
	Switches to the Navigator window	Window|Navigator
	Switches to the Command window	Window|Command
	Opens the Form Expert	Help|Experts|Form Expert
	Opens the Interactive Tutors	Help|Interactive Tutors


See Also

Running the Primary dBASE File Types

Designing the Primary dBASE File Types


Navigator SpeedMenu

Use the Navigator SpeedMenu to quickly perform a common operation on the Navigator.

To use the SpeedMenu, right-click anywhere in the Navigator window except in the file list.

Choose from the following commands:

Navigator Properties...

Cut

Copy

Paste


Catalog File SpeedMenu

Use the Catalog File SpeedMenu to quickly perform a common operation on a catalog.

To use the SpeedMenu, select a catalog file in the Navigator, then right-click it or press Spacebar.

For more information, choose from the menu commands listed below.

Untitled

New Catalog...

Titled

Catalog Properties...

Delete

Open Catalog


Form File SpeedMenu

Use the Form File SpeedMenu to quickly perform a common operation on a form.

To use the SpeedMenu, select a form file in the Navigator or Catalog window, then right-click it or press Spacebar.

For more information, choose from the menu commands listed below.

Untitled

New Form

Titled

Form Properties...

Delete

Run Form

Design Form

Edit as Program


Image File SpeedMenu

Use the Image File SpeedMenu to quickly perform a common operation on an image.

To use the SpeedMenu, select an image file in the Navigator, then right-click it or press Spacebar.

For more information, choose from the menu commands listed below.

Untitled

New Image

Titled

Image Properties...

Delete

Display Image

Design Image


Label File SpeedMenu

Use the Label File SpeedMenu to quickly perform a common operation on a label.

To use the SpeedMenu, select a label file in the Navigator or Catalog window, then right-click it or press Spacebar.

For more information, choose from the menu commands listed below.

Untitled

New Labels

Titled

Label Properties...

Delete

Run Labels

Design Labels

Edit as Program (.LBG files only)


Program File SpeedMenu

Use the Program File SpeedMenu to quickly perform a common operation on a program.

To use the SpeedMenu, select a program file in the Navigator or Catalog window, then right-click it or press Spacebar.

For more information, choose from the menu commands listed below.

Untitled

New Program

Titled

Program Properties...

Delete

Do

Debug

Design Program


Query File SpeedMenu

Use the Query File SpeedMenu to quickly perform a common operation on a query.

To use the SpeedMenu, select a query file in the Navigator or Catalog window, then right-click it or press Spacebar.

For more information, choose from the menu commands listed below.

Untitled

New Query

Titled

Query Properties...

Delete

Run Query

Design Query

Edit as Program (.QBE files only)


Report File SpeedMenu

Use the Report File SpeedMenu to quickly perform a common operation on a report.

To use the SpeedMenu, select a report file in the Navigator or Catalog window, then right-click it or press Spacebar.

For more information, choose from the menu commands listed below.

Untitled

New Report

New Cross-Tab

Titled

Report Properties...

Delete

Run Report

Design Report

Edit as Program (.FRG files only)


Sound File SpeedMenu

Use the Sound File SpeedMenu to quickly perform a common operation on a sound.

To use the SpeedMenu, select a sound file in the Navigator, then right-click it or press

Spacebar.

For more information, choose from the menu commands listed below.

Untitled

New Sound

Titled

Sound Properties...

Delete

Play Sound

Design Sound


Table File SpeedMenu

Use the Table File SpeedMenu to quickly perform a common operation on a table.

To use the SpeedMenu, select a table file in the Navigator or Catalog window, then right-click it or press Spacebar.

For more information, choose from the menu commands listed below.

Untitled

New Table

Titled

Table Properties...

Delete

Edit Records

Add Records

Design Table Structure


File SpeedMenu | Design or Edit as Program

Opens the selected program file in the Text Editor.

Some dBASE file types, such as .QBE, are stored in ASCII text format. Usually, you design these files in their appropriate designer window, such as the Query Designer. You can also open them as text files to view the program generated from the designer window.

The dBASE for Windows Text Editor is the default editing window for programs, memo fields, and text files. You can specify a different editor in the Desktop Properties dialog box. Choose Properties|Desktop. Then click the Files tab and set the Program Editor to the application of your choice, for example, NOTEPAD.EXE. When you design a program, the program file name is sent as a command-line option to the selected editor.

dBASE opens the Text Editor and sets its defaults to those of a program. For information about the defaults, see Text File Defaults.

Edit as Program appears on the SpeedMenu for the following file extensions:

.QBE	Query

.WFM	Form

.FMT	Form

.FRG	Report

.LBG	Label

.CC	Custom control

.DEF	Define file

.H	Header file

.MNU	Menu Designer program

Shortcuts

Menu:	Navigator|Design Program (from selected program)
Catalog|Design Program (from selected program)
Navigator|Edit as Program (from selected file)
Catalog|Edit as Program (from selected file)

SpeedBar:	 (from selected program in Navigator or Catalog window)

Keyboard:	Shift+F2 (from selected program in Navigator or Catalog window)

Mouse:	Double-right-click the program file in the Navigator or Catalog window.


Catalog File SpeedMenu | Open Catalog

Opens the selected catalog file in the Catalog window.

Shortcuts

Menu:	Navigator|Open Catalog (from selected catalog)

SpeedBar:	 (from selected catalog in Navigator window)

Keyboard:	F2 (from selected catalog in Navigator window)

Mouse:	Double-click the catalog file in the Navigator window.
Drag the catalog file from the Navigator window into the Desktop or Command window.


File SpeedMenu | Edit as Program or Text

Opens the selected file in the Text Editor.

Some dBASE file types, such as .QBE, are stored in ASCII text format. Usually, you design these files in their appropriate designer window, such as the Query Designer. You can also open them as text files to view the program generated from the designer window.

If the SpeedMenu command you choose is Edit as Program, dBASE opens the Text Editor and sets its defaults to those of a program. If the SpeedMenu command you choose is Edit as Text, dBASE opens the Text Editor and sets its defaults to those of a text file. For information about the defaults, see Text File Defaults.

Note:	The dBASE for Windows Text Editor is the default editor for editing text and program files. You can change the editing application in the Desktop Properties dialog box. See Properties|Desktop.

Edit as Program appears on the SpeedMenu for the following file extensions:

.QBE	Query

.WFM	Form

.FMT	Form

.FRG	Report

.LBG	Label

Edit as Program or Edit as Text also appears on the SpeedMenu for file extensions that you can view in the Custom file type. Here are some examples:

.BAK	Backup file	Edit as Text
.BAT	DOS Batch file	Edit as Text
.CC	Custom control	Edit as Program
.DEF	Define file	Edit as Program
.H	Header file	Edit as Program
.MNU	Menu Designer program	Edit as Program
.PRT	Print file	Edit as Text
.TXT	Text file	Edit as Text
Shortcuts

Menu:	Navigator|Edit as Program or Text
Catalog|Edit as Program or Text


Custom File SpeedMenu

Use the Custom File SpeedMenu to quickly perform a common operation on a custom file.

To use the SpeedMenu, select a custom file in the Navigator, then right-click it or press Spacebar.

The primary dBASE files types are recognized by file extension. When you right-click one of these files, the SpeedMenu provides commands appropriate to the file type you select.

When you right-click a nonprimary dBASE file type, the SpeedMenu lists two basic menu commands: File Properties and Delete Selected Item. Other menu commands are available depending on the file type or file attributes. If the file is recognized as a program or text file, such as <filename>.H, Edit as Program or Edit as Text appears. If the file has a File Manager association, Open Associated Application appears.

Custom File SpeedMenus have the following two menu commands:

File Properties...

Delete

One or more of the following additional menu commands can also appear:

Design Menu

Edit as Program or Text

Load Custom Controls

Open Associated Application

Run Executable File


Custom | Run Executable File

Runs the selected application.

Executable files have the file extension .BAT, .COM, or .EXE.

You can edit .BAT files in the Text Editor.

Shortcuts

Menu:	Navigator|Run Executable File

SpeedBar:	 (from selected file in Navigator window)

Keyboard:	F2 (from selected file in Navigator window)

Mouse:	Double-click a file in the Navigator window.
Drag the file from the Navigator window into the Desktop or Command window.


Custom | Open Associated Application

Opens the selected file, if the file extension has a File Manager association.

Using the menu command, you can open any file from within dBASE for Windows. The primary dBASE file types are recognized by file extension. When you right-click one of these files, the SpeedMenu provides commands appropriate to the file type you select. Other file types are supported by using the File Manager association. When you choose Open Associated Application, the application associated with that file extension is opened and the file displayed.

Shortcuts

Menu:	Navigator|Open Associated Application

SpeedBar:	 (from selected file in Navigator window)

Keyboard:	F2 (from selected file in Navigator window)

Mouse:	Double-click a file in the Navigator window.
Drag the file from the Navigator window into the Desktop or Command window.


Edit Menu (Navigator)

Use the Edit menu to perform editing operations and to copy or remove text.

The Edit menu works differently in each of the windows. The most common use of the Edit menu is to work with text, for example, to move text around or to delete text. For information about using the Edit menu in different windows, see Where the Edit Menu Works.

You can cut, copy, or paste text using the Clipboard. The Clipboard is a temporary storage area for information you want to move or copy from one location to another.

Choose from the following commands:

Undo or Redo

Cut

Copy

Paste

Delete

Select All


Where the Edit Menu Works

Below is a list of where the Edit menu commands work in the different windows:

Window	Editing Area

Navigator	Current Directory and Search Path text boxes

Catalog window	Catalog Description and Current Item Descriptions text boxes

Command window	Input pane, results pane

Table Designer	Name, Width, and Decimal text boxes

Table Records window	Entry fields, memo fields, entire records

OLE Viewer	OLE documents in the window

Query Designer	Example elements

Form Designer (Layout)	Objects on the form

Form Designer (Order)	Objects on the form

Form Viewer	Text boxes, entry fields, memo fields, editor objects

Text Editor	Entire window


Edit | Undo or Redo

See Also

Reverses the effect of the last typing or Clipboard operation.

Undo reverses the following editing operations:

Typing

Edit|Cut

Edit|Paste (you cannot Undo a record paste operation)

Edit|Delete

After you undo an edit, the Undo menu command is replaced with Redo. Redo restores the original editing operation. After you redo an edit, the Redo command is replaced with Undo. Otherwise, the next editing operation brings back the Undo command.

Note:	Redo is not available in the Table Records window.

You can undo only one editing operation.

The Undo command is not available if you have not performed an editing operation.

For information about using the Edit menu in different windows, see Where the Edit Menu Works.

Shortcuts

Keyboard:	Ctrl+Z


See Also

Edit Menu (Navigator)


Edit | Cut

See Also

Removes the selected text or object and places it on the Clipboard.

Use this command to move text or an object, such as an OLE picture, from one place to another.

Once the Clipboard contains text or an object, you can paste it elsewhere using Edit|Paste.

The contents of the Clipboard are not deleted when you paste, so you can paste many times.

The Clipboard holds only one entry, so each time you cut, the previously cut or copied entry is replaced.

To reverse the effect of this command, choose Edit|Undo.

To copy text or an object and move it to another place, choose Edit|Copy followed by Edit|Paste.

To remove text or an object without placing it on the Clipboard, choose Edit|Delete.

The Cut command is not available if no text or objects are selected.

For information about using the Edit menu in different windows, see Where the Edit Menu Works.

Shortcuts

SpeedBar:

SpeedMenu:	Cut

Keyboard:	Ctrl+X


See Also

Edit Menu (Navigator)

Edit|Copy

Edit|Delete

Edit|Paste

Edit|Undo


Edit | Copy

See Also

Copies the selected text, object, or record to the Clipboard without removing it from its original location.

Use this command to copy an item, such as an OLE picture, to another location.

Once the Clipboard contains an item, you can paste it elsewhere using Edit|Paste.

The contents of the Clipboard are not deleted when you paste, so you can paste many times.

The Clipboard holds only one entry, so each time you copy, the previously cut or copied entry is replaced.

To move text or an object, use Edit|Cut followed by Edit|Paste.

To reverse the effect of this command, choose Edit|Undo.

The Copy command is not available if no text, objects, or records are selected.

For information about using the Edit menu in different windows, see Where the Edit Menu Works.

Shortcuts

SpeedBar:

SpeedMenu:	Copy

Keyboard:	Ctrl+C


See Also

Edit Menu (Navigator)

Edit|Cut

Edit|Delete

Edit|Paste

Edit|Undo


Edit | Paste

See Also

Inserts text, an object, or a record from the Clipboard to the location you specify in the active window.

This command inserts data previously put on the Clipboard by Edit|Cut, Edit|Copy, or another application. Text appears at the insertion point. Objects appear in the active window.

The contents of the Clipboard are not deleted when you paste, so you can paste many times.

To reverse the effect of this command, choose Edit|Undo. You cannot Undo a Paste operation if you are pasting a record in the Table Records window.

The Paste command is not available if the Clipboard is empty or when what is on the Clipboard cannot be pasted into the active window.

For information about using the Edit menu in different windows, see Where the Edit Menu Works.

Shortcuts

SpeedBar:

SpeedMenu:	Paste

Keyboard:	Ctrl+V


See Also

Edit Menu (Navigator)

Edit|Copy

Edit|Cut

Edit|Undo


Edit | Delete

See Also

Removes the selected text or object without placing it on the Clipboard.

To reverse the effect of this command, choose Edit|Undo.

To remove text or an object and place it on the Clipboard for later pasting, choose Edit|Cut. As long as you do not cut or copy any other text, the contents of the Clipboard remains intact.

The Delete command is not available if no text or objects are selected.

In the Navigator or Catalog window, this command deletes the selected file from the disk or catalog.

In the Navigator, use Delete to delete a specified file from your disk. If an open catalog referenced the deleted file, the file is not automatically removed from the catalog. However, the next time you open the catalog, dBASE asks if you want to remove the reference to the deleted file.

In the Catalog window, use Delete to delete a specified file first from the catalog, then from the disk.

Before the file is deleted from the catalog or disk, a dialog box appears asking you to confirm. Choose Yes to delete the file. Choose No to keep the file and return to the Navigator or Catalog window.

For information about using the Edit menu in different windows, see Where the Edit Menu Works.

Shortcuts

SpeedBar:	 (Navigator and Catalog window)

SpeedMenu:	Delete (each file in the Navigator or Catalog window)

Keyboard:	Del


See Also

Edit Menu (Navigator)

Edit|Cut

Edit|Paste

Edit|Undo


Edit | Select All

See Also

Selects all the text or objects in the active editing area.

Once text or objects are selected, you can cut or copy them to the Clipboard. Once the Clipboard contains text or an object, such as an OLE picture, you can paste it elsewhere using Edit|Paste.

To reverse the effect of this command, click outside the editing area.

The Select All command is not available if the editing area contains no text or objects.

For information about using the Edit menu in different windows, see Where the Edit Menu Works.


See Also

Edit Menu (Navigator)

Edit|Copy

Edit|Cut

Edit|Paste


File Menu (Navigator)

Use the File menu to create new files, open and run existing files, and exit dBASE for Windows.

The New and Open commands manipulate the primary file types, such as tables, queries, and forms. The New command displays a menu allowing you to choose the type of file you want to create. The Open command lets you run or design an existing file.

You can open as many files as you like, and each appears in its own window. However, the Navigator and Command windows are unique and cannot be opened more than once.

Choose from the following commands:

New

Open...

Close

Import...

Exit

(closed file list)


File | New

See Also

Displays a cascading menu. From the menu, choose the type of file you want to create.

Choose from the following commands:

Table

Query

Form

Report

Cross-Tab

Labels

Program

Catalog...

Shortcuts

SpeedBar:


See Also

File Menu (Navigator)

File|Open


File | New | Table

See Also

Opens the Table Designer. In the Table Designer, you can define or modify the structure of a table. For information about the Table Designer, see Designing Table Structures.

This command defaults to an untitled dBASE table. Once in the Table Designer, you can change the table type, and save and name the table with File|Save As.

Shortcuts

Menu:	Navigator|New Table (from Untitled table)
Catalog|New Table (from Untitled table)

SpeedBar:	 (from Untitled table in Navigator or Catalog window)

SpeedMenu:	New Table (from Untitled table in Navigator or Catalog window)

Keyboard:	Shift+F2 (from Untitled table in the Navigator or Catalog window)

Mouse:	Double-click or double-right-click the Untitled table in Navigator or Catalog window.


See Also

File Menu (Navigator)

Designing Table Structures


File | New | Query

See Also

Opens the Query Designer. In the Query Designer, you can organize, sort, and select data from one or more tables. For information about the Query Designer, see Designing Queries.

If a table is not already open in the current session, this command asks you to open a table by specifying it in the Open Table Required dialog box.

This command defaults to an untitled query. Once in the Query Designer, you can save and name the query with File|Save As.

Shortcuts

Menu:	Navigator|New Query (from Untitled query)
Catalog|New Query (from Untitled query)

SpeedBar:	 (from Untitled query in Navigator or Catalog window)

SpeedMenu:	New Query (from Untitled query in Navigator or Catalog window)

Keyboard:	Shift+F2 (from Untitled query in the Navigator or Catalog window)

Mouse:	Double-click or double-right-click the Untitled query in Navigator or Catalog window.


See Also

File Menu (Navigator)

Designing Queries


Open Table Required Dialog Box

See Also	Language

Opens a table using the name, location, and type that you specify.

dBASE tables have the extension .DBF and have the file type "dBASE Table (*.DBF)." Paradox tables have the extension .DB and have the file type "Paradox Table (*.DB)."

By default, this dialog box displays dBASE tables.

If you frequently use Paradox tables, you can change the default file type to Paradox by choosing Properties|Desktop. Click the Table tab and set the Default Table Type to Paradox.

If you are connected to a database server or if you have local databases, a Databases button appears. Choose the Databases button to work with a table stored in a database. The Open Table Required dialog box changes to display databases. See Open Table dialog box for information. Choose the Files button to work with tables from your directory structure.

For general information about opening files, see Open File dialog box.


See Also

File|Open

Open File dialog box


Language

SET DBTYPE


Open Table Dialog Box

See Also

Connects to a specified database and opens a specified table.

Choose a Database to connect to, then specify the table name to open. Once you choose a table, dBASE loads it into the Table Records window or the Table Designer. Once that window becomes active, the menus and SpeedBar change to reflect the purpose of the window.

For information about standard and nonstandard databases, see Navigator Components.

This dialog box is similar to the Databases option of the Open Table Required dialog box.

Dialog Box Options

Table Name

Specifies the name of the table to open. Type the name or choose it from the Table Name list box.

Table Types

Specifies the types of files displayed in the Table Name list box. Use the drop-down button to choose from the list of available file types. If the active database is a standard database, you can choose between dBASE and Paradox table types. The default is typically dBASE. If you frequently use Paradox tables, you can change the default file type to Paradox. Choose Properties|Desktop, click the Table tab, and set the Default Table Type to Paradox.

If the active database is a nonstandard database, you can choose between User Tables and All Tables. User tables are non-system SQL tables. All tables includes both user and system tables.

Databases

Specifies which database to connect to. Double-click a database to view its tables. If the database you choose requires a password, the Open Database dialog box appears. After you connect to the database, the list of tables in that database appears.

Files

Displays the Open File dialog box or displays files from your directory structure.

Run or Design

Specifies how to open the table. Choose Run to view the data in the table. Choose Design to modify the table structure. These options are available if you open this dialog box by choosing File|Open and choose Databases.


See Also

Navigator Components

Open Database dialog box

Open File dialog box

Open Table Required dialog box


File | New | Form

See Also

Opens the Form Expert or the Form Designer. In the Form Expert, you select from several simple options, then let dBASE create your form layout. The new form layout appears in the Form Designer.

In the Form Designer, you can build or modify screen displays, such as data entry forms, and build applications. For information about the Form Designer, see Designing Forms.

This command defaults to an untitled form. Once in the Form Designer, you can save and name the form with File|Save As.

You can specify whether the Form Expert appears automatically when you create a new form in the Form Designer Properties dialog box.

Shortcuts

Menu:	Navigator|New Form (from Untitled form)
Catalog|New Form (from Untitled form)

SpeedBar:	 (from Untitled form in Navigator or Catalog window)

SpeedMenu:	New Form (from Untitled form in Navigator or Catalog window)

Keyboard:	Shift+F2 (from Untitled form in the Navigator or Catalog window)

Mouse:	Double-click or double-right-click the Untitled form in Navigator or Catalog window.


See Also

File Menu (Navigator)

Designing Forms


File | New | Report

See Also

Opens the Report Designer. In the Report Designer, you can design, display, and print data in a tabular, cross-tab, or mailing label format.

If you have a table open, the Report Designer uses its structure as the base definition of the report. Otherwise this command asks you to open a table by specifying it in the Open Table Required dialog box.

For information about the Report Designer, see Designing Reports and Labels.

Shortcuts

Menu:	Navigator|New Report (from Untitled report)
Catalog|New Report (from Untitled report)

SpeedBar:	 (from Untitled report in Navigator or Catalog window)

SpeedMenu:	New Report (from Untitled report in Navigator or Catalog window)

Keyboard:	Shift+F2 (from Untitled report in the Navigator or Catalog window)

Mouse:	Double-click or double-right-click the Untitled report in Navigator or Catalog window.


See Also

File Menu (Navigator)

Designing Reports and Labels


File | New | Cross-Tab

See Also

Opens the Report Designer and displays the Cross-Tab dialog box.

If you have a table open, the Report Designer uses its structure as the base definition of the report. Otherwise this command asks you to open a table by specifying it in the Open Table Required dialog box.

For information about the Report Designer, see Designing Reports and Labels.

Shortcuts

Menu:	Navigator|New Cross-Tab (from Untitled report)
Catalog|New Cross-Tab (from Untitled report)

SpeedMenu:	New Cross-Tab (from Untitled report in Navigator or Catalog window)


See Also

File Menu (Navigator)

Designing Reports and Labels


File | New | Labels

See Also

Opens the Report Designer. In the Report Designer, you can design, display, and print data in a tabular, cross-tab, or mailing label format.

If you have a table open, the Report Designer uses its structure as the base definition of the labels. Otherwise this command asks you to open a table by specifying it in the Open Table Required dialog box.

For information about the Report Designer, see Designing Reports and Labels.

Shortcuts

Menu:	Navigator|New Labels (from Untitled label file)
Catalog|New Labels (from Untitled label file)

SpeedBar:	 (from Untitled label file in Navigator or Catalog window)

SpeedMenu:	New Labels (from Untitled label file in Navigator or Catalog window)

Keyboard:	Shift+F2 (from Untitled label file in the Navigator or Catalog window)

Mouse:	Double-click or double-right-click the Untitled label file in Navigator or Catalog window.


See Also

File Menu (Navigator)

Designing Reports and Labels


File | New | Program

See Also

Opens the Text Editor. In the Text Editor, you can type your dBASE programs. For information about the dBASE for Windows Text Editor, see Editing Text.

This command defaults to an untitled file. When you save and name the file with File|Save As, the default file extension is .PRG.

The dBASE for Windows Text Editor is the default editing window for programs, memo fields, and text files. You can specify a different editor in the Desktop Properties dialog box. Choose Properties|Desktop. Then click the Files tab and set the Program Editor to the application of your choice, for example, NOTEPAD.EXE.

Shortcuts

Menu:	Navigator|New Program (from Untitled program)
Catalog|New Program (from Untitled program)

SpeedBar:	 (from Untitled program in Navigator or Catalog window)

SpeedMenu:	New Program (from Untitled program in Navigator or Catalog window)

Keyboard:	Shift+F2 (from Untitled program in the Navigator or Catalog window)

Mouse:	Double-click or double-right-click the Untitled program in Navigator or Catalog window.


See Also

File Menu (Navigator)

Editing Text


File | New | Catalog...

See Also

Opens a Catalog window and creates a catalog file. In a Catalog window, you can visually group related files, such as tables, queries, and forms. For information about the Catalog window, see Using the Catalog Window.

This command asks you to specify the name and location of the catalog in the Create Catalog dialog box. Catalog files have the extension .CAT and have the File Type Catalog (*.CAT).

For general information about saving files, see Save As dialog box.

Shortcuts

Menu:	Navigator|New Catalog... (from Untitled catalog)

SpeedBar:	 (from Untitled catalog in Navigator window)

SpeedMenu:	New Catalog... (from Untitled catalog in Navigator window)

Keyboard:	Shift+F2 (from Untitled catalog in Navigator window)

Mouse:	Double-click or double-right-click the Untitled catalog in Navigator window.


See Also

File Menu (Navigator)

Using the Catalog Window


File | Open...

See Also

Opens an existing file and displays it in a window corresponding to its file type, such as table, query, or form.

You can open the file in either Run or Design mode. For information about running and designing files, see Running the Primary dBASE File Types and Designing the Primary dBASE File Types.

This command displays the Open File dialog box from which you choose the file type, name, and location.

Shortcuts

SpeedBar:

Keyboard:	Ctrl+O


See Also

File Menu (Navigator)

File|New


Open File Dialog Box

See Also	Language

Opens or selects a file that you specify. This help topic describes the dialog box that appears when you choose File|Open. It also describes the options common to all dialog boxes that choose a file name.

Select the drive and directory in which to find your file, then specify the file name.

When you are opening a file, once you choose the file name, dBASE loads the file into the appropriate file-type window. For example, if you choose to run a dBASE table file (.DBF), it appears in the Table Records window. Once the newly opened window becomes active, the menus and SpeedBar change to reflect the purpose of the window.

By default, this dialog box displays the primary file extension of the file type currently in use. If you are using the Navigator or Catalog window, the selected file type is displayed. If you are editing a file in a window, that file type is displayed.

Dialog Box Options

File Name

Specifies the name of the file to open. If the Navigator or Catalog window is active, the selected file name appears. Type the name or choose it from the File Name list box.

File Types

Specifies the types of files displayed in the File Name box. Use the drop-down button to choose it from the list of available file types. By default, the Open File dialog box displays the file type that is in use or is being displayed in the Navigator or Catalog window.

If you frequently use Paradox tables, you can change the default table type to Paradox by choosing Properties|Desktop, choosing the Table page, and setting the Default Table Type to Paradox.

For more information about the file types, see File Types and SpeedMenus.

Directories

Specifies the full path and directory where the current list of files resides. Select the path and directory from which to open the file. When you first load dBASE for Windows, the default directory is the Current Directory in the Navigator. After that, the default is the last directory you used.

Drives

Specifies the drive letter where the current list of files resides. Use the drop-down button to choose a drive from the list of available drives.

Run or Design

When you are opening a file, these options specify how to open the file. These options change for each file type selected. For example, program files have the options Do and Design Program and form files have the options Run Form and Design Form.

Databases

Opens the Open Table dialog box. Use this option to connect to a standard or nonstandard database and open a table stored in the database. The Databases buttons is not available unless you have one or more database aliases defined in the IDAPI configuration file.

Network

Opens the Windows Connect Network Drive dialog box, where you can specify a remote network drive and directory. The Network button is not available on all Windows systems. See your Windows documentation for more information.


See Also

File Types and SpeedMenus

Navigator Components

Open Database dialog box

Properties|Desktop


Language

SET DBTYPE


File | Close

See Also	Language

Closes or minimizes the active window.

Use File|Close to close the active window and remove it from the screen. The Navigator and Command windows minimize rather than close. You can reopen the Navigator and Command windows by double-clicking the minimize icon or by choosing Window|Navigator or Window|Command. You can reopen recently closed windows by choosing them from the File|(closed file list).

If Sessions is checked in the Desktop Properties dialog box, closing the window also closes the file.

If Sessions is unchecked, closing the window does not necessarily close the file. The files that remain open and in memory, even though the window is closed, are

Tables

Catalogs

To close and remove tables and catalogs from memory,

Type USE in the Command window.

Type SET CATALOG TO in the Command window.

Note:	This command is the same as choosing Close from the Control menu of the active window.

Shortcuts

Keyboard:	Ctrl+F4


See Also

Basics: About Sessions

File Menu (Navigator)

Properties|Desktop


Language

SET CATALOG

USE


File | Exit

See Also	Language

Closes all open files and exits dBASE for Windows.

Changes to open tables, indexes, and catalogs are automatically saved. If any other files are unsaved, a dialog box appears asking if you want to save them before exiting. If you choose Yes, the file is saved, or the Save As dialog box appears.

When you exit, the position and state of the Command window and Navigator are saved. The position of dialog boxes and windows and the font and color selections are also saved.


See Also

File Menu (Navigator)

Table|Table Utilities|Close All Tables


Language

QUIT


File | (closed file list)

See Also

Reopens a previously closed or recently used file.

When you use or close a file, it is added to the bottom of the File menu, so you can quickly reopen it. Choose a file name from the list at the bottom of the File menu to reopen the file.

dBASE opens the file in the window it was last used in. For example, if you reopen a table in which you were most recently adding records, the table appears in the Table Records Window.

If the file extension does not correspond to a primary dBASE file type, the file is opened in the Text Editor.

To open files and view them in the Text Editor, hold down Ctrl while choosing the file name. This is useful for viewing generated program code. For example, the Query Designer generates a .QBE file, which is a text file of dBASE commands. Similarly, the Form Designer generates a .WFM text file. To open these files and see the text, hold down Ctrl, then choose a file from the list. The file appears in the Text Editor. This works effectively with text files, which are files containing regular text characters.

You can specify how many file names appear in the closed file list by changing the MRU (most recently used) Size on the Application page of the Desktop Properties dialog box.


See Also

File Menu (Navigator)

Properties|Desktop

View|All


File | Print...

See Also

Prints the contents of the active window.

The windows you can print are

Table Records Window (See tables File|Print for information)

Table Structure

Query Designer

Form Viewer

Form Designer

Text Editor

Image Viewer

When you choose OK, a printer status box appears while the data is sent to the printer or file.

Shortcuts

SpeedBar:

Keyboard:	Ctrl+P

Dialog Box Options

Printer

Displays the name of the active printer. Choose Setup if you want to change the active printer.

Print Range

Specifies which pages to print.

All

Prints all pages.

Selection

Prints the selected text.

Pages

Specifies a specific number of pages to print.

To print a range of pages, enter the starting and ending page numbers in the From and To boxes.

To print a single page, enter the page number in both boxes.

To print from a specific page to the end, enter the starting page in the From box and leave the To box empty.

Print Quality

Specifies the quality and resolution of the printed page. Choose from the list box. The Print Quality choices vary for different printers. In general, the higher the number, the better the quality.

Print to File

Prints to a file, rather than the printer. If you choose Print to File, the Print to File dialog appears when you choose OK. Type the full path and file name of the file to receive the output. If the file exists, dBASE asks if you want to overwrite it. The file generated is not a standard text file; it contains printer and formatting codes so you can print the file later from DOS with full formatting.

Copies

Specifies the number of copies to print. The maximum number of copies is 999.  dBASE sends the output to the Windows Print Manager only once. If you specify more than one copy, Print Manager sends multiple copies of the output to the printer.

Collate Copies

Prints multiple copies as a set instead of printing multiple copies of each page before moving on to the next page.

Setup

Opens the Print Setup dialog box. For more information, see File|Printer Setup.


See Also

File|Printer Setup

File|Print (Table Records window)

File Menu (Form Designer)

File Menu (Forms)

File Menu (Image Viewer)

File Menu (Query Designer)

File Menu (Reports and Labels)

File Menu (Table Designer)

File Menu (Table Records window)

File Menu (Text Editor)


File | Printer Setup...

See Also

Changes printer options and selects a printer from a list.

For more information about setting printer options, see your Windows documentation.

Dialog Box Options

Default Printer

Makes the default printer current.

Specific Printer

Makes a specific printer current. Choose the printer you want from the list box.

Orientation

Prints your document lengthwise or widthwise.

Portrait

Prints text across the narrowest side of the paper (e.g. 8.5" x 11").

Landscape

Prints text along the widest side of the paper (e.g. 11" x 8.5").

Paper Size

Specifies the standard paper sizes supported by your printer.

Paper Source

Specifies which paper tray or paper feeding method your printer uses.

Options

Opens the Options dialog box so you can set options specific to your printer driver. For information on Options, choose the Help button.


See Also

File|Print...

File|Print (Table Records window)

File Menu (Form Designer)

File Menu (Forms)

File Menu (Image Viewer)

File Menu (Query Designer)

File Menu (Reports and Labels)

File Menu (Table Designer)

File Menu (Table Records window)

File Menu (Text Editor)


Navigator Menu (Navigator)

See Also

Use the Navigator menu to perform operations on the selected item in the Navigator.

In the Navigator, choose from the list of file types, and then select a file in the file list on the right side of the window. Once you select a file, you can manipulate it in one of four ways:

Choose a menu command on the Navigator menu.

Double-click the file to run it, or double-right-click the file to design it.

Choose a SpeedMenu command. To view the SpeedMenu, right-click the file or press Spacebar.

Click [image] to run the file. Click [image] to design the file.

The Navigator menu changes for each file type, and within each file type, for titled and untitled files. Refresh Items always appears. The file-specific menu commands are the following:

Tables	Programs
New Table	New Program
Edit Records	Do
Add Records	Debug
Design Table Structure	Design Program
Queries	Images
New Query	New Image
Run Query	Display Image
Design Query	Design Image
Edit as Program	Sounds
Forms	New Sound
New Form	Play Sound
Run Form	Design Sound
Design Form	Catalogs
Edit as Program	New Catalog...
Reports	Open Catalog
New Report	Custom
Run Report	Open Associated Application
Design Report
Edit as Program
Labels
New Labels
Run Labels
Design Labels
Edit as Program
Note:	The Navigator menu corresponds to the SpeedMenu for each file type. In addition, the SpeedMenu offers choices for viewing the file properties and deleting the file. See Properties|Selected File Item and Edit|Delete for information.


See Also

File Types and SpeedMenus


Navigator | Refresh Items

See Also

Re-creates the list of files in the Navigator window.

Use Refresh Items to force dBASE to re-create the list of file icons for the current file type. This command is useful if you work on a network or shared drive that changes frequently.

The Navigator window automatically refreshes the list when

You return to dBASE for Windows from another application

You use the ERASE, RENAME, or COPY FILE commands in the Command window

You use a command in the Command window that operates on a database, such as SET DATABASE or OPEN DATABASE


See Also

Navigator Menu

Navigator Components


Properties Menu (Navigator)

Use the Properties menu to change the characteristics of the dBASE for Windows Desktop, the Navigator, and specific files.

Choose from the following commands:

Desktop...

Navigator...

Selected File Item...


Properties | Desktop...

See Also	Language

Changes the characteristics of items that affect the dBASE environment, files, data, keystrokes, directories, and external applications. This menu command opens the Desktop Properties dialog box. This menu command is always available.

dBASE records the choices you make in this dialog box in the DBASEWIN.INI file. Each time a new session is created, dBASE reads the settings from the DBASEWIN.INI file. To change settings for a session, first make the session active by making the table or query active. Then choose Properties|Desktop and make the changes. The changes are used immediately in that session and are also stored in the DBASEWIN.INI file for future sessions. The changes are not used in other open sessions.

Unless otherwise noted, options in this dialog box apply globally in the dBASE environment. Those that do not affect the global environment affect the environment of the current session.

Many items in the Desktop Properties dialog box correspond to a SET command in the dBASE language. You can read more about the language commands by using the Language popup in the Country, Table, Data Entry, Files, Application, and Programming topics.

This dialog box is separated into six pages, which you access by clicking the tabs at the bottom of the dialog box.

Dialog Box Options

Country

Sets how currency, dates, and numbers are displayed.

Table

Sets how tables, records, and fields are opened, compared, excluded, saved, searched, locked, refreshed, and reprocessed.

Data Entry

Sets how you use the keyboard, view data entry fields, and use the bell.

Files

Sets the working directories, editors, data layouts, and file types, and how files are opened in the dBASE environment.

Application

Sets how you view the SpeedBar, status bar, Object Inspector, and closed file list.

Programming

Sets how data, test programs, and text appear, how numbers are calculated, and how programs are compiled and analyzed.


See Also

Properties Menu (Navigator)

Basics: About Sessions


Language

SET


Properties | Navigator...

See Also

Changes the characteristics of the Navigator window.

In the Navigator window, you work with file types, files, and directories.

Settings you make in this dialog box are also reflected in the Catalog Properties dialog box.

dBASE records the choices you make in this dialog box in the DBASEWIN.INI file.

Shortcuts

SpeedMenu:	Navigator Properties...

Dialog Box Options

Large Icons

Specifies the spacing of large file icons. You set the view to large icons using View|Large Icons.

Small Icons

Specifies the spacing of small file icons. You set the view to small icons using View|Small Icons.

Details

Specifies the spacing of file icons in Details view. You set the view to show file details using View|Details.

X Spacing

Sets the amount of space in pixels between columns of file icons. A pixel is a single dot on your computer screen.

Y Spacing

Sets the amount of space in pixels between rows of file icons. A pixel is a single dot on your computer screen.

Use Supplemental Search Path

Adds a Search Path text box to the Navigator. When Search Path and Current Directory are both displayed, dBASE displays files in all the directories specified in both text boxes.

Reset

Changes the X and Y Spacing text boxes to their default values.


See Also

Properties Menu (Navigator)

Navigator Components

Properties|Catalog Window


Properties | Selected File or Catalog Item...

See Also

Displays the characteristics of the file selected in the Navigator or Catalog window.

This command is not available if the selected file is Untitled.

Shortcuts

SpeedMenu:	File Properties... (each file in the Navigator or Catalog window)

Keyboard:	Alt+Enter

Dialog Box Options

Name

Displays the file name.

Path

Displays the full path name of the file. If the file is in a catalog and the path is unknown, the current directory appears.

Type

Displays the file type and file icon. The file types match those listed in the Navigator and Catalog window.

Records

Displays the number of records in the table, if the selected file is a dBASE table. If the selected file has the file extension .DBF but is not a table, Not a dBASE table appears.

Description

Specifies a description for the file. The maximum length of the description is 80 characters. This description appears at the bottom of the Catalog window, when the file is selected. This option is available only if you are viewing the properties for files in the Catalog window.

Associated Table or Query Name

Specifies the path and file name associated with the selected file, if any. This option is available only if you are viewing the properties for form, report, or label files in the Catalog window.

Last Changed

Displays the date and time the file was last saved. You can specify the date format in the Desktop Properties dialog box.

Size

Displays the size in bytes of the file. You can specify the number format in the Desktop Properties dialog box.

Read Only or Not Read Only

Specifies if you can change the file. A read-only file cannot be changed.

Archived or Not Archived

Specifies if the file has been backed up with the DOS BACKUP or XCOPY commands.


See Also

Properties Menu (Navigator)

Properties Menu (Catalog window)

Navigator Components

Properties|Desktop

View|Associations


Country Properties

See Also	Language

Sets how currency, dates, and numbers are displayed.

The defaults for each of these options are set by the International option of the Windows Control Panel. For more information, see your Windows documentation or Windows Help.

Numerics

Sets attributes for how numbers are displayed. An example displays the results of your changes.

Separator

Specifies the character that separates each group of 3 digits (whole numbers) to the left of the decimal point in the display of numbers greater than or equal to 1000. This setting is part of a session.

Point

Specifies the character that separates decimal digits from integer digits in numeric display and input. This setting is part of a session.

Currency

Sets attributes for how dollar amounts are displayed. An example displays the results of your changes.

Position Left

Places currency symbol(s) to the left of currency numbers. This setting is part of a session.

Position Right

Places currency symbol(s) to the right of currency numbers. This setting is part of a session.

Symbol

Determines the character(s) used for the currency sign. The maximum length is six. This setting is part of a session.

Date

Sets attributes for how dates are displayed. An example displays the results of your changes.

Date Format

Specifies the format for the display and entry of dates. This setting is part of a session. Below are the choices and formats:

Option	Format

GERMAN	DD.MM.YY

JAPAN	YY/MM/DD

USA	MM-DD-YY

YMD	YY/MM/DD

MDY	MM/DD/YY

DMY	DD/MM/YY

Mark

Sets the character to separate the month, day, and year when displaying dates. This setting is part of a session.

Century

Displays dates with either 2- or 4-digit years: when unchecked, 2-digit years; when checked, 4-digit years. This setting is part of a session.


See Also

Basics: About Sessions

Properties|Desktop

Application Properties

Data Entry Properties

Files Properties

Programming Properties

Table Properties


Language

SET CENTURY

SET CURRENCY

SET DATE

SET MARK

SET POINT

SET SEPARATOR


Table Properties

See Also	Language

Sets how tables, records, and fields are opened, compared, excluded, saved, searched, and locked.

Multiuser

Sets options for tables with more than one user.

Lock

Determines whether dBASE attempts to lock a shared table during execution of commands that read the table but do not change its data. The default is on (checked). This setting is part of a session.

Exclusive

Controls whether dBASE opens tables and their associated index and memo files for exclusive or shared use. The default is off (unchecked). This setting is part of a session.

Refresh

Determines how often (in seconds) the workstation screen is refreshed with table information from the server. The default is 0, meaning the screen is not updated. This setting is part of a session.

Reprocess

Specifies the number of times dBASE tries to lock a file or one or more records before generating an error or returning .F. (false). The default is 0, meaning dBASE does not try to lock a file or one or more records more than once. This setting is part of a session.

Default Table Type

Sets the default table type used by commands that open or create a table. This setting is part of a session.

dBASE

Sets the table type to a dBASE table. The default is dBASE.

Paradox

Sets the table type to a Paradox table. The default is dBASE.

Block Sizes

Sets the number of bytes allocated when creating index files and memo fields. Using these values, you can affect the size and efficiency of these files.

Index Block

Changes the size of blocks in which dBASE stores .MDX index files on disk to improve the performance and efficiency of indexes. The default is 1. The size in bytes is the number you specify multiplied by 512. The minimum block size is 1024 bytes. This setting is part of a session.

Memo Block

Changes the default block size of new memo field (.DBT) files. The size in bytes is the number you specify multiplied by 64. The default is 8, or 512 bytes. If your table will have a small amount of information in each memo field, use a smaller number. This setting is part of a session.

Other

Sets other options for working with tables.

Autosave

Determines if data is written to disk each time a record is changed or added. The default is off (unchecked). This setting is part of a session.

Exact

Sets how character strings are compared. When checked, two character strings are equal when they are identical and are the same length. When unchecked, two character strings are equal if the characters in one string match the beginning characters in the other string. The default is off (unchecked). This setting is part of a session.

Language Driver Check

Disables or enables checking for language-driver compatibility. The default is on (checked).

Deleted

Controls whether dBASE includes or excludes records marked for deletion in a table. When unchecked, all records appear in a table. When checked, records marked for deletion are excluded from processing by subsequent commands. The default is on (checked). This setting is part of a session.

Near

Specifies where to move the record pointer if a FIND, SEEK, or SEEK( ) operation fails to find an exact match. If on (checked), dBASE finds the record nearest the search value. The default is off (unchecked). This setting is part of a session.


See Also

Basics: About Sessions

Properties|Desktop

Application Properties

Country Properties

Data Entry Properties

Files Properties

Programming Properties


Language

SET AUTOSAVE

SET DBTYPE

SET DELETED

SET EXACT

SET EXCLUSIVE

SET IBLOCK

SET LDCHECK

SET LOCK

SET MBLOCK

SET NEAR

SET REFRESH

SET REPROCESS


Data Entry Properties

See Also	Language

Sets how you use the keyboard, view data entry fields, and use the bell.

Keyboard

Specifies how certain keystrokes operate.

Confirm

When checked, the insertion point moves to the next input area only when you press Enter or a direction key, or when you click another field with the mouse. When unchecked, the insertion point moves immediately to the next input area when the current one is full. The default is off (unchecked). This setting is part of a session.

CUA Enter

Determines whether the Enter key behaves in Windows mode (checked) or DOS (unchecked) mode when a form is open. If checked, Enter submits the current form. If unchecked, Enter moves from object to object on a form. The default is on (checked). This setting is part of a session.

Escape

Specifies whether pressing Esc interrupts program execution. The default is on (checked).

Typeahead

Specifies the size of the keyboard typeahead buffer. The range is 0 to 1600. The default size is 50 characters.

Delimiters

Controls whether delimiter characters mark the beginning and end of data entry fields. The default is off (unchecked). This setting is part of a session.

Characters

Specifies the characters used to mark the beginning and end of data entry fields. The default is a colon ( : ) on each side. This setting is part of a session.

Bell

Turns the computer bell on or off. The computer bell rings when you reach the end of a field or variable while editing data, or when you enter invalid data. The default is on (checked).

Frequency

The frequency of the bell tone in cycles per second. The range is 19 to 10,000. The default is 512 Hertz (cycles per second).

Duration

The duration of the bell tone in ticks (1/18 of a second). The range is 1 to 19. The default is 2.

Play Bell

Plays the bell with the frequency and duration you specify.


See Also

Basics: About Sessions

Properties|Desktop

Application Properties

Country Properties

Files Properties

Programming Properties

Table Properties


Language

SET BELL

SET CONFIRM

SET CUAENTER

SET DELIMITERS

SET ESCAPE

SET TYPEAHEAD


Files Properties

See Also	Language

Sets the working directories, editors, data layouts, and file types, and how files are opened in the dBASE environment.

Search Path

Specifies the directory or directories where dBASE looks for files that are not in the current directory. Separate multiple directory names with spaces, commas, or semicolons. The default is the current drive and directory. The path also appears in the Search Path text box of the Navigator. This setting is part of a session.

Current Directory

Specifies the primary directory where dBASE looks for files. By default, the Current Directory is the directory containing the dBASE for Windows program files (usually C:\DBASEWIN\BIN). The Search Path directories are the secondary directories searched. By default, the Navigator displays files in the Current Directory, and in the Search Path directories, if Use Supplemental Search Path is on in the Navigator Properties dialog box. This setting is part of a session.

Editors

Specifies a text editor to use for programs and memo fields.

Program

Specifies an editor to run when you open a program. By default, dBASE opens the built-in Text Editor for editing programs. Click [image] to open the Specify Program Editor dialog box where you specify the name and location of the editor. Executable files (*.EXE) are displayed by default. For general information about choosing files, see Open File dialog box.

Memo

Specifies an editor to run when you open a memo field. By default, dBASE opens the built-in Text Editor for editing memo fields. Click [image] to open the Specify Memo Editor dialog box where you specify the name and location of the editor. Executable files (*.EXE) are displayed by default. For general information about choosing files, see Open File dialog box.

Edit Records

Specifies the default layout when you open and edit a table. This setting applies when you edit a table using any of the following procedures:

Double-click the table in the Navigator or Catalog window.

Right-click the table in the Navigator or Catalog window and choose Edit Records.

Click the table in the Navigator or Catalog window and choose Navigator|Edit Records or Catalog|Edit Records.

Choose File|Open and specify a table with the Table Records option selected.

Choose Table|Edit Records from the Command window.

Choosing one of these options does not change the current layout of any open Table Records windows. To change the layout of an open window, select the window, then choose a layout command from the View menu.

In Browse Layout

Displays several records of the table in rows and columns. When editing the table, the View menu displays a checkmark next to Browse Layout.

In Form Layout

Displays one record of the table in a format like a printed form. When editing the table, the View menu displays a checkmark next to Form Layout.

In Columnar Layout

Displays one record of the table in a vertical format with all fields aligned on the left. When editing the table, the View menu displays a checkmark next to Columnar Layout.

Add Records

Specifies the default layout when you add records to an open table. This setting applies when you add records to the table using any of the following procedures:

Right-click the table in the Navigator or Catalog window and choose Add Records.

Click the table in the Navigator or Catalog window and choose Navigator|Add Records or Catalog|Add Records.

Choose Table|Add Records from the Command window.

If you edit a table, then choose Table|Add Records, the new record appears in the same layout as the Table Records window. To change the layout of an open window, select the window, then choose a layout command from the View menu.

In Form Layout

Displays an empty record in a format like a printed form. The View menu displays a checkmark next to Form Layout.

In Columnar Layout

Displays an empty record in a vertical format with all fields aligned on the left. The View menu displays a checkmark next to Columnar Layout.

Other

Sets other options for working with files.

Older File Types

Specifies which file extensions appear in the Navigator, Catalog window, Open File dialog box, and Save File dialog box. When checked, all file extensions in the following table appear. When unchecked, only the newer file extensions appear. The default is on (checked).

File Type	Newer File Extensions	Older File Extensions
Tables	.DBF, .DB
Queries	.QBE	.VUE, .QRY
Forms	.WFM	.FMT
Reports	.RPT, .RPC	.FRM, .FRG
Labels	.RPL	.LBL, .LBG
Programs	.PRG
Images	.BMP, .PCX
Sounds	.WAV
Catalogs	.CAT
Menus	.MNU
Full Path

Specifies whether functions that return file names return the full path name. The default is off (unchecked).

Sessions

Determines if sessions are used automatically. A session is an environment that includes databases, tables, indexes, transactions, and several environment characteristics. If Sessions is on, then tables and queries are opened in a different session. Thus files act independently of each other.

Sessions are created when you use the File menu, Navigator, or Catalog window to run or design a table or query. The session ends when the files in use in that session are closed. The Command window has its own session.

If Sessions is off, then queries and tables you open using the File menu, Navigator, or Catalog window are opened in different work areas, not different sessions. When sessions is off, the dBASE for Windows environment is more like the dBASE IV environment.

By default, Sessions is on (checked).

Title

Specifies whether you are prompted to enter a file title to accompany the file entry in a catalog. The default is on (checked).


See Also

Basics: About Sessions

Properties|Desktop

Application Properties

Country Properties

Data Entry Properties

Programming Properties

Table Properties

Catalog|Add Item

File|Close

File|Open

File|Save As

Navigator Components

Program|Display Coverage

Table|Add Records

View|Browse Layout

View|Columnar Layout

View|Form Layout

View|Table Records


Language

APPEND

BROWSE

CD

CREATE SESSION

EDIT

SELECT

SET DIRECTORY

SET EDITOR

SET FULLPATH

SET PATH

SET TITLE

SET WP


Application Properties

See Also

Sets how you view the SpeedBar, status bar, Object Inspector, and closed file list.

SpeedBar Position

Changes the orientation of the dBASE for Windows SpeedBar. The SpeedBar is the row of buttons below the menu bar. A SpeedMenu is a list of menu commands that appears wherever you right-click the mouse.

Horizontal, Top

Changes the orientation of the SpeedBar to a horizontal row of buttons at the top of the dBASE Desktop. This is the default orientation of the SpeedBar.

Horizontal, Bottom

Changes the orientation of the SpeedBar to a horizontal row of buttons at the bottom of the dBASE Desktop.

Vertical, Right

Changes the orientation of the SpeedBar to a vertical column of buttons on the right side of the dBASE Desktop.

Vertical, Left

Changes the orientation of the SpeedBar to a vertical column of buttons on the left side of the dBASE Desktop.

Horizontal, Floating

Changes the orientation of the SpeedBar to a horizontal row of buttons that appears in a free-floating bar. You can move the floating SpeedBar by dragging the left side of it to a new location.

Vertical, Floating

Changes the orientation of the SpeedBar to a vertical column of buttons that appears in a free-floating bar. You can move the floating SpeedBar by dragging the top of it to a new location.

Status Bar

Determines if the status bar appears. The status bar is the bar at the bottom of the application window that displays informational and error messages as you work with files and windows. The default is on (checked).

Status Bar Message Font

Changes the font of the status bar. The status bar, at the bottom of the dBASE for Windows application window, displays informational and error messages. Click [image] to open the Font dialog box. Choose a font that looks good and fits well on your monitor within the predefined height of the status bar area.

Object Properties Outline

Displays properties in the Form Designer Object Inspector in groups or in alphabetical order. When Object Properties Outline is on, the Properties page of the Object Inspector outlines the properties and lets you expand or collapse the outline. The default is on (checked).

MRU Size

Sets the number of files that appear at the bottom of the File menu. The list at bottom of the File menu represents the Most Recently Used (MRU) files. By default, the list contains up to five files. The maximum is nine files.


See Also

Basics: About SpeedBars and SpeedMenus

Basics: About Object Inspectors

Properties|Desktop

Country Properties

Data Entry Properties

Files Properties

Programming Properties

Table Properties


Programming Properties

See Also	Language

Sets how data, test programs, and text appear, how numbers are calculated, and how programs are compiled and analyzed.

Decimals

Determines the number of decimal places, from 0 to 18, to display for numeric and float numbers. The default is 2. This setting is part of a session.

Precision

Determines the number of digits used when comparing numbers. The range is 10 to 19. The default is 16. This setting is part of a session.

Margin

Adjusts the printer offset for the left margin for all printed output. The default is 0.

Space

Determines whether a space is inserted between expressions displayed or printed with a ? or ?? command and separated by commas. The default is on (checked).

Talk

Specifies whether system messages are displayed in the Command window. The default is on (checked). This setting is part of a session.

Headings

When checked, the output of AVERAGE, DISPLAY, LIST, and SUM includes a heading identifying the fields of the table(s). When unchecked, the field-name headings do not appear. The default is on (checked).

Coverage

Sets whether coverage files are created or updated when you call a program, procedure, or user-defined function (UDF) in a separate program file. A coverage file is a binary file containing cumulative information on how many times dBASE enters and exits each logical block of a program. The default is off (unchecked).

Ensure Compilation

Specifies whether a program, procedure, or format file is automatically compiled when you change the file and then execute it or open it for execution. The default is on (checked).

Design

Specifies whether CREATE and MODIFY commands can be executed. The default is on (checked).

Safety

Specifies whether you must confirm before overwriting a file or removing records from a table. The default is on (checked). This setting is part of a session.


See Also

Properties|Desktop

Application Properties

Country Properties

Data Entry Properties

Files Properties

Table Properties


Language

SET COVERAGE

SET DECIMALS

SET DESIGN

SET DEVELOPMENT

SET HEADINGS

SET MARGIN

SET PRECISION

SET SAFETY

SET SPACE

SET TALK


View Menu (Navigator)

See Also

Use the View menu to change the category of file types displayed in the Navigator window and set how files are displayed. For example, View|Queries opens the Queries file type and displays query files.

A checkmark indicates which category of file types is currently displayed. By default, the Tables file type is displayed.

Another way to choose a file type is to click it with the mouse in the Navigator window.

Choose from the following commands:

All

Tables

Queries

Forms

Reports

Labels

Programs

Images

Sounds

Catalogs

Custom

Sort

Large Icons

Small Icons

Details


See Also

View Menu (Catalog Window)


View | All

See Also

Changes the category of file types to All and displays all dBASE-related files in the list box of file icons.

Files are displayed in one of two ways:

To view files in alphabetical order, choose View|Sort|By Name.

To view files by file type, then in alphabetical order, choose View|Sort|By Type and Extension. This is the default. The file types are listed in the same order as they appear in the Navigator or Catalog window. For example, the Tables are listed first in the list of file icons, then Queries, and so on.

The status bar displays the file name of the selected file. To see more information about the selected file, such as its full path name and date changed, choose Properties|Selected File Item.

The following file extensions are displayed in the All category:

Tables	*.DBF	dBASE table

*.DB	Paradox table

Queries	*.QBE	dBASE for Windows or dBASE IV query-by-example

*.QBO	Compiled query-by-example; appears when no .QBE of the same name exists (Navigator only)

*.VUE	dBASE III PLUS or dBASE IV view

*.QRY	dBASE III PLUS filter

Forms	*.WFM	dBASE for Windows form

*.WFO	Compiled form, appears when no .WFM of the same name exists (Navigator only)

*.FMT	dBASE III PLUS and dBASE IV screen format

*.FMO	Compiled screen format, appears when no .FMT of the same name exists (Navigator only)

Reports	*.RPT	Report Designer report

*.RPC	Report Designer cross-tab report

*.FRM	dBASE III PLUS or dBASE IV report form

*.FRG	dBASE IV generated report form

*.FRO	Compiled report form, appears when no .FRG of the same name exists (Navigator only)

Labels	*.RPL	Report Designer label

*.LBL	dBASE III PLUS or dBASE IV label form

*.LBG	dBASE IV generated label form

*.LBO	Compiled label form, appears when no .LBG of the same name exists (Navigator only)

Programs	*.PRG	dBASE for Windows, dBASE III PLUS, or dBASE IV program

*.PRO	Compiled program, appears when no .PRG of the same name exists (Navigator only)

Images	*.BMP	Bitmap graphic

*.PCX	PC Paintbrush graphic

Sounds	*.WAV	Sound wave

Catalogs	*.CAT	dBASE for Windows and dBASE IV catalog

Shortcuts

Mouse:	Click the All file type in the Navigator or Catalog window.


See Also

View Menu (Navigator)

View Menu (Catalog Window)

Catalog Window Components

Navigator Components

File Types and SpeedMenus

Running the Primary dBASE File Types

Designing the Primary dBASE File Types


View | Tables

See Also

Changes the category of file types to Tables and displays all table files in the list box of file icons.

Once you choose a category of file types, the last file you used is selected. To display the file SpeedMenu, right-click a file or select the file and press Spacebar. Right-click outside the file list to display the Navigator Properties dialog box or Catalog Properties dialog box.

The status bar displays the file name of the selected file. To see more information about the selected file, such as its full path name and date changed, choose Properties|Selected File Item.

If Tables from Directory is selected, the following file extensions are displayed in the Tables category:

Tables	*.DBF	dBASE table

*.DB	Paradox table

Note:	Previous versions of dBASE use .DB as a configuration-file extension, such as CONFIG.DB and LOGIN.DB, and these should not be confused with Paradox tables.

If Tables from Database is selected, all the tables found in the selected database appear. For more information about databases, see Navigator Components.

When you design a table file, it appears in the Table Designer. See Designing Table Structures for information.

When you run a table file, it appears in the Table Records window. See Displaying and Editing Table Records for information.

Shortcuts

Mouse:	Click the Tables file type in the Navigator or Catalog window.


See Also

View Menu (Navigator)

View Menu (Catalog Window)

Catalog Window Components

Navigator Components

File Types and SpeedMenus

Running the Primary dBASE File Types

Designing the Primary dBASE File Types


View | Queries

See Also

Changes the category of file types to Queries and displays all query files in the list box of file icons.

Once you choose a category of file types, the last file you used is selected. To display the file SpeedMenu, right-click a file or select the file and press Spacebar. Right-click outside the file list to display the Navigator Properties dialog box or Catalog Properties dialog box.

The status bar displays the file name of the selected file. To see more information about the selected file, such as its full path name and date changed, choose Properties|Selected File Item.

The following file extensions are displayed in the Queries category:

Queries	*.QBE	dBASE for Windows or dBASE IV query-by-example

*.QBO	Compiled query-by-example; appears when no .QBE of the same name exists (Navigator only)

*.VUE	dBASE III PLUS or dBASE IV view

*.QRY	dBASE III PLUS filter

When you design a query, it appears in the Query Designer. See Designing Queries for information.

When you run a query, it appears in the Query Results window. See Running Queries for information.

Shortcuts

Mouse:	Click the Queries file type in the Navigator or Catalog window.


See Also

View Menu (Navigator)

View Menu (Catalog Window)

Catalog Window Components

Navigator Components

File Types and SpeedMenus

Running the Primary dBASE File Types

Designing the Primary dBASE File Types


View | Forms

See Also

Changes the category of file types to Forms and displays all form files in the list box of file icons.

Once you choose a category of file types, the last file you used is selected. To display the file SpeedMenu, right-click a file or select the file and press Spacebar. Right-click outside the file list to display the Navigator Properties dialog box or Catalog Properties dialog box.

The status bar displays the file name of the selected file. To see more information about the selected file, such as its full path name and date changed, choose Properties|Selected File Item.

The following file extensions are displayed in the Forms category:

Forms	*.WFM	dBASE for Windows form

*.WFO	Compiled form; appears when no .WFM of the same name exists (Navigator only)

*.FMT	dBASE III PLUS and dBASE IV screen format

*.FMO	Compiled screen format; appears when no .FMT of the same name exists (Navigator only)

When you design a form, it appears in the Form Designer. See Designing Forms for information.

When you run a form, it appears in a form window. See Using Forms for information.

Shortcuts

Mouse:	Click the Forms file type in the Navigator or Catalog window.


See Also

View Menu (Navigator)

View Menu (Catalog Window)

Catalog Window Components

Navigator Components

File Types and SpeedMenus

Running the Primary dBASE File Types

Designing the Primary dBASE File Types


View | Reports

See Also

Changes the category of file types to Reports and displays all report files in the list box of file icons.

Once you choose a category of file types, the last file you used is selected. To display the file SpeedMenu, right-click a file or select the file and press Spacebar. Right-click outside the file list to display the Navigator Properties dialog box or Catalog Properties dialog box.

The status bar displays the file name of the selected file. To see more information about the selected file, such as its full path name and date changed, choose Properties|Selected File Item.

The following file extensions are displayed in the Reports category:

Reports	*.RPT	Report Designer report

*.RPC	Report Designer cross-tab report

*.FRM	dBASE III PLUS or dBASE IV report form

*.FRG	dBASE IV generated report form

*.FRO	Compiled report form; appears when no .FRG of the same name exists (Navigator only)

When you design a report, it appears in the Report Designer. See Designing Reports and Labels for information.

When you run a report, it appears in the Report and Label Viewer. See Using Reports and Labels for information.

Shortcuts

Mouse:	Click the Reports file type in the Navigator or Catalog window.


See Also

View Menu (Navigator)

View Menu (Catalog Window)

Catalog Window Components

Navigator Components

File Types and SpeedMenus

Running the Primary dBASE File Types

Designing the Primary dBASE File Types


View | Labels

See Also

Changes the category of file types to Labels and displays all label files in the list box of file icons.

Once you choose a category of file types, the last file you used is selected. To display the file SpeedMenu, right-click a file or select the file and press Spacebar. Right-click outside the file list to display the Navigator Properties dialog box or Catalog Properties dialog box.

The status bar displays the file name of the selected file. To see more information about the selected file, such as its full path name and date changed, choose Properties|Selected File Item.

The following file extensions are displayed in the Labels category:

Labels	*.RPL	Report Designer label

*.LBL	dBASE III PLUS or dBASE IV label form

*.LBG	dBASE IV generated label form

*.LBO	Compiled label form; appears when no .LBG of the same name exists (Navigator only)

When you design a label, it appears in the Report Designer. See Designing Reports and Labels for information.

When you run a label, it appears in the Report and Label Viewer. See Using Reports and Labels for information.

Shortcuts

Mouse:	Click the Labels file type in the Navigator or Catalog window.


See Also

View Menu (Navigator)

View Menu (Catalog Window)

Catalog Window Components

Navigator Components

File Types and SpeedMenus

Running the Primary dBASE File Types

Designing the Primary dBASE File Types


View | Programs

See Also

Changes the category of file types to Programs and displays all program files in the list box of file icons.

Once you choose a category of file types, the last file you used is selected. To display the file SpeedMenu, right-click a file or select the file and press Spacebar. Right-click outside the file list to display the Navigator Properties dialog box or Catalog Properties dialog box.

The status bar displays the file name of the selected file. To see more information about the selected file, such as its full path name and date changed, choose Properties|Selected File Item.

This is the file extension displayed in the Programs category:

Programs	*.PRG	dBASE for Windows, dBASE IV, or dBASE III PLUS program

*.PRO	dBASE for Windows compiled program; appears when no .PRG of the same name exists (Navigator only)

When you design a program, it appears in the Text Editor. See Editing Text for information.

When you run a program, it appears either in a user-defined window, a predefined window, or in the results pane of the Command window. See Running Programs for information.

Shortcuts

Mouse:	Click the Programs file type in the Navigator or Catalog window.


See Also

View Menu (Navigator)

View Menu (Catalog Window)

Catalog Window Components

Navigator Components

File Types and SpeedMenus

Running the Primary dBASE File Types

Designing the Primary dBASE File Types


View | Images

See Also

Changes the category of file types to Images and displays all image files in the list box of file icons. This option is available only in the Navigator.

Once you choose a category of file types, the last file you used is selected. To display the file SpeedMenu, right-click a file or select the file and press Spacebar. Right-click outside the file list to display the Navigator Properties dialog box or Catalog Properties dialog box.

The status bar displays the file name of the selected file. To see more information about the selected file, such as its full path name and date changed, choose Properties|Selected File Item.

The following file extensions are displayed in the Images category:

Images	*.BMP	Bitmap graphic

*.PCX	PC Paintbrush graphic

When you design an image, it appears in an external graphics application. See Editing Images for information.

When you run an image, it appears in the Image Viewer. See Displaying Images for information.

Shortcuts

Mouse:	Click the Images file type in the Navigator.


See Also

View Menu (Navigator)

Navigator Components

File Types and SpeedMenus

Running the Primary dBASE File Types

Designing the Primary dBASE File Types


View | Sounds

See Also

Changes the category of file types to Sounds and displays all sound files in the list box of file icons. This option is available only in the Navigator.

Once you choose a category of file types, the last file you used is selected. To display the file SpeedMenu, right-click a file or select the file and press Spacebar. Right-click outside the file list to display the Navigator Properties dialog box or Catalog Properties dialog box.

The status bar displays the file name of the selected file. To see more information about the selected file, such as its full path name and date changed, choose Properties|Selected File Item.

This is the file extension displayed in the Sounds category:

Sounds	*.WAV	Sound wave

When you design a sound, it appears in an external sound application. See Editing Sounds for information.

When you run a sound, it plays from the Sound Player. See Playing Sounds for information.

Shortcuts

Mouse:	Click the Sounds file type in the Navigator.


See Also

View Menu (Navigator)

Navigator Components

File Types and SpeedMenus

Running the Primary dBASE File Types

Designing the Primary dBASE File Types


View | Catalogs

See Also

Changes the category of file types to Catalogs and displays all catalog files in the list box of file icons. This option is available only in the Navigator.

Once you choose a category of file types, the last file you used is selected. To display the file SpeedMenu, right-click a file or select the file and press Spacebar. Right-click outside the file list to display the Navigator Properties dialog box or Catalog Properties dialog box.

The status bar displays the file name of the selected file. To see more information about the selected file, such as its full path name and date changed, choose Properties|Selected File Item.

This is the file extension displayed in the Catalogs category:

Catalogs	*.CAT	dBASE for Windows and dBASE IV catalog

When you use a catalog, it appears in the Catalog window. See Using the Catalog window for information.

Shortcuts

Mouse:	Click the Catalogs file type in the Navigator.


See Also

View Menu (Navigator)

Navigator Components

File Types and SpeedMenus

Running the Primary dBASE File Types

Designing the Primary dBASE File Types


View | Custom

See Also

Changes the category of file types to Custom and displays all file names that match the file-name skeleton you specify. This option is available only in the Navigator.

When you choose the Custom category, enter the file-name skeleton in the Custom Files text box. For example, to view text files, enter *.TXT, then press Enter. To enter multiple file-name skeletons, separate them with commas, spaces, or semicolons. For example,

*.TXT, *.WB1
*.TXT *.WB1
*.TXT; *.WB1

As with the other file types, file names appear in the list box of file icons based on the directories specified in Current Directory and Search Path.

Once you choose a category of file types, the last file you used is selected. To display the file SpeedMenu, right-click a file or select the file and press Spacebar. Right-click outside the file list to display the Navigator Properties dialog box or Catalog Properties dialog box.

The status bar displays the file name of the selected file. To see more information about the selected file, such as its full path name and date changed, choose Properties|Selected File Item.

Shortcuts

Mouse:	Click the Custom file type in the Navigator.


See Also

View Menu (Navigator)

Navigator Components

File Types and SpeedMenus

Running the Primary dBASE File Types

Designing the Primary dBASE File Types


View | Large Icons

See Also

Displays file names under large icons in the Navigator or Catalog window.

Use the View menu to select how files appear in the files list box. Files appear in one of three ways:

Large Icons	The file name appears under a large icon representing the file type.

Small Icons	The file name appears to the right of a small icon representing the file type.

Details	The file name, size, date, and time appear to the right of a small icon representing the file type.

You can specify the distance between the icons in the Navigator Properties dialog box or Catalog Properties dialog box.


See Also

View Menu (Navigator)

View Menu (Catalog Window)

Properties|Catalog Window

Properties|Navigator Window


View | Small Icons

See Also

Displays file names next to small icons in the Navigator or Catalog window.

Use the View menu to select how files appear in the files list box. Files appear in one of three ways:

Large Icons	The file name appears under a large icon representing the file type.

Small Icons	The file name appears to the right of a small icon representing the file type.

Details	The file name, size, date, and time appear to the right of a small icon representing the file type.

You can specify the distance between the icons in the Navigator Properties dialog box or Catalog Properties dialog box.

By default, when you load dBASE for Windows, small file icons appear in rows of three icons.


See Also

View Menu (Navigator)

View Menu (Catalog Window)


View | Details

See Also

Displays file names with their size, date, and time in the Navigator or Catalog window.

Use the View menu to select how files appear in the files list box. Files appear in one of three ways:

Large Icons	The file name appears under a large icon representing the file type.

Small Icons	The file name appears to the right of a small icon representing the file type.

Details	The file name, size, date, and time appear to the right of a small icon representing the file type.

This view is not available from the Catalog window if you are also using the Associations view.

You can specify the distance between file names in the Navigator Properties dialog box or Catalog Properties dialog box.


See Also

View Menu (Navigator)

View Menu (Catalog Window)

View|Associations


View | Sort

See Also

Displays a cascading menu. From the menu, choose how you want to sort the list of files in the Navigator or Catalog window.

Choose from the following commands:

By Name

By Type and Extension

By Size

By Date and Time


See Also

View Menu (Navigator)

View Menu (Catalog Window)


View | Sort | By Name

See Also

Sorts file names in the Navigator or Catalog window file list in alphabetical order.

By default, files are sorted by name.

This view is not available from the Catalog window if you are also using the Associations view.


See Also

View Menu (Navigator)

View Menu (Catalog Window)


View | Sort | By Type and Extension

See Also

Sorts files in the Navigator or Catalog window file list by file type, then by file extension.

If you select All files, this command sorts files in the following order:

By the primary file types (tables, queries, forms, and so on, in the order in which they appear in the Navigator or Catalog window)

By file extension

In alphabetical order by file name

If you select a category other than All, this command sorts files by file extension, then in alphabetical order by file name.

This view is not available from the Catalog window if you are also using the Associations view.


See Also

View Menu (Navigator)

View Menu (Catalog Window)

View|All


View | Sort | By Size

See Also

Sorts files in the Navigator or Catalog window file list by file size in bytes, from smallest to largest.

This view is not available from the Catalog window if you are also using the Associations view.


See Also

View Menu (Navigator)

View Menu (Catalog Window)


View | Sort | By Date and Time

See Also

Sorts files in the Navigator or Catalog window file list by file date and time, from oldest to newest.

This view is not available from the Catalog window if you are also using the Associations view.


See Also

View Menu (Navigator)

View Menu (Catalog Window)


Working with Forms

About Forms

Designing Forms

Using Forms


 About Forms

See Also

Forms display messages and data, respond to user input, and provide interaction controls such as menus, pushbuttons, and scroll bars. You can build simple data entry or data retrieval screens based on one or more tables, or you can use forms to build a complete user interface for a complex application.

When you create a form with the Form Designer, you start with an empty form window. You then select and place objects, such as entry fields, list boxes, and check boxes on the form. dBASE for Windows provides many of the standard Windows controls. Both the form and the controls it contains are objects.

Once you have created the basic user interface, you set the properties of the objects to customize their characteristics and behavior. To do so interactively, use the Object Inspector. The Object Inspector lists all the properties of an object and its current values.

Essentially, properties are memory variables that contain data about an object. There are three types of properties:

Properties define an object's characteristics, such as its size, location and color.

Events (event properties) determine an object's behavior, that is, how it responds to events, such as mouse clicks and keystrokes. You can specify what happens when an event occurs by linking a codeblock, or a procedure to the event property. This code is called an event handler.

Methods are procedures that are associated with an object. They determine what actions can be performed on objects; for example, releasing objects from memory, giving focus to objects, or moving objects.

With the dBASE language, you can create your own objects and add new properties to objects. For an extensive discussion about working with objects, see the Programmer's Guide.


See Also

About Form (.WFM) Files

Overview of Designing and Using Forms

Views and Tools

Designing Forms

Using Forms


 About Form (.WFM) Files

See Also	Language

When you save a form, the Form Designer generates the dBASE code that defines the form and its objects. The code defines the objects' properties and any event-handling code you attached to the form and its objects.

Working with Form Files

A form is saved as a text file with a default .WFM (Windows ForM) extension. You can do the following with a .WFM file:

Run it with the DO command

Debug it

Edit it with the Text Editor

The Form Designer is a Two-Way tool--you can modify a form either visually with the Form Designer, or by editing the generated code in the .WFM file with a text editor. You can use both techniques interchangeably; all changes are reflected in the Form Designer and the generated code.

How Code is Organized in a .WFM file

There are three main parts to a form file that is generated from the Form Designer:

The code that precedes the form's CLASS...ENDCLASS declaration (see the second item, below). This code executes before the form is constructed. Typically, this section contains comments and variable declarations.

The CLASS...ENDCLASS definition for the form. This includes the property and method declarations for the form.

Any code following the form's CLASS...ENDCLASS declaration. This section typically contains procedures that are referenced by event handlers.

The dBASE Procedure Editor provides options to help you organize the code in this way.

See the Programmer's Guide for a detailed discussion about form files.


See Also

About Forms

Procedure Editor Options and Components

Using the Procedure Editor - Overview


Language

CLASS


 Overview of Designing and Using Forms

See Also

dBASE for Windows provides two views for working with forms: a design view and run view.

About the Design View: the Form Designer

The design view for forms is the Form Designer. Use the Form Designer to design the appearance and behavior of the form.

There are two views of the Design View. Use the Layout view to

Lay out the form's controls on a design surface

Specify the form's properties, for example its visual attributes

Specify how the form and the controls respond to events, for example when a user clicks a button

Use the Order view of the Form Designer to specify the visual layers and the tabbing order of the form's controls.

About the Run View: the Form Itself

The run view for forms is the form itself, or, more specifically, the form at run time. When a user runs the form, the controls become active. If the form is associated with data, for example, the records in a table, that data can be viewed and/or edited. You can design a form with its own menus, or you can use the default dBASE menus for basic operations such as working with table records.

Switching Between Design and Run Views

When you run a form, it appears in the same window in which it was designed. To switch between run mode and design mode, use the SpeedBar buttons or menu commands, as shown in the following table:

Button	Menu Item	Action
	View|Form	Runs the form (when in the Form Designer)
	View|Form Design	Switches to the Form Designer (when running the form)


See Also

About Forms

View|Form

View|Form Design


 Designing Forms

See Also

Create forms as the primary user interfaces for your applications. Use the Form Designer to create forms visually and without extensive programming.

Form Designer Concepts and Tasks

Choose from the following topics for information about using the Form Designer:

Using  the Form Designer - Overview

Getting Context-Sensitive Online Help in the Form Designer

About Z-Order and Tabbing Order on a Form

Form Designer Tasks

Form Designer Tools

The Form Designer has menus, a SpeedBar, a design surface, and other tools for laying out a form and specifying its appearance and behavior. Choose from the following topics for more information:

Design Surface	Surface for laying out the form and its controls.

Object Inspector	Window for assigning values to properties and linking event-handling code to events.

Control Palette	Palette for selecting controls to add to the form.

Procedure Editor	Window and tools for writing and editing procedures and methods.

Menu Designer	Design surface and menus for creating menus for a form.

Order View	Design surface and tools for changing the order of controls on the form.

Menus	Lists and descriptions of Form Designer menus.

SpeedBar	Descriptions of the Form Designer SpeedBar options.

SpeedMenu	List and description of the Form Designer SpeedMenu.


See Also

Views and Tools

Using Forms


 Using the Form Designer - Overview

See Also

Use the Form Designer to do the following tasks.

Click any of the illustrations, below, to display a more detailed discussion of the illustrated tool.

Create Controls

Create control by selecting a control from the Control Palette and placing it on the design surface.

Design surface	Control Palette
Specify the Properties of the Form and Its Controls

Assign or change properties by setting their values in the Properties page of the Object Inspector.

Object Inspector - Properties Page

Link Event-Handling Code to Events

Link event-handling code to events so that when the event occurs, the code executes. There are two ways and two places to do this. Write codeblocks and attach them to events in the Events page of the Object Inspector. Or, use the Procedure Editor to create methods that specify what will happen when an event occurs.

Object Inspector -   Events page	Procedure Editor
An object's methods are listed (read-only) in the methods page of the Object Inspector. You can use those methods in the procedures you write as event-handlers.

Object Inspector - Methods Page

Create Menus

Use the Menu Designer, along with the Object Inspector and the Procedure Editor to design a menu and save it as an .MNU file.

Menu Designer	Object Inspector	Procedure Editor


See Also

Designing Forms

Form Designer Design Surface

Control Palette

Object Inspector Events Page

Object Inspector Methods Page

Object Inspector Properties Page

Procedure Editor Options and Components

Menu Designer


 Getting Context-Sensitive Online Help in the Form Designer

See Also

When you press F1 to get context-sensitive online Help in the Form Designer, different information is displayed, depending on which tool you are using.

Standard Behavior

Context-sensitive Help works the same way in the Form Designer as in the rest of dBASE for Windows for these items:

Menus and menu items

Dialog boxes and dialog box options

When you give focus to a menu, menu command, or dialog box option and press F1, a Help topic for the item with focus appears. This Help usually describes the purpose and use of the item, and lists what values you can enter or actions you can take.

Language Reference Help for Objects, Methods, and Properties

When you create and save a form in the Form Designer, it generates code with class definitions, event properties, and methods. When you use the tools that specify that information, you can obtain Language Reference Help on the class, event, or method.

The following table shows what kind of Help is displayed when you press F1 in different contexts.

Pressing F1 when this has focus...	Displays this Reference Help...	Examples
An object on the design surface	The class from which the object is derived	SpinBox
A property, event, or method in the Object Inspector	The property, event, or method	ColorNormal  OnClick  ReadModal


See Also

Designing Forms

How to Use Help in dBASE for Windows


About Z-Order and Tabbing Order in a Form
 About Z-Order and Tabbing Order on a Form

See Also

Objects Exist in Layers on a Form

When a form contains two or more controls, the plane in which a control exists always lies in front of or behind the plane in which another control exists. In other words, objects on a form exist in layers.

   Back   [image]  Front

This affects two aspects of the form:

Visual layers. This is known as the z-order, to indicate that this is the z-axis (depth) of the layout. This determines what appears in front of (or on top of) what. But note, even when controls are laid out side-by-side, each control is in a unique plane of the form, that is, each control occupies a unique position in the z-order.

Tabbing order. This determines the order in which controls receive focus when a user presses the Tab key.

Each control is numbered to indicate its position in the z-order. The item in the back (or on the bottom, if you prefer), is number 1. The next item in front of the first is number 2, and so on.

When the Z-Order Has More Items than the Tabbing Order

Usually, the same number of items exists in the z-order as in the tabbing order. However, if one or more controls cannot receive focus (for example, a rectangle), more items will exist in the z-order than in the tabbing order.

For example, consider the following set of radio buttons:

There are only two items in the tabbing order: the XXX button and the YYY button. If you repeatedly press Tab, the focus alternates between XXX and YYY. However, there are three items in the z-order: the two radio buttons and the rectangle behind them:

Changing One Order Changes Them Both

When you change the z-order, you also change the tabbing order (and vice versa). Therefore, if you move one item forward or backward in the tabbing order, you also change its visual position. In practice, this is not important, because controls do not usually lie right on top of other controls. Therefore, you can change the tabbing order without affecting the visual appearance of the form. Also, those controls that are appropriate for placing directly behind another control usually cannot receive focus, and therefore are not part of the tabbing order.

Where to Change the Order

You can change the order of objects in the Layout view or the Order view of the Form Designer.

In the Layout view, use these SpeedBar buttons or menu items:

Layout|Send to Back

Layout|Bring to Front

Layout|Send Farther

Layout|Bring Closer

Layout|Align Left

Layout|Align Right

Layout|Align Top

Layout|Align Bottom

In the Order view, use the Order spin box and the numbered items on the design surface, as explained in Form Designer Order View.


See Also

Form Designer Order View

Changing the Order of Controls in the Form Order View


 Form Designer Tasks

Choose from the following tasks for information about using the Form Designer:

Using the Categorical and Alphabetical Lists in the Object Inspector

Opening and Displaying the Object Inspector

Opening and Displaying the Control Palette

Using the Procedure Editor - Overview

Opening the Procedure Editor

Linking Event-Handling Code to Events

Writing a Codeblock and Linking It to an Event

Writing a Procedure and Linking It to an Event

Creating Form Methods Using External Procedures

Changing the Order of Controls in the Form Designer Order View


Using the Categorical and Alphabetical Lists in the Properties Inspector
 Using the Categorical and Alphabetical Lists in the Object Inspector

See Also

The Properties page in the Object Inspector can list an object's properties categorically or alphabetically.

When properties are displayed categorically, the Properties page lists several category names. A category name always has a plus (+) or minus (-) sign preceding it to indicate that there is a list of properties available beneath it. A plus (+) indicates that the list is closed, while a minus (-) indicates that the list is expanded.

Opening and Closing Categorical Lists

To toggle between open and closed, double-click the category name or press the plus key or minus key on the numeric keypad. Press Ctrl++ (that is, the Control key along with the plus key on the numerical keypad) or Ctrl+* to open all the categorical lists, or press Ctrl+- to close them all.

Not all properties belong to a category, so they appear in the Inspector without a plus or minus next to them.

Setting the Lists to Categorical or Alphabetical

To set whether the properties are displayed categorically or alphabetically,

1.	Choose Properties|Desktop. The Desktop Properties dialog box is appears.

2.	Choose the Applications tab at the bottom of the dialog box.

3.	Click the Object Properties Outline check box to display the properties categorically. Uncheck the check box to display the properties alphabetically.

The change takes effect when you choose OK.


See Also

Opening and Displaying the Object Inspector

Object Inspector

Object Inspector Properties Page

Basics: About Properties Inspectors

Properties|Desktop


 Opening and Displaying the Object Inspector

See Also

To open the Object Inspector, do one of the following:

Choose View|Object Properties.

Right-click the Form Designer design surface or the Menu Designer window, then choose Object Properties from the SpeedMenu.

If the Object Inspector is already open, choosing this command closes it.

The Object Inspector is visible only when the main Form Designer design surface or the Menu Designer window has focus. If you click outside one of them, the Object Inspector is hidden. To redisplay it, click one of the design surfaces to return focus to it. Or choose Windows|Properties.

Displaying Property Lists Categorically or Alphabetically

To set whether the properties on the Properties page of the Object Inspector are displayed categorically or alphabetically,

1.	Choose Properties|Desktop. The Desktop Properties dialog box is appears.

2.	Choose the Applications tab at the bottom of the dialog box.

3.	Click the Object Properties Outline check box to display the properties categorically. Uncheck the check box to display the properties alphabetically.

The change takes effect when you choose OK.


See Also

Designing Forms

Object Inspector


Opening the Control Palette
 Opening and Displaying the Control Palette

See Also

To open the Control Palette, do one of the following:

Choose View|Controls.

Right-click the Form Designer design surface and choose Controls from the SpeedMenu.

If the Control Palette is already open, choosing this command closes it.

The Control Palette is visible only when the Form Designer design surface has focus. If you click outside the design surface, the Control Palette is hidden. To redisplay it, click the design surface to return focus to it. Or choose Windows|Controls.


See Also

Designing Forms

Control Palette


 Using the Procedure Editor - Overview

See Also

Use the Procedure Editor and its related tools (including the Link Event to Procedure and the Edit Event dialog boxes) to help you write and structure the code that defines the form and its behavior. In particular, use them to:

Write methods for the form

Write comments at the beginning of the program

Write code to be executed before the form is constructed, typically to declare static variables and public variables

Create event handlers by linking procedures and methods to events

Write general procedures that can be referenced from other sections in the code


See Also

About Form (.WFM) Files

About Forms

Opening the Procedure Editor

Procedure Editor Options and Components

Procedure|Link Event

Procedure|Edit Event


 Opening the Procedure Editor

See Also

To open the Procedure Editor without creating a new method, do one of the following:

Choose View|Procedures.

Right-click the form or any of its controls to display the SpeedMenu, then choose Procedures from the SpeedMenu. (If the Procedure Editor is already open, clicking this command closes it.)

The Procedure Editor opens. If the form already has methods, the first method in the combo box appears in the Text Editor window. If the form does not have methods, the Procedure Editor displays comments and/or code in the header section of the form code.

To open the Procedure Editor and create a new method, do one of the following:

In the Object Inspector, click the Events page, choose an event, then click the Tool button to the right of the text box:

This process creates a new method and links it to the selected event. The Procedure Editor opens (or it becomes active if it is already open).

The Text Editor window contains a PROCEDURE statement, with a suggested name for the new method. You can write a new procedure to link to the current event in the Object Inspector.

Choose Procedure | New Method.

This creates a new method that is not linked to an event. The Procedure Editor opens (or it becomes active if it is already open).

The Text Editor window contains a PROCEDURE statement, with a suggested name for the new method. You can write a new procedure, then link it to an event through the Link Event dialog box.

All methods that you create are listed in the combo box in the Procedure Editor, whether you link them to events or not.


See Also

Using the Procedure Editor - Overview

Procedure Editor Options and Components

Procedure|Edit Event


 Linking Event-Handling Code to Events

See Also

Every built-in object has events to which it can respond. For example, a button can respond to an OnClick event. You can link code with an event so that when the event occurs, the code executes. For example, you can add code so that when a user clicks the Next button, the record pointer moves to the next record. This code is called event-handling code, or an event handler.

In the Form Designer, there are two ways to write and link event handlers to events. You can write a small segment of code, called a codeblock, and link it with one event for one object. Or you can write a procedure and link it with an event. You can link a procedure with more than one event and with more than one object. See the following topics for more information:

Writing a Codeblock and Linking It to an Event

Writing a Procedure and Linking It to an Event


See Also

About Forms

Using the Procedure Editor - Overview

Procedure Editor Options and Components


 Writing a Codeblock and Linking It to an Event

See Also

A codeblock is an unnamed, logical grouping of one or more dBASE statements, or a dBASE expression.

This topic explains how to use the Form Designer tools to write a codeblock. It does not explain in detail how to use the dBASE language. For information about programming, see the Language Reference and the Programmers Guide.

To write a codeblock and link it to an event,

1.	On the design surface, click the object to whose event you want to attach the codeblock.

2.	Select the Object Inspector.

3.	Click the Events page, if it is not already selected.

4.	Click the event to which you want to link the codeblock. The cursor appears in the text box to the right of the event name. If you had previously linked this event to a procedure, you need to unlink it first.

5.	Type the codeblock in the text box.

Statement Codeblock Syntax

The syntax for a statement codeblock is:

{[|<parameters>|];<statement>[;<statement>...]}

Comments:

Opening and closing curly braces ({ }) are required.

If you pass parameters, delimit them with vertical bars (| |).

Place a semicolon (;) in front of each statement.

For example, to execute the QUIT command when a user clicks a pushbutton, type this codeblock in the text box next to the pushbutton's OnClick event:

{;QUIT}

Expression Codeblock Syntax

The syntax for an expression codeblock is:

{[|<parameters>|]<expression>}

Comments:

Opening and closing curly braces ({ }) are required.

If you pass parameters, delimit them with vertical bars (| |).

For example, to specify the following VALID condition for an entry field, type this codeblock in the text box next to the entry field's Valid event:

{Salary<= 10000}


See Also

About Forms

Using the Procedure Editor - Overview

Procedure Editor Options and Components


 Writing a Procedure and Linking It to an Event

See Also

This explains how to use the Form Designer tools to write a procedure and link it to an event. It does not explain how to use the dBASE language. For information about programming, see the Language Reference and the Programmer's Guide.

To specify an event and write a new procedure for it,

1.	Specify an event of an object, as follows:

Choose the object by clicking it on the design surface or by choosing it from the list box in the Object Inspector.

Click the Events page, if it is not already current.

Click the event.

2.	Click the Tool button to the right of the entry field, for example:

The Procedure Editor opens (if it was closed), or focus switches to it (if it is already open).

A unique procedure name is created from the name of the control and the event.

3.	Write the body of the procedure, following the PROCEDURE statement. For more information about how to write a procedure, see PROCEDURE. For more information about programming, see the Programmer's Guide.

This procedure is now linked to the event you chose in step 1, so that when the event occurs, this procedure will execute. The event and the procedure together are now one of the form's methods, and therefore appears in the Methods page of the Object Inspector.


See Also

About Forms

Using the Procedure Editor - Overview

Opening the Procedure Editor

Procedure Editor Options and Components


 Creating Form Methods Using External Procedures

See Also

You can create methods for a form using procedures written outside the form, for example from a procedure library.

To create a method using an external procedure,

1.	Open the Procedure Editor.

2.	Choose General from the list in the upper left corner.

3.	Type a SET PROCEDURE TO, followed by the name of the file or files containing the procedure(s).

4.	Wherever you want to call one of these procedures, type DO, followed by the name of the procedure. For example, you could create a method, as follows:

Procedure BUTTON1_OnClick

DO MyProc


See Also

About Forms

Using the Procedure Editor - Overview

Opening the Procedure Editor

Procedure Editor Options and Components


 Changing the Order of Controls in the Form Designer Order View

See Also

When you switch to the Order view, all the controls on the form are displayed with a number in the lower right corner. That number is the number of the control in the z-order.

To change the z-order of a control,

1.	Set a number for the z-order of a control. Do this by clicking the Up or Down arrows in the Order spin box to increment or decrement the counter to the number you want:

(Click the button on the right of the spin box to return the counter to 1.)

2.	Click the control (on the work surface) whose position in the z-order you want to change. The following occurs:

The control's position in the z-order is changed, as indicated by the new number in the lower right.

The counter in the Order spin box is incremented to the next higher number. When it reaches the number of the last control, the counter is reset to 1.

The numbers of the other controls are incremented or decremented, as necessary, to accommodate the new position of the control you clicked.

To re-set the z-order of all controls on the form:

1.	Click the button on the right of the Order spin box to set the counter to 1:

2.	Click the control you want to be the first in the z-order. It is set to 1, and the spin box is incremented to 2.

3.	Click the control you want to be second in the z-order. It is set to 2, and the spin box is incremented to 3.

4.	Continue clicking all the controls in the order you want them placed in the z-order.


See Also

About Z-Order and Tabbing Order on a Form

Form Designer Design Surface

Form Designer Order View


 Form Designer Design Surface

See Also

Using the Design Surface

The design surface is the background of the form. Use it to

Set the size of the form window.

Place controls on the design surface in the positions you want them to appear on the form.

Set the sizes of the controls.

Specify the visual layers of the controls, along with the tabbing order of those controls that can receive focus.

Setting Properties and Specifying Event Handlers for the Form

For the purposes of setting properties, the design surface is the form itself. To specify a value for a form property, click the design surface and then go to the Object Inspector to set the value. To link a procedure with a form event (for example, OnClose), click the design surface, and then go to the Procedure Editor to write or select the procedure.

The Parts of the Design Surface

The design surface is composed of:

A window. When you change the size and position of this window, you are changing the size and position of the form you are designing. To be exact, you are changing the values of these form properties: Height, Left, Top, Width.

A grid. Use this grid to help align the controls. The size of the grid is based on the size of the current form font. When visible, the grid is a matrix of dots.

Vertical and horizontal rulers. Units on the ruler are based on the size of the current form font. The vertical unit is equivalent to the height of the font. The horizontal unit is equivalent to the average width of the characters in the font.

About the Order View

When you switch to Order view, you can specify the order of the controls. When you specify order, you are affecting two aspects of the relation of the controls to one another and to the form:

The visual layering of the form. In other words, what appears on top of what. This is sometimes called the z-order, to refer to the z-axis of the form.

A typical need for this is when you use a Rectangle object, for example, to group a series of radio buttons. The radio buttons must appear on top of the rectangle, so you must place the rectangle behind them in the order.

The tabbing order of the form. This refers to the order in which the controls receive focus when a user presses the tab key to move from control to control.


See Also

Opening and Displaying the Object Inspector

Object Inspector

Form Designer Order View


 Form Designer Order View

See Also

Use the Form Designer Order View to set the z-order (and thereby the tabbing order) of the controls on the form design surface.

How Order View is Different from Layout View

When you switch from Layout view to Order view in the Form Designer, the following occurs:

The menus and SpeedBar change.

The Order spin box appears on the SpeedBar.

The design surface shows the order of the controls on the form.

Order View Design Surface

In Order view, the outlines of all the controls on the form appear with a number. The number indicates their position in the tabbing and z-order. Item number 1 is the furthest back (or the closest to the bottom, if you prefer), and the item with the highest number is in the front (or on top) of the form. For example:

	1	2	3	4	5
Order Spin Box

There are three parts to the Order spin box on the SpeedBar:

The number in the box is a counter. It shows the order number that will be assigned to the next control you click on the design surface. To change the order of a control, change this number, then click the control that will become this number in the order.

Click the up and down arrows to increment and decrement the counter.

Click the button on the right to return the counter to 1.


See Also

About Z-Order and Tabbing Order on a Form

Changing the Order of Controls in the Form Designer Order View

Form Designer Design Surface


Control Palette (Form Designer)
 Control Palette

See Also

The Control Palette displays a list of the controls you can add to a form.

To add a control to the form, click the control on the palette to select it. When you pass the pointer over the design surface, the pointer turns into crosshairs. Click and drag the pointer across the design surface until the control is the desired size. Or, you can click the design surface (without dragging) to add a control in a default size.

The Control Palette has two pages: Standard and Custom. The standard controls are part of dBASE for Windows. Custom controls can be custom dBASE controls (which have a .CC file-name extension) or custom .VBX controls.

Standard

Pointer

TextObject

EntryField

ComboBox

SpinBox

ListBox

PushButton

CheckBox

RadioButton

Line

Rectangle

Browse

Editor

Image

Vertical scroll bar

Horizontal scroll bar

OLE

Custom

This page shows the pointer and any .VBX or dBASE custom controls that are installed.


See Also

Opening the Control Palette

File|Set Up Custom Controls


Pointer (Form Designer Control Palette)
 Pointer

See Also

The pointer is a tool for selecting objects on the design surface. Unlike the other items on the palette, the pointer is not a control.

You must select an object to move it, resize it, delete it, or edit its properties. You can also select multiple objects at a time and work with them collectively. To resize a group of objects, however, you can only use the keyboard (Shift+Arrow key).

When an object is selected on the design surface, handles appear on its edges. Drag these handles to change the size of the object.

Selecting Objects with the Pointer

To select a single object, click it. To select more than one object, click (but don't release) on the edge of the area you want to select, and drag the pointer until all the objects are selected. You can also hold down the Shift key and click individual controls to add them to the selection, or to remove them if they are already selected.

To de-select an object or objects on the form, click anywhere outside the selected area. Doing so selects the form object.


See Also

Control Palette (Form Designer)


Text (Form Designer Control Palette)
 Text

See Also	Language

The text object displays text that cannot be edited by users. The text can be any alphanumeric characters allowed in a character expression.


See Also

Control Palette (Form Designer)


Language

CLASS TEXT


EntryField (Form Designer Control Palette)
 EntryField

See Also	Language

An entry field accepts a value typed in by a user.


See Also

Control Palette (Form Designer)


Language

CLASS ENTRYFIELD


ComboBox (Form Designer Control Palette)
 ComboBox

See Also	Language

A combo box combines an entry field and a drop-down list box. A combo box accepts a value typed into the entry field or selected from the drop-down list box.


See Also

Control Palette (Form Designer)


Language

CLASS COMBOBOX


SpinBox (Form Designer Control Palette)
 SpinBox

See Also	Language

A spin box accepts a numeric value. A user can type a number into the entry field or can increment or decrement the number by clicking the up and down arrows.


See Also

Control Palette (Form Designer)


Language

CLASS SPINBOX


ListBox (Form Designer Control Palette)
 ListBox

See Also	Language

A list box displays values in a list. A user can select a value from the list. The values in a list can be file names, records, array elements, table names, or field names.


See Also

Control Palette (Form Designer)


Language

CLASS LISTBOX


PushButton (Form Designer Control Palette)
 PushButton

See Also	Language

A pushbutton (sometimes called a command button) is a control that a user can "push" by clicking it or by giving it focus and pressing Enter. You can attach code to a pushbutton so that when a user chooses it, the code executes.


See Also

Control Palette (Form Designer)


Language

CLASS PUSHBUTTON


CheckBox (Form Designer Control Palette)
 CheckBox

See Also	Language

A check box consists of a box and an optional read-only text label. A user can check and uncheck the box to toggle between .T. or .F. (yes or no). Check boxes often are arranged in groups to present choices or options a user can turn on or off. All, some, or none of the check boxes in a group can be checked at a time.


See Also

Control Palette (Form Designer)


Language

CLASS CHECKBOX


RadioButton (Form Designer Control Palette)
 RadioButton

See Also	Language

A radio button represents a single choice in a set of mutually exclusive choices. Radio buttons are used in groups where the user can select only one radio button.


See Also

Control Palette (Form Designer)


Language

CLASS RADIOBUTTON


Line (Form Designer Control Palette)
 Line

See Also	Language

A line is a graphic element that can be placed on a form to organize elements visually. Users cannot edit or manipulate a line.


See Also

Control Palette (Form Designer)


Language

CLASS LINE


Rectangle (Form Designer Control Palette)
 Rectangle

See Also	Language

A rectangle is a graphic element (with an optional read-only text label) that can be placed on a form to organize elements visually. Users cannot edit or manipulate a rectangle.


See Also

Control Palette (Form Designer)


Language

CLASS RECTANGLE


Browse (Form Designer Control Palette)
 Browse

See Also	Language

A browse control displays records from a table or query in rows and columns for editing.


See Also

Control Palette (Form Designer)


Language

CLASS BROWSE


Editor (Form Designer Control Palette)
 Editor

See Also	Language

An editor control displays the contents of a text file or memo field. A user can edit the contents of an editor unless you disable that functionality.


See Also

Control Palette (Form Designer)


Language

CLASS EDITOR


Image (Form Designer Control Palette)
 Image

See Also	Language

An image control displays an image.


See Also

Control Palette (Form Designer)


Language

CLASS IMAGE


Vertical Scrollbar (Form Designer Control Palette)
 Vertical Scrollbar

See Also	Language

A vertical scroll bar enables a user to select from a sorted set of numeric or date values.


See Also

Control Palette (Form Designer)


Language

CLASS SCROLLBAR


Horizontal Scrollbar (Form Designer Control Palette)
 Horizontal Scrollbar

See Also	Language

A horizontal scroll bar enables a user to select from a sorted set of numeric or date values.


See Also

Control Palette (Form Designer)


Language

CLASS SCROLLBAR


OLE (Form Designer Control Palette)
 OLE

See Also	Language

An OLE object is a control that contains a document from another application, for example a sound file from a sound recorder application.


See Also

Control Palette (Form Designer)

Displaying and Editing OLE Documents


Language

CLASS OLE


 Object Inspector

See Also

The Object Inspector displays all the properties of the form and its controls, as well as all their events and methods.

The Object Inspector is divided into three pages:

Properties

Events

Methods

The name of the current object appears in a combo box at the top of the Object Inspector. To display the properties, events, and methods for a different object, select that object from the list.


See Also

Opening and Displaying the Object Inspector


 Object Inspector Properties Page

See Also

Displays all the properties of the current object. The right column shows the current value for each property.

Displaying Tools to Set the Current Property

Specialized tools are available for some properties. For example, you can display the Choose Color dialog box to help you set the color for an object. When a tool is available for a property, the Tool button [image] appears to the right of the property's value when that property has focus in the inspector. For example:

Click the button to display the tool appropriate for that property.

Displaying Properties Categorically or Alphabetically

You can choose whether to display the properties categorically or alphabetically.

When set to categorical, expand and collapse the lists as follows:

To expand a category, press + on the numeric keypad.

To collapse a category, press - on the numeric keypad.

To expand all categories, press Ctrl++ on the numeric keypad.

To collapse all categories, press Ctrl+- on the numeric keypad.

See Using the Categorical and Alphabetical Lists in the Object Inspector for more information.


See Also

Object Inspector

Object Inspector Events Page

Object Inspector Methods Page

Using the Categorical and Alphabetical Lists in the Object Inspector


 Access Properties

See Also

The Access category in the Object Inspector includes the following properties. All of these properties may not appear for any single object. Click the name of the property to display reference Help for that property.

Before

Default

Enabled

Group

TabStop

Visible

Press + on the numeric keyboard to display the list of Access properties for the current object.

Press - on the numeric keyboard to hide the list.

When the list is appears, you can select a property and press F1 to display reference Help for the selected property.


See Also

Object Inspector

Object Inspector Properties Page

Using the Categorical and Alphabetical Lists in the Object Inspector


 Bitmap Properties

See Also

The Bitmap category in the Object Inspector includes the following properties. Click the name of the property to display reference Help for that property.

DisabledBitmap

DownBitmap

FocusBitmap

UpBitmap

Press + on the numeric keyboard to display the list of Bitmap properties for the current object.

Press - on the numeric keyboard to hide the list.

When the list is appears, you can select a property and press F1 to display reference Help for the selected property.


See Also

Object Inspector

Object Inspector Properties Page

Using the Categorical and Alphabetical Lists in the Object Inspector


 Data Linkage Properties

See Also

The Data Linkage category in the Object Inspector includes the following properties. All of these properties may not appear for any single object. Click the name of the property to display reference Help for that property.

Alias

DataLink

DataSource

Fields

Multiple

Sorted

Working with the Object Inspector Lists

Press + on the numeric keyboard to display the list of Data Linkage properties for the current object.

Press - on the numeric keyboard to hide the list.

When the list appears, you can select a property and press F1 to display reference Help for the selected property.


See Also

Object Inspector

Object Inspector Properties Page

Using the Categorical and Alphabetical Lists in the Object Inspector


 dBASE Variable Properties

See Also

The dBASE Variable category in the Object Inspector shows the object reference variables defined for the form. Usually, this is a list of the names (that is, the Name properties) of the controls on the form.


See Also

Object Inspector

Object Inspector Properties Page

Using the Categorical and Alphabetical Lists in the Object Inspector


 Edit Properties

See Also

The Edit category in the Object Inspector includes the following properties. All of these properties may not appear for any single object. Click the name of the property to display reference Help for that property.

Append

Delete

Follow

Function

LineNo

MaxLength

Mode

Modify

Picture

RangeMax

RangeMin

RangeRequired

SelectAll

Toggle

ValidErrorMsg

ValidRequired

Wrap

Working with the Object Inspector Lists

Press + on the numeric keyboard to display the list of Edit properties for the current object.

Press - on the numeric keyboard to hide the list.

When the list appears, you can select a property and press F1 to display reference Help for the selected property.


See Also

Object Inspector

Object Inspector Properties Page

Using the Categorical and Alphabetical Lists in the Object Inspector


 Font Properties

See Also

The Font category in the Object Inspector includes the following properties. All of these properties may not appear for any single object. Click the name of the property to display reference Help for that property.

FontBold

FontItalic

FontName

FontSize

FontStrikeOut

FontUnderline

Working with the Object Inspector Lists

Press + on the numeric keyboard to display the list of Font properties for the current object.

Press - on the numeric keyboard to hide the list.

When the list appears, you can select a property and press F1 to display reference Help for the selected property.


See Also

Object Inspector

Object Inspector Properties Page

Using the Categorical and Alphabetical Lists in the Object Inspector


 Help Properties

See Also

The Help category in the Object Inspector includes the following properties. All of these properties may not appear for any single object. Click the name of the property to display reference Help for that property.

HelpFile

HelpID

StatusMessage

Working with the Object Inspector Lists

Press + on the numeric keyboard to display the list of Help properties for the current object.

Press - on the numeric keyboard to hide the list.

When the list appears, you can select a property and press F1 to display reference Help for the selected property.


See Also

Object Inspector

Object Inspector Properties Page

Using the Categorical and Alphabetical Lists in the Object Inspector


 Identification Properties

See Also

The Identification category in the Object Inspector includes the following properties. All of these properties may not appear for any single object. Click the name of the property to display reference Help for that property.

ClassName

hWnd

ID

Name

Parent

Working with the Object Inspector Lists

Press + on the numeric keyboard to display the list of Identification properties for the current object.

Press - on the numeric keyboard to hide the list.

When the list appears, you can select a property and press F1 to display reference Help for the selected property.


See Also

Object Inspector

Object Inspector Properties Page

Using the Categorical and Alphabetical Lists in the Object Inspector


 Position Properties

See Also

The Position category in the Object Inspector includes the following properties. All of these properties may not appear for any single object. Click the name of the property to display reference Help for that property.

Alignment

Bottom

Height

Left

Right

Top

Width

Working with the Object Inspector Lists

Press + on the numeric keyboard to display the list of Position properties for the current object.

Press - on the numeric keyboard to hide the list.

When the list appears, you can select a property and press F1 to display reference Help for the selected property.


See Also

Object Inspector

Object Inspector Properties Page

Using the Categorical and Alphabetical Lists in the Object Inspector


 Visual Properties

See Also

The Visual category in the Object Inspector includes the following properties. All of these properties may not appear for any single object. Click the name of the property to display reference Help for that property.

Border

BorderStyle

ColorHighLight

ColorNormal

FieldWidth

MousePointer

OldStyle

PatternStyle

Pen

ScrollBar

ShowDeleted

ShowHeading

ShowRecNo

Style

Vertical

Width

Working with the Object Inspector Lists

Press + on the numeric keyboard to display the list of Visual properties for the current object.

Press - on the numeric keyboard to hide the list.

When the list appears, you can select a property and press F1 to display reference Help for the selected property.


See Also

Object Inspector

Object Inspector Properties Page

Using the Categorical and Alphabetical Lists in the Object Inspector


Window Properties (Object Inspector)
 Window Properties

See Also

The Window category in the Object Inspector includes the following properties. These properties are specific to Form objects. Click the name of the property to display reference Help for that property.

AutoSize

EscExit

Maximize

MDI

Minimize

Moveable

ScaleFontName

ScaleFontSize

Sizable

SysMenu

WindowState

Working with the Object Inspector Lists

Press + on the numeric keyboard to display the list of Window properties for the form.

Press - on the numeric keyboard to hide the list.

When the list appears, you can select a property and press F1 to display reference Help for the selected property.


See Also

Object Inspector

Object Inspector Properties Page

Using the Categorical and Alphabetical Lists in the Object Inspector


 Object Inspector Events Page

See Also

The Events page displays the events to which the current object can respond.

To specify what will happen when an event occurs, you can do one of the following:

Type a codeblock into the entry field for the event. See Writing a Codeblock and Linking It to an Event for instructions and codeblock syntax.

Click [image] (to the right of the entry field) to display the Procedure Editor, where you can write a procedure to link to the event. See Writing a Procedure and Linking It to an Event for instructions.


See Also

Object Inspector

Object Inspector Methods Page

Object Inspector Properties Page

Using the Categorical and Alphabetical Lists in the Object Inspector


 Object Inspector Methods Page

See Also

The Methods page displays the current object's built-in methods, that is, the methods defined for the control.

To get reference Help on a built-in method, select it and press F1.


See Also

Object Inspector

Object Inspector Events Page

Object Inspector Properties Page

Using the Categorical and Alphabetical Lists in the Object Inspector


  No Help found

See Also

The item for which you are requesting Help is a custom property, event, method, or variable, and no Help is available for it.


See Also

Object Inspector


  No Help found

See Also

No property, event, or method exists in this page of the Object Inspector, so no Help is currently available.


See Also

Object Inspector


 Procedure Editor Options and Components

See Also	Language

Use the Procedure Editor to help you write and structure the code that defines the form and its behavior.

Procedure Editor Options

The combo box in the upper left corner of the Procedure Editor contains the following options:

(Header)

Choose this option to insert comments or code to precede the CLASS...ENDCLASS declaration for the form. After choosing this item, type the comments or code into the Text Editor window.

Begin a comment line with one or more asterisks.

A typical use for this area of the code is to declare module static variables and public variables.

(General)

Choose this option to add code after the CLASS...ENDCLASS declaration. After choosing this item, type the comments or code into the Text Editor window.

A typical use of this area is to insert procedures that are not methods defined for the form but that can be referenced by other elements.

List of existing methods

This list shows the methods that have been defined for the form. These are all the methods that are defined within the CLASS...ENDCLASS declaration that declares the form. Choose a method from this list to display it in the Text Editor window for editing.

To the right of the method list is a panel that lists any events that are linked to the current method. When you pass the pointer over this panel, and there are two or more events listed, the pointer changes to a pointer with a question mark. Click the panel to display a pop-up list of the events.

To create a new method and add it to this list, do either of the following:

Choose Procedure|New Method. This command is available only when the Procedure Editor is open and has focus. This creates a method that is not linked to an event.

Select an event in the Object Inspector and click  the Tool button to right of the entry field, for example:

This creates a method in which a procedure is linked to an event.

Text Editor Window

Use the Text Editor window to write the comments and code in this form file. Choose from the following for more information about text editing features:

Copying, Cutting, and Pasting Text Between Windows

Indenting Text

System-wide Keystrokes

Text Editing Keystrokes

Text Editor Components

Procedure|New Method.


See Also

Using the Procedure Editor - Overview

About Form (.WFM) Files

Opening the Procedure Editor

Linking Event-Handling Code to Events

Writing a Codeblock and Linking It to an Event

Writing a Procedure and Linking It to an Event


Language

CLASS...ENDCLASS


 Form Designer Menus

The Form Designer has the following menus. Not all of the commands on these menus are available in Order view.

File Menu

Edit Menu

View Menu

Layout Menu

Procedure Menu

Properties Menu

Window Menu

Help Menu


See Also

Designing Forms

Form Order View and the Order Spin Box


 Form Designer SpeedBar

See Also

The Form Designer SpeedBar contains the following buttons. Some of the buttons are available only in Layout view and one item is available only in Order view, as noted below.

Each button corresponds to a menu item (with one exception, noted below). Click any button or menu item in the following list to display help for the button and the menu item.

Button	Action	Menu Equivalent
	Creates a new dBASE-related file	File|New
	Opens a dBASE-related file	File|Open
	Saves the current file	File|Save
	Prints the current form as it appears on screen	File|Print
	Removes the selected object and places it on the Clipboard	Edit|Cut
	Copies the selected object onto the Clipboard	Edit|Copy
	Inserts the object from the Clipboard onto the active window	Edit|Paste
	Runs the form (when in the Form Designer)	View|Form
	Switches to the Form Designer (when running the form)	View|Form Design
	Switches to Layout view (when in Order view)	View|Layout View
	Switches to Order view (when in Layout view)	View|Order View
	Sets the z-order position of the selected object. (Not available in Layout view)	See Form Designer Order View
	Sends current item to last position in z-order (Not available in Order view)	Layout|Send to Back
	Brings current item to first position in z-order (not available in Order view)	Layout|Bring to Front
	Pushes current item one position toward back of z-order (Not available in Order view)	Layout|Send Farther
	Pushes current item one position toward front of z-order (Not available in Order view)	Layout|Bring Closer
	Aligns the left sides of selected objects with the left side of the object furthest to the left (Not available in Order view)	Layout|Align Left
	Aligns the right sides of selected objects with the right side of the object furthest to the right (Not available in Order view)	Layout|Align Right
	Aligns the top of selected objects with the top of the object closest to the top of the form (Not available in Order view)	Layout|Align Top
	Aligns the bottom of selected objects with the bottom of the object closest to the bottom of the form (Not available in Order view)	Layout|Align Bottom
	Switches to the Navigator window	Window|Navigator
	Switches to the Command window	Window|Command
	Opens the Form Expert	Help|Experts|Form Expert
	Opens the Interactive Tutors	Help|Interactive Tutors


See Also

About Z-Order and Tabbing Order in a Form


 Form Designer SpeedMenu

Use the Form Designer SpeedMenu to display the design tools and to perform common operations on the design surface.

To use the Speed Menu, right-click anywhere in the Form Designer design surface.

Choose from the following commands:

Form Designer Properties

Cut

Copy

Paste

Controls

Object Properties

Procedures


See Also

Basics: About SpeedBars and SpeedMenus


 File Menu (Form Designer)

See Also

Use the File menu to create new files, open and run existing files, print files, and exit the Form Designer.

Choose from the following commands:

New

Open...

Save

Save As...

Save and Close

Abandon and Close

Close

Print

Printer Setup

Set Up Custom Controls

Exit

(Closed file list)


See Also

Using the Form Designer - Overview


File | Set Up Custom Controls

See Also

Installs custom controls so they can be used to create a form. When you install custom controls, they are listed in the Control Palette and the Object Inspector.

This command displays the Open File dialog box, from which you can choose the file type, name, and location.

Shortcuts

Menu:	Navigator|Load Custom Controls

SpeedBar:	 (from selected custom controls file in Navigator window)

SpeedMenu:	Load Custom Controls (from selected custom controls file in Navigator window)

Keyboard:	F2 (from selected custom controls file in Navigator window)

Mouse:	Double-click the custom controls file in Navigator window.
Drag the custom controls file from Navigator window into the Desktop or Command window.


See Also

File Menu (Form Designer)


 Edit Menu  (Form Designer)

See Also

Use the Edit menu to perform editing and selection operations and to copy or remove items or text.

Choose from the following commands:

Undo or Redo

Cut

Copy

Paste

Delete

Select All

Select Form

Insert from File...

Copy to File...

Search

Convert Case

Join Text Lines

Build Expression...


See Also

Using the Form Designer - Overview


Edit | Select Form

See Also

Selects the form itself (and none of its controls). When you select this item, the form is selected in the Object Inspector.


See Also

Edit Menu (Menu Designer)

Opening the Object Inspector


 View menu  (Form Designer)

See Also

Use the View menu to run or design form, to switch between layouts, and to open the form tools.

Choose from the following commands:

Form

Form Design

Layout View

Order View

Controls

Object Properties

Procedures


See Also

Using the Form Designer - Overview


View | Form

See Also

Runs the form.

Shortcuts

Menu:	Navigator|Run Form (from selected form)
Catalog|Run Form (from selected form)

SpeedBar:
 (from selected form in Navigator or Catalog window)

SpeedMenu:	Run Form (from selected form in Navigator or Catalog window)

Keyboard:	F2 (from selected form in Navigator or Catalog window)

Mouse:	Double-click the form file in Navigator or Catalog window.
Drag the form file from Navigator or Catalog window into the Desktop or Command window.


See Also

View Menu (Form Designer)


View|Form Design (Form Designer)
View | Form Design

See Also

Displays the form in the Form Designer, where you can modify its design.

Shortcuts

Menu:	Navigator|Design Form (from selected form)
Catalog|Design Form (from selected form)

SpeedBar:
 (from selected form in Navigator or Catalog window)

SpeedMenu:	Design Form (from selected form in Navigator or Catalog window)

Keyboard:	Shift+F2 (from selected form in Navigator or Catalog window)

Mouse:	Double-right-click the form file in the Navigator or Catalog window.


See Also

View Menu (Form Designer)


View|Layout View (Form Designer)
View | Layout View

See Also

Displays the Layout view of the form in the Form Designer.

Shortcuts

SpeedBar:


See Also

View Menu (Form Designer)

View|Order View


View|Order View (Form Designer)
View | Order View

See Also

Displays the Order view of the form in the Form Designer.

Shortcuts

SpeedBar:


See Also

View Menu (Form Designer)

View|Layout View


View|Controls (Form Designer)
 View | Controls

See Also

Opens and displays the Control Palette if it is not open. If the Control Palette is already open, choosing this command closes it.

The Control Palette is visible only when the Form Designer design surface has focus. If you click outside of the design surface, the Control Palette is hidden. To redisplay it, click one of the design surfaces to return focus to it. Or choose Window|Controls.


See Also

View Menu (Form Designer)

Opening the Control Palette


 View | Object Properties

See Also

Opens and displays the Object Inspector if it is not open. If the Object Inspector is already open, choosing this command closes it.

The Object Inspector is visible only when the main Form Designer design surface or the Menu Designer window has focus. If you click outside of these design surfaces, the Object Inspector is hidden. To redisplay it, click one of the design surfaces to return focus to it. Or choose Window|Properties.


See Also

View Menu (Form Designer)

Designing Forms

Basics: About Object Inspectors

Opening the Object Inspector


 View | Procedures

See Also

Opens and displays the Procedure Editor if it is not open. If the Procedure Editor is already open, choosing this command closes it.

The Procedure Editor is visible only when the main Form Designer design surface or the Menu Designer window has focus. If you click outside of these design surfaces, the Procedure Editor is hidden. To redisplay it, click one of the design surfaces to return focus to it. Or choose Window|Procedures.


See Also

View Menu (Form Designer)

Designing Forms

Opening the Procedure Editor

Designing Menus


 Layout menu  (Form Designer)

See Also

These are the commands on the Form Designer Layout menu:

Align Left	(not available in Order view)

Align Right	(not available in Order view)

Align Top	(not available in Order view)

Align Bottom	(not available in Order view)

Align Special	(not available in Order view)

Bring to Front	(not available in Order view)

Send to Back	(not available in Order view)

Bring Closer	(not available in Order view)

Send Farther	(not available in Order view)

Tools


See Also

Form Order View and the Order Spin Box


Layout | Align Left

See Also

Aligns the left edges of selected objects with the left edge of the object farthest to the left.

Shortcuts

SpeedBar:


See Also

Layout Menu (Form Designer)


Layout | Align Right

See Also

Aligns the right edges of selected objects with the right edge of the object farthest to the right.

Shortcuts

SpeedBar:


See Also

Layout menu (Form Designer)


Layout | Align Top

See Also

Aligns the top edge of selected objects with the top edge of the object closest to the top of the form

Shortcuts

SpeedBar:


See Also

Layout Menu (Form Designer)


Layout | Align Bottom

See Also

Aligns the bottom edge of selected objects with the bottom edge of the object closest to the bottom of the form

Shortcuts

SpeedBar:


See Also

Layout Menu (Form Designer)


Layout | Align Special

See Also

Aligns the center axis of selected objects with the center axis of the form (absolute) or with the center axis relative to all the selected objects (relative). This menu contains the following four commands:

Absolute Horizontal Center

Relative Horizontal Center

Absolute Vertical Center

Relative Vertical Center


See Also

Layout Menu (Form Designer)


 Layout | Bring to Front

See Also

Sends the current object to the front of the z-order, which makes it the last position in the tabbing order.

Shortcuts

SpeedBar:

Example

The following illustration shows what happens to the tabbing order of five buttons if you select the third button and then select Layout|Bring to Front. The buttons remain in their original positions, but the tabbing order is changed.

1	2	3	4	5		1	2	5	3	4
 Old tabbing order	        New tabbing order


See Also

Layout Menu (Form Designer)

About Z-Order and Tabbing Order on a Form


Layout | Send to Back

See Also

Sends the current object to the back of the z-order, which makes it the first position in the tabbing order.

Shortcuts

SpeedBar:

Example

The following illustration shows what happens to the tabbing order of five buttons if you select the third button and then select Layout|Send to Back. The buttons remain in their original positions, but the tabbing order is changed.

1	2	3	4	5		2	3	1	4	5
 Old tabbing order	        New tabbing order


See Also

Layout Menu (Form Designer)

About Z-Order and Tabbing Order on a Form


Layout | Bring Closer

See Also

Sends the current object forward one position in the z-order, which makes it one position later in the tabbing order.

Shortcuts

SpeedBar:

Example

The following illustration shows what happens to the tabbing order of five buttons if you select the third button and then select Layout|Bring Closer. The buttons remain in their original positions, but the tabbing order is changed.

1	2	3	4	5		1	2	4	3	5
 Old tabbing order	        New tabbing order


See Also

Layout Menu (Form Designer)

About Z-Order and Tabbing Order on a Form


 Layout | Send Farther

See Also

Sends the current object back one position in the z-order, which makes it one position earlier in the tabbing order.

Shortcut

SpeedBar:

Example

The following illustration shows what happens to the tabbing order of five buttons if you select the third button and then select Layout|Send Farther. The buttons remain in their original positions, but the tabbing order is changed.

1	2	3	4	5		1	3	2	4	5
 Old tabbing order	        New tabbing order


See Also

Layout Menu (Form Designer)

About Z-Order and Tabbing Order on a Form


 Layout | Tools

See Also

Displays a menu from which you can choose to run the Menu Designer or the Query Designer.


See Also

Layout Menu (Form Designer)


 Layout | Tools | Design Menu

See Also

Opens the Menu Designer, where you can create a menu for the form.

Shortcuts

Menu:	Navigator|Design Menu (from selected menu file)

SpeedBar:	 (from selected menu file in Navigator window)

SpeedMenu:	Design Menu (from selected menu file in Navigator window)

Keyboard:	Shift+F2 (from selected table in Navigator window)

Mouse:	Double-right-click the table file in the Navigator window.


See Also

Layout Menu (Form Designer)


 Layout | Tools | Design Query

See Also

Opens the Query Designer, where you can create a query to use for the form.


See Also

Layout Menu (Form Designer)


 Procedure menu  (Form Designer)

See Also

Use the commands on the Procedure menu to work with procedures in the Procedure Editor. Some of these commands are available only when the Procedure Editor is open and has focus.

Choose from the following commands:

New Method

Remove Method

Verify Method

Edit Event

Link Event

Unlink Event


See Also

Using the Procedure Editor - Overview

Procedure Editor Options and Components


Procedure | New Method

See Also	Language

Creates a new method for the form.

This command places a PROCEDURE statement into the first line of the Text Editor window of the Procedure Editor, including a suggested name for the method. You can accept that name or replace it with any valid procedure name.

This method becomes available in the combo box in the Procedure Editor.

When you save the .WFM file, this procedure is placed within the CLASS...ENDCLASS declaration for the form, after the DEFINE statements that define the form's controls.

Procedure|New Method does not automatically link the new method to an event. In other words, this command does not automatically create an event handler. To link the method to an event, choose Procedure|Link Event, to display the Link Event dialog box and choose the event.

Shortcut

SpeedMenu:	New Method


See Also

Procedure Menu (Form Designer)

Using the Procedure Editor - Overview

Opening the Procedure Editor

Linking Event-Handling Code to Events

Writing a Codeblock and Linking It to an Event

Writing a Procedure and Linking It to an Event

Creating Form Methods Using External Procedures


Language

DEFINE

PROCEDURE


Procedure | Remove Method

See Also

Deletes the current method, that is, the one currently displayed in the Procedure Editor. This command is available only when the Procedure Editor is open and has focus.

When you choose this command, the current method is removed from the method list and is no longer available for linking to events or other editing. When the form is saved, the method does not appear in the .WFM file.


See Also

Procedure Menu (Form Designer)

Using the Procedure Editor - Overview

Opening the Procedure Editor

Linking Event-Handling Code to Events

Writing a Codeblock and Linking It to an Event

Writing a Procedure and Linking It to an Event

Creating Form Methods Using External Procedures


Procedure | Verify Method

See Also

Checks the current method for correct syntax. This command is available only when the Procedure Editor is open and has focus.

If any errors are found, an alert message appears.

Shortcut

SpeedMenu:	Verify Method


See Also

Procedure Menu (Form Designer)

Using the Procedure Editor - Overview

Opening the Procedure Editor

Linking Event-Handling Code to Events

Writing a Codeblock and Linking It to an Event

Writing a Procedure and Linking It to an Event

Creating Form Methods Using External Procedures


Procedure | Edit Event

See Also

Selects or creates a procedure that is linked to the selected event. This command displays the Edit Event dialog box, which lists the form, its controls, and all their events.

When you select an event that is linked to an existing method and then press OK, that method becomes current, and you can edit the code in the Text Editor window.

When you select an event that is not linked to a method, a new method is created. A PROCEDURE statement is placed in the Text Editor, followed by a suggested name for the procedure.

This command is available only when the Procedure Editor is open and has focus.

Shortcut

SpeedMenu:	Edit Event

Dialog Box Options

Object

Lists the form and all the controls in the form. When you select one of these items, all the events for the item appear in the Event list on the right of the dialog box (see below).

Event

Lists the events to which the object that is currently selected in the Object list can respond. This list contains the same events as are listed in the Events page of the Object Inspector for this object.

If an event is not linked to any procedure or codeblock, it appears alone in the list. When an event is linked, an icon to its left indicates it is linked. There are three icons that can appear:

 indicates the event is linked to a codeblock.

 indicates the event is linked to a procedure.


See Also

Procedure Menu (Form Designer)

Using the Procedure Editor - Overview

Opening the Procedure Editor

Linking Event-Handling Code to Events

Writing a Codeblock and Linking It to an Event

Writing a Procedure and Linking It to an Event

Creating Form Methods Using External Procedures


Procedure | Link Event

See Also

Links the current method to an event. This command is available only when the Procedure Editor is open and has focus.

When you choose this command, the Link Event to Procedure dialog box appears.

Shortcut

SpeedMenu:	Link Event

Dialog Box Options

Object

Lists the form and all the objects on the form.

Event

Lists the events to which the object that is currently selected in the Object list can respond. This list contains the same events as are listed in the Events page of the Object Inspector for this object.


See Also

Procedure Menu (Form Designer)

Using the Procedure Editor - Overview

Opening the Procedure Editor

Linking Event-Handling Code to Events

Writing a Codeblock and Linking It to an Event

Writing a Procedure and Linking It to an Event

Creating Form Methods Using External Procedures


Procedure | Unlink Event

See Also

Unlinks an event from the current method, that is, the method that is current in the Procedure Editor. This command displays the Unlink Events dialog box, where you can choose which events to unlink. To unlink an event, select it from the list and click OK. To unlink all events from the current method, click Select All and then click OK.

Dialog Box Options

Events to Unlink

Lists the events linked to the current method.

Select All

Selects all the events linked to the current method.


See Also

Procedure Menu (Form Designer)

Using the Procedure Editor - Overview

Opening the Procedure Editor

Linking Event-Handling Code to Events

Writing a Codeblock and Linking It to an Event

Writing a Procedure and Linking It to an Event

Creating Form Methods Using External Procedures


 Properties Menu  (Form Designer)

See Also

Use the Properties menu to change the characteristics of dBASE for Windows, the Form Designer, and the Procedure Editor.

Choose from the following topics:

Desktop...

Form Designer

Procedure Editor


See Also

Form Designer(L)|Form Designer Properties...


Properties | Form Designer

See Also

Sets characteristics of the design surface grid and ruler. The grid is a matrix of dots you can use to align objects.

dBASE records the choices you make in this dialog box in the DBASEWIN.INI file.

Dialog Box Options

Show Grid

When on (checked), displays the grid. When off (unchecked), hides the grid.

Snap To Grid

Determines if objects are automatically aligned with the grid when you add, move, or resize them.

When on, corners of the object "snap" to the nearest grid intersection point when you add, move, or resize the object. That is, each corner of the object is aligned with a dot in the grid so the edges of the object are one pixel above and one pixel to the left of dots in the grid. The following illustration shows a button aligned to the grid with Snap To Grid set on. (The red dotted lines are not part of the grid, but are used in this illustration to emphasize the grid matrix.)

When Snap To Grid is off, you can add, move, and resize an object anywhere on the design surface. The following illustration shows a button on the design surface when Snap To Grid is off.

If an object was created when Snap To Grid was off and then you turn Snap To Grid on, the size and position of the object is not changed until you move it or change its size. Then, the size and position of the object will be adjusted so that all four corners lie on top of a grid dot.

Show Ruler

When on, displays rulers on the left and top of the design surface. One unit on the ruler is one character unit, based on the current form font. That is, one unit on the horizontal ruler is equivalent to the average character width of the font. One unit on the vertical ruler is equivalent to the height of the font.

Control Palette Draw Mode

These options specify how controls are displayed on the Standard page of the Control Palette.

Bitmap Only - Shows a picture of the control without text.

Text Only - Gives the name of the control only without a picture.

Bitmap and Text - Shows both text and picture.

Form Expert - Invoke for New Forms

When this box is checked, the Form Expert opens whenever you create a new form. When this box is not checked, the Form Designer opens whenever you create a new form.

Grid Settings

Determines the size of the grid units. The settings are calculated relative to the current form font.

Fine - Approximately half the size of the current form font.

Medium - Approximately three-quarters the size of the current form font.

Coarse - Equivalent to the size of the current form font.

Custom - User-defined size, relative to the form font. Set the size in the X Grid and Y Grid spin boxes.

X and Y Grids

X Grid determines width. Y Grid determines height. The maximum for each setting is 1, which is equivalent to the size of the current form font.

Mouse - Revert to Pointer

This option affects how the pointer behaves when you choose controls from the Control Palette.

When in default mode, the pointer selects the form or objects on the form. When you click an object with the default pointer, that object is selected. You can then perform actions on the object, for example move it or change its properties.

When the Revert to Pointer box is checked, the pointer always reverts to this default behavior after you place a control on the design surface. Use this mode when you want to place a control on the form and then manipulate it, for example when you want to move and resize it.

The pointer switches to another mode when you click a control in the Control Palette. It becomes a tool for placing the selected control on the form. For example, if you click SpinBox on the Control Palette and then click the design surface, a spin box appears on the surface.

When the Revert to Pointer box is not checked, the pointer stays in this mode after you place a control on the form. You can click the design surface again to place another instance of the same control on the form. Use this mode when you want to place several controls of the same type on the design surface without reselecting the control from the palette each time.


See Also

Properties Menu (Form Designer)

Using  the Form Designer - Overview

Using the Procedure Editor - Overview


 Choose Color Dialog Box

See Also

Sets the color or colors for the form or for the current object on the form. You can set both foreground and background colors for those objects that have both. This dialog box appears when you click [image] in the Object Inspector for a property that references a color.

Some objects have a normal color and a highlight color. For example, an entry field can have one foreground/background color combination when it is not selected (normal) and a different foreground/background color combination when it is selected (highlighted). The normal foreground/background color is one property of the object. The highlight foreground/background color is another property.

Dialog Box Options

Foreground/Background

Select the Foreground radio button to set the colors for the foreground color of the object. When this button is selected, everything else you set in the dialog box applies to the foreground color for the object.

Select the Background radio button to set the colors for the background color of the object (if available). When this button is selected, everything else you set in the dialog box applies to the background color for the object.

The fields to the right of the radio buttons show the currently selected color for that option. These settings are automatically entered when you choose a color from the samples in the dialog box. You can also enter these settings directly if you know the number or the code to use. Most colors are expressed as hexadecimal values (for example, 0x8000ff for a deep pink). Some of the basic colors are expressed using these color codes:

Black	N	Red	R

Blue	B	Magenta	RB

Green	G	Brown	RG

Cyan	GB	White	W

High intensity for foreground is indicated by a plus sign (+) following the code. High intensity for background is indicated by an asterisk (*) following the code. For example, green is G for both foreground and background, while bright green for the foreground is G+, and bright green for the background is G*.

Basic Colors

Shows a selection of standard colors. Click a color to apply it to the foreground or background of the current object (depending on whether the Foreground or Background radio button is selected).

Custom Colors/Add to Custom Colors

Custom colors that you can set by selecting a color from the color field on the right side of the dialog box and then by clicking Add to Custom Colors.

Click one of these colors to apply it to the foreground or background color of the current object.

Sample

Shows a sample of the currently selected foreground and background colors.

Color Field

This box shows the spectrum of available colors. The crosshairs indicate the current color. For example, the crosshairs look like this when the color is a shade of yellow:

Ordinarily, you do not need to use this color field. When you select a color from the Basic Colors or when you type in the color code in the Foreground or Background entry fields, the crosshairs show where that color lies in the spectrum.

Click anywhere in the color field to select a color. When you select a color here and then click Add to Custom Color, the selected color is added to one of the Custom Color boxes so you can use it again.

Color|Solid

The patch of color in the left half of this box shows the currently selected color. The patch in the right half shows the closest solid color. Double-click the solid color to make it the current color.

Hue

Hue is the "actual" color, for example, red, yellow-green, or purple. Hue refers to the color without regard to saturation or brightness (luminosity).

Sat(uration)

Saturation refers to how much gray is in the color. The Sat(uration) field shows the saturation from 0 (medium gray) to 240 (pure color).

Note: Saturation affects how clear the color is. Luminosity affects how bright the color is.

Lum(inosity) and the Luminosity Slider Control

Luminosity is the brightness of a color. The Lum(inosity) field shows the luminosity from 0 (black) to 240 (white). The column to the right of the color field shows the range of luminosity for the current color. Slide the arrow to the right of the column up or down to adjust the luminosity. When you change the luminosity, the Red/Green/Blue color values also change.

Red/Green/Blue

The values in these fields show the balance of red, green, and blue in the current color. This is sometimes called the RGB color.


See Also

Using  the Form Designer - Overview


 Choose Alias Dialog Box

See Also	Language

Links a table to the current Browse control on a form. This dialog box appears when you click [image] in the Object Inspector for the Alias property of a Browse.

Dialog Box Options

Tables

Lists the tables in the query specified in the form's View property (or lists the single table if the View property is a .DBF file). When you choose a table from this list, that table appears in the Browse control on the form. You can choose only one table.

View button

Displays the Choose View dialog box from which you can choose a different query or table to use for the Browse control. For general information about opening files, see the Open File dialog box topic.


See Also

Using  the Form Designer - Overview

Using the Procedure Editor - Overview


Language

Alias

View


  Choose Bitmap Dialog Box

See Also	Language

Links a bitmap to the current control on a form. The Choose Bitmap dialog box appears when you click [image] in the Object Inspector for a property that specifies an image, for example the DataSource property of an image object.

Choose an option from the Location list to specify the source of the bitmap. Then specify the name in the Bitmap field. Click [image] to the right of the Bitmap field to display a second dialog box from which you can select a bitmap. The dialog box that appears depends on what you choose from the Location list.

Dialog Box Options

Location

Filename

Choose this option for a bitmap that is a standalone .BMP file.

When you select this option and click [image], an Open File dialog box appears, from which you can choose a .BMP file. For general information about opening files, see the Open File dialog box topic.

Binary

Choose this option for a bitmap that is stored in a binary field of a table.

When you select this option and click [image], a Choose Field dialog box appears, from which you can choose a binary field from a table, if you have already linked the form with the table through the form's View property. If you haven't set the form's View property, a message box prompts you to do so.

Resource

Choose this option for a bitmap that is stored in the DBAS0009.DLL file. This file contains the bitmaps used in dBASE for Windows itself, and you can use the same bitmaps for your applications.

When you select this option and click [image], the dBASE for Windows Bitmaps dialog box appears.

Bitmap

The name or label of the bitmap. When you choose Filename from the Location list, this is a file name. When you choose Binary, this is a field name. When you choose Resource, this is a resource number. This field is automatically filled when you click [image] and choose a bitmap from one of the dialog boxes.


See Also

Using  the Form Designer - Overview


Language

DataSource

View


  Choose Data Source Dialog Box

See Also	Language

Links specified data to the current control on a form. This dialog box appears when you click [image] in the Object Inspector for a DataSource property, for example for a list box or combo box.

Choose an option from the Type list to specify the source of the data, that is, the kind of data as determined by where it is stored. Then enter the appropriate information in the Data Source field, as discussed below. If you choose Field, you can click [image] to help you choose a field.

Dialog Box Options

Type

Array

Choose this option to reference data that is stored in an array. The array must already be declared for you to be able to reference it here. (You can declare an array in the Header section of the .WFM file that defines the current form.See Procedure Editor Options and Components for more information about using the Procedure Editor to enter information in the Header section of the code.)

In the Data Source field, type the reference to the array using this format:

ARRAY arrayName

where arrayName is the name of a declared array.

Field

Choose this option to reference data that is stored in a field in a table. Enter the name of the field (qualified with its table name if it is in a multi-table query), or click [image] to display the Choose Field dialog box, from which you can choose a field. This dialog box appears if you have already linked the form with the table through the form's View property. If you haven't set the form's View property, a message box prompts you to do so.

File

Choose this option to display a list of files, filtered by partial file names and wildcards. For example, enter *.DBF in the Data Source field to indicate that all files with the extension DBF will be displayed in the list box. If you do not qualify the filemask with a path, the files in the current directory will be displayed. You can see and change the current directory in the Navigator.

Structure

Choose this option to display the fields in the current table. Do not type anything in the Data Source field.

Tables

Choose this option to display the tables in the current directory or SQL database.Do not type anything in the Data Source field.

Data Source

The name or other reference to the data source, as explained for each type under Type, above.


See Also

Using  the Form Designer - Overview

Using the Procedure Editor - Overview

About Form (.WFM) Files


Language

DECLARE

DataSource

View


  Choose Data Link Dialog Box

See Also	Language

Links specified data to the editor control on a form. This dialog box appears when you click [image] in the Object Inspector for the DataLink property of an editor control.

Choose an option from the Type list to specify the source of the data. Then enter the appropriate information in the Data Source field, as discussed below. You can click [image] to help you choose a field or file.

Dialog Box Options

Type

Field

Choose this option to link to data that is stored in a field in a table. Enter the name of the field (qualified with its table name if it is in a multi-table query), or click [image] to display the Choose Field dialog box, from which you can choose a field. This dialog box appears if you have already linked the form with the table through the form's View property. If you haven't set the form's View property, a message box prompts you to do so.

File

Choose this option to link to a text file. Enter the name of the file, or click [image] to display the Choose Datasource dialog box, which is a typical open file dialog box from which you can choose a file. By default, the .TXT files in the current directory will be displayed.

Data Source

The name or other reference to the data source, as explained for each type under Type, above.


See Also

Using  the Form Designer - Overview

Using the Procedure Editor - Overview

About Form (.WFM) Files


Language

DataLink

View


  Choose Field Dialog Box

See Also	Language

Links a field from a table to a control such as an entry field. This dialog box appears when you click [image] in the Object Inspector for a property that references a table field. For example, it appears when you click [image] in the Object Inspector for the DataLink property.

Dialog Box Options

Tables

Lists the table (or tables if a query) used as the basis for the form. This table or query is the one referenced as the View property of the form.

Fields

Lists the fields in the table selected in the Tables list. Select one of these fields to link it to the control.

View button

Displays the Choose View dialog box from which you can choose a query or table to use as the underlying data for the control. For general information about opening files, see the Open File dialog box topic.


See Also

Using  the Form Designer - Overview

Using the Procedure Editor - Overview

About Form (.WFM) Files


Language

DataLink

View


 dBASE for Windows Bitmap Dialog Box

See Also	Language

The dBASE for Windows Bitmap dialog box lists all the bitmap resources in the DBAS0009.DLL file, which contains the bitmaps used in dBASE for Windows itself.

Dialog Box Options

ID

The identification number for the bitmap in the .DLL file.

Bitmap

The bitmap named by the ID number in the ID field.


See Also

Using  the Form Designer - Overview


Language

DataSource

View


 Using Forms

See Also

The run view for forms is the form itself, or, more specifically, the form at run-time. When a user runs the form, the controls become active. If the form is associated with data, for example, the records in a table, that data can be viewed and/or edited. You can design a form with its own menus, or you can use the default dBASE menus for basic operations such as working with table records.

Form Tools

Menus

SpeedBar


See Also

Basics: About the System-Wide Tools

Basics: About Design and Run Modes

Using  the Form Designer - Overview

About Forms


 Form SpeedBar

See Also

The SpeedBar in a form that uses the default dBASE for Windows menu contains the following buttons. Each button corresponds to an item on one of the menus. Click any button or menu item in the following list to display help for the button and the menu item.

Button	Action	Menu Equivalent
	Displays menu of items you can create	File|New
	Displays file handling dialog box for choosing file to open	File|Open
	Saves current file	File|Save
	Prints current file	File|Print
	Cuts current item and places it on the Clipboard	Edit|Cut
	Copies current item and places the copy on the Clipboard	Edit|Copy
	Pastes item from Clipboard to current position	Edit|Paste
	Runs the form (switches from Design view to Run view)	View|Run Form
	Switches from Run view to Design view	View|Design Form
	Finds a specified record	Form|Find Records...
	Adds a record to the end of the table	Form|Add Records
	Moves to the first record	Form|Top Record
	Moves to the previous record	Form|Previous Record
	Moves to the next record	Form|Next Record
	Moves to the last record	Form|Bottom Record
	Displays the dBASE Navigator	Window|Navigator
	Displays the Command window	Window|Command
	Opens the Form Expert	Help|Experts|Form Expert
	Opens the Interactive Tutors	Help|Interactive Tutors...


See Also

Basics: About SpeedBars and SpeedMenus


 Form Menus

See Also

A form that is created without its own menus uses the following default dBASE for Windows menus:

File Menu

Edit Menu

View Menu

Form Menu

Properties Menu

Window Menu

Help Menu


See Also

Designing Forms

Designing Menus


 File Menu (Forms)

See Also

Use the create new files, open existing files, and print files.

Choose from the following commands on the File menu in forms that use the default dBASE for Windows menus:

New

Open

Close

Print...

Printer Setup...

Exit


See Also

Form Menus


Edit Menu (Forms)

See Also

Use the Edit menu to perform editing operations, to copy or remove text, and to work with embedded objects.

Undo or Redo

Cut

Copy

Paste

Paste Link

Delete

Select All

Insert Object

Links

Object


See Also

Form Menus


 View Menu (Forms)

See Also

Use the View menu to switch between Run and Design views in forms that use the default dBASE for Windows menus.

Choose from the following commands:

Form

Form Design


See Also

Form Menus


 Form Menu (Forms)

See Also

Use the Form menu in forms that use the default dBASE for Windows menus to find and replace records, access table utilities, append, delete, lock, and blank records, and navigate in the table.

Choose from the following commands:

Find Records...

Replace Records...

Table Utilities

Add Records

Delete or Recall Selected Record

Lock or Unlock Selected Record

Blank Selected Record

Go to Record Number...

Previous Record

Next Record

Previous Page

Next Page

Top Record

Bottom Record


See Also

Form Menus


 Properties Menu (Forms)

See Also

Choose the Desktop command from the Properties menu to change the characteristics of dBASE for Windows.


See Also

Form Menus


 Form Expert - Step One

See Also

About the Form Expert

The Form Expert helps you design and create forms that use table data, such as data entry or data display forms. It presents you with a series of data and design options and creates a form based on your selections. Once created, you can modify the form with the Form Designer.

The Form Expert expedites the task of creating a data entry form--it automates the process of placing data entry controls and text labels on the form, and linking the controls to fields in the table.

Choose one of the following options:

Expert Assistance

Select this if you want the Form Expert to help you create a form that uses table data.

Blank Form

Select this to bypass the Form Expert and to create a form from scratch. You typically select this option to create a form that does not use table data, such as a dialog box.


See Also

About Forms

Designing Forms


 Form Expert - Step Two

See Also

Select the table or query whose data you want the form to use. To proceed to the next step, you need to select a file. To select a file, do one of the following:

Select a file from the Available Files list. By default, the list shows all the query (.QBE) files in the current directory.

Click the Tool button to the right of the text box to select a file in a different directory.

Type a file name into the text box.


See Also

About Forms

Designing Forms


 Form Expert - Step Three

See Also

Select the table fields you want to display in the form. The Form Expert lists all the fields in the table or query that you selected in the previous step. Select fields in the order in which you want them to appear on the form. To proceed to the next step, you need to select at least one field. To select individual fields or all fields, use the arrow buttons:

Add (>)

Adds the selected field in the Available list to the bottom of the list of fields in the Selected list.

Add All (>>)

Adds all fields in the Available list to the Selected list.

Remove (<)

Removes the selected field in the Selected list and places it at the bottom of the Available list.

Remove All (<<)

Removes all fields in the Selected list and moves them to the Available list.


See Also

About Forms

Designing Forms


 Form Expert - Step Four

See Also

Select one of the following layout designs for the form:

Columnar Layout

Displays selected fields of a single record vertically in a single column.

Form Layout

Displays selected fields of a single record horizontally with the field name above each field.

Browse Layout

Displays selected fields of multiple records in a grid of rows (records) and columns (fields).

One to Many

Displays data for two tables linked in a one-to-many relationship. The child records appear in a browse object. This layout is suitable for presenting a lookup table where child records are displayed as the user navigates through records in the parent table.


See Also

About Forms

Designing Forms


 Form Expert - Step Five

See Also

Customize display attributes--font, color, borders--for various elements of the form, or use the default settings. The selections you make are reflected in the sample form shown in the top left corner. You can set the font and/or colors for the following form elements:

Title

The text that appears at the top of the form. The Form Expert uses the name of the table or query as the default text. You can change this title once the form has been created.

Text

The text labels that appear next to entry fields. The Form Expert uses the names of the fields as the default text. You can change the text labels once the form has been created.

Entry

The data entry controls--entry fields, spin boxes, or check boxes--that are linked to fields in the table. The Form Expert creates and links data entry controls to the table fields you selected in step 3. You can specify a color for the text that appears in the control (foreground) and a color for the entry area (background). You can also specify a border around the entry area by selecting the Entry Borders checkbox.

Form

The form window background.

Setting Font Attributes

You can specify the font, font style, and size visually by clicking the Tool button and selecting the options you want from the Font dialog box.

Setting Colors

To specify a color for any form element, click the arrow button next to the text box, and select a color from the drop-down list. As you move from one color option to the next (using the arrow keys), the color changes are reflected in the sample form so you can see the results before you actually make your selection.


See Also

About Forms

Designing Forms


Designing Menus

See Also

Use the Menu Designer to create a complete menu system for a form, including a menu bar, pull-down menus, and cascading menus.

Menu Designer Concepts and Tasks

About Menus

Using the Menu Designer - Overview

Menu Designer Tasks

Menu Designer Tools

The Menu Designer has a menu, a SpeedBar, and a SpeedMenu. Choose from the following list for more information about these topics:

Menu commands

SpeedBar

SpeedMenu


See Also

Using the Procedure Editor - Overview

Object Inspector

Menu menu


About Menus

Language

Menus display a hierarchy of choices for the user. Each menu item performs an action, such as starting a process, displaying a dialog box, changing a setting, or displaying another menu. Choosing a menu item executes its OnClick event handler.

Choose from the following list for more information about menus:

Kinds of Menus

MDI and Menus

The .MNU File


Language

CLASS MENU

MDI


Kinds of Menus

Forms can contain the following kinds of menus:

	Menu bar Pull-down menu Cascading menu
Menu systems are made up of a hierarchy of menu objects. Each prompt in the menu above (File, Save, Bitmap) is a menu object. The location of a menu object is determined by its place in the hierarchy.

Menu bars contain the top-level menus on a form. Each form can have one menu bar. Each item on the menu bar opens a pull-down menu, launches an action, or both.

Pull-down menus are the second-level menus on a form. Each pull-down menu appears below an item on the menu bar. Each item on a pull-down menu launches an action or opens a cascading menu. In the illustration above, Open, Save, Save as, and Close launch actions, and Import launches a cascading menu.

Cascading menus appear beside a pull-down menu or another cascading menu. Each item on a cascading menu launches an action or opens another cascading menu. In the illustration above, Text file, Sound and Bitmap are cascading menu items.


MDI and Menus

The MDI property of a form determines whether the form is an MDI form. The default is True, making it an MDI form. When you attach a menu to an MDI form, the menu does not appear in the form itself. Rather, it appears in the application window replacing the dBASE menu bar. If you want the menu to appear in the form window, set the MDI property to False.


The .MNU file

Language

The Menu Designer saves the menu definition in a text file with an .MNU extension. The .MNU file contains the dBASE code for creating the menu objects. You attach a menu to a form by specifying the .MNU file name in the MenuFile property of the form.

In most cases, you can create menus with the Menu Designer and never edit the code in the .MNU file. However, like the .WFM file generated by the Form Designer, you can generate an .MNU file with the Menu Designer, modify its code with a text editor, then reload the .MNU file into the Designer.


Language

MenuFile

CLASS Menu


Using the Menu Designer - Overview

See Also

Like the Form Designer, the Menu Designer is a tool for placing objects in a window. It uses the Object Inspector to set properties and the Procedure Editor to write event handlers. Since a menu system is made up of only one kind of object - a Menu object - there is no Control Palette for the Menu Designer. Instead, you create menu objects by positioning the insertion point and typing the menu prompt.

Menu Designer	Object Inspector	Procedure Editor
Create a menu system by building a hierarchy of menu objects from left to right, top to bottom. Add each menu object by moving the insertion point to where you want the object to appear and entering the text. If you remove focus from a menu object without entering text, the Menu Designer automatically deletes the object.

Choose from the following list for more information about using the Menu Designer:

Adding and Deleting Menu Items

Specifying Shortcut and Mnemonic Keys

Assigning Actions to Menu Objects


See Also

The .MNU File

Designing Forms

Procedure Editor

Object Inspector


Menu Designer Tasks

Choose from the following list for more information about using the Menu Designer:

Adding and Deleting Menu Items

Specifying Shortcut and Mnemonic Keys

Assigning Actions to Menu Objects


Adding and Deleting Menu Objects

The following table lists the keystrokes and menu commands for adding and deleting menu objects. You have to fill in the prompt text for a menu item before adding another menu item below or next to it.

Task	Keystroke	Menu Command
Add a pull-down menu item below the selected menu bar item.	Enter,  Down arrow, Ctrl+M	Menu|Insert Menu
Add a cascading menu item beside the selected pull-down or cascading menu item.	Ctrl+M, Tab,  Right arrow at end of prompt text	Menu|Insert Menu
Add menu bar item to the right of selected item.	Tab,  Right arrow at end of prompt text
Insert a menu item before the selected item.	Ctrl+N	Menu|Insert Menu Item
Delete the selected item.	Ctrl+U	Menu|Delete Selected
To navigate between menu items, use the arrow keys, Tab and Shift+Tab, or click an item to select it. Use PgUp and PgDn to scroll menu items.


Specifying Shortcut and Mnemonic keys

Specifying Shortcut Keys

A shortcut key is a keystroke combination that chooses a menu item even if the menu is closed. For example, pressing Ctrl+O in dBASE displays the Open File dialog box even when the File menu is closed.

To specify a shortcut key for a menu item, enter the key combination in the Shortcut property.

When the form executes, pressing the key combination causes the OnClick event of the menu item to execute. The key combination also appears next to the menu title when the form executes (not in the Menu Designer).

Specifying Mnemonic Keys

A mnemonic key is a letter in the menu prompt that the user presses to choose the item when the menu is open.

To specify a mnemonic key for a menu item, precede the letter in the menu prompt with an ampersand (&). For example, to specify X as the mnemonic key for an Exit menu item, enter the menu title as E&xit.

When the form executes, the letter representing the mnemonic key appears underlined.


Assigning Actions to Menu Objects

See Also

You assign an action to a menu object by writing an event handler for the OnClick event. The steps are similar to those used in the Form Designer. The event handler can be a procedure or a codeblock.

To assign a procedure to a menu object,

1.	Select the object.

2.	Open the Procedure Editor for the OnClick event in either of these ways:

Double-click the object, or

Open the Object Inspector, select the OnClick event from the Events page, and click [image].

3. Enter the procedure.

To assign a codeblock to a menu object,

1.	Select the object.

2.	Open the Object Inspector.

3.	Enter the codeblock in the text box next to the OnClick event.


See Also

Opening and Displaying the Object Inspector

Using the Procedure Editor - Overview

Opening the Procedure Editor

Linking Event-Handling Code to Events


Menu Designer Menus

The Menu Designer has the following menus:

File Menu

Edit Menu

View Menu

Menu Menu

Procedure Menu

Properties Menu

Window Menu

Help Menu


 File Menu (Menu Designer)

See Also

Use the File menu to create new files, open and run existing files, print files, and exit the Menu Designer.

Choose from the following commands:

New

Open...

Save

Save As...

Save and Close

Abandon and Close

Close

Exit

(Closed file list)


See Also

Using the Form Designer - Overview

Designing Menus


 Edit Menu  (Menu Designer)

See Also

Use the Edit menu to perform editing and selection operations and to copy or remove items or text.

Choose from the following commands:

Undo or Redo

Cut

Copy

Paste

Delete

Select All

Insert from File...

Copy to File...

Search

Convert Case

Join Text Lines

Build Expression...


See Also

Using the Form Designer - Overview

Designing Menus


 View Menu  (Menu Designer)

See Also

Use the View menu to open the form tools.

Choose from the following commands:

Object Properties

Procedures


See Also

Using the Form Designer - Overview

Designing Menus


Menu Menu (Menu Designer)

See Also

When the Menu Designer is the active window, use the Menu menu to add and delete menus and menu items.

Choose from the following commands:

Insert Menu Item

Insert Menu

Insert Separator

Delete Selected


See Also

Using the Form Designer - Overview

Designing Menus


Menu | Insert Menu Item

See Also

Inserts a menu item before the selected menu item.

Shortcuts

SpeedBar:

Keyboard:	Ctrl+N


See Also

Menu Menu (Menu Designer)

Menu | Insert Menu

Menu | Delete Selected


Menu | Insert Menu

See Also

Adds a menu on the next level of the hierarchy from the selected menu item.

If a menu bar item is selected, Insert Menu adds a pull-down menu item below it.

If a pull-down or cascading menu item is selected, Insert Menu adds a cascading menu item beside it.

Shortcuts

Keyboard:	Ctrl+M


See Also

Menu Menu (Menu Designer)

Menu | Insert Menu Item

Menu | Delete Selected


Menu | Insert Separator

See Also	Language

Inserts a separator line above the selected item on a pull-down or cascading menu.

Separators help to group menu items on a menu, making it easy for users to scan for the items they want to choose. Users cannot choose or give focus to a separator.

A separator is a menu object with the Separator property set to True.

Shortcuts

Keyboard:	Ctrl+T


See Also

Menu Menu (Menu Designer)


Language

Separator


Menu | Delete Selected

See Also

Removes the selected menu item and any menu items below it in the hierarchy.

Before removing menus below the selected menu item, a message box prompts for confirmation.

Shortcuts

SpeedBar:

Keyboard:	Ctrl+U


See Also

Menu Menu (Menu Designer)

Menu | Insert Menu Item

Menu | Insert Menu


 Procedure Menu  (Menu Designer)

See Also

Use the commands on the Procedure menu to work with procedures in the Procedure Editor. Some of these commands are available only when the Procedure Editor is open and has focus.

Choose from the following commands:

New Method

Remove Method

Verify Method

Edit Event

Link Event

Unlink Event


See Also

Using the Form Designer - Overview

Designing Menus

Using the Procedure Editor - Overview

Procedure Editor Options and Components


 Properties Menu  (Menu Designer)

See Also

Use the Properties menu to change the characteristics of dBASE for Windows and the Procedure Editor.

Choose from the following topics:

Desktop...

Procedure Editor


See Also

Using the Form Designer - Overview

Designing Menus

Using the Procedure Editor - Overview

Procedure Editor Options and Components


 Menu Designer SpeedBar

The Menu Designer SpeedBar contains the following buttons.

Each button corresponds to a menu item. Click any button or menu item in the following list to display help for the button and the menu item.

Button	Action	Menu Equivalent
	Creates a new dBASE-related file	File|New
	Opens a dBASE-related file	File|Open
	Saves the current file	File|Save
	Removes the selected text and places it on the Clipboard	Edit|Cut
	Copies the selected text onto the Clipboard	Edit|Copy
	Inserts the text from the Clipboard into the selected menu prompt	Edit|Paste
	Inserts a menu item before the selected menu item	Menu|Insert Menu Item
	Removes the selected menu item	Menu|Delete Selected
	Switches to the Navigator window	Window|Navigator
	Switches to the Command window	Window|Command
	Opens the Form Expert	Help|Experts|Form Expert
	Opens the Interactive Tutors	Help|Interactive Tutors


 Menu Designer SpeedMenu

Use the Menu Designer SpeedMenu to display the design tools and to perform common operations on the design surface.

To use the Speed Menu, right-click anywhere in the Menu Designer design surface.

Choose from the following commands:

Cut

Copy

Paste

Object Properties

Procedures


Working with Queries

About Queries

Designing Queries

Running Queries


 About Queries

See Also

A query is a set of dBASE commands that selects, filters, and organizes data from one or more tables. Use the Query Designer to specify the details of a query. Then run the query to see the query results, that is, to see the selected, filtered, and organized data. When you run the query, the data is presented in the Query Results window in the form of a table. This table is called a view of the data. It does not contain the actual data, but provides a view of the data that is stored in the table(s) on which the query is based. In many cases you can edit the data in a view, and the changes are written back to the original tables. You can, if you wish, save the view as a new table. This duplicates the selected data from the original table(s). If you edit the data in the new table, the data in the original tables is not changed.

About Query Code and .QBE Files

The Query Designer generates dBASE code that specifies the details of the query. When you run the query, the code executes to display the view of the data as specified in the query. For example, the Query Designer generates statements using the following commands:

INDEX

USE

SET FIELDS

SET FILTER

SET INDEX

SET RELATION

SORT

When you save a query, the code is saved in a text file with the extension .QBE. You can open this file in the Text Editor and edit it directly. You can also return to the Query Designer, open the .QBE file, and edit the details of the query using the Query Designer's interactive tools.


See Also

Views and Tools

Basics: About the View Model in the User Interface

Designing Queries

Running Queries


 Designing Queries

See Also

Use the Query Designer to select, filter, and organize data from one or more tables. You can then run the query to view and (in some cases) edit the data.

Query Designer Concepts and Tasks

Choose from the following list for information about the using the Query Designer:

Using the Query Designer - Overview

Query Designer Tasks

Query Designer Tools

The Query Designer consists of a design surface, menus, and a SpeedBar. Choose from the following list for more information:

Design Surface	Descriptions of the components of the query design surface

Menus	Lists and descriptions of all Query Designer menu commands

SpeedBar	Descriptions of the Query Designer SpeedBar options

SpeedMenu	List and descriptions of the Query Designer SpeedMenu commands


See Also

About Queries

Running Queries


 Using the Query Designer - Overview

Use the Query Designer to organize, sort, and select the data you want to see from one or more tables. In particular, use the Query Designer to:

Specify which fields you want to appear in the view of the data when you run the query. You can also specify the order of the fields as they appear in the view. For more information, see:

Changing the Order of Fields to Display in a View

Selecting Fields to Display in a View

Filter which records you want shown in the view of the data when you run the query. Do this by specifying conditions that must be met for each record to appear in the view. When you specify the filter condition or conditions, the appropriate fields are evaluated one record at a time to see if they match the conditions. For more information, see:

Setting Filter Conditions in a Query - Overview

Filter Condition Syntax in the Query Designer

Setting Simple Filter Conditions in the Query Designer

Setting AND Conditions in the Query Designer

Setting OR Conditions in the Query Designer

Combining AND and OR Conditions in the Query Designer

Using the Conditions Box to Set Complex Filters

Specify the order in which the records will appear in the view. For more information, see:

Specifying Record Order in a Query

Basing Record Order on Two or More Fields in a Query

Create calculated fields that use operators and functions to perform operations on one or more fields. The results of these operations appear in a new field in the view. For example, you can combine the values of two fields into a single new field, or you can perform calculations on a numeric field to show a calculated result in a new field. These operations work on one record at a time. For more information, see:

Working with Calculated Fields in a Query

Creating or Adding a Calculated Field in the Query Designer

Specifying Calculations for a Calculated Field

Displaying Results from a Calculated Field

Setting Filter Conditions in a Calculated Field

Set relations between tables, so that the records in a table are associated with records in one or more other tables, based on common fields. For more information, see:

Setting a Relation Between Tables in a Query

Modifying a Relation Between Tables in a Query

Removing a Relation Between Tables in a Query

Define or Modify Relation dialog box

When you have finished specifying the details of the query, you can

Run the query immediately to display the results. See Running a Query to Display the Results.

Save the query to run it later or to use as the basis of a form, report, or label. See Saving a Query.

Copy the results to a new table. See Copying Query Results to a New Table.


Query Designer Tasks

Choose from the following list for information about how to use the Query Designer:

Basic Query Designer Operations

Creating a New Query

Opening an Existing Query

Closing the Query Designer

Saving a Query

Copying Query Results to a New Table

Displaying the Results of a Query

Changing the Order of Fields to Display in a View

Selecting Fields to Display in a View

Running a Query to Display the Results

Working with Tables in the Query Designer

Adding a Table to a Query

Removing a Table from a Query

Filtering Data in a Query

Setting Filter Conditions in a Query - Overview

Filter Condition Syntax in the Query Designer

Setting Simple Filter Conditions in the Query Designer

Setting AND Conditions in the Query Designer

Setting OR Conditions in the Query Designer

Combining AND and OR Conditions in the Query Designer

Using the Conditions Box to Set Complex Filters

Working with Calculated Fields in a Query

Working with Calculated Fields in a Query

Creating or Adding a Calculated Field in the Query Designer

Specifying Calculations for a Calculated Field

Displaying Results from a Calculated Field

Setting Filter Conditions in a Calculated Field

Specifying the Order of Records in a Query

Specifying Record Order in a Query

Basing Record Order on Two or More Fields in a Query

Working with Multiple Tables and Relations in a Query

Setting a Relation Between Tables in a Query

Modifying a Relation Between Tables in a Query

Removing a Relation Between Tables in a Query


Basic Query Designer Operations


Creating a New Query

See Also	Language

If tables are open when you create a query, those tables might or might not be used as the basis for the query, depending on whether or not Sessions is on. The following procedures describe the effects of Sessions, where appropriate.

To create a query from anywhere in dBASE for Windows,

Choose File|New|Query.

If Sessions is on, the Open Table Required dialog box appears. Choose a table on which to base the query. The Query Designer opens with the skeleton of the table displayed on the design surface:

If Sessions is off, the Open Table Required dialog box does not appear. If no tables are open, the Query Designer opens with nothing on the design surface. If one or more tables are open, the Query Designer opens with the skeleton(s) of the table(s) displayed on the design surface.

To create a query from the Navigator or Catalog window,

1.	Click [image] All or [image] Queries from the file types list in the left pane of the window.

2.	Do one of the following:

Double-click [image] (Untitled) in the files list in the right pane of the window.

Right-click [image] (Untitled), then choose New Query from the SpeedMenu.

Click [image] (Untitled), then press Shift+F2 or click [image] on the SpeedBar.

Drag [image] (Untitled) to the Command window.

Click any [image] icon, then choose Navigator|New Query,

Note: The icon in the right pane of the Navigator or Catalog window might be small or large, depending on whether you choose View|Small Icons or View|Large Icons:

The Sessions setting determines how dBASE responds, as described above, under "To create a query from anywhere in dBASE for Windows."

To create a query based on the current table when browsing or editing the table,

Select Table|Create Query, or click [image] on the SpeedBar.

The Query Designer opens with the skeleton(s) of the table(s) displayed on the design surface. The window showing the table remains visible and active.


See Also

Basics: About Sessions

File|New|Query

Table|Create Query


Language

CREATE QUERY


Opening an Existing Query

See Also	Language

You can modify or run an existing query. To modify the design of a query, you open it in the Query Designer. When you run a query, the query results appear in the Query Results window, where you can view and edit the data.

To open and design an existing query from the Navigator or Catalog window,

1.	Click [image] All or [image] Queries from the file types list in the left pane of the window.

2.	Do one of the following:

Double-right-click the [image] <query name> icon for the query you want in the files list in the right pane of the window.

Right-click the [image] <query name> icon for the query you want, then choose Design Query from the SpeedMenu.

Click the [image] <query name> icon for the query you want. Then, do one of the following:

- Choose Navigator|Design Query from the menu bar,

- Press Shift+F2, or

- Click [image] on the SpeedBar.

Note: The icon in the right pane of the Navigator or Catalog window might be small or large, depending on whether you choose View|Small Icons or View|Large Icons:

The Query Designer appears with the view skeleton on the design surface:

To run an existing query from the Navigator or Catalog window,

1.	Click [image] All or [image] Queries from the file types list in the left pane of the window.

2.	Do one of the following:

Double-click the [image] <query name> icon for the query you want in the files list in the right pane of the window.

Right-click the [image] <query name> icon for the query you want, then choose Run Query from the SpeedMenu.

Click the [image] <query name> icon for the query you want. Then, do one of the following:

-	Choose Navigator|Run Query from the menu bar,

-	Press F2, or

-	Click [image] on the SpeedBar.

Drag the [image] <query name> icon for the query you want to the Command window.

The Query Results window appears:


See Also

Basics: Introduction to the dBASE Navigator

Basics: Introduction to the Catalog Window


Language

MODIFY QUERY


Closing the Query Designer

See Also

To close the Query Designer,

Choose File|Close.

If you have made changes since the query was last saved, you are asked if you want to save the query before closing it.

When you run the query, the query design surface is no longer visible. However, you can switch back to it without reopening the query. Choose View|Query Design or click [image] to switch back.

If you run the query and close that view, the Query Designer is also closed. You are prompted to save changes before closing.


See Also

View|Browse Layout


Saving a Query

See Also

To save a query,

Choose File|Save, or click [image] on the SpeedBar.

If the query has not been saved before, a Save File dialog box appears, where you can specify the name for the query.

You can save a query only while in the Query Designer, that is, when you are designing the query. If you are running a query, switch back to the Query Designer to save it (however, if you try to close an unsaved query in Run mode, you are prompted to save it).

When you save a query, it is saved with the default extension .QBE. A .QBE file contains dBASE commands that define the query. You can run the query to edit data, or you can use the query as the basis for a form, report, or label.

To save a query using a different name,

Choose File|Save As...

The Save As dialog box appears, where you can specify a name for the query.


See Also

Copying Query Results to a New Table.


Copying Query Results to a New Table

See Also	Language

When you run a query, the results appear in the Query Results window. The data is displayed as a table, which is sometimes called a view. That table exists only in memory; it is not saved when you close the query.

However, you can copy the results of the query to a new table. When you do so, the new table exists as a separate .DBF or .DB file that has the same structure, organization, and selection of records as you see in the view when you run the query. This new table duplicates records from the tables upon which the query is based. If you change data in the new table, the original data remains unchanged.

To copy query results to a new table,

Choose Query|Copy Results to New Table. The Save Table dialog box appears, where you can specify the name for the file.


See Also

Basics: About the View Model in the User Interface


Language

SORT


Displaying the Results of a Query


Changing the Order of Fields to Display in a View

See Also

When you run a query to display the data in a view, the fields in the resulting table appear in the same order as they are in the skeleton.

To change the order of fields to display in a view,

1.	Pass the pointer over the field name in the view skeleton. The pointer turns into a hand:

2.	Click and drag the field left or right to its new position. Release the mouse.

When you run the query, the field appears in its new position in the view. When you save the query, field positions are saved as part of the query definition.

You can also change the order of fields in the Query Results window, which is displayed when you run the query. However, when you change the order of fields in the Query Results window, field positions are not saved as part of the query definition.


See Also

Saving a Query

Selecting Fields to Display in a View

Running a Query to Display the Results


Selecting Fields to Display in a View

See Also

In the Query Designer, you can select which fields to display from a table or tables. When you run the query, only the fields you have selected appear in the view.

To select a field to display in the view,

Click the field selection check box for each field you want to appear in the view. When you click the box, a checkmark appears to show that the field has been selected.

Alternatively, you can tab to a field and press F5 to select it.

When you run the query, only those fields whose field selection check boxes are checked appear in the view. However, if no fields are selected in any of the tables in the skeleton, all fields are displayed.

To select all the fields in a table to display in the view,

Click the field selection check box beneath the table name at the left of the table skeleton.

Alternatively, you can press Ctrl+F5 to select all fields.

The check boxes for all fields in the table are checked.

When you run the query, all the fields in the table appear in the view.

To uncheck a field, click the check box again. To uncheck all fields, click the check box beneath the table name again.

To remove a field from the view,

Click the checked field selection check box for the field you want to remove from the view. The field does not appear in the view.


See Also

Running a Query to Display the Results


Running a Query to Display the Results

See Also

After you have specified the details of the query in the Query Designer, run the query to see the results.

You can run a query from the Navigator, the Catalog window, or the Query Designer.

To run a query from the Navigator or Catalog window,

1.	Click [image] All or [image] Queries from the file types list in the left pane of the window.

2.	Do one of the following:

Double-click the [image] <query name> icon for the query you want in the files list in the right pane of the window.

Right-click the [image] <query name> icon for the query you want, then choose Run Query from the SpeedMenu.

Click the [image] <query name> icon for the query you want. Then, do one of the following:

-	Choose Navigator|Run Query from the menu bar,

-	Press F2, or

-	Click [image] on the SpeedBar.

Drag the [image] <query name> icon for the query you want to the Command window.

The Query Results window appears:

To run a query from the Query Design view,

Choose View|Query Results, click [image] on the SpeedBar, or press F2.

The view of the query appears.

Depending on how you designed the query, you might be able to edit all the data in the view, or you might be prevented from editing some or all of the fields. See the User's Guide for more information.

Displaying the View in Different Layouts

When you run a query, you can display the query results in any of three layouts: Browse, Form, or Columnar. These are all different views of the same data.

Browse layout	Form layout	Columnar layout

These layouts are also available when you display a table for viewing and editing.

To select the different layouts, choose View|Query Results, then choose from these commands:

View|Browse Layout

View|Form Layout

View|Columnar Layout


See Also

Basics: About Design and Run Modes

Selecting Fields to Display in a View

Setting Filter Conditions in a Query - Overview


Working with Tables in the Query Designer


Adding a Table to a Query

See Also

To add a new table to a query, do one of the following:

Choose Query|Add Table... from the menu bar.

Click [image] on the SpeedBar.

Right-click anywhere in the Query Designer, then choose Add Table from the SpeedMenu.

The Open Table Required dialog box appears, where you can choose the table you want to add to the query. When you choose a table, its skeleton is added to the design surface.


See Also

Removing a Table from a Query


Removing a Table from a Query

See Also

To remove a table from a query,

1.	Click anywhere in the table to select it.

2.	Do one of the following:

Choose Query|Remove Selected Table from the menu bar.

Click [image] on the SpeedBar.

Right-click anywhere in the Query Designer, then choose Remove Selected Table from the SpeedMenu.

The table skeleton is removed from the design surface, and the table is removed from the query.


See Also

Query|Remove Selected Table


Working with Filters in a Query


Setting Filter Conditions in a Query - Overview

See Also

About Filter Conditions in a Query

In the Query Designer, you can set filter conditions that determine which records will be shown in the view of the data when you run the query.

A filter condition is an expression that is compared to a value or values in a record. When you run the query, the data in the filtered field or fields is evaluated for each record and compared to the expression(s) entered as the filter(s). If the comparison evaluates to true (and all other filter conditions for the record evaluate to true), the record is included in the view.

Example

In the following example, the filter condition in the YTD_SALES field is >500000. Therefore, every record whose YTD_SALES field contains a value greater than 500,000 is shown in the resulting view.

Unfiltered data in original table	Filter condition in Query Designer	View of filtered data


See Also

Filter Condition Syntax in the Query Designer

Setting Simple Filter Conditions in the Query Designer

Setting AND Conditions in the Query Designer

Setting OR Conditions in the Query Designer

Combining AND and OR Conditions in the Query Designer

Using the Conditions Box to Set Complex Filters


Filter Condition Syntax in the Query Designer

See Also

In the Query Designer, you enter filter conditions in the filter condition field beneath the name of a field or in the Conditions box.

A filter condition must have this syntax:

<comparison operator> <expression>

Comparison and Relational Operators Used in Queries

The following operators are allowed in filter condition fields and in filter condition boxes in the Query Designer.

> 	Greater than

< 	Less than

= 	Equal to

<> or # 	Not equal to

>= or => 	Greater than or equal to

<= or =<	Less than or equal to

$ 	Contains

Like 	Pattern match

Notes on Comparison and Relational Operators Used in Queries

The Equal to (=) operator is not required. If you enter an expression in the filter condition field and do not specify any operator, Equal to (=) is understood.

The meaning of the $ operator is different in a filter condition field than in the query Conditions box. In a filter condition field, $ means "contains." In the Conditions box, (and in the dBASE language), $ means "is contained in." For example, if you enter $ "Supplies" in a condition field for a field named COMP_NAME, the query's view will show all records where the COMP_NAME field contains the word "Supplies." To accomplish the same thing in the Conditions box, you have to enter "Supplies" $ COMP_NAME.

Use the Like operator with wildcard characters to search for a pattern of characters. The wildcard characters are:

*	Any number of characters, or none. For example, Like "G*" matches G or any string starting with G .

?	Any one character. For example, Like "J??n" matches John or Jean but not Jan.

For more information about relational operators, see Relational Operators in the Language Reference.

Expressions Used in Queries

You can use any valid dBASE expression that results in the same data type as the field to follow the comparison or relational operator in a filter condition. As with any expression, you must use the correct delimiters for the data type. (See below.)  See Expressions for more information about using expressions.

Notes on Data Types and Data Type Delimiters in Queries

Character

Enclose character data in double quotes (" "), single quotes (' '), or brackets ([ ]).

Numeric

Enter numeric values exactly as they are stored, including a decimal point, if there is one.

Date

Enclose dates in braces ({ }). To find all records with no date, enter {}. To find only those records with a valid date, enter <>{}.

Logical

For true, use .t., .T., .y., or .Y.

For false, use  .f., .F., .n., or .N.

Memo

Use the $ operator to search for all text contained in a memo field. For example, to find all records that contain the name Jackson in a memo field, enter $ "Jackson".


See Also

About dBASE Expressions

Setting AND Conditions in the Query Designer

Setting OR Conditions in the Query Designer

Combining AND and OR Conditions in the Query Designer

Setting Simple Filter Conditions in the Query Designer


Setting Simple Filter Conditions in the Query Designer

You can filter on a single field--including calculated fields--or on multiple fields.

To set a simple filter condition for a field,

1.	Click the space beneath the name of the field you want to filter. The filter condition field is available for input, for example:

2.	Type a filter condition for the field.

3.	Run the query to see the results.

When you run the query, only those records matching this condition (and any other conditions you set for other fields or combinations of fields) are displayed in the view.

For information on the syntax you must use for a filter condition, see Filter Condition Syntax in the Query Designer.


Setting an AND Conditions in the Query Designer
Setting AND Conditions in the Query Designer

See Also

Use the AND operator to specify that two conditions (or more with multiple ANDs) must be met for the entire condition to be met. For example, you might want to show all records where the state or province is New York AND the year-to-date sales are greater than $300,000.

You can specify an AND condition for one field, where two conditions must be met in the same field, or for more than one field, where one condition must be met in one field AND another condition must be met in another field.

You can specify both types of AND conditions in the Query Designer, as explained below.

To set an AND condition for one field,

1.	Click the space beneath the name of the field you want to filter. The filter condition field becomes available for input.

2.	Type the first filter condition for the field.

3.	Immediately following the first filter condition, type a comma (,).

4. Immediately following the comma, type the second filter condition for the field.

5.	Continue as above to specify more than two AND conditions.

6.	Run the query to see the results.

For example, to see all records in the Customer table where the first contact with a customer was between January 1,1992 and January 1,1993, type the following into the condition field for FIRST_CONT:

To set an AND condition using more than one field,

1.	Click the space beneath the name of the first field you want to use for the filter condition. The filter condition field becomes available for input.

2.	Type the filter condition for the field.

3.	Click the space beneath the name of the second field you want to use for the filter condition. This must be on the same line in the skeleton as the condition you specified for the first field.

4. Type the filter condition for the second field.

5.	Continue as above to specify more than two AND conditions.

6.	Run the query to see the results.

For example, to see all records in the Customer table where the customer lives outside California AND was contacted on or after 1/1/92 AND was contacted before 1/1/93, type the following conditions in the appropriate filter condition fields:


See Also

Combining AND and OR Conditions in the Query Designer

Setting OR Conditions in the Query Designer


Setting OR Conditions in the Query Designer

See Also

Use the OR operator to specify that either one condition OR another condition must be met for the entire condition to be met. For example, you might want to show all records where the state or province is New York OR California.

You can specify an OR condition for one field, where one condition OR another must be met for the field; or you can specify an OR condition using more than one field, where a condition for one field must be met OR a condition for another field must be met.

You can specify both types of OR conditions in the Query Designer, as explained below.

To set an OR condition for one field,

1.	Click the space beneath the name of the field you want to filter. The filter condition field becomes available for input.

2.	Type the first filter condition for the field.

3.	Press the Down arrow key ( [image]). A second line appears in the filter condition field.

4. Type the second filter condition for the field, that is, the OR condition.

5.	Continue as above to specify more than two OR conditions.

6.	Run the query to see the results.

For example, to see all records where the state or province is New York OR California, type the following into the condition field for STATE_PROV:

To set an OR condition using more than one field,

1.	Click the space beneath the name of the first field to use for the filter condition. The filter condition field becomes available for input.

2.	Type the first filter condition for the record.

3.	Click the space beneath the name of the second field to use for the filter condition.

4.	Press the Down arrow key ( [image]). A second line appears in the filter condition field.

5. Type the filter condition for the second field, that is, the OR condition.

6.	Continue as above to specify more than two OR conditions.

7.	Run the query to see the results.

For example, to see all records where the state or province is New York OR California OR the Customer number is less than 1500, type the following conditions in the appropriate condition boxes:


See Also

Combining AND and OR Conditions in the Query Designer

Setting AND Conditions in the Query Designer


Combining AND and OR Conditions in the Query Designer

See Also

When you combine AND and OR conditions in the filter condition fields, dBASE evaluates the conditions line-by-line, not field-by-field. That is, it evaluates all the conditions specified in the first line of condition fields first; then it evaluates all the conditions specified in the second line; then the third line, and so on.

The following diagram illustrates in what order the conditions are evaluated. For a record to be included in the view of this query, it would have to meet all the conditions specified in the first line of FIELDs 1 and 3, OR it would have to meet the condition specified in the second line of FIELD 2, OR it would have to meet all the conditions specified in the third line of FIELDS 1, 2, and 3.


See Also

Setting AND Conditions in the Query Designer

Setting OR Conditions in the Query Designer


Using the Conditions Box to Set Complex Filters

See Also

Use the Conditions box to set complex filters in the Query Designer. Use the Conditions box to:

Combine multiple conditions in a single expression

Filter data based on comparisons of field values

Filter on fields in two different tables

Filter on an expression rather than on a simple field value

To add a condition to a query,

1.	Choose Query|Add Conditions. The Conditions box appears.

2.	Type the filter condition(s) into the box. (See below for more information on how to enter the filter conditions.)

3.	Run the query to see the results.

Using Standard Expressions in the Conditions Box

You can use standard dBASE expressions in the Conditions box. These expressions must conform to standard dBASE syntax. This syntax differs from that required in the filter fields beneath the field names, where there are exceptions to how you can formulate filter conditions. For example,

In filter fields, the = (Equal to) operator is understood. When you type a filter condition expression in the Conditions box, you must type the name of the field you are filtering, type the = operator (or some other comparison or relational operator), then type the expression to be compared against the field value.

In filter fields, the $ operator means  "contains" instead of "is contained in." For example, $ "CA" in a filter field selects California records from the STATE_PROV field of the table, while the correct entry in the Conditions box is "CA" $ STATE_PROV.

You can use parentheses to indicate precedence in the Conditions box, which you cannot do in a filter field.

You can use .AND. and .OR. operators in an expression in the Conditions box. The .AND. and .OR. operators are not allowed in filter fields. (You can also use a comma to specify an AND condition, and you can use separate lines to specify an OR condition in the Conditions box, just as you can in filter fields. See below for more information.)

Using a Comma to Add an AND Condition in the Conditions Box

You can use the .AND. operator directly in an expression in the Conditions box. Or you can use a comma to specify an AND condition. To specify an AND condition using a comma,

1.	Type the first filter condition.

2.	Immediately following the first filter condition, type a comma (,).

3. Immediately following the comma, type the second filter condition.

4.	Continue as above to specify more than two AND conditions.

5.	Run the query to see the results.

Using Separate Lines to Add an OR Condition in the Conditions Box

You can use the .OR. operator directly in an expression in the Conditions box. Or you can use separate lines in the Conditions box to specify an OR condition. To specify an OR condition using separate lines,

1.	Type the first part of the condition on the first line of the Conditions box.

2.	Press the Down arrow key ( [image]). A second line appears in the Conditions box.

3. Type the second filter condition for the field, that is, the OR condition.

4.	Continue as above to specify more than two OR conditions.

5.	Run the query to see the results.


See Also

Basics: Introduction to the Expression Builder

About dBASE Expressions

Using the Expression Builder

Components of the Query Design Surface


Working with Calculated Fields in a Query

Create a calculated field to perform calculations on data in a table; then display the results in the new field. You can use a calculated field to perform a calculation on one or more fields. You can also set a filter condition based on the calculated field, just as you can set a filter condition based on any other field.

Create one or more calculated fields by adding the calculated field skeleton to the design surface and then specifying the details of the calculation(s) and any filter conditions for the field or fields.

See the following topics for more information:

Creating or Adding a Calculated Field in the Query Designer

Specifying Calculations for a Calculated Field

Displaying Results from a Calculated Field

Setting Filter Conditions in a Calculated Field


Creating or Adding Calculated Fields in a Query
Creating or Adding a Calculated Field to a Query

See Also

To create or add a calculated field,

Choose Query|Create Calculated Field.

If a calculated field has not been added to this query, the blank calculated field skeleton appears. If one or more calculated fields already exist for this query, a new field is added to the calculated field skeleton, to the right of the existing field(s).


See Also

Working with Calculated Fields in a Query

Specifying Calculations for a Calculated Field

Displaying Results from a Calculated Field

Setting Filter Conditions in a Calculated Field


Specifying Calculations for a Calculated Field

See Also

To specify the calculation for a calculated field,

1.	Click the space to the right of the equal sign in the calculated field skeleton. A blank entry field appears.

2.	Type a calculation in the entry field.

For example, to calculate the price of an item (from a SELL_PRICE field) plus four percent, enter this expression:

SELL_PRICE * 1.04

To calculate the number of days between a sale (field SALE_DATE) and its shipping date (field SHIP_DATE), enter this expression:

SHIP_DATE - SALE_DATE


See Also

Working with Calculated Fields in a Query

Creating or Adding a Calculated Field in the Query Designer

Displaying Results from a Calculated Field

Setting Filter Conditions in a Calculated Field


Displaying Results from a Calculated Field

See Also

To display the results from a calculated field,

If it is not already checked, check the field selection box next to the field in the skeleton.

When you run the query, the calculated field specified here appears on the right side of the Query Results window.

To display the results from all calculated fields in a query

Check the All fields selection box beneath the word CALCULATED on the left side of the calculated field skeleton.

When you run the query, all the calculated fields specified for this query appear on the right side of the Query Results window.


See Also

Working with Calculated Fields in a Query

Creating or Adding a Calculated Field in the Query Designer

Specifying Calculations for a Calculated Field

Setting Filter Conditions in a Calculated Field


Setting Filter Conditions in a Calculated Field

See Also

When you set a filter condition for a calculated field, it performs the same function as a filter condition set for a regular field: it is used to determine which records will be shown in the view of the data when you run the query.

To filter on a calculated field,

1.	Create the calculated field.

2.	Click the space beneath the calculation field in the calculated field skeleton. A filter condition field appears.

Use this filter condition field the same way you use a filter condition field for a regular field. For example, separate AND conditions by a comma. Press [image] to add a line where you can enter an OR condition. Click "See Also," directly under the title of this topic for a list of Help topics about setting filter conditions in a query.


See Also

Working with Calculated Fields in a Query

Creating or Adding a Calculated Field in the Query Designer

Specifying Calculations for a Calculated Field

Displaying Results from a Calculated Field

Setting Filter Conditions in a Query - Overview

Filter Condition Syntax in the Query Designer

Setting Simple Filter Conditions in the Query Designer

Setting AND Conditions in the Query Designer

Setting OR Conditions in the Query Designer

Combining AND and OR Conditions in the Query Designer


Ordering Data and Working with Indexes in a Query


Specifying Record Order in a Query

See Also

Use the order box to specify the direction in which records are ordered in a query. The Order box appears next to every field in a table skeleton, for example:

To order records on a field,

1.	Click the order box. A list of order arrows appears.

2.	Drag to select one of the arrows, to select one of the following orders:

 	Natural order

 	Ascending, case-sensitive

 	Descending, case-sensitive

 	Ascending, case-insensitive

 	Descending, case-insensitive

Notes on Order Options

Natural order

Displays records in the order in which they physically exist in the table, that is, in the order in which the records were added to the table. The default order for all fields is natural order, even if Ascending or Descending is specified for the index.

Ascending, case-sensitive

Displays records from lowest to highest: Punctuation comes before numbers, numbers before uppercase letters, and uppercase letters before lowercase letters (A...Z, then a...z).

Descending, case-sensitive

Displays records from highest to lowest: Punctuation comes before numbers, numbers before uppercase letters, and uppercase letters before lowercase letters (Z...A, then z...a).

Ascending, case-insensitive (character fields only)

Displays records from lowest to highest: Punctuation comes before numbers, numbers come before letters, and case is irrelevant for the letters (Aa, Bb, Cc...).

Descending, case-insensitive (character fields only)

Displays records from highest to lowest: Punctuation comes before numbers, numbers before letters, and case is irrelevant for the letters (Zz, Yy, Xx...).

About the Relationship between Indexes and Record Order

When a field in a table is a key field, the key icon appears next to the field name in the table skeleton:

.


See Also

Components of the Query Design Surface

Index Concepts


Basing Record Order on Two or More Fields in a Query

Record order is determined by the order in which fields appear in the view skeleton. Records are ordered first by any order specified for the leftmost field, then by any order specified for the next field to the right, and so forth.

How you specify the order can determine whether the view of the data will be read-only or not. See the User's Guide for more information.

To order records on two or more fields,

1. Drag the fields so that the fields are in the same relative order as you want to order the records. For example, if you want names in a table to be ordered first by state and then alphabetically within each state, drag the STATE field to a position left of the NAME field. See Changing the Order of Fields to Display in a View for instructions on dragging fields to change their position.

2.	For each field you want to use as the basis for the record order (for example, STATE and NAME in step 1, above), select the Order box for the field and choose the order option, as explained in Specifying Record Order in a Query.


Working with Multiple Tables and Relations in a Query


Setting Relations Between Tables in a Query
Setting a Relation Between Tables in a Query

See Also

To set a relation between two tables in the Query Designer, the tables must both be open and on the design surface.

To set a relation, do one of the following:

Choose Query|Set Relation, or click [image] on the SpeedBar. The Define Relation dialog box appears.

Click the [image] icon on the skeleton of the parent table and drag to the same icon on the child table skeleton . When you click the icon, a small icon appears next to the pointer and a linking line appears to indicate the link:

The pointer resumes its shape when you release the mouse button after having dragged the line to the child table. The Define or Modify Relation dialog box appears.

Once the link is established, tables are reordered as necessary to put them next to each other.


See Also

Adding a Table to a Query

Creating a New Query

Opening an Existing Query

Modifying a Relation Between Tables in a Query

Define or Modify Relation dialog box


Modifying a Relation Between Tables in a Query

See Also

You can modify the details of a relation after it is set. These are the same details you specify when you set a relation between tables.

To modify a relation between tables in a query, do one of the following:

Right-click anywhere other than the parent table skeleton, then choose Modify Relation from the SpeedMenu.

Note: The link arrow extends from the parent table skeleton and points to the child table's skeleton:

 Parent table

  Link arrow

     Child table

Click the child table's skeleton, then choose Query|Modify Relation.

In either case, the Define Relation dialog box appears, with details of the relation. Change the details in the dialog box and click OK.


See Also

Setting a Relation Between Tables in a Query

Define or Modify Relation dialog box

Removing a Relation Between Tables in a Query


Removing a Relation Between Tables in a Query

See Also

To remove a relation between tables in a query, do one of the following:

Right-click the skeleton of the child table you want to remove from the relation, then choose Remove Relation from the SpeedMenu.

Note: The link arrow extends from the parent table skeleton and points to the child table's skeleton:

 Parent table

  Link arrow

     Child table

Click the child table's skeleton, then choose Query|Remove Relation, or click [image] on the SpeedBar.

Both table skeletons remain on the design surface (and therefore are still included in the query), but the tables are no longer linked.


See Also

Setting a Relation Between Tables in a Query

Modifying a Relation Between Tables in a Query


Query Designer UI reference - Design Surface


Components of the Query Design Surface

See Also

The Query Designer consists of a design surface and several components for constructing a query. These components include those shown below.

Table/view skeletons

A skeleton is a visual representation of a table or tables plus several indicators that specify details of the query. A skeleton appears on the design surface for every table you add to the query.

Click the names or any of the parts of the following illustration for more information about each part:

Complex index field

If a complex index is defined for the table, the key expression of the index is used to define a complex index field, and that field appears on the far right side of the skeleton,

You can work with complex index fields the same way you work with other fields: move them to a new position in the skeleton, filter on them, use them to set the order of records, and so on.

Calculated field skeleton

Add a calculated field skeleton to specify a calculation that uses fields in the table or tables in the query. Click anywhere on the illustration below for a list of Help topics about using calculated fields in a query.

Conditions box

Add a Conditions box to specify a condition or conditions for filtering data in the query.

See this topic for more information:

Using the Conditions Box to Set Complex Filters

Specifying Record Order in a Query


Table name

Shows the name of the table represented by the skeleton.


Field list scroll arrows

Click these arrows to scroll the fields in the skeleton left or right. Use these arrows if the fields extend beyond the window on the right.


Sort box
Order box

Specifies if and how this field should be ordered in the view.

See these topics for more information:

Specifying Record Order in a Query

Basing Record Order on Two or More Fields in a Query


Field names

Shows the fields in the table whose name is on the left of the skeleton.

See these topics for more information:

Changing the Order of Fields to Display in a View

Selecting Fields to Display in a View


Set relation icon

Drag the pointer from this icon to the same icon on another table skeleton to set a relation between the tables.

See these topics for more information:

Setting a Relation Between Tables in a Query

Modifying a Relation Between Tables in a Query

Removing a Relation Between Tables in a Query

Define or Modify Relation dialog box


All fields selection check box

Click this box to include all the fields in the view resulting from this query. When this box is checked, the field selection check boxes for all fields are checked. Click the All fields selection check box again to uncheck the check boxes for all the fields. Then you can click them individually to reselect them. If no fields are checked, all fields are selected for the view.

After clicking this box to include all fields, you can click the field selection check box for any field to remove it from the view.

See these topics for more information:

Selecting Fields to Display in a View

Running a Query to Display the Results


Field selection check box

Click this box to include this field in the view resulting from this query. Click the box again to remove this field from the view.

See these topics for more information:

Selecting Fields to Display in a View

Running a Query to Display the Results


Key (indexed) field icon

Indicates that this field is indexed. In other words, an index tag based on this field exists in the active index file for this table.

Views that are ordered on indexed fields are faster than those ordered on non-indexed fields. Also, if you order a view on a non-indexed field, the view may be read only. See the User's Guide for more information on the role of indexes in a query.

See these topics for more information:

Specifying Record Order in a Query

Basing Record Order on Two or More Fields in a Query


Condition field

Specifies which records to include in the query, based on a condition that must be met for the current field.

See these topics for more information:

Filter Condition Syntax in the Query Designer

Setting Simple Filter Conditions in the Query Designer

Setting AND Conditions in the Query Designer

Setting OR Conditions in the Query Designer

Combining .AND. and .OR. Conditions in the Query Designer


Choose from these topics for more information about using calculated fields in a query:

Working with Calculated Fields in a Query

Creating or Adding a Calculated Field in the Query Designer

Specifying Calculations for a Calculated Field

Displaying Results from a Calculated Field

Setting Filter Conditions in a Calculated Field


See Also

Filtering Data in a Query

Combining .AND. and .OR. Conditions in the Query Designer

Creating a Calculated Field in a Query

Define or Modify Relation dialog box

Running a Query to Display the Results

Filter Condition Syntax in the Query Designer

Working with Multiple Tables and Relations in a Query

Modifying a Relation Between Tables in a Query

Removing a Relation Between Tables in a Query

Selecting Fields to Display in a View

Setting AND Conditions in the Query Designer

Setting OR Conditions in the Query Designer

Setting a Relation Between Tables in a Query

Setting Simple Filter Conditions in the Query Designer

Using the Conditions Box to Set Complex Filters


Query Designer UI reference - SpeedBar, Menus, and Dialogs


Query Designer SpeedBar

See Also

The SpeedBar is the row of buttons beneath the menu bar. Each button represents a menu command. Click the button representing the command you want to execute. The Query Designer view contains these buttons:

Button	Action	Menu Equivalent
	Creates a new dBASE-related file	File|New
	Opens a dBASE-related file	File|Open
	Saves current query to a file	File|Save
	Prints the .QBE file that defines the current query	File|Print
	Removes the selected text and places it on the Clipboard	Edit|Cut
	Copies the selected text onto the Clipboard	Edit|Copy
	Inserts text from the Clipboard to the current position in the current entry field	Edit|Paste
	From the Query Designer, displays the results of the query in the Query Results window	View|Query Results
	From the Query Results window, displays the Query Designer	View|Query Design
	Adds a table to the query  (inserts file skeleton of the table to the query design surface )	Query|Add Table...
	Removes a table from the query  (removes the file skeleton of the table from the query design surface)	Query|Remove Selected Table
	Displays the Define Relation dialog box so you can link (set a relation between) two tables	Query|Set Relation
	Removes the relation between the currently highlighted child table and its parent	Query|Remove Relation
	Switches to the Navigator window	Window|Navigator
	Switches to the Command window	Window|Command
	Opens the Form Expert	Help|Experts|Form Expert
	Opens the Interactive Tutors	Help|Interactive Tutors


See Also

Designing Queries


Query Designer Menus

See Also

The Query Designer has the following menus:

File Menu

Edit Menu

View Menu

Query Menu

Properties Menu

Window Menu

Help Menu


See Also

Designing Queries


Query Designer SpeedMenu

See Also

Use the Query Designer SpeedMenu to perform common operations in the Query Designer.

To use the SpeedMenu, right-click anywhere in the Query Designer.

Choose from the following commands:

Query Designer Properties...

Cut

Copy

Paste

Add Table...

Remove Selected Table

Modify Relation...

Remove Relation


See Also

Designing Queries


File Menu (Query Designer)

See Also

Use the File menu to create new files, open and run existing files, save files, print files, and exit dBASE for Windows.

The New and Open commands manipulate the primary file types, such as tables, queries, and forms. The New command displays a menu allowing you to choose the type of file you want to create. The Open command lets you run or design an existing file.

You can open as many files as you like, and each appears in its own window. However, the Navigator and Command windows are unique and cannot be opened more than once.

From the Query Designer, you can also save, close, or abandon your changes to the current record, print the current .QBE file, or set up the printer.

Choose from the following commands:

New

Open...

Save

Save As...

Save and Close

Abandon and Close

Close

Print...

Printer Setup...

Exit

(Closed file list)


See Also

Designing Queries


Edit Menu (Query Designer)

See Also

Use the Edit menu to perform editing operations and to copy or remove text. The Edit menu works differently in each of the windows. The most common use of the Edit menu is to work with text, for example, to move or delete it. For information about using the Edit menu in different windows, see Where the Edit Menu Works.

You can cut, copy, or paste text using the Clipboard. The Clipboard is a temporary storage area for information you want to move or copy from one location to another.

Choose from the following commands:

Undo/Redo

Cut

Copy

Paste

Delete

Select All


See Also

Designing Queries


View Menu (Query Designer)

See Also

Use the View menu in the Query Designer to run or design a query.

Choose from the following commands:

Query Results

Query Design


See Also

Designing Queries


View | Query Results

See Also

Runs the query; in other words, displays the results of the query in the Query Results window. When you choose this item, the organization and selection of data defined in the query is displayed in a "virtual" table called a view. This virtual table is removed from memory when the query is closed.

Shortcuts

Menu:	Navigator|Run Query (from selected query)
Catalog|Run Query (from selected query)

SpeedBar:
 (from selected query in Navigator or Catalog window)

SpeedMenu:	Run Query (from selected query in Navigator or Catalog window)

Keyboard:	F2 (from selected query in Navigator or Catalog window)

Mouse:	Double-click the query file in Navigator or Catalog window.
Drag the query file from Navigator or Catalog window into the Desktop or Command window.


See Also

View Menu (Query Designer)

View Menu (Table Records Window)

Running a Query to Display the Results


View | Query Design

See Also

Displays the Query Designer, where you can specify the details of the query.

Shortcuts

Menu:	Navigator|Design Query (from selected query)
Catalog|Design Query (from selected query)

SpeedBar:
 (from selected query in Navigator or Catalog window)

SpeedMenu:	Design Query (from selected query in Navigator or Catalog window)

Keyboard:	Shift+F2 (from selected query in Navigator or Catalog window)

Mouse:	Double-right-click the query file in the Navigator or Catalog window.


See Also

View Menu (Query Designer)

View Menu (Table Records Window)

Designing Queries


Query Menu (Query Designer)

See Also

Use the Query menu commands to design the details of a query.

Choose from the following commands:

Add Table...

Remove Selected Table

Copy Results to New Table...

Manage Indexes

Set Relation...

Modify Relation...

Remove Relation

Create Calculated Field

Delete Selected Calculated Field

Add Conditions

Remove Conditions


See Also

Designing Queries


Query | Add Table...

See Also

Adds a table to the query in the Query Designer. This command displays the Open Table Required dialog box where you can choose a table.

Shortcuts

SpeedBar:

SpeedMenu:	Add Table...

Keyboard:	Ctrl+A


See Also

Query Menu (Query Designer)

Query|Remove Table

Adding a Table to a Query

Removing a Table from a Query


Query | Remove Selected Table

See Also

Removes the current table from the query.

Click the skeleton of the table you want to remove, then choose this command to remove the table from the query.

Shortcuts

SpeedBar:

SpeedMenu:	Remove Selected Table


See Also

Query Menu (Query Designer)

Query|Add Table

Adding a Table to a Query

Removing a Table from a Query


Query | Manage Indexes...

See Also	Language

Specifies an index tag to use as the master index. You can also create, modify, or delete index tags.

This command opens the Manage Indexes dialog box.


See Also

Query Menu (Query Designer)

Table|Table Utilities|Reindex


Language

INDEX

SET INDEX


Query | Set Relation...

See Also

Sets a relation between two tables. This command displays the Define Relation dialog box where you can set options for the relation.

Shortcuts

SpeedBar:

Mouse: 	Click the link icon [image] of the parent table's skeleton and drag the pointer to the link icon of child table's skeleton.


See Also

Query Menu (Query Designer)

Query|Modify Relation

Query|Remove Relation

Define or Modify Relation dialog box

Setting a Relation Between Tables in a Query

Modifying a Relation Between Tables in a Query

Removing a Relation Between Tables in a Query


Query | Modify Relation

See Also

Changes specified options in a previously set relation. This command displays the Define Relation dialog box where you can change the previously set options. You must select a child table before you can choose this command.

Shortcuts

SpeedMenu: 	Modify Relation... (A child table skeleton. must be selected)


See Also

Query Menu (Query Designer)

Query|Set Relation

Query|Remove Relation

Define or Modify Relation dialog box

Setting a Relation Between Tables in a Query

Modifying a Relation Between Tables in a Query

Removing a Relation Between Tables in a Query


Define or Modify Link dialog box
Define or Modify Relation dialog box

See Also	Language

Use this dialog box to specify the details of a relation set between two tables. This dialog box is displayed when you first set a relation between two tables or when you modify the details of an existing relation.

Dialog Box Options

Parent Table

Specifies the parent table in the relation.

The way you display this dialog box determines what is placed by default in the Parent Table field:

If you set a new relation by dragging from the Define Relation icon in one table skeleton to another, this field contains the name of the table whose skeleton you are dragging from.

If you are modifying an existing relation, this field contains the name of the parent of the current table. The current table is the one whose skeleton has focus.

Change the parent table by clicking the arrow next to the name and choosing a new name from the drop-down list. This list contains the names of all the tables in the query. (The list is available only if a table is available to be used as the parent.) You cannot select the current table to be a parent to itself. That is, you cannot link a table to itself.

Field

Lists the names of the fields in the table listed in the Parent Table field. Click a field name from this list to use it as the linking field for the relation, or more precisely, the master expression on which the relation is linked. When you click the field name, the name appears in the Master Expression field.

You can also select an index tag from the Index field to be used as the Master Expression.

Note: When you display this dialog box to set a relation, dBASE for Windows attempts to suggest a field that can be used as the linking field. See the explanation for the Master Expression field, below.

Master Expression

Specifies the expression used to link the two tables.

When you set a relation and this dialog box appears, the Master Expression field might contain a suggested value. If the child table is indexed and if the parent and child table has a key field name or a key expression in common, this field name (or expression) appears in the Master Expression field as the suggested linking expression.

When you click a field in the Field list (described above), that field is placed in the Master Expression field. You can also type an expression directly into the Master Expression field.

Every Parent

Check this box to specify that every record in the parent table will appear in the view, whether or not it matches any records in the child table. If this box is unchecked, only records in the parent table that match a record in the child table will appear in the view.

One to Many

Check this box to specify that all records in a child table that match the parent in a linked field will appear in the view. If this box is unchecked, only the first matching record from the child will appear.

When this box is checked, the view of the child table is restricted to include only records for the currently selected parent. If you create a form and add a Browse control for the child table, and if One to Many is checked, then the Browse control in the form will display only those records in the child table that match the current record in the Parent table.

Enforce Integrity

This option determines what happens if you initiate an action that will interfere with parent-child relations (for dBASE tables only). When this box is checked, the following occurs:

If you try to delete a parent record when there are still child records for the parent, you are prompted to cancel the deletion or to cascade it, that is, to delete the parent and all its child records.

If you add a child record, the child record is automatically given the key value of the current parent record, and this value is read-only. This ensures that you cannot create a child record that is not linked to a parent record.

Child Table

Specifies the child table for the relation.

If you set a new relation by dragging from the Define Relation icon in one table skeleton to another, this field contains the name of the table whose skeleton you are dragging to.

If you are modifying an existing relation, this field contains the name of the current child table.

Change the child table by clicking the arrow next to the name and choosing a new name from the drop-down list. This list contains the names of all the tables in the query. (The list is available only if a table is available to be used as a child.) You cannot select the current table to be a child to itself. That is, you cannot link a table to itself.

Index

Lists the index tags in the index file for the child table. To set a relation, the child table must be indexed on the linking key field or key expression. Therefore, this box lists the index tags only, and not all the field names (whereas the Field list, described above, includes all the fields in the parent table).

Click one of these tags to use it as the master expression upon which the tables are linked.

Add Index button

Click this button to display the Create Index dialog box, where you can create or add an index tag for the child table.


See Also

Query|Set Relation

Query|Remove Relation

Setting a Relation Between Tables in a Query

Modifying a Relation Between Tables in a Query

Removing a Relation Between Tables in a Query


Language

SET FILTER

SET RELATION


Query | Remove Relation

See Also

Removes the relation set into the current child table.

Shortcuts

SpeedBar:

SpeedMenu:	Remove Relation


See Also

Query Menu (Query Designer)

Query|Set Relation

Query|Modify Relation

Define or Modify Relation dialog box

Setting a Relation Between Tables in a Query

Modifying a Relation Between Tables in a Query

Removing a Relation Between Tables in a Query

Index Concepts


Query | Create Calculated Field

See Also

Adds a calculated field skeleton to the design surface for the current query, or adds a new calculated field to the skeleton if it is already on the design surface.


See Also

Query Menu (Query Designer)

Query|Delete Selected Calculated Field

Working with Calculated Fields in a Query

Creating or Adding a Calculated Field in the Query Designer

Specifying Calculations for a Calculated Field

Displaying Results from a Calculated Field

Setting Filter Conditions in a Calculated Field


Query | Delete Selected Calculated Field

See Also

Deletes the current calculated field from the calculated field skeleton, or removes the skeleton if it contains only one field.


See Also

Query Menu (Query Designer)

Query|Create Calculated Field

Working with Calculated Fields in a Query

Creating or Adding a Calculated Field in the Query Designer

Specifying Calculations for a Calculated Field

Displaying Results from a Calculated Field

Setting Filter Conditions in a Calculated Field


Query | Add Conditions

See Also

Adds a filter condition that is applied to the query as a whole.

This command adds a Conditions box to the query, where you can enter an expression that specifies the filter condition.

Only those records that satisfy the condition appear in the view defined by the query.

This condition can address more than one field, unlike the conditions you place in filter condition fields for particular fields.

You must use full dBASE expressions in the Conditions box.


See Also

Query Menu (Query Designer)

Query|Remove Conditions

Setting Filter Conditions in a Query - Overview

Filter Condition Syntax in the Query Designer

Setting Simple Filter Conditions in the Query Designer

Setting AND Conditions in the Query Designer

Setting OR Conditions in the Query Designer

Combining AND and OR Conditions in the Query Designer

Using the Conditions Box to Set Complex Filters


Query | Remove Conditions

See Also

Removes the current condition field from the Conditions box. If there is only one condition field in the box, removes the Conditions box from the design surface.


See Also

Query Menu (Query Designer)

Query|Add Conditions

Setting Filter Conditions in a Query - Overview

Filter Condition Syntax in the Query Designer

Setting Simple Filter Conditions in the Query Designer

Setting AND Conditions in the Query Designer

Setting OR Conditions in the Query Designer

Combining AND and OR Conditions in the Query Designer

Using the Conditions Box to Set Complex Filters


Query | Copy Results to New Table

See Also

Copies the results of the query to a new table. When you choose this command, a new .DBF file is created. The new file is a single new table that is structured and organized according to the current query definition. In other words, the view defined by the table is saved as a new table. This table is not indexed. If you make changes to this new table, those changes are not reflected in the original table(s) on which you based the query.


See Also

Query Menu (Query Designer)

Saving a Query

Copying Query Results to a New Table


Properties Menu (Query Designer)

See Also

The following Properties menu commands are available in the Query Designer:

Desktop...

Query Designer...


See Also

Designing Queries


Properties | Query Designer...

Displays the Query Designer Properties Inspector, where you set whether or not complex indexes will be shown as fields in the view skeleton.

dBASE records the choices you make in this dialog box in the DBASEWIN.INI file.

Shortcuts

SpeedMenu:	Query Designer Properties... (in Query Designer)

Dialog Box Options

Display Complex Indexes

Check the check box to indicate that complex key expressions will appear as fields in the Query Designer table skeleton(s). Uncheck this box to indicate that the fields will not appear.


 Running Queries

See Also

When you run a query, the results of the query (called a view) are displayed in the Query Results window. In many ways, the Query Results window looks and behaves like the Table Records window. For example, you can rearrange columns, perform calculations, navigate through records, and display the data in Browse, Form, and Columnar layouts:

Browse layout	Form layout	Columnar layout

However, data in a view (in the Query Results window), differs from data in the Table Records window in these ways:

Data in a view might be read-only, depending on the details of the query. For example, if you base a query on a non-dBASE table, or if you order records on two fields that are not indexed, the view will be read-only. For more information, see the User's Guide.

The Query Results window displays a view of data that resides in another table or other tables. When you edit the data in a view, the edits are written back to the original table(s). Data is not stored in a view (although you can save the view as a new table).

For information on working with data in the Query Results window, see the appropriate Help topics for the Table Records window.


See Also

Views and Tools

Table Records Window Components

Displaying and Editing Table Records

About Queries

Designing Queries


Working with Images

About Images

Editing Images

Displaying Images


About Images

See Also	Language

Images are graphics or pictures. In dBASE for Windows, you can work with images stored in files and tables. dBASE displays the image in the Image Viewer window.

Images in Files

The Navigator lists the available Windows bitmap (.BMP) or PC Paintbrush format bit image (.PCX) files when you choose the Images file type. You can view or edit the image file.

Images in Tables

You can store image data in a table in fields that support nontext data. In dBASE for Windows, if you want to retrieve and view the image from the table, you must do the following:

Store only Windows bitmap (.BMP) or PC Paintbrush format bit image (.PCX) files.

Use the dBASE binary or Paradox graphic field type.

In dBASE tables, image data can be stored in the following field types:

Binary. You can view images stored in binary fields in the Image Viewer. You cannot edit images stored in binary fields. You can insert image data into an empty binary field by using the language or by opening the Table Records window and then choosing View|Field Contents.

OLE. You can view and edit images stored in OLE fields using the OLE Viewer. See Displaying and Editing OLE Documents for information about inserting data into OLE fields.

Memo. You cannot view or edit images stored in memo fields. You must use the language to insert image data into an empty memo field. Unless you want to maintain compatibility with dBASE IV tables, avoid using memo fields to store binary data. Use either binary or OLE fields to store image data.

In Paradox tables, image data can be stored in the following field types:

Graphic. You can view images stored in graphic fields in the Image Viewer. You cannot edit images stored in graphic fields. In dBASE for Windows, you can insert image data into an empty graphic field by using the dBASE language or by opening the Table Records window and then choosing View|Field Contents.

Binary. You cannot view or edit images stored in Paradox binary fields. In dBASE for Windows, you must use the dBASE language to insert image data into an empty binary field.

OLE. You can view and edit images stored in OLE fields in the OLE Viewer. See Displaying and Editing OLE Documents for information about inserting data into OLE fields.

Memo. You cannot view or edit images stored in memo fields. In dBASE for Windows, you must use the dBASE language to insert image data into an empty memo field.

In SQL tables, image data can be stored in various field types supported by the database server. You cannot view images stored in an SQL table. In dBASE for Windows, you must use the dBASE language to insert image data into the field.


See Also

Editing Images

Displaying Images

Displaying and Editing OLE Documents

Opening and Closing the Table Records Window


Language

REPLACE

REPLACE BINARY

REPLACE MEMO

REPLACE OLE


Editing Images

See Also	Language

Images are graphics or pictures. In dBASE for Windows, you can edit images stored in files.

In the Navigator, you can select an image file to edit. The Navigator lists the available Windows bitmap (.BMP) or PC Paintbrush format bit image (.PCX) files when you choose the Images file type.

An image stored in a table can be edited directly only if it is stored in an OLE field. See About Images and Displaying and Editing OLE Documents for information.

You can edit an image in a table indirectly by copying the image to a file, editing the file, then inserting the image file back into the binary field.

You can remove an image from a table by selecting the record and choosing Table|Blank Selected Record. This removes the data from all fields in the record.

To edit an image stored in a file, do one of the following:

Choose File|Open, change the File Type to "Bitmap (*.BMP)" or "PC Paintbrush TM (*.PCX)," choose the image file you want to edit, click Design Image, then click OK.

Double-right-click the image file from the Navigator.

Right-click the image file in the Navigator, then choose Design Image.

Select the image file in the Navigator, then choose Navigator|Design Image or press Shift+F2.

Select the image file in the Navigator, then click [image].

dBASE for Windows opens Windows Paintbrush and displays the image. Edit the image using the Paintbrush tools. When you are done, choose File|Save and File|Exit to return to dBASE for Windows. See your Windows documentation for information on using Paintbrush to edit images.

To create a new image, choose the Images file type in the Navigator, then do one of the following:

Double-click the Untitled file.

Right-click the Untitled file, then choose New Image.

Select the Untitled file, then choose Navigator|New Image or press Shift+F2.

Select the Untitled file, then click [image].


See Also

About Images

Displaying Images

Displaying and Editing OLE Documents


Language

COPY BINARY

REPLACE BINARY

RUN( )


Displaying Images

See Also

Images are graphics or pictures. In dBASE for Windows, you can display images stored in files, tables, and dynamic link libraries. The image appears in the Image Viewer window. You use the Image Viewer window to store and view images in tables.

Shortcuts

Menu:	Navigator|Display Image (from selected image)

SpeedBar:	 (from selected image in Navigator window)

SpeedMenu:	Display Image (from selected image in Navigator window)

Keyboard:	F2 (from selected image in Navigator window)

Mouse:	Double-click the image file in Navigator window.
Drag the image file from Navigator window into the Desktop or Command window.

Image Viewer Concepts and Tasks

Choose from the following list for information about using the Image Viewer:

Image Viewer Tasks

Working with Binary Data

When to Use Binary and OLE Fields

Image Viewer Tools

The Image Viewer has menus and a SpeedBar associated with it. Choose from the following list for more information about these topics:

Components	Description of the Image Viewer window

Menus	Lists and descriptions of all Image Viewer menu commands

SpeedBar	Descriptions of the Image Viewer SpeedBar options


See Also

About Images

Editing Images


Working with Binary Data

See Also

In dBASE for Windows, you can store any type of binary data in tables. dBASE, Paradox, and SQL tables have several field types for binary data:

In dBASE tables, you can store binary data in binary, OLE, and memo fields. Use either the binary or OLE field types if you want to store an image or sound that you can retrieve and view or play.

In Paradox tables, you can store binary data in graphic, binary, OLE, and memo fields. Use the graphic or OLE field types if you want to store an image that you can retrieve and view. Use the OLE field type if you want to store a sound that you can retrieve and play.

In SQL tables, you can store binary data in various field types supported by the database server. You cannot view or edit images stored in an SQL table.

Like memo fields, binary field data is stored in the memo file (.DBT for dBASE tables, .MB for Paradox tables) associated with the table.

When you create a binary or graphic field in the table, it is a good idea to store the same type of data in each record. For example, if you create a table with a field called TripPict, all the TripPict fields in the table should store an image. However, dBASE for Windows does not prevent you from storing different types of binary data in different records.

You can have one or more fields in your table that can store binary data. See Table Designer Components for information on field types.

When you edit the records in the table, you select the field containing the binary data, and the Image Viewer displays the image, or the Sound Player window appears and you can play the sound. Using the Form Designer, you can also assign a custom event to a binary field based on the type of data stored in it. See Form Designer Tasks for information.

dBASE binary fields store three types of binary data:

Images: .BMP and .PCX files

Sounds: .WAV files

User-defined: any other file type

Images and Sounds are predefined binary data types. When you add the binary data, dBASE automatically detects the file type of an image or sound file and stores the data type in the field along with the data. When you add any type of binary data other than an image or sound, dBASE stores the data and type as user-defined data.

Paradox graphic fields store Images (.BMP and .PCX files).


See Also

Opening the Image Viewer

Opening the Sound Player

When to Use Binary and OLE Fields

Changing Data in a Single Record

Displaying and Editing OLE Documents


When to Use Binary and OLE Fields

See Also

Because binary and OLE fields can store similar types of data, consider the strengths of each field type when you design your table.

Binary fields contain data stored in a binary format, such as bitmap image or sound data. You can store any type of data in a binary field.

OLE fields contain documents inserted in the table from other Windows applications that support Object Linking and Embedding (OLE). You can either link the document by reference or embed the document in the field.

Advantages of Binary Fields

You can store any type of binary data. The data does not have to be connected with an external Windows application.

The storage space required for a binary field is smaller than an embedded OLE document.

Inserting data into a binary field is faster than inserting data into OLE fields.

You can assign a custom binary data type using the language when you add data to a binary field.

Advantages of OLE Fields

Storing a link to an OLE document requires less disk space than embedding the document or inserting the data in a binary field.

You can edit the data once it is embedded or linked by opening the external application in which it was created.

You can store linked data and have it automatically updated when the data changes in the original file.


See Also

Field Type

Edit|Links


Image Viewer Tasks

See Also

Choose from the following list for more information about how to use the Image Viewer:

Opening the Image Viewer

Copying an Image to a Binary or Graphic Field

Adding an Image to a Form


See Also

Sound Player Tasks


Opening the Image Viewer

See Also	Language

To open the Image Viewer, do one of the following:

Double-click the image file from the Navigator.

Right-click the image file in the Navigator, then choose Display Image.

Select the image file in the Navigator, then choose Navigator|Display Image or press F2.

Select the image file in the Navigator, then click [image].

Drag the image file from the Navigator window to the Command window.

Open a table in the Table Records window with a dBASE binary or Paradox graphic field containing an image, select the field, then do one of the following:

Press F9.

Double-click the field.

Choose View|Field Contents.


See Also

Image Viewer Tasks

Copying an Image to a Binary or Graphic Field

Adding an Image to a Form

Opening and Closing the Table Records Window


Language

RESTORE IMAGE


Copying an Image to a Binary or Graphic Field

See Also	Language

To copy an image into a dBASE binary or Paradox graphic field,

1.	Open a table containing a binary or graphic field in the Table Records window. CUSTOMER.DBF in the SAMPLES directory contains a binary field.

2.	Double-click the binary or graphic field. If the field is empty, the Empty Binary Field dialog box appears. Choose Image Viewer and click OK. The Image Viewer appears.

3.	Choose File|Insert from File.

4.	Specify the name and location of the image (.BMP or .PCX) to store in the field.


See Also

Image Viewer Tasks

Opening and Closing the Table Records Window

Opening the Image Viewer

Adding an Image to a Form


Language

REPLACE BINARY


Adding an Image to a Form

See Also

To add an image to a form,

1.	Open the Form Designer with either an existing form or a new form.

2.	If it is not already checked, choose View|Controls to open the Control Palette.

3.	Select the image control from the palette.

4.	Click and drag on the Form Designer grid to create an outline box.

5.	Right-click inside the outline box. If it is not already checked, choose Object Properties from the SpeedMenu.

6.	On the Properties page of the Object Inspector, select the Data Source property, then click [image] to open the Choose Bitmap dialog box.

7.	Specify how the bitmap is stored using the Location list box, then specify the actual source in the Bitmap text box. Choose OK. The image appears on the form.

To add a browse control containing an image to a form,

1.	Open the Form Designer with either an existing form or a new form.

2.	If it is not already checked, choose View|Controls to open the Control Palette.

3.	Select the browse control from the palette.

4.	Click and drag on the Form Designer grid to create an outline box.

5.	Right-click inside the outline box. If it is not already checked, choose Object Properties from the SpeedMenu.

6.	On the Properties page of the Object Inspector, select the Data Linkage Properties. Set the Alias to the table. Set the Fields to the fields you want to view, including the binary field.

Note:	Data Linkage Properties does not appear in the Object Inspector if Object Properties Outline is unchecked in the Desktop Properties dialog box.


See Also

Image Viewer Tasks

Opening the Image Viewer

Copying an Image to a Binary or Graphic Field

Control Palette

Designing Forms


Image Viewer Components

See Also

The Image Viewer window displays a graphic image from a file or field.

The Image Viewer opens to the default size of the image. If you resize the window, the image size remains the same.

You can open the Image Viewer from four views in dBASE for Windows:

The Navigator window

The Table Records window

The Form window if it contains an entry field or browse control containing a binary field

The Command window or a custom window if it contains an entry field control containing a binary field

If you are editing a dBASE table with a binary field, you can identify the contents of the field by its icon.

	Empty Image Sound User-defined
If you are editing a Paradox table with a graphic field, you see the empty or image icon.

When you display an image from a table, the Image Viewer displays the contents of the binary or graphic field in the current record. If you move to another record, the window refreshes to display the data for that record.


See Also

About Images

Working with Binary Data

Opening the Image Viewer

Opening and Closing the Table Records Window

Using Forms


Image Viewer Menus

See Also

The Image Viewer has the following menus:

File Menu

Properties Menu

Window Menu

Help Menu


See Also

Sound Player Menus


Image Viewer SpeedBar

See Also

The SpeedBar is the row of buttons beneath the menu bar. Each button represents a menu command. Click the button representing the command you want to execute.

Button	Action	Menu Equivalent
	Creates a new dBASE-related file	File|New
	Opens a dBASE-related file	File|Open
	Prints the information in the active window	File|Print
	Switches to the Navigator window	Window|Navigator
	Switches to the Command window	Window|Command
	Opens the Form Expert	Help|Experts|Form Expert
	Opens the Interactive Tutors	Help|Interactive Tutors


See Also

Sound Player SpeedBar


File Menu (Image Viewer)

Use the File menu to create new files, open existing files, insert files, print data, close files and windows, and exit dBASE for Windows.

The New and Open commands manipulate the primary file types, such as tables, queries, and forms. The New command displays a menu allowing you to choose the type of file you want to create. The Open command lets you run or design an existing file.

You can open as many files as you like, and each appears in its own window. However, the Navigator and Command windows are unique and cannot be opened more than once.

Choose from the following commands:

New

Open...

Insert from File...

Close

Print...

Printer Setup...

Exit

(closed file list)


File | Insert from File...

See Also	Language

Inserts an image into a dBASE binary or Paradox graphic field, or a sound into a dBASE binary field.

This command is available from two windows: Sound Player and Image Viewer.

If the current window is the Image Viewer, this command displays the Choose Image dialog box. Choose an image file with file extension .BMP or .PCX.

If the current window is the Sound Player window, this command displays the Choose Sound dialog box. Choose a sound file with file extension .WAV.

If you choose a file with a file extension other than .WAV, .BMP, or .PCX, the field will store the data as user-defined data, but you will not be able to play or display it.

For general information about choosing files, see Open File dialog box.


See Also

File Menu (Image Viewer)

File Menu (Sound Player)

About Images

About Sounds

Copying an Image to a Binary or Graphic Field

Empty Binary Field Dialog Box


Language

REPLACE BINARY


Empty Binary Field Dialog Box

See Also	Language

Specifies the type of data to be stored in a dBASE binary field.

Choose Image Viewer or Sound Player, then choose OK. The Image Viewer or Sound Player window appears. Choose File|Insert from File to insert an image or sound into the binary field.

Dialog Box Options

Image Viewer

Specifies that the binary field will contain an image. dBASE for Windows supports images with the file extension .BMP or .PCX.

Sound Player

Specifies that the binary field will contain a sound. dBASE for Windows supports sounds with the file extension .WAV.

Note:	To store data types other than .BMP, .PCX, or .WAV, you must use the language.


See Also

View|Field Contents

Copying an Image to a Binary or Graphic Field

Data Types


Language

REPLACE BINARY


Properties Menu (Image Viewer)

Use the Properties menu to change the characteristics of the dBASE for Windows Desktop.

Desktop...


File Menu (Sound Player)

Use the File menu to create new files, open and run existing files, close files, and exit dBASE for Windows.

The New and Open commands manipulate the primary file types, such as tables, queries, and forms. The New command displays a menu allowing you to choose the type of file you want to create. The Open command lets you run or design an existing file.

You can open as many files as you like, and each appears in its own window. However, the Navigator and Command windows are unique and cannot be opened more than once.

Choose from the following commands:

New

Open...

Insert from File...

Close

Exit

(closed file list)


Properties Menu (Sound Player)

Use the Properties menu to change the characteristics of the dBASE for Windows Desktop.

Desktop...


Working with Sounds

About Sounds

Editing Sounds

Playing Sounds


About Sounds

See Also	Language

In dBASE for Windows, you can work with sounds stored in files and tables. dBASE plays sounds directly from files and opens a Sound Player window to play sounds from tables. In forms, you have the option to play sounds directly or open the Sound Player window.

Sounds in Files

The Navigator lists the available Windows sound (.WAV) files when you choose the Sounds file type. You can play or edit the sound file.

Sounds in Tables

You can store sound data in a table in fields that support nontext data. In dBASE for Windows, if you want to retrieve and play the sound from the table, you must do the following:

Store only Windows sound (.WAV) files.

Use the dBASE binary, or the dBASE or Paradox OLE field type.

In dBASE tables, sound data can be stored in the following field types:

Binary. You can play sounds stored in binary fields in the Sound Player. You cannot edit sounds stored in binary fields. You can insert sound data into an empty binary field by using the language or by opening the Table Records window and then choosing View|Field Contents.

OLE. You can play and edit sounds stored in OLE fields in the OLE Viewer. See Displaying and Editing OLE Documents for information about inserting data into OLE fields.

Memo. You cannot play or edit sounds stored in memo fields. You must use the language to insert sound data into an empty memo field. Unless you want to maintain compatibility with dBASE IV tables, avoid using memo fields to store binary data. Use either binary or OLE fields to store sound data.

In Paradox tables, sound data can be stored in the following field types:

Graphic. You cannot play or edit sounds stored in Paradox graphic fields. In dBASE for Windows, you must use the dBASE language to insert sound data into an empty graphic field.

Binary. You cannot play or edit sounds stored in Paradox binary fields. In dBASE for Windows, you must use the dBASE language to insert sound data into an empty binary field.

OLE. You can play and edit sounds stored in OLE fields using the OLE Viewer. See Displaying and Editing OLE Documents for information about inserting data into OLE fields.

Memo. You cannot play or edit sounds stored in Paradox memo fields. In dBASE for Windows, you must use the dBASE language to insert sound data into an empty memo field.

In SQL tables, sound data can be stored in various field types supported by the database server. You cannot play sounds stored in an SQL table. In dBASE for Windows, you must use the dBASE language to insert sound data into the field.


See Also

Editing Sounds

Playing Sounds

Displaying and Editing OLE Documents

Displaying and Editing Table Records

Opening and Closing the Table Records Window


Language

REPLACE

REPLACE BINARY

REPLACE MEMO

REPLACE OLE


Editing Sounds

See Also	Language

In dBASE for Windows, you can edit sounds stored in files.

In the Navigator, you can select a sound file to edit. The Navigator lists the available Windows sound (.WAV) files when you choose the Sounds file type.

A sound stored in a table can be edited directly only if it is stored in an OLE field. See About Sounds and Displaying and Editing OLE Documents for information.

You can edit a sound in a table indirectly by copying the sound to a file, editing the file, then inserting the sound file back into the binary field.

You can remove a sound from a table by selecting the record and choosing Table|Blank Selected Record. This removes the data from all fields in the record.

To edit a sound stored in a file, do one of the following:

Choose File|Open, change the File Type to "Sound (*.WAV)," choose the sound file you want to edit, click Design Sound, then click OK.

Double-right-click the sound file from the Navigator.

Right-click the sound file in the Navigator, then choose Design Sound.

Select the sound file in the Navigator, then choose Navigator|Design Sound or press Shift+F2.

Select the sound file in the Navigator, then click [image].

dBASE for Windows opens the Windows Sound Recorder and displays the sound wave. Edit the sound using Sound Recorder commands. When you are done, choose File|Save and File|Exit to return to dBASE for Windows. See your Windows documentation for information on using Sound Record to edit sounds.

To create a new sound file, choose the Sounds file type in the Navigator, then do one of the following:

Double-click the Untitled file.

Right-click the Untitled file, then choose New Sound.

Select the Untitled file, then choose Navigator|New Sound or press Shift+F2.

Select the Untitled file, then click [image].


See Also

About Sounds

Playing Sounds

Displaying and Editing OLE Documents


Language

COPY BINARY

REPLACE BINARY


Playing Sounds

See Also

In dBASE for Windows, you can play sounds stored in files and tables. To play a sound, your computer must have a sound driver or a sound adapter board. If the sound is stored in a file, you play it directly. If the sound is stored in a table, you play it from the Sound Player window. You use the Sound Player window to store and play sounds in tables.

Shortcuts

Menu:	Navigator|Play Sound (from selected sound)

SpeedBar:	 (from selected sound in Navigator window)

SpeedMenu:	Play Sound (from selected sound in Navigator window)

Keyboard:	F2 (from selected sound in Navigator window)

Mouse:	Double-click the sound file in Navigator window.
Drag the sound file from Navigator window into the Desktop or Command window.

Sound Concepts and Tasks

Choose from the following list for information about using the Sound Player:

Sound Player Tasks

Playing Sounds from Files

Working with Binary Data

When to Use Binary and OLE Fields

Sound Player Tools

The Sound Player has menus and a SpeedBar associated with it. Choose from the following list for more information about these topics:

Components	Description of the Sound Player window

Menus	Lists and descriptions of all Sound Player menu commands

SpeedBar	Descriptions of the Sound Player SpeedBar options


See Also

About Sounds

Editing Sounds

Opening the Sound Player


Sound Player Tasks

See Also

Choose from the following list for more information about how to use the Sound Player:

Opening the Sound Player

Copying a Sound to a Binary Field

Adding a Sound to a Form


See Also

Image Viewer Tasks


Opening the Sound Player

See Also	Language

To open the Sound Player, do one of the following:

Open a table in the Table Records window with a dBASE binary field containing a sound, select the field, then do one of the following:

Press F9.

Double-click the field.

Choose View|Field Contents.

When the Sound Player window appears, choose Play.


See Also

Sound Player Tasks

Copying a Sound to a Binary Field

Opening and Closing the Table Records Window

Playing Sounds from Files


Language

PLAY SOUND


Copying a Sound to a Binary Field

See Also	Language

To copy a sound into a binary field,

1.	Open a table containing a binary field in the Table Records window. PICTURES.DBF in the SAMPLES directory contains a binary field.

2.	Double-click the binary field. If the field is empty, the Empty Binary Field dialog box appears. Choose Sound Player and click OK. The Sound Player window appears.

3.	Choose File|Insert from File.

5.	Specify the name and location of the sound (.WAV) to store in the field.


See Also

Sound Player Tasks

Opening and Closing the Table Records Window

Opening the Sound Player

Adding a Sound to a Form


Language

REPLACE BINARY


Adding a Sound to a Form

See Also

To add a browse control containing a sound to a form,

1.	Open the Form Designer with either an existing form or a new form.

2.	If it is not already checked, choose View|Controls to open the Control Palette.

3.	Select the browse control from the palette.

4.	Click and drag on the Form Designer grid to create an outline box.

5.	Right-click inside the outline box. If it is not already checked, choose Object Properties from the SpeedMenu.

6.	On the Properties page of the Object Inspector, select the Data Linkage Properties. Set the Alias to the table. Set the Fields to the fields you want to view, including the binary field.

Note:	Data Linkage Properties does not appear in the Object Inspector if Object Properties Outline is unchecked in the Desktop Properties dialog box.


See Also

Sound Player Tasks

Opening the Sound Player

Copying a Sound to a Binary Field

Control Palette

Designing Forms


Playing Sounds from Files

See Also	Language

To play a sound from a file, do one of the following:

Double-click the sound file from the Navigator.

Right-click the sound file in the Navigator, then choose Play Sound.

Select the sound file in the Navigator, then choose Navigator|Play Sound or press F2.

Select the sound file in the Navigator, then click [image].

Drag the sound file from the Navigator window to the Command window.


See Also

About Sounds

Playing Sounds

Opening the Sound Player


Language

PLAY SOUND


Sound Player Components

See Also

The Sound Player window appears if you open a binary field containing sound data in a dBASE table.

The Sound Player window provides two options for sounds:

Play begins playing the sound for the current record. If you move to another record and click Play again, the sound for that record plays.

Stop stops playing the sound. If you have a sound adapter board, you can click this to stop playing the sound. If you have only a sound driver, you cannot stop playing the sound.

You can open the Sound Player from three views in dBASE for Windows:

The Table Records window

The Form window if it contains an entry field or browse control containing a binary field

The Command window or a custom window if it contains an entry field control containing a binary field

In the Table Records window, if you are editing a dBASE table with a binary field, you can identify the contents of the field by its icon.

	Empty Image Sound User-defined


See Also

About Sounds

Working with Binary Data

Opening the Sound Player

Opening and Closing the Table Records Window

Using Forms


Sound Player Menus

See Also

The Sound Player has the following menus:

File Menu

Properties Menu

Window Menu

Help Menu


See Also

Image Viewer Menus


Sound Player SpeedBar

See Also

The SpeedBar is the row of buttons beneath the menu bar. Each button represents a menu command. Click the button representing the command you want to execute.

Button	Action	Menu Equivalent
	Creates a new dBASE-related file	File|New
	Opens a dBASE-related file	File|Open
	Switches to the Navigator window	Window|Navigator
	Switches to the Command window	Window|Command
	Opens the Form Expert	Help|Experts|Form Expert
	Opens the Interactive Tutors	Help|Interactive Tutors


See Also

Image Viewer SpeedBar


Working with Reports and Labels

About Reports and Labels

Designing Reports and Labels

Using Reports and Labels


About Reports and Labels

See Also	Language

dBASE for Windows includes Crystal Reports for dBASE, a full-featured Report and Label Designer. Use the Designer to create reports and labels based on tables or queries.

Crystal Reports is integrated into the dBASE environment. When you create or modify a report or label design, dBASE automatically launches Crystal Reports. You can run existing Crystal reports and labels from within Crystal Reports or from within dBASE. When you run reports or labels from within dBASE, they appear in the Report and Label Viewer, a window that previews the report or labels.

You can also run reports and labels created in dBASE III PLUS or dBASE IV from the Navigator or the Catalog window, or by using a command in the Command window. To modify dBASE III PLUS or dBASE IV reports or labels, first convert them to Crystal Reports format using the Component Builder, then modify them using Crystal Reports. See the Component Builder Help for more information about the Component Builder.


See Also

Designing Reports and Labels

Using Reports and Labels

Report and Label File Types

Component Builder Overview


Language

CREATE LABEL

CREATE REPORT

LABEL FORM

REPORT FORM


Report and Label File Types

See Also

dBASE for Windows supports the following report and label file types:

.RPL	A label file created in Crystal Reports.

.RPT	A report file created in Crystal Reports.

.RPC	A cross-tab report file created in Crystal Reports.

.FRG	A report source code file created in dBASE IV. You can run .FRG files and edit the source code. However, to modify the design visually, you need to convert it to Crystal Reports format using the Component Builder.

.FRM	A report file created in dBASE III PLUS. To modify an .FRM file, convert it to Crystal Reports format using the Component Builder.

.LBG	A label source code file created in dBASE IV. You can run .LBG files and edit the source code. However, to modify the design visually, you need to convert it to Crystal Reports format using the Component Builder.

.LBL	A label file created by dBASE III PLUS. To modify an .LBL file, convert it to Crystal Reports format using the Component Builder.

Note:	dBASE IV .FRG and .LBG files are source code files generated by the dBASE IV Report and Label Designers, respectively. Each .FRG file has a corresponding .FRM file; each .LBG file has a corresponding .LBL file. The .FRM and .LBL files are intermediate binary files used by the dBASE IV Designers.

dBASE for Windows does not run dBASE IV .FRM or .LBL files. Run the corresponding .FRG or .LBG file instead.

See the Component Builder help for more information about the Component Builder.


See Also

Component Builder Overview


Designing Reports and Labels

See Also

Design reports and labels using Crystal Reports for dBASE. You can create a new report or label design, or modify an existing one. See Using Crystal Reports for dBASE or the Crystal Reports online Help for information on using Crystal Reports.

1.	Open the table or query on which the design is based. If you do not open a table or query, the Open Table Required dialog box prompts you to enter one when you start Crystal Reports.

2.	Start Crystal Reports in one of the following ways:

From the menu,

Choose File|New|Report to create a new report.

Choose File|New|Cross-Tab to create a new cross-tab report.

Choose File|New|Labels to create a new label.

From the Navigator or Catalog window, select a report or label file, then do one of the following:

Click [image].

Choose Design Report or Design Labels from the SpeedMenu.

Choose Navigator|Design Report or Labels, or Catalog|Design Report or Labels.

Press Shift+F2.

Double-right-click the report or label file.


See Also

Using Reports and Labels

About Reports and Labels


Using Reports and Labels

See Also

You can run a report directly from the Navigator, the Catalog window, or by using the File|Open command. You can also run it from within Crystal Reports.

Report and Label Tasks

Choose from the following list for more information about using reports and labels:

Running Reports and Labels

Running dBASE IV and dBASE III PLUS Reports and Labels

Report and Label Viewer Tools

The Report and Label Viewer has menus and a SpeedBar associated with it. Choose from the following list for more information about these topics:

Components	Description of the Report and Label Viewer

Menus	Lists and descriptions of all Report and Label Viewer menu bar commands

SpeedBar	Descriptions of the Report and Label Viewer SpeedBar options


See Also

About Reports and Labels

Report and Label File Types

Designing Reports and Labels


Running Reports and Labels

To run a report or label, do one of the following:

Choose File|Open and select a report or label file.

Double-click the report or label file in the Navigator or Catalog window, or drag it into the Desktop or Command window.

Right-click the report or label file in the Navigator or Catalog window, then choose Run Report or Run Labels from the SpeedMenu.

Select the report or label file in the Navigator or Catalog window, then choose Navigator|Run Report (or Labels) or Catalog|Run Report (or Labels).

Select the report or label file in the Navigator or Catalog window, then click [image].

Select the report or label file in the Navigator or Catalog window, then press F2.


Running dBASE IV and dBASE III PLUS Reports and Labels

See Also

dBASE for Windows can run dBASE III PLUS and dBASE IV report and label files. Screen output appears in the results pane of the Command window. See Report and Label File Types for information on supported file extensions.

To run a dBASE IV or dBASE III PLUS report or label,

1.	Open the table or query on which the design is based. If you do not open a table or query, the Open Table Required dialog box prompts you to enter one when you run the report.

2.	Select the report or label file in the Navigator or Catalog window.

3.	Do one of the following to run the report or label file:

Click [image].

Choose Run Report or Run Labels from the SpeedMenu.

Press F2.

Double-click the report or label file, or drag it into the Desktop or Command window.

Choose Navigator|Run Report or Labels or Catalog|Run Report or Labels.

To print a dBASE IV or dBASE III PLUS report or label,

Type the REPORT FORM or LABEL FORM command in the Command window using the TO PRINT option.

The following example prints the Employee report from the dBASE IV SAMPLES directory:

* Open the EMPLOYEE table

USE EMPLOYEE

* Send output to printer

REPORT FORM EMPLOYEE TO PRINT

* Send output to file

REPORT FORM EMPLOYEE TO FILE TEMP.TXT


See Also

Report and Label File Types

Modifying dBASE IV and dBASE III PLUS Reports and Labels


Modifying dBASE IV and dBASE III PLUS Reports and Labels

See Also

To modify a dBASE IV or dBASE III PLUS report or label, first use the Component Builder to convert it to Crystal Reports format. Then modify the file with Crystal Reports.

See the Component Builder Help for more information about the Component Builder.


See Also

Report and Label File Types

Running dBASE IV and dBASE III PLUS Reports and Labels

Designing Reports and Labels

Component Builder Overview


Report and Label Viewer Components

The Report and Label Viewer is a window in which reports and labels appear. The Viewer lets you preview the report or labels exactly as they will appear when printed.

You can view the report or labels, using the scroll bars or SpeedBar buttons to navigate, but you cannot make changes. To change the appearance of the report, return to Crystal Reports and modify the design. To change the data, make changes to the tables on which the report or labels are based.

To print the report or labels, do one of the following:

Choose File|Print.

Click [image].


Reports and Labels Menus

When you run reports and labels from within dBASE for Windows (not from within Crystal Reports), the following menus are available:

File Menu

View Menu

Report or Label Menu

Properties Menu

Window Menu

Help Menu


Reports and Labels SpeedBar

When you run reports and labels from within dBASE for Windows (not from within Crystal Reports), the SpeedBar contains the buttons shown below.

Each button corresponds to a menu item. Click any button or menu item in the following list for more information about the menu item.

Button	Action	Menu Equivalent
	Creates a new dBASE-related file	File|New
	Opens a dBASE-related file	File|Open
	Prints the current report or label as it appears onscreen	File|Print
	Displays the first page of the report or labels	Report or Label|Top Page
	Displays the previous page of the report or labels	Report or Label|Previous Page
	Displays the next page of the report or labels	Report or Label|Next Page
	Displays the last page of the report or labels	Report or Label|Bottom Page
	Switches to the Command window	Window|Command
	Opens the Form Expert	Help|Experts|Form Expert
	Opens the Interactive Tutors	Help|Interactive Tutors


File Menu (Reports and Labels)

Use the File menu to create new files, open and run existing files, print files, and close the report or labels.

Choose from the following commands:

New

Open...

Close

Print

Printer Setup

Exit

(Closed file list)


View Menu (Reports and Labels)

Use the View menu to reduce or enlarge the report or labels on your monitor. These commands do not affect the printed size of reports or labels.

Choose from the following commands:

Reduced

Normal

Enlarged


View | Reduced

See Also

Displays the current report or label at a reduced size. This command does not affect printed output.


See Also

View Menu (Reports and Labels)

View|Normal

View|Enlarged


View | Normal

See Also

Displays the current report or label at normal size. This command does not affect printed output.


See Also

View Menu (Reports and Labels)

View|Reduced

View|Enlarged


View | Enlarged

See Also

Displays the current report or label at an enlarged size. This command does not affect printed output.


See Also

View Menu (Reports and Labels)

View|Reduced

View|Normal


Report or Label Menu (Reports and Labels)

Use the Report menu or Label menu to navigate through the pages of the report or labels.

Choose from the following commands:

Previous Page

Next Page

Top Page

Bottom Page


Report or Label | Previous Page

See Also

Displays the previous page of the current report or label.

Shortcuts

SpeedBar:

Keyboard:	PgUp


See Also

Report or Label Menu

Report or Label|Next Page

Report or Label|Top Page

Report or Label|Bottom Page


Report or Label | Next Page

See Also

Displays the next page of the current report or label.

Shortcuts

SpeedBar:

Keyboard:	PgDn


See Also

Report or Label Menu

Report or Label|Previous Page

Report or Label|Top Page

Report or Label|Bottom Page


Report or Label | Top Page

See Also

Displays the first page of the current report or label.

Shortcuts

SpeedBar:

Keyboard:	Ctrl+PgUp


See Also

Report or Label Menu

Report or Label|Previous Page

Report or Label|Next Page

Report or Label|Bottom Page


Report or Label | Bottom Page

See Also

Displays the last page of the current report or label.

Shortcuts

SpeedBar:

Keyboard:	Ctrl+PgDn


See Also

Report or Label Menu

Report or Label|Previous Page

Report or Label|Next Page

Report or Label|Top Page


Properties Menu (Reports and Labels)

Use the Properties menu to change the characteristics of the dBASE for Windows Desktop.

Choose the following command:

Desktop...


Working with Tables

About Tables

Designing Table Structures

Displaying and Editing Table Records


About Tables

See Also

In dBASE for Windows, a database is a collection of one or more tables, plus related files, such as indexes and memo files. Each table is a distinct file with a .DBF extension. dBASE IV and dBASE III PLUS called files with a .DBF extension databases.

A table consists of one or more records and fields. A record contains information about a specific entry in the table, such as a person or invoice. A field is a category of information that describes the kinds of entries a table contains, such as a person's name or an invoice date. A field type describes the type of data stored in the field, such as character fields for the name of a person or a date field for the invoice date.

The goal of a well-planned table is to store all the information you need in an accessible, efficient manner using the structure of the table described in the previous paragraph. Before you actually start creating tables, some general guidelines and concepts are recommended.

Choose from the following list for information about tables and table concepts:

Table Design Guidelines

Using Multiple Tables

Using SQL Tables

Basics: About Design and Run Modes

Table Indexes

An important table design feature is indexing. Indexes process information quickly by arranging records in a table according to a particular order. Indexes are stored in a separate file that is automatically created when you define the first index for a table. With multiple tables, indexes are necessary to link related tables together.

Choose from the following list for information about indexes and index concepts:

About Indexes and Sorting

Index Tips for Users of Earlier Versions of dBASE

Setting Record Order

Index Concepts

Key Expressions

Rules for Complex Indexes

Using dBASE Functions in Key Expressions

Duplicate Values

Paradox Indexes


See Also

Designing Table Structures

Displaying and Editing Table Records

Views and Tools


Table Design Guidelines

See Also

Design tables to make it easy for users to enter, process, and extract information. Here are some table design guidelines that will help create well-designed tables:

Identify the information you want to store. Write down all the information you need without organizing it yet.

Start organizing the information by including only the relevant data. Do not store unnecessary data as it wastes disk space and distracts users from the task at hand.

Once you identify the information you need, classify the information into distinct entities (such as persons, places, and things), and activities (such as transactions and events). In general, each table should contain only one kind of entity or activity.

Organize the classified information into a table for each category. For example, the Customers table would include name, address, city, state, phone number, credit standing, notes, and so on. The Orders table would include the order date, order number, sales date, amount paid, terms, and so on.


See Also

Designing Table Structures

Working with Multiuser Tables


Using Multiple Tables

See Also

It is often better to create several small tables and link them together rather than try to store everything in one large table. Storing data in one large table often leads to storing redundant information. For example, if you store the customer information with each order, you would have to enter the customer name and address with every order.

Use multiple tables to minimize the amount of data that appears more than once. By storing the name and address information once in a customer table, you have only one location to update if that information changes. When a customer places an order, the order information goes in a separate table that is linked to the name and address table.

About Parent and Child Tables

When you relate two tables, you establish one as the parent table and the other as the child table. As you select a record in the parent table, you see the corresponding child record or records.

Parent and child tables are linked on a common field, called the linking field. The linking field in the child table must have an index. You can link tables using the Query Designer. See Setting a Relation Between Tables in a Query for more information.


See Also

Basics: About Sessions

Aliases

Setting a Relation Between Tables in a Query

Using the Query Designer - Overview


Using SQL Tables

See Also

dBASE for Windows supports creating and using SQL tables. You need the Borland SQL Link product to access SQL tables. SQL databases are listed in the Aliases section of the IDAPI Configuration Utility, as are local databases.

For information on SQL databases, local databases, and accessing SQL tables, see Navigator Components.


See Also

Designing Table Structures

Displaying and Editing Table Records


Indexing and Sorting
About Indexes and Sorting

See Also

Indexing and sorting are two approaches for arranging table data in meaningful ways. You use them to answer different needs in an application.

Indexing orders records in a specific sequence, usually in ascending or descending order on one or more fields. Indexing creates a list of records in the current table arranged in a logical order, such as by date or by name, and stores this list in a separate file called an index file. An index (.MDX) file can have up to 47 indexes, but only one controls the order of records at any time. The index that is controlling the order is the current master index.

Sorting creates an entirely separate copy of the current table with the records in a different order. Use sorting only when you want to create a separate table with a different natural order.


See Also

Creating a Complex Index

Creating a Simple Index in the Manage Indexes Dialog Box

Creating a Simple Index in the Table Designer

Index Tips for Users of Earlier Versions of dBASE

Reindexing

Setting Record Order

Sorting Data


Index Tips for Users of Earlier Versions of dBASE

See Also	Language

If you have used earlier versions of dBASE, such as dBASE IV or dBASE III PLUS, you will find some new features and differences with dBASE indexing.

Multiple index files. dBASE for Windows stores indexes in multiple (.MDX) index files, and recognizes .MDX files created in earlier dBASE versions. You can design and maintain multiple indexes using the Manage Indexes dialog box, which provides most of the capabilities available under the Data menu in the dBASE IV Control Center.

Individual index files. .NDX files contain a single index. For compatibility with earlier dBASE versions, dBASE for Windows can use .NDX files, but you must open them with dBASE commands, either through the Command window or in a program. Indexes in .NDX files should be upgraded to .MDX files, which can be done using the Command window. See COPY INDEXES for information.


See Also

About Indexes and Sorting

Command Window

Index Concepts

Manage Indexes Dialog Box

Table|Table Utilities|Manage Indexes...


Language

COPY INDEXES

INDEX


Setting Record Order

See Also

You can organize records in two different ways:

Natural order is the physical sequence of records in a table, the order in which they were entered. A record number identifies the physical position of a record in a table. In natural order, records appear sequentially by record number: the top record is record number one, the next record is record number two, and so on. Natural order is sometimes called data entry order or physical order.

Indexed, or logical, order is a logical sequence of records in a table, independent of their physical position. In indexed order, the records are organized numerically or alphabetically, in ascending or descending order. An index orders records according to the data contained in one or more fields. The index keeps track of where the record belongs in logical order in addition to where it physically appears in the table. The logical order is independent of the natural order of records in the table.


See Also

About Indexes and Sorting


Index Concepts

See Also

Before you create indexes, you need to become familiar with a few general concepts:

Multiple index files (.MDX). When you create an index, it is stored in a file with the file-name extension .MDX. Each index has a name (called a tag) that defines the index uniquely in the .MDX file.

The main .MDX file for a table is called the production index file. The production index file opens automatically when you open a table, so its indexes are automatically available, though no index sets the record order until you select it as the master index. As you update records in a table, the affected indexes in the production index file are also updated. If you use any non-production .MDX files, they must be opened explicitly by entering commands in the Command window.

The production index file has the same name as the table plus the .MDX extension. For example, the Orders table has a production index file called ORDERS.MDX.

Key expressions. A key expression is a field name, or a combination of field names, functions, or operators, that determines how an index orders records in a table. It must be a character, numeric, date, or float field, or an expression that evaluates to one of these types. You can use the Expression Builder to help create a valid key expression. The key expression can be up to 220 characters in length. The total length of the key (the length of the evaluated key expression) can be up to 100 characters, although most keys are much shorter (and more efficient).

Simple indexes. A simple index uses a single field name for the key expression.

Complex indexes. A complex index uses a combination of one or more fields, or an expression that includes dBASE functions and operators.

Ascending and descending order. Records can be ordered in ascending order (the default), A to Z or 1 to 100 (lowest to highest), or descending order, Z to A or 100 to 1 (highest to lowest). For character fields, the order is ASCII or the order established by the language driver installed by the IDAPI Configuration Utility. See IDAPICFG.HLP for information.

Note:	Keeping a large number of indexes affects performance, since dBASE must update each one as the table is revised. If you need to improve performance, consider removing rarely used indexes from the production index file.


See Also

About Indexes and Sorting

Command Window

Creating a Complex Index

Creating a Simple Index in the Manage Indexes Dialog Box

Creating a Simple Index in the Table Designer

Key Expressions

Setting Record Order


Key Expressions

See Also

A key expression is a field name, or a combination of field names, functions, or operators, that determines how an index orders records in a table. It must be a character, numeric, date, or float field, or an expression that evaluates to one of these types.

The following table shows several examples of key expressions and the fields used:

Key Expressions	Fields Used

CUSTOMER_N	CUSTOMER_N

CUSTOMER_N+ORDER_NO	CUSTOMER_N, ORDER_NO

CUSTOMER_N+DTOS(SALE_DATE)	CUSTOMER_N, SALE_DATE

UPPER(LAST_NAME)+UPPER(FIRST_NAME)	LAST_NAME, FIRST_NAME

Note:	DTOS( ) converts date fields to character for indexing; UPPER( ) changes character fields to all caps.

The first example is a single field as the key expression. Complex indexes, on the other hand, can use a combination of one or more fields, plus dBASE functions and operators.

CUSTOMER_N+ORDER_NO is a complex key expression using multiple fields and the dBASE concatenation operator (+).

CUSTOMER_N+DTOS(SALE_DATE) is a complex key expression consisting of multiple field names and a dBASE function.

UPPER(LAST_NAME)+UPPER(FIRST_NAME) converts characters to all caps before concatenating them. The UPPER function prevents sorting problems when capitalized entries are mixed in with lowercase letters.

You can either type the expression or use the Expression Builder to create it.


See Also

Index Concepts

Creating a Complex Index

Creating a Simple Index in the Manage Indexes Dialog Box

Creating a Simple Index in the Table Designer

Rules for Complex Indexes

Using dBASE Functions in Key Expressions


Rules for Complex Indexes

See Also	Language

For complex indexes, the complexity of the key expression varies according to the way the index is used. The following rules apply when defining complex indexes:

An index value can be up to 100 characters long. The text of the key expression can be up to 220 characters long.

The complex index must be a valid dBASE expression - it must be syntactically correct according to the rules for expressions. Note that a single field name is a valid dBASE expression.

The expression must evaluate to a character, date, numeric, or float value.

It usually, but not always, contains at least one field name.

For multiple character fields, you concatenate, or combine, fields using the plus sign (+), as shown in the following examples:

LAST_NAME + FIRST_NAME + M_INITIAL
CUSTOMER + ORDER_NO

You can concatenate fields of different data types by converting them to a single type. In the following example, the key expression concatenates the CUSTOMER_N field, which is a character field, and ORDER_DATE, which is a date field. The DTOS( ) function converts the date value to a character string in the format YYYYMMDD:

CUSTOMER_N + DTOS(ORDER_DATE)

For converting number fields, use the STR( ) function. Include the width and number of decimal places of the numeric field(s), to ensure accuracy of the index.

CUSTOMER_N + STR(YTD_SALES,12,2)


See Also

Creating a Complex Index

Key Expressions

Using dBASE Functions in Key Expressions


Language

DTOS( )

STR( )


Using dBASE Functions in Key Expressions

See Also	Language

The index expression can include dBASE functions (including user-defined functions) to reformat data.

For character fields, especially name fields, consider converting all letters to uppercase or lowercase to ensure a consistent order and increase your chances of finding a match when searching for a record. The following sample key expressions create an index key of all uppercase letters:

UPPER(LAST_NAME)
UPPER(LAST_NAME)+UPPER(FIRST_NAME)+UPPER(M_INITIAL)

For character fields, especially long fields, consider indexing on a portion of the field rather than the entire field. This produces a more efficient index. Use only as much of the field length as you need to ensure unique values. The following sample key expression creates an index on the first ten characters (a substring) of the LAST_NAME and FIRST_NAME fields, plus the middle initial.

SUBSTR(LAST_NAME,1,10)+SUBSTR(FIRST_NAME,1,10)+M_INITIAL

Do not use dBASE functions, such as TRIM( ) that would make the index key an inconsistent length.

For numeric and float fields, consider indexing on a portion of the value rather than the entire value of the field. This reduces the size of the index and makes it more efficient. Use only as much of the field length as you need to ensure unique values or to obtain the degree of precision you want. The following sample key expression removes the fractional portion of a currency amount:

INT(AMT_PAID)

For date fields, which are usually entered in MM/DD/YY format, you can convert the values to a chronological format that produces a meaningful order (such as YYYYMMDD). The following sample key expression converts a date to a character expression in the format YYYYMMDD:

DTOS(ORDER_DATE)

For logical fields, use a dBASE expression that results in a valid index data type - character, date, numeric, or float. The following sample key expression tests a logical value (EXEMPT). However, instead of returning the logical (T/F) value, it returns a result that is a character type, either "E" or an empty string.

IIF(EXEMPT,"E","")

Note:	Using functions in the expression does not affect the field values in the table - only the order in which records appear in the index.


See Also

Creating a Complex Index

Key Expressions

Rules for Complex Indexes


Language

DTOS( )

IIF( )

INT( )

LOWER( )

SUBSTR( )

UPPER( )


Duplicate Values

See Also

dBASE for Windows uses the term unique to refer to hiding duplicate values. This usage differs from the concept of creating unique indexes in Paradox and SQL tables. In dBASE indexes, records can have duplicate values in the indexed field. In Paradox primary indexes, records cannot have duplicate values. In SQL indexes, uniqueness is required if the index is defined as a unique index.

If you check Unique in the Create Index dialog box, only the first record with a duplicate value in the indexed field is included in the index. Any subsequent records with duplicate values in that field are excluded.


See Also

Create Index dialog box

Manage Indexes Dialog Box

Paradox Indexes

Table|Table Utilities|Manage Indexes...


Paradox Indexes

See Also

Each Paradox table can have a primary index and secondary indexes, which are stored separately from the table.

Primary Indexes

A primary index is the main index in a table. It consists of one or more consecutive fields, starting with the first field in the table. Although not required, each Paradox table should have one primary index. The primary index is stored in a file with a .PX extension.

Secondary Indexes

A secondary index is supplemental to the primary index in a table. A Paradox table can have two types of secondary indexes:

Maintained secondary indexes are automatically maintained when data changes in the table, and are similar to dBASE indexes in the production .MDX file.

Non-maintained secondary indexes are not automatically updated when the table is open, and are similar to .NDX files in earlier versions of dBASE. You can create maintained, but not non-maintained, secondary indexes in dBASE.

Simple and Composite Indexes

Like dBASE indexes, Paradox index keys can contain multiple fields in the table. In dBASE, these are called complex indexes. In Paradox, they are called composite indexes. However, unlike complex indexes in dBASE, you cannot use dBASE functions or operators in the Paradox index expression.

Unique Keys

Unlike dBASE indexes, Paradox primary indexes require unique key values - they do not permit duplicate values. For example, if a Paradox table has a primary index on ORDER_NO, you cannot add two orders with the same order number - only one can exist in the table. In a Paradox composite index, individual field values can be duplicates, but the combined value of all key fields must be unique. (Secondary indexes do permit duplicate values.)

When you create the primary index, use a field that will contain a unique value for each record, such as the customer number field in the Customer table.

A table can have only one blank (empty) value in the keyed field, because subsequent blank keys are considered duplicates. Therefore, key fields usually require entries.

Field Types for Key Fields

Paradox has different field types than dBASE. You can use the following field types in Paradox keys and indexes: alphanumeric, number, currency, date, and short.

Record Order

dBASE supports ascending and descending record order, but Paradox permits ascending order only. You cannot create a descending index on a Paradox table.


See Also

Creating a Primary Paradox Index in the Manage Indexes Dialog Box

Creating a Primary Paradox Index in the Table Designer

Creating Secondary Paradox Indexes

Index Concepts

Manage Indexes Dialog Box

Setting Record Order

Table|Table Utilities|Manage Indexes


Displaying and Editing Table Records

See Also

In dBASE for Windows, you view, add, and edit records in a table using the Table Records window. The Table Records window is sometimes referred to as the Browse window or the Query Results window. You can create the structure of a table in the Table Structure window, or Table Designer.

Table Records Window Concepts and Tasks

Choose from the following topics for information about the Table Records window:

Table Records Window Tasks

Working with Multiuser Tables

Paradox Tables

Keystrokes in the Table Records Window

Table Records Window Tools

The Table Records window has menus, a SpeedBar, and a SpeedMenu. Choose from the following list for more information about these topics:

Components	Description of the Table Records window

Menus	Lists and descriptions of all Table Records window menu commands

SpeedBar	Descriptions of the Table Records window SpeedBar options

SpeedMenu	List and descriptions of the Table Records window SpeedMenu


See Also

About Tables

Designing Table Structures


Table Records Window Tasks

See Also

Choose from the following list for information about how to use the Table Records window:

Basic Table Records Window Operations

Opening and Closing the Table Records Window

Working with Records in Tables

Navigating Through Records in a Table

Finding Records in a Table

Adding Records to a Table

Deleting Records from a Table

Selecting Records to Process

Working with Data in Records

Changing Data in a Single Record

Saving or Abandoning Changes

Replacing Data in Records

Calculating Data

Export and Import File Types

Exporting Data

Importing Data

Managing Indexes

Creating a Simple Index in the Table Designer

Creating a Simple Index in the Manage Indexes Dialog Box

Creating a Complex Index

Selecting a Master Index

Deleting an Index

Reindexing

Sorting Data

Creating a Primary Paradox Index in the Table Designer

Creating a Primary Paradox Index in the Manage Indexes Dialog Box

Creating Secondary Paradox Indexes


See Also

Table Designer Tasks


Opening and Closing the Table Records Window

See Also

Open a table when you want to see or change the information it contains. When you open a dBASE table, the associated production index (.MDX) file and memo (.DBT) file, if any, are automatically opened.

If you attempt an operation that requires an open table and no table is open, the Open Table Required dialog box appears so you can select one.

To open the Table Records window, do any of the following:

Double-click a table in the Navigator or Catalog window.

Select a table in the Navigator or Catalog window, then choose Navigator|Edit Records or Catalog|Edit Records, or press F2.

Right-click a table in the Navigator or Catalog window. From the SpeedMenu that appears, choose either Edit Records or Add Records, or press F2.

From the Table Designer or Query Designer, choose View|Table Records, or click [image] on the SpeedBar, or press F2.

To open a table exclusively,

1.	Choose Properties|Desktop.

2.	Click the Table tab.

3.	Check Exclusive, and click OK.

4.	Open the Table Records window.

To close the Table Records window, do one of the following:

Choose File|Close or press Ctrl+F4.

Choose File|Save Record and Close or press Ctrl+W.

Choose File|Abandon Record and Close or press Ctrl+Q.

Double-click the Control-menu box.


See Also

Table Records Window Tasks

Navigator Tasks

Catalog Window Components

Query Designer Tasks


Navigating Through Records in a Table

See Also

You can use one of the following methods to navigate the records in a table:

Move To	Menu	Keyboard	SpeedBar
Previous record	Table|Previous Record	Up arrow (Browse), PgUp (Form/Columnar)
Next record	Table|Next Record	Down arrow (Browse), PgDn (Form/Columnar)
Previous page	Table|Previous Page	PgUp (Browse)
Next page	Table|Next Page	PgDn (Browse)
Top record	Table|Top Record	Ctrl+PgUp
Last record	Table|Bottom Record	Ctrl+PgDn
Find record	Table|Find Records	Ctrl+F


See Also

Displaying and Editing Table Records

Table Records Window Components

Table Records Window Tasks


Finding Records in a Table

See Also

You can find a record in a table by searching the contents of a field for some specified text or value. You can search character, numeric, float, date, logical, and memo fields.

To search for a value in a field,

1.	Choose Table|Find Records. The Find Records dialog box appears.

2.	Specify the value in the Find What box.

3.	Select the field in the Located in Field list.

4.	Click the Find button.


See Also

Table Records Window Tasks

Table|Find Records


Adding Records to a Table

See Also

Adding records to a table is called appending records. New records are appended to the end of a table. If the table has an open index, new blank records appear at the end of the table until you finish adding the data. dBASE for Windows then updates the index and displays the record in its correct position.

To append a record while using the Table Records window, do any of the following:

Choose Table|Add Records.

Press Ctrl+A.

Go to the bottom record of the table and press Down arrow.

An empty record appears.

To append a record from the Navigator or Catalog window,

1.	Select a table.

2.	Right-click to display the SpeedMenu.

3.	Choose Add Records.

4.	The Table Records window appears and displays a blank record.


See Also

Table Records Window Tasks


Deleting Records From a Table

See Also

For dBASE tables, deleting records involves two steps:

First, mark the records you want to delete.

Then, remove the marked records from the table. This is called packing the table.

You can recall, or unmark, records marked for deletion, as long as you have not yet packed the table. Recalling a record removes its deleted flag.

Deleted records do not appear in the Table Records window if Deleted is checked in the Desktop Properties dialog box. When Deleted is unchecked, the Browse layout of the Table Records window displays a Del (delete) column next to the Rec (record-number) column. An X in the delete column indicates a record marked for deletion. The delete column does not appear for Paradox and SQL tables.

For Paradox and SQL tables, deleting records involves one step:

Select the record and delete it.

When you delete records, they are permanently deleted from the table and cannot be recovered.

To delete a record, select the record, then do any of the following:

Choose Table|Delete Selected Record.

Press Ctrl+U.

Click the Del column in Browse layout (for dBASE tables only).

To recall (undelete) a record from a dBASE table,

1.	Uncheck Deleted in the Desktop Properties dialog box.

2.	Select the deleted record.

3.	Choose Table|Recall Selected Record or press Ctrl+U, or click the Del column in Browse layout to remove the X.

To pack a dBASE table,

Choose Table|Table Utilities|Pack Records.

Packing a dBASE table permanently removes all records marked for deletion. It also updates any open indexes. You must have enough disk space for dBASE to make another complete copy of the table as it is packed. Because you cannot recover deleted records after a pack, you should back up a table before you pack it.

To permanently delete all records in a table in a single operation,

Choose Table|Table Utilities|Zap Records.


See Also

Table Records Window Tasks


Language

DELETE

PACK

RECALL

SET DELETED

ZAP


Selecting Records to Process

See Also	Language

When you edit or view the records in a table, you might not see all the records in the table. Additionally, to process multiple records in a single step, you first need to select the records you want to change.

To select records, you identify the criteria by which a record would qualify. There are four common methods to select records. You can perform more complex selections using the Query Designer.

Method	Where to Set	Selects

Scope	Scope panel in various dialog boxes	All records that meet the specified conditions

Deleted	Desktop Properties dialog box	All records not marked for deletion

Unique	Create Index dialog box	All records, except for duplicate keys, where only the first record with a duplicate key is selected

Index Range	Table Records Properties dialog box	All records between a Low Key and High Key in the master index

The following is a list of menu commands that operate on a group of records, rather than a single record:

File|Print

Table|Find Records

Table|Replace Records

Table|Table Utilities|Manage Indexes

Table|Table Utilities|Delete Records

Table|Table Utilities|Recall Records

Table|Table Utilities|Export

Table|Table Utilities|Sort

Table|Table Utilities|Count

Table|Table Utilities|Calculate


See Also

Create Index Dialog Box

Desktop Properties Dialog Box

Scope Panel

Setting Filter Conditions in a Query - Overview

Designing Queries

Table Records Properties Dialog Box

Table Records Window Tasks


Language

INDEX

SET DELETED

SET FILTER


Changing Data in a Single Record

See Also

When you add or edit data in the records of a table, dBASE for Windows automatically checks the data to make sure it is valid.

Note:	The built-in validation is basic, and you can add more specialized validation and formatting requirements to the data using a form or by setting the properties on fields.

When you exit the current field, the Table Records window validates the data you entered:

For all fields, it verifies that the data you enter in a field matches the field data type.

For date fields, it verifies whether you entered a valid date.

If the index requires a unique key, as in Paradox tables, it checks whether the key values you entered are unique.

Editing Character Fields

Character fields accept any combination of letters, numbers, punctuation, spaces, and other characters. Text is left-aligned. If the text is shorter than the length of the field, spaces appear to the right of the text.

Editing Numeric Fields

Numeric fields accept numbers, periods, commas, and hyphens. Numeric fields are either numeric or float types. Numbers appear right-aligned and, if applicable, aligned along a decimal point.

Editing Date Fields

Date fields accept valid date values in the format specified in the Country page of the Desktop Properties dialog box. For formats such as mm/dd/yy, you do not need to enter the slashes. You must enter a leading zero for single-digit values, such as 03/04/05. If you type an invalid date, such as 02/31/94, an error message appears.

Editing Logical Fields

Logical fields accept only two values: true (.T.) or false (.F.). True values include Y, y, T, and t. False values include N, n, F, and f.

Editing Memo Fields

Memo fields contain free-form text. Memo data is stored in a separate file. To open a memo field, double-click its icon, choose View|Field Contents, or press F9. The memo field appears in the Text Editor window. To close a memo field, press Ctrl+W to save your changes, or press Ctrl+Q to abandon your changes.

Editing Binary and OLE Fields

Choose from the following list for information about viewing, storing, adding, and editing binary data, such as images and sounds, and OLE documents:

Working with Binary Data

Editing Images

Displaying Images

Editing Sounds

Playing Sounds

Displaying and Editing OLE Documents

To blank a record,

You can blank a record to clear all the data it contains. Blanking empties every field, including indexed fields, but does not delete the record.

Select the record, then choose Table|Blank Selected Record.

If you want to restore the data to the record, choose File|Abandon Record before moving to another record.


See Also

Saving or Abandoning Changes

Finding Records in a Table

Navigating Through Records in a Table

Table Records Window Tasks


Saving or Abandoning Changes

See Also

dBASE for Windows automatically saves changes to a record if you:

Press F2 to switch between Browse, Form, and Columnar layout.

Choose File|Save Record.

Choose File|Save Record and Close.

dBASE also accumulates changes to records the saves them periodically as you work with data in the table. If you set the Auto Save option on in the Table page of the Desktop Properties dialog box, dBASE saves changes to the disk automatically when data is changed or added.


See Also

Table Records Window Tasks

Desktop Properties Dialog Box


Replacing Data in Records

See Also	Language

You can replace records to quickly update a group of records with new values.

Replacing Text

To replace records, choose Table|Replace Records. The Replace Records dialog box appears. You can find a value in a field, then replace a value in the same or another field. dBASE removes the existing data in the Replacement Field before adding the new value. Use care when specifying a memo field as the replacement field, because all previous data in the memo is erased.

The replacement value must match the data type of the selected text.

Replacing Data in Indexed Fields

dBASE for Windows updates any open indexes as the value in each record is replaced. If you change the value of a field that is part of the master index, the record and the record pointer immediately move to the position in the index based on the new value of the field.

If replacement in the indexed field causes a record and the record pointer to move past other records that fall within the scope of the replacement, those records are not replaced.

When replacing data in the key field of an indexed table, you can prevent records from moving to a new position when the value changes:

1.	Set the master index to natural order in the Manage Indexes dialog box.

2.	Replace the data.

3.	Reset the master index using the Manage Indexes dialog box.

Replacements in fields other than the indexed field of the master index do not affect the display of the current record order.


See Also

Table Records Window Tasks


Language

REINDEX

SET INDEX


Calculating Data

See Also	Language

To calculate values, choose Table|Table Utilties|Calculate Records. You see the Calculate Records dialog box.

To calculate values from records,

1.	Specify the calculation you want to perform in the Calculation panel.

2.	Specify the field or fields upon which to perform the calculation in the Fields panel.

3.	Specify any criteria for selection of records in the Scope panel.

Calculations on Fields with Blank Values

Table|Table Utilities|Calculate Records treats a blank in a numeric or float field as a zero and includes the field in its calculations. For example, if you calculate the average of a numeric field in a table containing 5 blank records in a total of 10 records, Table|Table Utilities|Calculate Records divides the sum by 10 to find the average.

If you calculate a minimum in a field where a record has a blank value, Table|Table Utilities|Calculate Records returns zero as the minimum. To exclude blank fields from a calculation, specify a For condition in the Scope panel such as .NOT. ISBLANK( ).


See Also

Table Records Window Tasks

Query Designer Tasks


Language

ISBLANK( )


Export and Import File Types

See Also

You can export to and import data from other applications and file formats.

When you export data, you copy information from a table to a new table or other file type.

When you import data, you append information to an open table from another table or a different type of file.

Three menu commands support importing and exporting data: File|Import, Table|Table Utilities|Append Records from File, and Table|Table Utilities|Export Records.

Import and Export File Types

Exchange data using the following kinds of file formats:

File Type	File Extension	Menu  Commands	Description
dBASE	DBF	Append Records, Export	dBASE table
Paradox	DB	Append Records, Export	Paradox table
DBMEMO3	DBF, DBT	Export	A table and memo files in dBASE III PLUS (Export only)
Delimited Text	TXT	Append Records, Export	Character fields are delimited with quotation marks or other characters; fields are separated by commas or another character; logical fields contain T or F; records are terminated by a carriage return plus linefeed; field types with variable-length data are not appended or exported
System Data Format (SDF)	TXT	Append Records, Export	Fixed-length records are terminated by a carriage return plus linefeed; field types with variable-length data are not appended or exported
Spreadsheet	WB1, WKS	Import	Quattro Pro or Lotus 1-2-3 spreadsheet with rows and columns similar to records and fields


See Also

Table Records Window Tasks

Exporting Data

Importing Data


Exporting Data

See Also

You can export data to copy information from a table to another table or to a different file format. You can also export data to:

Exchange data with other applications

Create a copy of a table with only a subset of data

Exporting creates a destination file, then copies data from the source table into it. You can select fields and records you want to export. Use Table|Table Utilities|Export Records to export records.

If you specify a destination file that already exists, dBASE for Windows asks for confirmation before replacing it.

Exporting Memo Fields

When you export a table with a memo field:

If the target file is a dBASE table, dBASE for Windows creates a .DBT file with the same name as the target .DBF file and exports the contents of the memo field to it.

If the target file is an SDF or delimited text file, the contents of the source memo field are not exported.

Exporting Fields from Multiple Tables

You can use Table|Table Utilities|Export Records to create a file that contains fields from more than one table. Before you use Table|Table Utilities|Export Records, you must create a query with multiple tables and a relation, using the Query Designer. See Designing Queries for information.


See Also

Table Records Window Tasks

Export and Import File Types

Importing Data


Importing Data

See Also

You can import or append data from a table or other type of data file to an open table. When you import or append data, dBASE for Windows appends a new record for every row of data in the source file, copies the contents of the source file to the new record, and updates open indexes. The records are appended in the order they appear in the source file.

Use File|Import to import a spreadsheet file.

Use Table|Table Utilities|Append Records from File to append data from text files, Paradox tables, and from other dBASE tables.

Importing Data from Spreadsheet Files

When you specify a spreadsheet file as the source:

Remove column headings and leading blank rows and columns in the spreadsheet source file; otherwise, this data is appended.

If you check Headings in the Import dialog box, when you import a spreadsheet file, the first row is turned into field names.

Appending Data from dBASE Tables

When you specify a dBASE table as the source, any of the following conditions will result in a successful operation:

The source and destination tables have the same field names and types.

The source field is a date type, the target field is a character type, and the field names are the same.

The source field is a character field, the target field is a date field, and the field names are the same.

When fields in the source and target tables have different widths:

If the field in the target table is longer than the field in the source, dBASE pads the data with spaces.

If the field in the target table is shorter than the field in the source, dBASE truncates the data.


See Also

Table Records Window Tasks

Export and Import File Types

Exporting Data


Creating a Simple Index in the Table Designer

See Also

The simple index consists of a single field. Creating an index creates a new index tag in the production index file. Creating a tag does not change any data in the table - it only creates a new index in the index file.

The key expression of a simple index is the name of a field. For example, in the Customer table, if you use the CUSTOMER_N field, the key expression will be the field name, CUSTOMER_N.

To create a simple index in the Table Designer,

1.	Open the table in the Table Designer.

2.	Choose the field you want to use.

3.	Select an index order in the (Ascending or Descending) in the Index column.

The Table Designer adds the index to the production index file when you save the table design.


See Also

Index Concepts

Table Designer

Table Designer - Index


Creating a Simple Index in the Manage Indexes Dialog Box

See Also

To open the Manage Indexes dialog box, do one of the following:

In the Table Records window, choose Table|Table Utilities|Manage Indexes.

In the Table Designer, choose Structure|Manage Indexes.

In the Query Designer, choose Query|Manage Indexes.

When running a form, choose Form|Table Utilities|Manage Indexes.

The Manage Indexes dialog box appears.

To create a simple index,

1.	In the Manage Indexes dialog box, click Create. The Create Index dialog box appears.

2.	Enter an index name, such as CUSTNUM, in the Index Name field. The name can be up to 10 characters. You can use letters, numbers, and underscores, but the first character must be a letter. The name you use must be unique within the index file. For a simple index, consider using the field name.

3.	Enter a field name in the Key Expression box, such as CUST_N.

4.	Choose Descending if you want to change the default Ascending order.

5.	Click OK. The Manage Indexes dialog box appears.

When you choose OK in the Manage Indexes dialog box, dBASE builds any indexes you created or changed and removes any indexes you deleted. If you selected an index, it becomes the current master index.


See Also

Create Index Dialog Box

Index Concepts

Manage Indexes Dialog Box

Form|Table Utilities|Manage Indexes...

Query|Manage Indexes...

Structure|Manage Indexes...

Table|Table Utilities|Manage Indexes...


Selecting a Master Index

See Also	Language

When you first open a table in the Navigator, it appears in natural order. The production .MDX file opens automatically with the table, but the indexes it contains are not in effect until you select one. To order records in a specific way, select the index you want, and it becomes the master index.

The master index is the controlling index for the table. Only one index can be active as the master index at any time. The current master index sets the order of records for browsing and all other operations until you select another master index.

To select a master index,

1.	Choose Table|Table Utilities|Manage Indexes to open the Manage Indexes dialog box.

2.	Choose the index from the list or click Create to create a new index.

The index you select sets the order of records for browsing and all other operations until you select another master index.


See Also

Index Concepts

Manage Indexes Dialog Box

Setting Record Order

Table|Table Utilities|Manage Indexes...


Language

SET ORDER


Deleting an Index

See Also	Language

You can delete an index you no longer need to save space and improve performance. Deleting an index does not delete any records in the table - it deletes only the separate index tag that arranges records in a particular order.

To delete an index in the Table Designer, choose None as the index type for the field.

The Table Designer removes the associated index from the production index file. If you delete the only index in the file, the .MDX file is deleted as well.

To delete an index in the Manage Indexes dialog box, select the index you want to remove, and click Delete.


See Also

Manage Indexes Dialog Box

Table|Table Utilities|Manage Indexes...

Table Designer

Table Designer - Index


Language

DELETE TAG


Creating a Complex Index

See Also

To open the Manage Indexes dialog box, do one of the following:

In the Table Records window, choose Table|Table Utilities|Manage Indexes.

In the Table Designer, choose Structure|Manage Indexes.

In the Query Designer, choose Query|Manage Indexes.

When running a form, choose Form|Table Utilities|Manage Indexes.

The Manage Indexes dialog box appears.

To create a complex index,

1.	In the Manage Indexes dialog box, choose Create to open the Create Index dialog box.

2.	Enter an index name in the Index Name field. The name can be up to 10 characters. You can use letters, numbers and underscores, but the first character must be a letter. The name you use must be unique within the index file. For a simple index, consider using the field name.

3.	In the Key Expression box, enter a key expression, or click [image] to create one using the Expression Builder. The key expression can be simple, using a single field name, or complex, using multiple field names, dBASE functions, and operators. You can enter up to 220 characters. The total length of the key (the length of the evaluated key expression) can be up to 100 characters, although most keys are much shorter (and more efficient).

4.	If applicable, enter a condition for records to include in the index, or choose the Tool button to create an expression using the Expression Builder.

5.	If applicable, select Unique to hide records that have duplicate values.

6.	Select the record order of the index, either Ascending or Descending. For keys with multiple fields, the order applies to the entire key, not to individual fields within the key.

Your index is saved when you click OK to exit the Manage Indexes dialog box.


See Also

Create Index Dialog Box

Duplicate Values

Form|Table Utilities|Manage Indexes...

Index Concepts

Manage Indexes Dialog Box

Query|Manage Indexes...

Rules for Complex Indexes

Setting Record Order

Structure|Manage Indexes...

Table|Table Utilities|Manage Indexes...


Reindexing

See Also

You can rebuild an index to ensure that it is accurate and up to date. Reindexing is normally not necessary, however, because dBASE for Windows maintains the production index file automatically when you open a table and make changes in it. Similarly, dBASE automatically rebuilds an index if you change it in the Manage Indexes dialog box. Single index files (.NDX) do not automatically open with the table. They can become inaccurate if you use the table apart from the index. Use reindexing to rebuild a single index file.

Under certain circumstances, however, an index can become inaccurate or damaged. Should this happen, you need to rebuild the file.

To reindex,

1.	Open the table and index you want to rebuild. (If it is not the production index you are rebuilding, you must open it through the Command window.)

2.	Choose Table|Table Utilities|Reindex.

dBASE for Windows rebuilds the index. In the worst case of a corrupted index, you might need to delete the .MDX file and then re-create each index.

Note:	You might need to wait while reindexing occurs, particularly if the table has many records or if key expressions are long and complex.


See Also

Key Expressions

Manage Indexes Dialog Box

Table|Table Utilities|Manage Indexes...

Table|Table Utilities|Reindex


Sorting Data

See Also

Sorting a table copies its contents to a separate table and arranges records in the order you specify in the new table. When you sort, the source table is the table containing the data you want to copy, and the target table is the new table to contain the copied data. Sorting does not change the data in the source file.

When you sort a table, all fields in the source table appear in the target table. You select the fields on which to sort records. You can also select the records you want to include in the target table by using the scope options.

Note:	Make sure you have enough available disk space to store the table on the target drive.

To sort data,

1.	Open the table you want to sort.

2.	Choose Table|Table Utilities|Sort Records to open the Sort dialog box.

3.	Select the field(s) on which to sort records, and click the > button to move them to the Key Fields list. The order they appear in the Key Fields list determines the order of the sort.

4.	Select the sort order you want for each key field by clicking the arrow button, or pressing Alt+Down arrow, and selecting the order from the menu.

5.	The Scope panel lets you select the records you want to include in the target table, using one of the buttons or a For or While condition.

6.	Specify the name of the target file.

7.	Specify whether the target table is a dBASE or Paradox table.

8.	Click OK.

dBASE for Windows creates a new table containing all records or the records you selected in the order you specified. If the target file exists, dBASE for Windows asks you whether you want to overwrite it. Then dBASE for Windows copies the records you selected to the target table, sorting them as you specified, starting with the first key field.


See Also

Scope Panel

Selecting Records to Process.

Table|Table Utilities|Sort Records...


Creating a Primary Paradox Index in the Table Designer

See Also

To create a primary Paradox index in the Table Designer,

1.	Open the table.

2.	Select Primary in the Index column of the first field in the table.

You can then create a composite primary key by selecting the second and additional consecutive fields, as needed, and checking the Primary box for each one.


See Also

Creating a Primary Paradox Index in the Manage Indexes Dialog Box

Creating Secondary Paradox Indexes

Paradox Indexes

Table Designer


Creating a Primary Paradox Index in the Manage Indexes Dialog Box

See Also

To create a primary Paradox index in the Manage Indexes dialog box,

1.	Open the table.

2.	Choose Table|Table Utilities|Manage Indexes to open the Manage Indexes dialog box.

3.	Click Create to open the Create Index dialog box. The Primary box is automatically checked if no primary index exists. The Index Name field is automatically filled with <Not Applicable> since the name of the index will be Primary. The first field name in the table appears as the key expression.

4.	For a composite primary index, type a comma-separated list of fields in the Key Expression box. The fields must be consecutive in the table structure.

5.	Choose OK. dBASE creates the index and gives it the name "Primary," which cannot be changed.


See Also

Create Index Dialog Box

Creating a Primary Paradox Index in the Table Designer

Creating Secondary Paradox Indexes

Manage Indexes Dialog Box

Paradox Indexes

Table|Table Utilities|Manage Indexes...


Creating Secondary Paradox Indexes

See Also

To create a secondary Paradox index in the Manage Indexes dialog box,

1.	Open the table.

2.	Choose Table|Table Utilities|Manage Indexes to open the Manage Indexes dialog box. Click Create. If a primary index exists, the Primary option will be unchecked.

3.	Enter the field name in the Key Expression box. The Index Name says <Not Applicable> because it will automatically be the same name as the field.

4.	Choose OK.

Note:	Paradox requires you to create at least one primary index before you can create a secondary index.


See Also

Creating a Primary Paradox Index in the Manage Indexes Dialog Box

Creating a Primary Paradox Index in the Table Designer

Manage Indexes Dialog Box

Paradox Indexes

Table|Table Utilities|Manage Indexes...


Working with Multiuser Tables

See Also	Language

To work with a table that is shared with other users, you need to have sufficient access rights. Access rights are usually associated with your network or database login name. See your system or database administrator about your access rights.

The following table lists common editing operations and the required access rights:

Operation	Access Rights	Minimum Open Access

Open a table	Open rights	Read-only

Display only	Read rights	Read-only

Add records	Insert or data entry rights	Read-write

Change data in records	Update rights	Read-write

Delete records	Delete rights	Read-write

Index	Index rights	Exclusive

Pack, Zap	All rights	Exclusive

Screen Refresh

Other users might change data in records that appear on your screen. The Table Records window periodically updates the screen to refresh the information in the records you see. You can set the frequency at which the screen refreshes by changing the Refresh setting in the Table page of the Desktop Properties dialog box.

Locking Records

When a table is shared, it is possible that several users can edit the same data simultaneously, and some edits can be lost. To prevent loss of data, you must lock a record before attempting to change its contents or delete it. To have dBASE for Windows lock records automatically, turn on the Lock option in the Table page of the Desktop Properties dialog box.

If you do not enable automatic record locking, you need to lock the record explicitly with Table|Lock Selected Record before attempting to change or delete it. If another user has locked the record or file, a message box appears.


See Also

Table Records Window Tasks

Changing Data in a Single Record

Desktop Properties Dialog Box

Paradox Tables


Language

LOCK( )

SET EXCLUSIVE

SET FIELDS

SET RELATION

UNLOCK


Paradox Tables

See Also	Language

dBASE for Windows works with Paradox DOS and Paradox for Windows tables in their native file formats.

Using Paradox Tables

You can use a Paradox table the same way you can use a dBASE table. Paradox tables have the file extension .DB. They appear in the Tables section of the Navigator or Catalog window, along with dBASE tables (.DBF).

One difference between dBASE and Paradox tables is record numbers. A record in a dBASE table has a record number. Paradox records do not have record numbers.

Another difference is field types. dBASE tables have certain field types, Paradox tables have others. See Field Type for more information.

If you frequently use Paradox tables, you can set the Default Table Type to Paradox on the Tables Page of the Desktop Properties dialog box.

Deleting Records

Unlike dBASE tables, Paradox tables do not let you mark a record for deletion and permanently remove it from the table at a later time. Instead, when you delete a Paradox record, it is permanently removed from the table immediately.

Formatted Memo Fields

dBASE for Windows does not display or let you modify a formatted memo field in a Paradox table. However, you can open a Paradox table that contains a formatted memo.

Protected Tables

dBASE for Windows opens, but cannot create, Paradox password-protected tables. A Paradox master password provides all rights to a table. When you open the table, the Paradox Password dialog box appears.

An auxiliary password provides the following types of table rights:

All provides all rights except the ability to change the master password.

Insert and Delete let a user insert or delete records, but not delete the table.

Data Entry lets a user insert records, but not delete records or restructure the table.

Update lets a user view the table and change non-key fields, but not insert or delete records or change fields.

Read-Only lets a user view the table, but not change it in any way.

Auxiliary passwords also provide the following types of field rights:

All provides all rights to the data in a field, within the limits of the table rights.

Read-Only lets a user view a field, but not change it in any way.

None prevents a user from viewing or changing data in a field.


See Also

Table Records Window Tasks

Changing Data in a Single Record


Language

SET DBTYPE


Keystrokes in the Table Records Window

See Also

When editing the fields of a table, you see the insertion point (often referred to as the "text cursor" in other products). You can use standard editing keys, such as Backspace and Del, and the Edit menu commands, Cut, Copy, and Paste, to edit the text in the fields.

By dragging with the mouse or by holding down the Shift key as you press the arrow keys, you can select text.

The following table lists the keystrokes in the Table Records window.

Field Navigation

The following keystrokes navigate through the fields of a record in Form or Columnar layout.

Keystrokes	Action

Enter	Next field

Home	Beginning of current field

End	End of current field

Ctrl+Home	First field in current record

Ctrl+End	Last field in current record

Ctrl+Left arrow	Left one word or field

Ctrl+Right arrow	Right one word or field

Up arrow	Up one field

Down arrow	Down one field

PgUp	Up one set of records

PgDn	Down one set of records

Record Navigation

The following keystrokes navigate through the records of a table in Browse layout.

Keystrokes	Action

Ctrl+G	Go to record number

Up arrow	Previous record

Down arrow	Next record

PgUp	Previous page

PgDn	Next page

Ctrl+PgUp	Top record

Ctrl+PgDn	Bottom record

Editing Keystrokes

The Table Records window has the standard editing keystrokes.

Keystrokes	Action

Backspace	Deletes the character to the left of the insertion point

Del	Deletes the character to the right of the insertion point

Ins	Toggles insert/overwrite mode

Tab	Moves to the next field or record

Shift+Tab	Moves to the previous field or record

Shift+Left arrow	Select left one character

Shift+Right arrow	Select right one character

Ctrl+X	Cuts selected text from the file and places it on Clipboard

Ctrl+C	Copies selected text to Clipboard; original text remains

Ctrl+V	Pastes contents of Clipboard at the insertion point, replacing any selected text

Del	Deletes selected text but does not place it on the Clipboard

Ctrl+Z	Undo

Ctrl+F	Find

Ctrl+R	Replace

Ctrl+L	Lock record

F9	Open memo field


See Also

Keyboard Shortcuts

Text Editing Keystrokes

Table Editing Keystrokes


Table Records Window Components

See Also	Language

The Table Records window provides three layouts for viewing and editing records in a table. You can switch among the three layouts to see the same data presented in different ways.

Browse layout	Form layout	Columnar layout

Browse layout displays multiple records in a grid of rows (records) and columns (fields). The Browse layout provides features the other two do not have. You can move and resize columns in this view, and you can see which records are marked for deletion. To see deleted records, uncheck Deleted in the Desktop Properties dialog box.

Form layout displays one record at a time. The fields in the record are laid out horizontally, from left to right, wrapping to the next line or lines as necessary.

Columnar layout displays one record at a time. The fields in the record are arranged vertically, with one field per line.

Scroll bars appear in the Table Records window when its contents exceed the width or length of the window.

Switching Among Layouts

Choose the following commands to switch among layouts:

View|Browse Layout

View|Form Layout

View|Columnar Layout

To toggle among the three layouts, press F2.

When you change layouts, the selected record remains current.

Working with Data

In dBASE tables, you can enter data directly into character, numeric, logical, date, and float fields. To display or edit the contents of a memo, binary, or OLE field, select the field, then choose View|Field Contents or press F9.

In Paradox tables, you can enter data directly into alpha, number, money, date, and short fields. To display or edit the contents of a memo, graphic, or OLE field, select the field then choose View|Field Contents or press F9. You cannot display or edit the contents of a binary or formatted memo field.

Memo fields appear in the Text Editor window. OLE fields appear in the OLE Viewer window. Binary fields are displayed or run in the appropriate tool for the data, for example the Image Viewer or the Sound Player. For more information on these field types, choose from the following:

Editing Text

Displaying and Editing OLE Documents

Displaying Images

Playing Sounds

To resize a column in Browse layout,

1.	Point to the column border.

2.	When the pointer changes to a double-headed arrow, drag the border until the column becomes the size you want.

3.	Release the mouse button.

Resizing a column does not change the field width in the table structure.

To move columns in Browse layout,

1.	Point to the title of the column you want to move.

2.	When the pointer changes to a hand pointer, drag the column to its new location.

Moving a column does not change the order of fields in the table structure.

Status Bar

As you use the Table Records window, the status bar displays the following information:

Name of the current table

The lock status of the current table, if any:

RLock: the current record is locked

FLock: the entire table is locked

Excl: the table is exclusive to you

Rdnly: the table is read-only

Current record number and the total number of physical records in the table

Status of the Insert key: "Ins" if you can insert characters in front of others, blank to overwrite characters


See Also

Displaying and Editing Table Records

Table Records Window Tasks


Language

BROWSE

EDIT


Table Records Window Menus

The Table Records window has the following menus:

File Menu

Edit Menu

View Menu

Table Menu

Properties Menu

Window Menu

Help Menu


Table Records Window SpeedBar

The SpeedBar is the row of buttons beneath the menu bar. Each button represents a menu command. Click the button representing the command you want to execute.

Button	Action	Menu Equivalent
	Creates a new dBASE-related file	File|New
	Opens a dBASE-related file	File|Open
	Saves a table	File|Save
	Prints a table view	File|Print
	Removes the selected text/object and places it on the Clipboard	Edit|Cut
	Copies the selected text, object, or record onto the Clipboard	Edit|Copy
	Inserts the text, object, or record into the active window	Edit|Paste
	Changes to the Table Records window	View|Table Records
	Changes to the Table Designer	View|Table Structure
	Switches to Browse layout	View|Browse Layout
	Switches to Form layout	View|Form Layout
	Switches to Columnar layout	View|Columnar Layout
	Finds a specified record	Table|Find Record
	Adds a record to the end of the table	Table|Add Records
	Creates a query based on this table	Table|Create Query
	Moves to the first record	Table|Top Record
	Moves to the previous page	Table|Previous Page
	Moves to the previous record	Table|Previous Record
	Moves to the next record	Table|Next Record
	Moves to the next page	Table|Next Page
	Moves to the last record	Table|Bottom Record
	Switches to the Navigator window	Window|Navigator
	Switches to the Command window	Window|Command
	Opens the Form Expert	Help|Experts|Form Expert
	Opens the Interactive Tutors	Help|Interactive Tutors


Table Records Window SpeedMenu

Use the Table Records window SpeedMenu to quickly perform a common operation on the Table Records window.

To use the Speed Menu, right-click anywhere in the Table Records window.

Choose from the following commands:

Table Records Window Properties...

Cut

Copy

Paste

Find Records...

Replace Records...

Add Records

Delete or Recall Selected Record


Edit Menu (Table Records Window)

See Also

Use the Edit menu to perform editing operations and to copy or remove text.

The Edit menu works differently in each of the windows. The most common use of the Edit menu is to work with text, for example, to move text around or to delete text. For information about using the Edit menu in different windows, see Where the Edit Menu Works.

You can cut, copy, or paste text using the Clipboard. The Clipboard is a temporary storage area for information you want to move or copy from one location to another.

Choose from the following commands:

Undo

Cut

Copy

Paste

Paste Add Records

Delete

Select All


See Also

Displaying and Editing Table Records

Running Queries


Edit | Paste Add Records

See Also

Adds one or more new records to the current table and fills them with the contents of the Clipboard.

This command inserts record data previously put on the Clipboard. To copy records to the Clipboard, in the Table Records window choose View|Browse layout. Then select one or more records by clicking in the Rec column.

The contents of the Clipboard are not deleted when you paste, so you can paste many times.

You cannot reverse the effect of this command with Edit|Undo. Instead, you can delete the newly added records.

The Paste Add Records command is not available if the Clipboard is empty or if the Clipboard does not contain records.

For information about using the Edit menu in different windows, see Where the Edit Menu Works.


See Also

Edit Menu (Table Records Window)

Edit|Copy

Edit|Cut

Edit|Paste

Edit|Undo


File Menu (Table Records Window)

See Also

Use the File menu to create new files, open and run existing files, and exit dBASE for Windows.

The New and Open commands manipulate the primary file types, such as tables, queries, and forms. The New command displays a menu allowing you to choose the type of file you want to create. The Open command lets you run or design an existing file.

You can open as many files as you like, and each appears in its own window. However, the Navigator and Command windows are unique and cannot be opened more than once.

From the Table Records window, you can also save, close, or abandon your changes to the current record, and print the current file or set up the printer.

Choose from the following commands:

New

Open...

Save Record

Save Record and Close

Abandon Record

Abandon Record and Close

Close

Print...

Printer Setup...

Import...

Exit

(closed file list)


See Also

Displaying and Editing Table Records

Running Queries


File | Save Record

See Also

Saves the changes made to the current record.

dBASE for Windows automatically saves the record you are editing when you move to another record in the table. Use this command to save the record you are editing without having to move the insertion point to another record.

Shortcuts

SpeedBar:

Keyboard:	Ctrl+S


See Also

File Menu (Table Records Window)


File | Save Record and Close

See Also

Saves the current record and closes the Table Records window.

Shortcuts

Keyboard:	Ctrl+W


See Also

File Menu (Table Records Window)

Saving or Abandoning Changes


File | Abandon Record

See Also

Abandons any changes to the current record without warning and restores its previously saved value.

Use this command to restore a record to its values before you changed it. Once you move to another record, you can no longer abandon your changes.


See Also

File Menu (Table Records Window)


File | Abandon Record and Close

See Also

Abandons any changes to the current record without warning, restores its previously saved value, and closes the Table Records window.

Once you move to another record, you can no longer abandon your changes.

Shortcuts

Keyboard:	Ctrl+Q


See Also

File Menu (Table Records Window)

Saving or Abandoning Changes


File|Print... (Table Records window only)
File | Print...

See Also

Opens the Print Records dialog box, where you choose which records to print. Records are printed in the current layout (Browse, Form, or Columnar) of the Table Records window.

Shortcuts

SpeedBar:

Keyboard:	Ctrl+P

Dialog Box Options

Printer

Displays the name of the active printer. This is a display-only field. Choose Setup if you want to change the active printer.

Scope

The Scope panel gives you options for specifying the scope of the operation. This panel is described in Scope Panel.

Multiple Records Per Page

Prints multiple records on the same page. When you print from Browse layout, this item is always checked. When you print from Form or Columnar layout, this item is checked by default.

Print Quality

Specifies the quality and resolution of the printed page. Choose the quality from the drop-down list. The Print Quality choices vary for different printers. In general, the higher the number, the better the quality.

Print to File

Specifies to print to a file, not to the printer. If you choose Print to File, the Print to File dialog box appears when you choose OK. Type the full path and file name of the file to receive the output. If the file exists, dBASE asks if you want to overwrite it. The file generated is not a standard text file; it contains printer and formatting codes so you can print the file later with full formatting.

Copies

Specifies the number of copies to print. The maximum is 99,999 copies. dBASE sends the output to the Windows Print Manager only once. If you specify more than one copy, Print Manager sends multiple copies of the output to the printer.

Collate Copies

Prints multiple copies as a set instead of printing multiple copies of each page before moving on to the next page.

Setup

Opens the Print Setup dialog box, where you can specify the printer, paper source, and orientation. For more information, see File|Printer Setup.


See Also

File Menu (Table Records Window)


File | Import...

See Also	Language

Imports a spreadsheet file and transfers the data to a dBASE or Paradox table.

This command creates a new table with the same name as the spreadsheet and a .DBF or .DB extension. If a file with this name exists, dBASE asks if you want to replace it.

dBASE creates a table based on the Default Table Type setting in the Desktop Properties dialog box.

When you specify a spreadsheet file as the source,

Decide if you want column headings to become the field names. If so, they must be in row 1 of the spreadsheet. If not, remove them from the spreadsheet; otherwise, this data is appended.

Remove leading blank rows and columns from the spreadsheet; otherwise, this data is appended.

Dialog Box Options

Spreadsheet

Enter the name of the spreadsheet you want to import. Click [image] to open the Choose Spreadsheet dialog box where you choose the spreadsheet file you want to open. For general information about opening files, see Open File dialog box.

The File Type box lists the spreadsheet types you can import:

Quattro Pro for Windows file extensions are .WB1.

Lotus 1-2-3 file extensions are .WK1.

Headings

Translates spreadsheet column headings into field names. If checked, the first row in the spreadsheet becomes the field names. dBASE converts the column headings as follows:

Spaces and other punctuation are automatically converted by the Borland Database Engine to legal characters for field names.

Spaces are converted to underscores.

Mixed-case characters are converted to uppercase characters.

Text is truncated to ten characters.


See Also

File Menu (Table Records Window)

File Menu (Navigator)

File Menu (Catalog Window)

File Menu (Command Window)

Importing Data

Table|Table Utilites|Append Records from File


Language

SET DBTYPE


Paradox Password Dialog Box

Lets you enter a password for a Paradox table.

This dialog box appears when you open a Paradox table that is password protected. You must enter the correct password and click OK to open the table.

Dialog Box Options

Table

Displays the name of the table you are trying to open. This is a display-only field.

Password

Enter the password. For security, you cannot see the text as you type it.


Transaction Pending Dialog Box

This dialog box appears if you are using a dBASE for Windows application with transaction processing. In transaction processing, changes to a record are part of a transaction. Normally, when you finish changing a record, the changes are committed (written) to the file on the disk and the transaction ends.

If a transaction does not end normally, due to an expected system error or application exit, this dialog box appears. Choose Commit to attempt to save again, or Rollback to abandon the current transaction.

Dialog Box Options

Commit

Ends the transaction and saves to the open files any changes made during the transaction.

Rollback

Ends the transaction without saving any changes to the open files.


Borland Database Engine Error Dialog Box

This dialog box appears when the Borland Database Engine (BDE) attempts to open a table and fails. The BDE provides access to tables, databases, and indexes. When an error occurs, the BDE provides options to handle or recover from the error. The selected option is the default option for the error displayed.

If you check Don't Bring Up this Dialog Again, the BDE assumes the default action when the same error with the engine occurs again.

Cannot Open MDX

The production index file for the dBASE table you are trying to open is missing or corrupt. You can open the table for viewing only, without the index, you can remove the dependency on the production index, or you can repair the .MDX file. If you are trying to open a FoxPro table with a production index, you have the option to convert it to dBASE production index format.

Cannot Open Memo

The memo file for the dBASE table you are trying to open is missing. You can open the table for viewing only, without the memo fields, or you can create a new blank memo file. If you are trying to open a FoxPro table with a memo or general field, you have the option to convert it to dBASE memo file format.

Cannot Open BLOB

The binary large object file (.MB) for the Paradox table you are trying to open is missing. You can open the table for viewing only, without the binary or OLE field.

Cannot Open Lookup

The lookup table for the Paradox table you are trying to open is missing. You can open the table for viewing only, without the lookup, or you can remove the dependency on the lookup table.


Error Committing Changes Dialog Box

See Also

This dialog box appears when the Borland Database Engine (BDE) attempts to save the changes to a table and fails. The BDE provides access to tables, databases, and indexes. When an error occurs, the BDE provides options to handle or recover from the error.

This dialog box appears when you use the Table Records window or a form for editing table data. Several conditions can cause this dialog box to appear, such as the following:

Table and field right violations

Validation check failures on Paradox tables

Server errors when saving SQL table data

Key violations on non-dBASE tables


See Also

Displaying and Editing Table Records

Designing Forms

Using Forms


Table Menu (Table Records Window)

See Also

Use the Table menu in the Table Records window to find and replace records, access the table utilities, append, delete, lock, and blank records, and navigate in the table.

Choose from the following commands:

Find Records...

Replace Records...

Create Query

Table Utilities

Add Records

Delete or Recall Selected Record

Lock or Unlock Selected Record

Blank Selected Record

Go to Record Number...

Previous Record

Next Record

Previous Page

Next Page

Top Record

Bottom Record


See Also

Displaying and Editing Table Records

Running Queries


Table or Form | Find Records...

See Also	Language

Finds the specified text or value in the selected field.

Use Table|Find Records to search for a record in the Table Records window. If a match is found, the record pointer moves to the found record.

For dBASE tables, you can search on character, numeric, float, date, logical, and memo fields.

For Paradox tables, you can search on alpha, number, money, date, short, memo, and formatted memo fields.

Shortcuts

SpeedBar:

SpeedMenu:	Find Records...

Keyboard:	Ctrl+F

Dialog Box Options

Find What

Enter the text or value you want to find. You can specify any printable character, including spaces. For example, you could search for records where the LastName field equals Johnson.

For text and memo fields, you do not have to enter the precise value you are searching for. You can enter the beginning of a phrase, such as Bank, to find all records beginning with the word Bank.

To search for a value stored in another field, a memory variable, or an expression, use parentheses in the Find What text box. dBASE searches the field specified in Located in Field for the value that the expression evaluates to.

Field names. dBASE searches for records where the selected field matches the value of another field in the same record. For example, you could search for records where the YTD_Sales field equals the Ord_Rev field by selecting YTD_Sales in the Located in Field list, and specifying (Ord_Rev) in the Find What text box.

Memory variables. dBASE searches for records where the selected field matches the value in the memory variable. For example, you could search for records where the YTD_Sales field equals the value of the TotSales memory variable by selecting YTD_Sales in the Located in Field list, and specifying (TotSales) in the Find What text box.

Expressions. dBASE searches for records where the selected field matches the value that the expression evaluates to. For example, you could search for records where the Sell_Price field equals nine times the quantity by selecting Sell_Price in the Located in Field list, and specifying (QTY*9) in the Find What text box.

Located in Field

Choose the field to search.

Search Rules

Defines the search parameters. These options are available for dBASE character and memo fields, and for Paradox alpha, memo, and formatted memo fields.

Standard

Searches for records whose field begins with or matches the Find What value.

Exact Length

Searches for records whose field contains exactly the Find What value, including its length.

Anywhere in Field

Searches for records whose field has the Find What value anywhere inside it.

Sounds Like

Searches for records whose field sounds like the Find What value. The search is a soundalike, or phonetic, search.

Match Case

Matches both uppercase and lowercase letters in the Find What value and field to search.

Start Search From

Choose where you want to start the search.

Top Record

Starts the search from the first record.

Current Record

Starts the search from the current record.

Find

Finds the next occurrence of the search value.

Close

Closes the dialog box, leaving the record pointer where it was after the last Find.

Advanced>>

The Scope panel gives you options for specifying the scope of the operation. This panel is described in Scope Panel.


See Also

Table Menu (Table Records Window)

Form Menu (Forms)

Finding Records in a Table

Replacing Records in a Table


Language

LOCATE


Table or Form | Replace Records...

See Also	Language

Replaces the value in a field with a value that you specify for one or more records in a table.

Use Table|Replace Records to change the data in a field. You can choose any type of field; however, the replacement value must have the same data type as the field you choose. When you use Table|Replace Records to change data, the changes appear in the Table Records window immediately.

If you provide a scope by using the Scope panel, data is replaced when the value in the field meets the set of criteria that you specify.

Shortcuts

SpeedMenu:	Replace Records...

Keyboard:	Ctrl+R

Dialog Box Options

Find What

Enter the text or value you want to find. You can specify any printable character, including spaces. For example, you could search for records where the LastName field equals Johnson.

For text and memo fields, you do not have to enter the precise value you are searching for. You can enter the beginning of a phrase, such as Bank, to find all records beginning with the word "Bank."

To search for a value stored in another field, a memory variable, or an expression, use parentheses in the Find What text box. dBASE searches the field specified in Located in Field for the value that the expression evaluates to.

Field names. dBASE searches for records where the selected field matches the value of another field in the same record. For example, you could search for records where the YTD_Sales field equals the Ord_Rev field by selecting YTD_Sales in the Located in Field list, and specifying (Ord_Rev) in the Find What text box.

Memory variables. dBASE searches for records where the selected field matches the value in the memory variable. For example, you could search for records where the YTD_Sales field equals the value of the TotSales memory variable by selecting YTD_Sales in the Located in Field list, and specifying (TotSales) in the Find What text box.

Expressions. dBASE searches for records where the selected field matches the value that the expression evaluates to. For example, you could search for records where the Sell_Price field equals nine times the quantity by selecting Sell_Price in the Located in Field list, and specifying (QTY*9) in the Find What text box.

Located in Field

Choose the field to search.

Replace With

Specifies the value that dBASE for Windows replaces the value of the specified field with. Enter the replacement value in the text box.

For memo fields, the replacement value must have a character data type.

For non-memo fields, the replacement value must have the same data type as the field.

For all types of numeric fields, the length of the new value must not exceed the field width. Otherwise, the data in the field is replaced with an approximation to the new value in scientific notation, if it will fit. If scientific notation will not fit, the field is replaced with asterisks, which permanently removes stored data.

Scientific notation is a method of representing numbers as a decimal value multiplied by positive or negative 10 raised to a value. For example, .6E+23 is .6*(10^23).

Like the Find What text box, you can specify a value stored in another field, memory variable, or an expression by surrounding the expression with parenthesis.

Located in Field

Choose the field to replace data in.

Search Rules

Defines the search parameters. These options are available for dBASE character and memo fields, and for Paradox alpha, memo, and formatted memo fields.

Standard

Searches for records whose field begins with or matches the Find What value.

Exact Length

Searches for records whose field contains exactly the Find What value, including its length.

Anywhere in Field

Searches for records whose field has the Find What value anywhere inside it.

Sounds Like

Searches for records whose field sounds like the Find What value. The search is a soundalike, or phonetic, search.

Match Case

Matches both uppercase and lowercase letters in the Find What value and field to search.

Start Search From

Choose where you want to start the search.

Top Record

Starts the search from the first record.

Current Record

Starts the search from the current record.

Find

Finds the next occurrence of the search value.

Replace

Replaces the specified replacement field of the current record with the Replace With value.

Replace All

Replaces all occurrences of the specified replacement field with the Replace With value.

Close

Closes the dialog box, leaving the record pointer where it was after the last Find or Replace.

Advanced>>

The Scope panel gives you options for specifying the scope of the operation. This panel is described in Scope Panel.


See Also

Table Menu (Table Records Window)

Form Menu (Forms)

Blank Selected Record

Finding Records in a Table

Replacing Records in a Table

Scope Panel


Language

REPLACE


Table | Create Query

See Also

Opens the Query Designer, where you create a query for the current table. The table structure appears in the Query Designer window.

Shortcuts

SpeedBar:


See Also

Table Menu (Table Records Window)

Form Menu (Forms)


Table or Form | Add Records

See Also	Language

Appends a new, blank record to the end of the current table and positions the insertion point in the first field of that record.

If you are using Form or Columnar layout, you need to enter a value in the first field displayed, or use arrow keys to bypass it. If you press Enter on the first blank field, the Add Records operation ends, the new record is not added, and the Table Records window closes.

If you enter data into an appended record and then move the insertion point past the end of the record, another record is automatically appended.

Table|Add Records automatically updates any open indexes while you append records.

Table|Add Records recognizes the current field list specified with a query or with the Table Records Properties dialog box.

If you choose Add Records from the Command window or from the SpeedMenu of a table file in the Navigator or Catalog window, the blank record appears in the layout specified on the Files page of the Desktop Properties dialog box. If you choose Add Records while editing a table, the blank record appears in the current layout.

If you relate tables in a one-to-many relation, you can view data from both tables in the Table Records window. One table is the parent table, the other the child table. If you are editing a record in the child table and you choose Add Records, you must specify which table to add the record to using the Append to Alias dialog box.

Shortcuts

Menu:	Navigator|Add Records (from selected table)
Catalog|Add Records (from selected table)

SpeedBar:

SpeedMenu:	Add Records (Table Records window)
Add Records (from selected table in Navigator or Catalog window)

Keyboard:	Ctrl+A


See Also

Table Menu (Table Records Window)

Form Menu (Forms)

Adding Records to a Table

View|Form Layout


Language

APPEND

SET CARRY

SET FIELDS


Append to Alias Dialog Box

Use the Append to Alias dialog box to specify which table to add a record to. An alias is another name for a table.

If you relate tables in a one-to-many relation, you can view data from both tables in the Table Records window. One table is the parent table, the other the child table. If you are editing a record in the child table and you choose Add Records, you must specify which table to add the record to using this dialog box.

Dialog Box Options

Tables

Specifies the table to add the record to.


Table or Form | Delete or Recall Selected Record

See Also	Language

Marks the current record for deletion or removes the deletion mark from the current record.

dBASE for Windows does not permanently remove a record from a dBASE table when you delete it. Instead, the record is retained in the table but is marked for deletion. Until records have been permanently removed from a table with Table|Table Utilities|Pack Records, you can recall deleted records (undelete them). Records removed with Table|Table Utilities|Pack Records or Table|Table Utilities|Zap Records are permanently removed and cannot be recalled.

To recall records, you must be able to see deleted records in the Table Records window. You can view table data either including or excluding records marked for deletion. Choose Properties|Desktop, then choose the Table page. If Deleted is checked, you do not see deleted records in the Table Records window. If Deleted is unchecked, you see both undeleted and deleted records in the Table Records window. Deleted records appear in Browse layout with an X in the Del column. To recall a record, select it, then choose Table|Recall Selected Record.

If the current table is a Paradox or SQL table, Table|Delete Selected Record permanently removes a record from the table immediately.

In addition to marking a record for deletion, you can mark a range of records for deletion by using Table|Table Utilities|Delete Records.

In addition to recalling a record, you can recall a range of records by using Table|Table Utilities|Recall Records.

Shortcuts

SpeedMenu:	Delete Selected Record
Recall Selected Record

Keyboard:	Ctrl+U


See Also

Table Menu (Table Records Window)

Form Menu (Forms)

Displaying and Editing Table Records

Table Records Window Components

Deleting Records from a Table


Language

DELETE

RECALL

SET DELETED


Table or Form | Lock or Unlock Selected Record

See Also	Language

Locks or unlocks the current record.

Use Table|Lock Selected Record to prevent other users from changing a record you are editing or viewing. You can view and update a record you lock; other users can view this record but not update it.

If another user has locked the record, a message box appears.

When you lock a record with this command, the record remains locked until you unlock it, move to another record, or close the table.

Use Table|Unlock Selected Record to allow other users to change a record you had previously locked while you were editing or viewing it.

If you work with shared tables frequently, you can automatically lock records before you change them. See Working with Multiuser Tables for information.

Shortcuts

Keyboard:	Ctrl+L


See Also

Table Menu (Table Records Window)

Form Menu (Forms)

Working with Multiuser Tables


Language

LOCK( )

UNLOCK


Table or Form | Blank Selected Record

See Also	Language

Replaces data in the current record with blanks.

Use Table|Blank Selected Record to replace the values of fields with blank or empty values.

Table|Blank Selected Record is most useful for replacing logical, float, and numeric fields with true blank values, which Table|Replace Records cannot do. Table|Replace Records replaces a numeric or float field with 0, which dBASE treats as a zero value rather than a blank value. The distinction between blank and zero values in numeric and float fields is significant when you calculate a value such as an average.


See Also

Table Menu (Table Records Window)

Form Menu (Forms)

Changing Data in a Single Record

Table|Replace Records...


Language

AVERAGE

BLANK

CALCULATE

SET FIELDS


Table or Form | Go to Record Number...

See Also	Language

Moves to a specified record and makes it current.

Use Table|Go to Record Number to navigate in a table. You can also navigate a table with the following commands on the Table menu:

Previous Record

Next Record

Previous Page

Next Page

Top Record

Bottom Record

In dBASE tables, you cannot go to a record marked for deletion if Deleted is checked in the Desktop Properties dialog box.

This command is unavailable for Paradox and SQL tables because they do not have record numbers.

Shortcuts

Keyboard:	Ctrl+G

Dialog Box Options

Record

Specifies the number of the record to which you are moving. Enter the record number or use the spin box to select it.


See Also

Table Menu (Table Records Window)

Form Menu (Forms)

Navigating Records in a Table


Language

GO


Table or Form | Previous Record

See Also

Moves to the previous record and makes it current.

Use Table|Previous Record to navigate in a table. You can also navigate a table with the following commands on the Table menu:

Go to Record Number

Next Record

Previous Page

Next Page

Top Record

Bottom Record

Shortcuts

SpeedBar:

Keyboard:	Up Arrow


See Also

Table Menu (Table Records Window)

Form Menu (Forms)

Navigating Records in a Table


Table or Form | Next Record

See Also	Language

Moves to the next record and makes it current.

Use Table|Next Record to navigate in a table. You can also navigate a table with the following commands on the Table menu:

Previous Record

Go to Record Number

Previous Page

Next Page

Top Record

Bottom Record

Shortcuts

SpeedBar:

Keyboard:	Down Arrow


See Also

Table Menu (Table Records Window)

Form Menu (Forms)

Navigating Records in a Table


Language

SKIP


Table or Form | Previous Page

See Also

Moves to the previous screen and makes the first record on that screen current.

Use Table|Previous Page to navigate in a table. You can also navigate a table with the following commands on the Table menu:

Next Page

Previous Record

Next Record

Go to Record Number

Top Record

Bottom Record

Shortcuts

SpeedBar:

Keyboard:	PgUp


See Also

Table Menu (Table Records Window)

Form Menu (Forms)

Navigating Records in a Table


Table or Form | Next Page

See Also

Moves to the next screen and makes the first record on that screen current.

Use Table|Next Page to navigate in a table. You can also navigate a table with the following commands on the Table menu:

Previous Page

Previous Record

Next Record

Go to Record Number

Top Record

Bottom Record

Shortcuts

SpeedBar:

Keyboard:	PgDn


See Also

Table Menu (Table Records Window)

Form Menu (Forms)

Navigating Records in a Table


Table or Form | Top Record

See Also	Language

Moves to the first record in the table and makes it current.

Use Table|Top Record to navigate in a table. You can also navigate a table with the following commands on the Table menu:

Bottom Record

Previous Record

Next Record

Go to Record Number

Previous Page

Next Page

Shortcuts

SpeedBar:

Keyboard:	Ctrl+PgUp


See Also

Table Menu (Table Records Window)

Form Menu (Forms)

Navigating Records in a Table


Language

GO


Table or Form | Bottom Record

See Also	Language

Moves to the last record in the table and makes it current.

Use Table|Bottom Record to navigate in a table. You can also navigate a table with the following commands on the Table menu:

Top Record

Previous Record

Next Record

Go to Record Number

Previous Page

Next Page

Shortcuts

SpeedBar:

Keyboard:	Ctrl+PgDn


See Also

Table Menu (Table Records Window)

Form Menu (Forms)

Navigating Records in a Table


Language

GO


Scope Panel

See Also

Specifies the scope of a command. The scope specifies which records are included in and affected by an operation.

The Scope panel appears in dialog boxes where you can specify a group of records to operate on.

Use the Scope options as follows:

Choose All, Rest, Next, or Record to specify which set of records is affected by the command.

Optionally specify For or While conditions to further narrow the set of records.

Each option has a priority. The list below defines the order of precedence for the scope options:

While

All, Rest, Next, Record

For

For example, if you choose Next 3, and For Name="Smith", dBASE operates on the next 3 records if the name field equals Smith.

All

Specifies every record in the current table.

Rest

Specifies all records from and including the current record to the end of the file.

Next

Specifies any number of records from and including the current record to the end of the table. Enter the number of records or use the spin box to select the number. If you specify more records than the table contains, the change affects all records from the current record to the end of the file. This is option is unavailable for Paradox and SQL tables.

Record

Specifies a single record by its record number. Enter the record number or use the spin box to select it. If you specify a record that does not exist, a message box informs you of the number of records in the table. This option is unavailable for Paradox and SQL tables.

For

Specifies a condition that restricts the operation to certain records.

For example, the For clause Company = "Santa Cruz Dry Goods" restricts operation of a command to records for which the COMPANY field evaluates to the string "Santa Cruz Dry Goods". Click [image] to create an expression in the Expression Builder.

While

Specifies a condition and causes processing to continue as long as the condition is true. Enter a condition that causes processing to continue up to a certain point.

For example, if you are using a table indexed by company name, the While clause Company <> "Santa Cruz Dry Goods" causes the command to process as long as the COMPANY field does not evaluate to the string "Santa Cruz Dry Goods". Click [image] to create an expression in the Expression Builder. This differs from the For clause: For skips over records that do not apply; While stops when it finds a record that does not apply.


See Also

Expression Builder

Table|Replace Records...

Table|Table Utilities|Calculate Records...

Table|Table Utilities|Count Records...

Table|Table Utilities|Delete Records...

Table|Table Utilities|Export Records...

Table|Table Utilities|Recall Records...


Table or Form | Table Utilities

See Also

Displays a cascading menu. From the menu, choose table utility.

The table utilities work with indexes, close tables, delete and recall ranges of records, import and export data, sort data into a new table, generate random values for records, count records, and perform calculations.

Choose from the following commands:

Manage Indexes...

Reindex

Close Table

Close All Tables

Delete Records...

Recall Records...

Pack Records...

Zap Records...

Append Records from File...

Export Records...

Sort Records...

Generate Records...

Count Records...

Calculate Records...


See Also

Table Menu (Table Records Window)

Form Menu (Forms)


Table or Form | Table Utilities | Manage Indexes...

See Also	Language

Specifies an index tag to use as the master index. You can also create, modify, or delete index tags.

This command opens the Manage Indexes dialog box.

If you change the structure of an existing table with a master index, you must specify the master index again after changing the structure.

Shortcuts

Menu:	Structure|Manage Indexes... (Table Designer)


See Also

Table Menu (Table Records Window)

Form Menu (Forms)

Table|Table Utilities|Reindex


Language

INDEX

SET INDEX

SET ORDER


Manage Indexes Dialog Box

See Also	Language

Use the Manage Indexes dialog box to specify the index to use as the master index.

The master index determines the order of the records in the table you are viewing. Use Table|Table Utilities|Manage Indexes or Structure|Manage Indexes to choose from a list of tags that are already defined for your table.

You can also create, modify, or delete index tags and indexes.

Dialog Box Options

Index and Key

Lists the name of each index tag available and the key expression for the index tag. The key expression specifies the sort order of the records. Click or use the arrow keys to choose the index that you want to use as the master index.

Create

Click the Create button to create a new index tag with the Create Index dialog box.

Modify

Click the Modify button to modify the selected index tag with the Modify Index dialog box.

Delete

Click the Delete button to delete the selected index tag from the index file (.MDX).


See Also

Table|Table Utilities|Manage Indexes

Creating a Simple Index in the Table Designer

Creating a Simple Index in the Manage Indexes Dialog Box

Creating a Complex Index

Setting Record Order


Language

INDEX

SET ORDER


Create or Modify Index Dialog Box

See Also	Language

Use the Create or Modify Index dialog box to create a new index tag for a table, or modify an index tag.  An index tag makes the table appear in a sorted order.

To create an index tag, you must be the only person using the table. Unless you opened the table for exclusive use, when you use this command, dBASE asks if you want to reopen the table exclusively. If the table reopens successfully, the Create Index dialog box appears. If it does not reopen, a message box appears, and you must coordinate with other users so you can gain exclusive access to the table.

After you create the index, if you want to share the table and index with other users, you must reopen the table nonexclusively.

Dialog Box Options

Index Name

Displays a descriptive name for this index tag. You can enter a name of up to 10 characters without spaces. If you are creating or modifying a Paradox index, this option is unavailable.

Primary

Appears checked if you are creating or modifying a Paradox primary index. You must have a Paradox primary index before you can create a secondary index.

Key Expression

Specifies the field or fields to order the table on.

For dBASE tables, the key expression can be a field name in the table, such as CITY, LASTNAME, or BALANCE. You can index on character, numeric, float, or date fields. The key expression can also be a combination of fields, values, and functions, such as UPPER(City), LastName+FirstName, or Balance>10000. The Key Expression can be up to 220 characters, and the key it evaluates to must be 100 characters or less. See Using the Expression Builder for more information about expressions.

For Paradox tables, the primary index (.PX) must be the first field name in the table structure, or the first and following consecutive field names separated with commas. You can index on alpha, number, money, date, and short fields. Secondary indexes (.Xnn) can be any field in the table or a comma-separated list of fields in the table.

Click [image] to open the Expression Builder, where you can create an expression.

Records

Specifies which records to include in the index.

For

Determines which records in the specified set are included in the index. Enter a condition that restricts the operation to certain records.

For example, the FOR clause COMPANY = "Santa Cruz Dry Goods" restricts the index to records for which the COMPANY field evaluates to the string "Santa Cruz Dry Goods". Click [image] to create an expression in the Expression Builder.

Unique

Restricts the records included in the index to those with unique key values. If two or more records have the same key value, only the first record with the key value is included. The "first" record is determined by record number, the order you entered them. Unique does not apply to Paradox tables. Create a primary index in a Paradox table to force keys to be unique.

Order

Specifies which sorting order to use with this index tag.

Ascending

Specifies that the key should be sorted in ascending order (A to Z, 1 to 9, past to future).

Descending

Specifies that the key should be sorted in descending order (Z to A, 9 to 1, future to past). This option is unavailable for Paradox tables.


See Also

Using the Expression Builder

Opening and Closing the Table Records Window

Table|Table Utilities|Manage Indexes

Table|Table Utilities|Reindex


Language

INDEX

SET INDEX


Table or Form | Table Utilities | Reindex

See Also	Language

Recreates all open indexes.

An .MDX index file is opened automatically when you open the table. It is updated automatically as you work with the table. Use Reindex to rebuild an index file that is corrupted or out-of-date. This can happen, for example, if the power fails while a table and index are open.

An .NDX index file is a single-index file. Since dBASE does not automatically open single-index files when you open the table, the .NDX file will be out-of-date if you change the table while the .NDX file is closed. Use Reindex to update an .NDX file.


See Also

Table Menu (Table Records Window)

Form Menu (Forms)

Table|Table Utilities|Index Tags...


Language

REINDEX


Table or Form | Table Utilities | Close Table

See Also	Language

Closes the current table, indexes, and format file.

In addition to closing the current table with Table|Table Utilities|Close Table, you can also close all open tables with Table|Table Utilities|Close All Tables.


See Also

Table Menu (Table Records Window)

Form Menu (Forms)

Table|Table Utilities|Close All Tables


Language

USE


Table or Form | Table Utilities | Close All Tables

See Also	Language

Closes open databases, tables, indexes, and format files.

In addition to closing the current database and tables with Table|Table Utilities|Close All Tables, you can close just the current table with Table|Table Utilities|Close Table.

If you opened tables with Sessions checked in the Desktop Properties dialog box, this command closes files only in the current session.


See Also

Table Menu (Table Records Window)

Form Menu (Forms)

Table|Table Utilities|Close Table


Language

CLOSE DATABASES


Table or Form | Table Utilities | Delete Records...

See Also	Language

Marks specified records for deletion.

dBASE for Windows does not permanently remove a record from a dBASE table when you delete it. Instead, the record is retained in the table but is marked for deletion. To permanently remove deleted records from a table, use Table|Table Utilities|Pack Records.

You can view table data either including or excluding records marked for deletion. Choose Properties|Desktop, then choose the Table page. If Deleted is checked, you do not see deleted records in the Table Records window. If Deleted is unchecked, you see both undeleted and deleted records in the Table Records window. Deleted records appear in Browse layout with an X in the Del column.

If the current table is a Paradox or SQL table, Table|Delete Selected Record permanently removes a record from the table immediately.

In addition to marking a range of records for deletion, you can do the following:

Mark a single record for deletion by using Table|Delete Selected Record.

Undelete records by using Table|Table Utilities|Recall Records.

Dialog Box Options

Scope

The Scope panel gives you options for specifying the scope of the operation. This panel is described in Scope Panel.


See Also

Table Menu (Table Records Window)

Form Menu (Forms)

Browse Layout

Deleting Records from a Table

Table|Delete or Recall Selected Record

Table|Table Utilities|Pack Records...

Table|Table Utilities|Recall Records...

Table|Table Utilities|Zap Records...


Language

DELETE

SET DELETED


Table or Form | Table Utilities | Recall Records...

See Also	Language

Unmarks records that are marked for deletion.

dBASE for Windows does not permanently remove a record from a dBASE table when you delete it. Instead, the record is retained in the table but is marked for deletion. Until records have been permanently removed, you can recall deleted records (undelete them). Records removed with Table|Table Utilities|Pack Records or Table|Table Utilities|Zap Records are permanently removed and cannot be recalled.

When you delete records in a Paradox or SQL table, they are permanently removed immediately and you cannot recall them.

To recall records, you must be able to see deleted records in the Table Records window. Choose Properties|Desktop, then choose the Table page. Uncheck Deleted, so you can see both undeleted and deleted records in the Table Records window. Deleted records appear in Browse layout with an X in the Del column. Select the record to recall, then choose Table|Table Utilities|Recall Records.

You can also recall a single record with Table|Recall Selected Record.

Dialog Box Options

Scope

The Scope panel gives you options for specifying the scope of the operation. This panel is described in Scope Panel.


See Also

Table Menu (Table Records Window)

Form Menu (Forms)

Deleting Records from a Table

Table|Delete or Recall Selected Record

Table|Table Utilities|Delete Records...

Table|Table Utilities|Pack Records...

Table|Table Utilities|Zap Records...


Language

RECALL


Table or Form | Table Utilities | Pack Records

See Also	Language

Permanently removes records marked for deletion in a dBASE table.

Table|Delete Selected Record and Table|Table Utilities|Delete Records mark records for deletion; they do not physically remove them from a table. Use Table|Table Utilities|Pack Records to permanently and physically remove records marked for deletion. dBASE for Windows prompts you for confirmation before packing the table.

Before you pack a table, you can unmark deleted records with Table|Recall Selected Record or Table|Table Utilities|Recall Records.

To pack a table, you must be the only person using the table. Unless you opened the table for exclusive use, when you use this command, dBASE asks if you want to reopen the table exclusively. If the table reopens successfully, the table is packed. If it does not reopen, a message box appears, and you must coordinate with other users so you can gain exclusive access to the table.

This command is unavailable for Paradox and SQL tables.


See Also

Table Menu (Table Records Window)

Form Menu (Forms)

Deleting Records from a Table

Table|Delete or Recall Selected Record

Table|Table Utilities|Delete Records...

Table|Table Utilities|Recall Records...

Table|Table Utilities|Zap Records...


Language

PACK


Table or Form | Table Utilities | Zap Records

See Also	Language

Permanently removes all records from a table.

dBASE for Windows prompts you for confirmation depending on the Safety setting in the Desktop Properties dialog box:

If Safety is checked, dBASE for Windows prompts you for confirmation before removing the records.

If Safety is unchecked, dBASE for Windows permanently removes all records without prompting for confirmation.

Note:	You cannot undo the Table|Table Utilities|Zap Records command.

To zap a table, you must be the only person using the table. Unless you opened the table for exclusive use, when you use this command, dBASE asks if you want to reopen the table exclusively. If the table reopens successfully, the table is zapped. If it does not reopen, a message box appears, and you must coordinate with other users so you can gain exclusive access to the table.

Zap Records differs from Pack Records in that Zap Records removes all records in the table. Pack Records removes only records marked for deletion.


See Also

Table Menu (Table Records Window)

Form Menu (Forms)

Deleting Records from a Table

Table|Delete or Recall Selected Record

Table|Table Utilities|Delete Records...

Table|Table Utilities|Recall Records...

Table|Table Utilities|Pack Records...


Language

SET SAFETY

ZAP


Table or Form | Table Utilities | Append Records from File...

See Also	Language

Adds data to the current table from files in non-dBASE formats and from other dBASE tables.

You can add data from the following file formats:

dBASE tables

Paradox tables

System Data format (SDF) text files

Delimited text files

You can add records to a dBASE, Paradox, or SQL table. The table into which you are adding data must be open. Open it by double-clicking it from the Navigator or Catalog window. Data is appended to the end of the existing table in the order in which it is stored in the source file.

If you append from a dBASE table that contains deleted records, this command either appends them or not depending on the setting of Deleted in the Desktop Properties dialog box.

If Deleted is unchecked, source records that are marked for deletion are appended to the target table and marked for deletion in the target table.

If Deleted is checked, source records that are marked for deletion are not added to the target table.

When you append data to a Paradox table with a primary index, only new records with a unique key are appended. Any record that duplicates an existing key is written to a separate Paradox table. dBASE notifies you of the Paradox table name.

Dialog Box Options

File Name

Specifies the file to import. Type the file name or click [image] to specify the name and location of the file to import using the Append Records from File dialog box. For general information about choosing files, see Open File dialog box.

File Type

Specifies the type of file to import. Choose any of the following file types:

dBASE specifies a .DBF table.

Paradox specifies a .DB table.

SDF specifies a System Data Format file. Records in an SDF file are fixed-length, and the end of a record is marked with a carriage return and linefeed. In the dBASE table receiving SDF data, unused portions of fields are padded with spaces. The example below shows an SDF format for a two-field table.

Ted     Robinson
Bob     Smith
Bill    Johnson

Delimited specifies a delimited text file. Fields are separated with commas. Each carriage return and linefeed indicates a new record. The example below shows a delimited format with a " delimiter.

"Ted","Robinson"
"Bob","Smith"
"Bill","Johnson"

Delimiter

Specifies the character used as a delimiter in delimited text files. Enter a delimiter character. If you do not specify a delimiter, dBASE for Windows assumes a space.

For

Determines which records in the table are imported, if a dBASE table is the source file. Enter a condition that restricts the operation to certain records.

For example, the For clause COMPANY = "Santa Cruz Dry Goods" restricts the import to records for which the Company field evaluates to the string "Santa Cruz Dry Goods". Click [image] to create an expression in the Expression Builder.


See Also

Table Menu (Table Records Window)

Form Menu (Forms)

Importing Data

Expression Builder

File|Import...

Table|Table Utilities|Export Records...

Paradox Indexes


Language

APPEND FROM

COPY

IMPORT

SET DELETED


Table or Form | Table Utilities | Export Records...

See Also	Language

Exports data from all or part of a table and stores the data in another file in non-dBASE format or in another dBASE table.

Use the Export Records dialog box to specify the name and type of the file to which you are exporting data, the fields to export, and the range of records to export.

If the table to export is using an index, the records of the new table or file are arranged in the index order.

This command does not export a _dbaselock field, the multiuser lock field.

If you export a dBASE table that contains deleted records, this command either exports them or not depending on the setting of Deleted in the Desktop Properties dialog box.

If Deleted is unchecked, source records that are marked for deletion are exported and marked for deletion in the target table.

If Deleted is checked, source records that are marked for deletion are not exported to the target table.

Note:	This command does not verify that the files you create are compatible with other software applications: you might specify field lengths, record lengths, number of fields, or number of records that are incompatible with the target software application. Check the file specifications of the target software program before exporting data.

Dialog Box Options

File Name

Specifies the name of the new file to export data into. Type the file name or click [image] to specify the name and location of the file to create using the Export File dialog box. For general information about saving files, see Save As dialog box. If you specify a file without including its path, dBASE for Windows creates the file in the current directory.

File Type

Specifies the type of file you are exporting to. Choose any of the following file types:

dBASE specifies a .DBF table.

Paradox specifies a .DB table.

SDF specifies a System Data Format file. Records in an SDF file are fixed-length, and the end of a record is marked with a carriage return and linefeed. The example below shows an SDF format for a two-field table.

Ted     Robinson
Bob     Smith
Bill    Johnson

Delimited specifies a delimited text file. Fields are separated by commas. Each carriage return and linefeed indicates a new record. The example below shows a delimited format with a " delimiter.

"Ted","Robinson"
"Bob","Smith"
"Bill","Johnson"

DBMemo3 specifies a dBASE III PLUS format for database and memo field files.

Delimiter

Specifies the character used as a delimiter in delimited text files. Enter a delimiter character. If you do not specify a delimiter, dBASE for Windows assumes a space.

Scope

The Scope panel gives you options for specifying the scope of the operation. This panel is described in Scope Panel.

Available Fields

Lists the fields available to export from the source table. Select a field and use Add (>) to place it in the Selected Fields box. When this box is empty, all fields will be exported.

Add (>)

Adds the field selected in Available Fields to the bottom of the list of fields in the Selected Fields box.

Add All (>>)

Adds all fields in Available Fields to the Selected Fields box.

Remove (<)

Removes the field selected in Selected Fields list and places it at the bottom of the Available Fields list.

Remove All (<<)

Removes all fields listed in the Selected Fields list and returns them to the Available Fields list.

Selected Fields

Lists the fields that you are exporting from the source table. Select a field in Available Fields and use Add (>) to place it in the Selected Fields box. Fields are exported in the order they appear in this list.


See Also

Table Menu (Table Records Window)

Form Menu (Forms)

Exporting Data

Table|Table Utilities|Append Records from File...


Language

CONVERT

COPY

IMPORT

SET DELETED

SET FIELDS


Table or Form | Table Utilities | Sort Records...

See Also	Language

Copies the current table to a new table and arranges the records in an order you specify. All fields are copied to the new table.

Table|Table Utilities|Sort Records is different from using an index to sort a table, because it creates a new table instead of rearranging the records in the current table. To order your data without creating a new table, use an index.

When you use Table|Table Utilities|Sort Records, dBASE for Windows creates a temporary index file. During the sorting process, your hard disk must have room for this temporary index file and the new table file.

To copy records to a new table excluding some fields, use an index and the Table|Table Utilities|Export Records.

Dialog Box Options

Target Table Name

Specifies the name of the new sorted table. If you specify a file without including its path, dBASE for Windows creates the file in the current directory.

Click [image] to specify the name and path of the file to use as the sort table. Select it from the Save File dialog box.

Target Table Type

Specifies the table type of the output file.

dBASE

Specifies that the sorted table is a dBASE table (.DBF).

Paradox

Specifies that the sorted table is a Paradox table (.DB).

Available Fields

Lists the fields available as sort fields in the source table. Select a field and use Add (>) to place it in the Key Fields box.

Add (>)

Adds the field selected in Available Fields to the bottom of the list of fields in the Key Fields box.

Remove (<)

Removes the field selected in Key Fields list and places it at the bottom of the Available Fields list.

Remove All (<<)

Removes all fields listed in the Key Fields list and returns them to the Available Fields list.

Key Fields

Lists the fields you are using as sort fields. Select a field in Available Fields and use > to place it in the Key Fields box. Use the arrow to the left of the field to specify one of the following sort orders:

Ascending sorts records in ascending order (A to Z; 1 to 9; past to future; False then True).

In character fields, uppercase letters are sorted in their own sequence followed by lowercase letters. For example, an ascending character field sorts A, B, a, b.

Ascending/No Case specifies that the field sorts in an ascending order but ignores the case. For example, an ascending/no case character field sorts a, A, b, B.

Descending sorts records in descending order (Z to A; 9 to 1; future to past; True then False).

In character fields, lowercase letters are sorted in their own sequence followed by uppercase letters. For example, a descending character field sorts b, a, B, A.

Descending/No Case specifies that the field sorts in a descending order but ignores the case. For example, a descending/no case character field sorts B, b, A, a.

When you add multiple fields to the Key Fields box, the records in the sorted table are arranged by the value in the first field. If the same value appears in the first field of more than one record, those records are then arranged by the value in the second field, and so forth.

Scope

The Scope panel gives you options for specifying the scope of the operation. This panel is described in Scope Panel.


See Also

Table Menu (Table Records Window)

Form Menu (Forms)

Sorting Data


Language

INDEX

SORT


Table or Form | Table Utilities | Generate Records...

See Also	Language

Appends records containing random information to the current table.

Table|Table Utilities|Generate Records fills a table with sample data so you can test and debug its structure.

dBASE appends records to the table. dBASE does not fill memo, binary, or OLE fields with data.

Dialog Box Options

Records

Enter the number of records to add to the current table or select it from the spin box.

You can generate up to 1 billion records. If you specify a value that is less than or equal to 0, dBASE for Windows does not generate any records. You cannot generate more than 2 billion bytes (2,000 megabytes) of data.


See Also

Table Menu (Table Records Window)

Form Menu (Forms)

View|Design Table


Language

GENERATE


Table or Form | Table Utilities | Count Records...

See Also	Language

Counts the records in a table that meet a specified condition.

The result appears in the Counted Records dialog box. Choose OK to close the window.

Count Records differs from the total number of records displayed in the status bar. The status bar number represents both deleted and nondeleted records in the table. If Deleted is checked in the Desktop Properties dialog box, Count Records does not count deleted records.

Dialog Box Options

Scope

The Scope panel gives you options for specifying the scope of the operation. This panel is described in Scope Panel.


See Also

Table Menu (Table Records Window)

Form Menu (Forms)

Table|Table Utilities|Calculate Records...


Language

COUNT

RECCOUNT()

SET DELETED


Table or Form | Table Utilities | Calculate Records...

See Also	Language

Performs financial and statistical operations on dBASE numeric and float fields, or Paradox number, money, or short fields, in the current table.

The result appears in the Calculation Results dialog box. Choose OK to close the window.

If the current table does not have any numeric or float fields, a message box appears.

If Deleted is off in the Desktop Properties dialog box, deleted records are included in the calculations.

Dialog Box Options

Calculation

Specifies the type of calculation to perform. Choose any one of the following:

Average calculates the average of the specified numeric or float expression and returns a float value.

Minimum calculates the minimum value of the specified field and returns the same data type as the field specified.

Maximum calculates the maximum value of the specified field and returns the same data type as the field specified.

Standard Deviation calculates the standard deviation of the specified numeric or a float field and returns a float value.

Sum calculates the sum of the specified field and returns a float value.

Variance calculates the variance of the specified numeric field and returns a float value.

Fields

Specifies the field or fields upon which the calculation is performed. The Fields list displays all the numeric and float fields in the current table. Select the fields upon which you want to perform the calculation. Use Shift+Click to select multiple contiguous fields. Use Ctrl+Click to select multiple fields, but not contiguously.

Scope

The Scope panel gives you options for specifying the scope of the operation. This panel is described in Scope Panel.


See Also

Table Menu (Table Records Window)

Form Menu (Forms)

Calculating Data

Table|Table Utilities|Count Records...


See Also

AVERAGE

CALCULATE

SET DELETED

SUM


Properties Menu (Table Records Window)

See Also

Use the Properties menu to change the characteristics of the dBASE for Windows Desktop and the Table Records window.

Choose from the following commands:

Desktop...

Table Records Window...


See Also

Displaying and Editing Table Records

Running Queries


Properties | Table Records Window...

See Also

Displays the Table Records Properties dialog box, where you set the attributes of the Table Records Window.

The settings you make in this dialog box are saved to the DBASEWIN.INI file. The Horizontal and Vertical Grid settings apply to all tables. All other settings apply to and are saved for the current table.

Shortcuts

SpeedMenu:	Table Records Window Properties...

Dialog Box Options

Fields

Selects fields in the current table to display in the Table Records window.

Records

Selects ranges of records to display in the Table Records window.

Window

Configures the Table Records window and chooses which editing operations are permitted.


See Also

Properties Menu (Table Records Window)

Opening and Closing the Table Records Window


Fields Properties

See Also

Selects which fields appear in the Table Records Window. By default, all fields appear.

Available Fields

Lists the fields that will not be displayed in the Table Records window. To move a field to this list, choose the field in the Selected Fields list, then click Remove (<).

Add (>)

Adds the selected field in the Available Fields list to the Selected Fields list.

Add All (>>)

Adds all the fields in the Available Fields list to the Selected Fields list.

Remove (<)

Removes the field selected in the Selected Fields list and moves it to the Available Fields list.

Remove All (<<)

Removes all the fields from the Selected Fields list and moves them to the Available Fields list.

Selected Fields

Lists the fields to display in the Table Records window. By default, all fields appear in this list. The fields appear in the order listed.

Add Calculated Field

Opens the Calculated Field dialog box, where you specify a calculated field to display in the Table Records window. When you click OK, the field is added to the Selected Fields list.

Current Selected Field Properties

Displays the properties assigned to the currently selected field.

Properties

Displays the properties for the current field. The properties appear in the form of the Fields option of the BROWSE command. Choose the Properties... button to open the Field Properties dialog box, where you set properties for the selected field.

Calculated

Displays the Calculated Field dialog box, where you edit the selected calculated field.


See Also

Properties|Table Records Window...


Calculated Field Dialog Box

See Also

Adds or edits a calculated field in the Selected Fields list of the Fields page (Table Records Properties dialog box). The calculated field appears in the Table Records window as a read-only field.

To display this dialog box, click the Add Calculated Field> or Calculated... button on the Fields page of the Table Records Properties dialog box.

Dialog Box Options

Name

Enter a name for the calculated field. The maximum length of the name is 32 characters.

Expression

Enter the expression to perform the calculation. The expression usually includes the name of at least one field in the table. Click [image] to create an expression in the Expression Builder.


See Also

Fields Properties


Field Properties Dialog Box

See Also

Sets properties for the field selected in the Selected Fields list of the Fields Page (Table Records Properties dialog box).

To display this dialog box, click the Properties... button on the Fields page of the Table Records Properties dialog box.

Dialog Box Options

Heading

Enter a heading for the field column. If you leave this blank, the heading is the field name. The maximum width of the heading is 127 characters.

Template

Specifies one or more symbols that format data entered into this field. For example, you can convert to uppercase. Click [image] to choose symbols with the Choose Template dialog box.

When

Enter a condition that allows the field to be edited. The condition should be an expression that, when it evaluates to True, allows editing of the field. (This often depends on the value of another field.) Click [image] to create an expression in the Expression Builder.

Width

Enter the display width of the selected field. If you leave this blank, the full width of the field appears.

Read-Only

Creates a field that cannot be edited.

Valid Expression

Enter an expression that determines whether an entry in the field is valid. Click [image] to create an expression in the Expression Builder.

Valid Error Message

Enter an error message to display if the data entered in the field is invalid because the Valid Expression evaluated to False.

Required

Turn on the Required option to prevent users from leaving the field until valid data is entered.

Lower Limit

Enter an expression that represents the lowest of a valid range of values. Click [image] to create an expression in the Expression Builder.

Upper Limit

Enter an expression that represents the highest of a valid range of values. Click [image] to create an expression in the Expression Builder.

Required

Turn on the Required option to prevent users from leaving the field until valid data is entered. To choose a range of values that are valid, use the Lower Limit and Upper Limit boxes.


See Also

Fields Properties

Expression Builder


Choose Template Dialog Box

See Also

Applies a data entry formatting template to the selected field.

You can use symbols from more than one page of this dialog box to form one template.

Dialog Box Options

Template

Displays the formatting symbols for the data entry template. You can apply more than one data entry template to a field. Templates for the same field can be any combination of character, number, or date symbols. You can use the list boxes to create or edit the template.

Description

Describes the symbol selected in the Template Symbols and Format Functions list.

Character

Defines the format for character data.

Numeric

Defines the format for numeric data.

Date

Defines the format for date data.

Paste

Pastes the symbol selected in the Template Symbols and Format Functions list into the Template box.


See Also

Fields Properties

Field Properties Dialog Box


Character Template Symbols

See Also

Lists symbols for formatting character data in the selected field.

Template Symbols and Format Functions

Displays the symbols you can enter in the Template box that apply to characters.

Symbol	Description

@!	Converts any letter to uppercase.

@A	Allows the input of letters only.

@R	Causes literal placeholders not to be stored as data.

@T	Trims leading and trailing blanks for display.

!	Converts input and display of characters to uppercase.

#	Allows input of a number, space, +, or -.

9	Allows input of a number for a character value, or a number, +, or - for numeric value.

A	Allows input of a letter.

L	Allows input and display of T, t, F, f, Y, y, or N, n.

Y	Allows input of Y, y, N, and n. Displays .T., T, t, and y as Y; .F., F, f, and n as N.

X	Leaves the character unchanged. Use X as a placeholder with other picture templates.


See Also

Fields Properties

Choose Template dialog box

Numeric

Date


Numeric Template Symbols

See Also	Language

Lists symbols for formatting numeric data in the selected field.

Template Symbols and Format Functions

Displays the symbols you can enter in the Template box that apply to numbers.

Symbol	Description

@$	Displays the currency character before or after the value.

@Z	Displays spaces rather than zeros if the value is 0.

@^	Displays the value in scientific notation.

$	Displays the currency character before or after the value.

*	Displays * in all blank positions before the value.

,	Inserts a comma in the thousands place.

.	Inserts a decimal point in this position.

9	Allows input of a number for a character value, or a number, +, or - for a numeric value.

The currency character and the position of it (left or right) are set by the Currency Symbol and Currency Position options on the Country page of the Desktop Properties dialog box.


See Also

Fields Properties

Choose Template dialog box

Character

Date


Language

SET CURRENCY


Date Template Symbols

See Also	Language

Lists symbols for formatting date data in the selected field.

Template Symbols and Format Functions

Displays the symbols you can enter in the Template box that apply to dates.

Symbol	Description

@D	Displays the date in the current date format.

@E	Displays the date in the European format - dd/mm/yy.

The date format is set on the Country page of the Desktop Properties dialog box.


See Also

Fields Properties

Choose Template dialog box

Character

Numeric


Language

SET DATE


Records Properties

See Also

Contains options for displaying records in the Table Records Window.

Append

Allows addition of records to this table.

Edit

Allows editing of records in this table.

Delete

Allows deletion of records in this table.

Follow Index

Follows a record to its new location in the index when you change the value of an indexed field in the master index.

Index Range - Low Key, High Key

Specifies an expression of the same type as the current master index. Only records with key values matching or coming after the Low Key value are displayed. If you enter a value in the High Key box, only records falling between Low Key and High Key are displayed. If Exclude is checked, records with the exact values of Low Key and High Key are excluded from the display, but records falling between them still appear. Click [image] to create an expression in the Expression Builder.

Exclude

Displays only records that fall between the values in the Low Key and High Key boxes. The display is non-inclusive.

Scope

The Scope panel gives you options for specifying the scope of the operation. This panel is described in Scope Panel. If you are using Browse layout, the Next and Record options in the Scope panel are not available.


See Also

Properties|Table Records Window...

Expression Builder Tasks


Window Properties (Table Records Properties dialog box)
Window Properties

See Also

Contains options for configuring and displaying records in the Table Records Window. Options include

Choosing the window title

Data entry operations you want to prevent

Freezing and locking columns

Title

Enter a new title for the Table Records window.

Toggle Layout

Allows or disallows toggling between Browse, Form, and Columnar layouts.

Horizontal Grid

Displays horizontal grid lines in Browse layout. Check Horizontal Grid to turn the display on.

Vertical Grid

Displays vertical grid lines in Browse layout. Check Vertical Grid to turn the display on.

Lock

Fixes a specified number of fields on the left side of Browse layout.

Width

Sets a uniform display width for character fields.

Freeze

Restricts editing and cursor movement to the selected field. You can change to another record, but not to another field in the record. Click the drop-down button to choose a field to freeze from the list. Choose <None> to unfreeze a field.


See Also

Properties|Table Records Window...


View Menu (Table Records Window)

See Also

Use the View menu in the Table Records window or Query Results window to run or design a table or query, to toggle between Browse, Form, and Columnar layouts, or to open a memo field in the Text Editor.

Choose from the following commands:

Table Records	(Table Records window only)

Table Structure	(Table Records window only)

Query Results	(Query Results window only)

Query Design	(Query Results window only)

Browse Layout

Form Layout

Columnar Layout

Field Contents


See Also

Displaying and Editing Table Records

Text Editor

Running Queries


View | Table Records

See Also

Displays the current table in the Table Records window, where you can view or modify table data.

The Table Records window provides one view of the current table. You can also switch to the Table Designer, another view of the current table, where you can view or modify the table structure. Open the Table Designer with View|Table Structure.

Because the Table Records window and Table Designer provide different views of the table, only one of them can be open at a time. The current view is indicated by a checkmark in the View menu.

You can set the default layout for editing and adding records. Choose Properties|Desktop, click the Files tab, then choose the layouts you want.

Shortcuts

Menu:	Navigator|Edit Records (from selected table)
Catalog|Edit Records (from selected table)

SpeedBar:
 (from selected table in Navigator or Catalog window)

SpeedMenu:	Edit Records (from selected table in Navigator or Catalog window)

Keyboard:	F2 (from selected table in Navigator or Catalog window)

Mouse:	Double-click the table file in Navigator or Catalog window.
Drag the table file from Navigator or Catalog window into the Desktop or Command window.


See Also

View Menu (Table Records Window)

View|Table Structure


View | Table Structure

See Also

Displays the current table in the Table Designer, where you view or modify the table structure.

The Table Designer provides one view of the current table. You can also switch to the Table Records window, another view of the current table, where you can view or modify the table data. Open the Table Records window with View|Table Records.

Because the Table Records window and Table Designer provide different views of the table, only one of them can be open at a time. The current view is indicated by a checkmark in the View menu.

Shortcuts

Menu:	Navigator|Design Table Structure (from selected table)
Catalog|Design Table Structure (from selected table)

SpeedBar:
 (from selected table in Navigator or Catalog window)

SpeedMenu:	Design Table Structure (from selected table in Navigator or Catalog window)

Keyboard:	Shift+F2 (from selected table in Navigator or Catalog window)

Mouse:	Double-right-click the table file in the Navigator or Catalog window.


See Also

View Menu (Table Records Window)

View|Table Records


View | Browse Layout

See Also

Selects the Browse layout, which displays several records at the same time.

The following example shows Browse layout:

In addition to using Browse layout, you can use the other Table Records window layouts to look at your data in different ways:

View|Form Layout displays one record at a time, with fields arranged contiguously.

View|Columnar Layout displays one record at a time with the fields arranged vertically.

The current layout of a table is indicated by a checkmark in the View menu.

You can set the default layout for editing and adding records. Choose Properties|Desktop, click the Files tab, then choose the layout you want.

Shortcuts

SpeedBar:

Keyboard:	F2


See Also

View Menu (Table Records Window)

Table Records Window Components

Displaying and Editing Table Records

View|Columnar Layout

View|Form Layout


View | Form Layout

See Also

Selects the Form layout, which displays one record at a time, with fields arranged contiguously.

The following example shows Form layout:

In addition to using Form layout, you can use the other Table Records window layouts to look at your data in different ways:

View|Browse Layout displays several records at the same time.

View|Columnar Layout displays one record with the fields arranged vertically.

The current layout of a table is indicated by a checkmark in the View menu.

You can set the default layout for editing and adding records. Choose Properties|Desktop, click the Files tab, then choose the layout you want.

Shortcuts

SpeedBar:

Keyboard:	F2


See Also

View Menu (Table Records Window)

Displaying and Editing Table Records

Table Records Window Components

View|Browse Layout

View|Columnar Layout


View | Columnar Layout

See Also

Selects the Columnar layout, which displays one record with the fields arranged vertically.

The following example shows Columnar layout:

In addition to using Columnar layout, you can use the other Table Records window layouts to look at your data in different ways:

View|Browse Layout displays several records at the same time.

View|Form Layout displays one record at a time, with fields arranged contiguously.

The current layout of a table is indicated by a checkmark in the View menu.

You can set the default layout for editing and adding records. Choose Properties|Desktop, click the Files tab, then choose the layout you want.

Shortcuts

SpeedBar:

Keyboard:	F2


See Also

View Menu (Table Records Window)

Displaying and Editing Table Records

Table Records Window Components

View|Browse Layout

View|Form Layout


View | Field Contents

See Also

Opens the current memo field, binary field, or OLE field in the appropriate window so you can view or edit data. The Table Records window indicates memo, binary, and OLE fields with an icon.

Memo Fields

A blank icon indicates that the memo field is empty. An "A" icon indicates that the memo field contains data.

	Empty Not empty
When you open the memo field, it appears in the Text Editor. See Editing Text for more information.

Binary and Graphic Fields

A dimmed icon indicates that the dBASE binary or Paradox graphic field is empty. If the binary field contains data, one of three icons appears: image, sound, or user-defined. If the graphic field contains data, the image icon appears.

	Empty Image Sound User-defined
When you open an empty dBASE binary field, the Empty Binary Field dialog box appears. Choose Image Viewer to store an image in the field. Choose Sound Player to store a sound in the field.

When you open a nonempty binary or graphic field, the window corresponding to the type of data in the field appears. See Displaying Images and Playing Sounds for more information. If the field contains user-defined data, dBASE cannot display it.

OLE Fields

A dotted outline icon indicates that the OLE field is empty. If the OLE field contains data, "OLE" appears in the dotted outline.

	Empty Not empty
When you open an OLE field, the OLE document appears in the OLE Viewer window. See Displaying and Editing OLE Documents for more information.

The View|Field Contents command is available only when a memo, binary, or OLE field is selected in the Table Records window.

Shortcuts

Keyboard:	F9

Mouse:	Double-click the icon.


See Also

View Menu (Table Records Window)

Text Editor


Designing Table Structures

See Also

In dBASE for Windows, you create, modify, or view the structure of a table using the Table Designer window.

Table Designer Concepts and Tasks

Choose from the following list for information about the Table Designer.

Using the Table Designer - Overview

Table Designer Tasks

Table Designer Tools

The Table Designer has menus, a SpeedBar, and a SpeedMenu. Choose from the following list for more information about these topics:

Components	Description of the Table Designer window

Menus	Lists and descriptions of all Table Designer menu commands

SpeedBar	Descriptions of the Table Designer SpeedBar options

SpeedMenu	List and description of the Table Designer SpeedMenu


See Also

About Tables

Displaying and Editing Table Records


Using the Table Designer - Overview

See Also

You work with tables in two windows. The Table Records window is where you edit and display records. The Table Structure window, or Table Designer, is where you create the structure of a table.

Before you can store data or information in a table, you must plan and create the table structure. The structure defines the rows and columns of the table. The rows and columns categorize and organize the data.

Typically, you define the table structure once, before you add data to the table. But if you change your mind and want to change the table structure, even after adding data, you can. Both defining a table structure and changing the structure later are accomplished with the Table Designer.

Table Files

When you create and name a dBASE table, it has the DOS file extension .DBF. If the table has memo, binary, or OLE fields, this data is stored in a .DBT file.

When you create and name a Paradox table, it has the DOS file extension .DB. If the table has memo, binary, OLE, or graphic fields, this data is stored in an .MB file.

Table Structure Backup Files

Before you change a dBASE table structure, dBASE for Windows makes a backup copy of the original table (.DBF) using the same file name as the original table with a .DBK extension. If data is accidentally truncated or lost, you can recover the original data from the .DBK file. Before modifying the structure of a table, make sure you have sufficient disk space to create the backup file (another complete copy of the table).

If a dBASE table contains a memo, binary, or OLE field, dBASE creates a backup file. The backup file has the same file name as the original memo file (.DBT) with a .TBK extension. If the new .DBT file is accidentally damaged, you can recover the .TBK file.

If a dBASE table contains a multiple index file, dBASE creates a backup file. The backup file has the same file name as the original multiple index file (.MDX) with a .MBK extension.

When you change the structure of a Paradox table, no backup of the table is made.

Exclusive Use

You must have exclusive use of a table to modify its structure. If you do not have exclusive use, when you attempt to modify the table structure, dBASE displays the Table Not Exclusive dialog box.

Another way to get exclusive access to a table is to check Exclusive in the Desktop Properties dialog box before opening the table.


See Also

About Tables

Index Concepts

Displaying and Editing OLE Documents - Overview

When to Use Binary and OLE Fields

Table Designer Components

File Extensions Supported in dBASE for Windows

Rules for Modifying Table Structures


Table Designer Tasks

See Also

Choose from the following list for information about how to use the Table Designer:

Opening and Closing the Table Designer

Creating a Table Structure

Modifying a Table Structure

Rules for Modifying Table Structures

Viewing a Table Structure


See Also

Table Records Window Tasks

Creating a Simple Index in the Table Designer

Creating a Primary Paradox Index in the Table Designer


Opening and Closing the Table Designer

See Also	Language

To open the Table Designer, do any of the following:

Choose File|New|Table.

Choose File|Open, select a table, and click Design Table Structure. Choose OK.

Select the Tables file type in the Navigator or Catalog window, then double-click the Untitled table icon. This creates a new table.

Right-click a table icon in the Navigator or Catalog window, then choose Design Table Structure from the SpeedMenu.

From within the Table Records Window, choose View|Table Structure.

If you do not have exclusive use of the table, when you attempt to modify the table structure, dBASE displays the Table Not Exclusive dialog box.

To close the Table Designer, do any of the following:

Choose File|Close or press Ctrl+F4.

Choose File|Save and Close or press Ctrl+W.

Choose File|Abandon and Close or press Ctrl+Q.

Double-click the Control-menu box.

Choose View|Table Records to close the Table Designer and open the Table Records Window, or press F2.


See Also

Using the Table Designer - Overview

Basics: Introduction to the dBASE Navigator

Navigator Tasks

Basics: Introduction to the Catalog Window

Catalog Window Components


Language

CREATE

MODIFY STRUCTURE


Creating a Table Structure

See Also	Language

To create a table structure,

1.	Choose File|New|Table. The Table Designer appears.

2.	Select a table type from the Type list box. If you choose an SQL table type, the Select Database dialog box appears. Choose the database to add this table to.

3.	Define each field of the table. The field information includes Name, Type, Width, Decimal, and Index.

4.	Choose File|Save and Close.

5.	Enter the name and location for the new table in the Save Table dialog box. For general information about naming and saving files, see Save As dialog box.

6.	Choose Add, Generate, or Done from the Add or Generate Records dialog box.

Once the table exists, you can open it from the Navigator or Catalog window and add or edit records.

See Table Designer Components for a description of the options in the Table Designer window.


See Also

Display-Only Fields

Table Designer Components


Language

CREATE


Add or Generate Records Dialog Box

Adds or generates records in a newly created table.

Dialog Box Options

Add

Opens the Table Records window and displays a blank record. Enter the new data in the blank record. This option is equivalent to choosing Table|Add Records from the Table Records window or Command window.

Generate...

Opens the Generate Records dialog box. Specify how many records you want dBASE to generate. dBASE adds the records and fills the fields with random sample data. This option is equivalent to choosing Table|Table Utilities|Generate Records from the Table Records window or Command window.


Modifying a Table Structure

See Also	Language

To modify the structure of a table,

1.	Open the table in the Table Designer.

2.	Change any of the existing information. Create new fields for the table. Delete existing fields from the table.

3.	Save the table structure with File|Save or File|Save As.

See Rules for Modifying Table Structures for restrictions on the changes you can make when you restructure a table.

You can move and resize the columns in the field definition area the way you resize columns in tables.

See Table Designer Components for a description of the options in the Table Designer window.


See Also

Opening and Closing the Table Designer

Rules for Modifying Table Structures

Table Designer Components

Viewing a Table Structure


Language

MODIFY STRUCTURE

SET EXCLUSIVE

USE


Rules for Modifying Table Structures

See Also	Language

When you modify the structure of a table, dBASE creates a new table structure and fills it with data from the old structure. To copy data, dBASE matches the field name; and then, in cases where the field name has been changed, by matching field position, width, and type. Here are some restrictions on changing field names.

Do not change the name of a field and its width or type at the same time.

If you do, dBASE for Windows does not append data from the old field, and your new field is blank. Instead, change the name of a field, save the file, and then use the Table Designer again to change the width or type of the field.

Do not insert or delete fields from a table and change field names at the same time.

When you change field names, the Table Designer uses the field position to append data from the old file. If you insert or delete fields when you change field names, you can lose data because the field positions change.

You can change the width or type of fields and at the same time insert or delete fields, because the Table Designer appends data by field name in those situations.

Indexes

When you save changes to a table structure, dBASE for Windows creates a new table with the changed structure, opens the table, and adds the data. If you modified the name, width, or type of any field that has an index tag in the production index (.MDX) file, the index is automatically rebuilt. However, you should choose the master index order again after you modify a table structure using Table|Table Utilities|Manage Indexes.

Converting Field Types

dBASE for Windows attempts to convert data if you change a field type, but the conversion must be a sensible one or data might be lost. If you change field types, keep a backup copy of your original table and check your new table to make sure the data was converted correctly.

Conversions with Numeric and Character Fields

If you convert a numeric field to a character field, dBASE for Windows converts the numeric data to right-aligned character strings.

If you convert a character field to a numeric field, dBASE for Windows converts each characters to a digit until it encounters a non-numeric character. If the first character in a character field is a letter, the converted numeric field contains zero. The numeric value will be right-aligned.

Conversions with Logical Fields

You can convert Logical fields to Character fields, and vice-versa. You cannot convert logical fields to numeric fields unless you use the dBASE language.

Conversions with Date and Character Fields

You can convert character strings that are formatted as dates (such as mm/dd/yy or mm-dd-yy) to date fields. You can also convert date fields to character fields.

If you want to convert incompatible data types (such as logical to numeric), first add a new field to the file, then choose Table|Replace Records to convert the data, then delete the old field.


See Also

Modifying a Table Structure


Language

CREATE

IIF( )

MODIFY STRUCTURE

REPLACE


Viewing a Table Structure

See Also	Language

By default, when you open the Table Designer, you can modify the structure of a table. However, if you open a table in the Table Records window, and then change views to the Table Designer, you can either view or modify the structure of the table.

When you view a table structure, the Table Designer displays the structure of the table. You can examine the structure of the table, but you cannot modify it.

To view a table structure while editing records in the Table Records window,

1.	Choose View|Table Structure.

2.	Choose View Only in the Table Not Exclusive dialog box.

See Table Designer Components for a description of the options in the Table Designer window.


See Also

Display-Only Fields

Table Designer Components

Displaying and Editing Table Records


Language

DISPLAY STRUCTURE

LIST STRUCTURE

USE


Table Designer Components

See Also

In the Table Designer window, you enter or view information about the structure of a table. This information includes the name and type of the table, and the name and description of each field in the table.

The following example shows the Table Designer:

To create or modify the structure of a table, use the Table Designer to enter or change the following information:

Table Name	Specifies the name of the table

Table Type	Specifies the type of table (available only when creating a table)

Field Name	Specifies the name of the field.

Field Type	Specifies the type of field in the table structure

Field Width	Specifies the width of the field

Decimal	Specifies the number of decimal places for the Numeric and Floating point fields

Index	Specifies the type of index associated with character, numeric, floating point, or date fields

The remaining fields are for display only and are described in Display-Only Fields.

You can also create and modify index tags with Structure|Manage Indexes.

Status Bar

As you edit the table structure, the status bar displays the following information:

Name of the current table

The lock status of the current table, if any:

Excl: the table is exclusive to you

Rdnly: the table is read-only

Current field number and the total number of fields in the table


See Also

Creating a Table Structure

Table Designer Menus

Modifying a Table Structure

Rules for Modifying Table Structures

SpeedBar

SpeedMenu

Viewing a Table Structure


Table Name

See Also

Specifies the table to modify in the Table Designer.

Select the name of the table by using the drop-down button to choose from a list of open tables. By default, the table name is the most recently used table or the table you selected to design.

If you are creating a new table, this option is unavailable.


See Also

Table Designer Components


Table Type

See Also

Specifies the type of table that is open in the Table Designer.

Select the type of the table by using the drop-down button to choose from a list of available table types. You can specify the following table types in dBASE for Windows:

dBASE specifies a dBASE for Windows, dBASE IV, or dBASE III PLUS table.

Paradox specifies a Paradox for Windows, Paradox 4.5, Paradox 4.0, or Paradox 3.5 table.

Other types might appear, such as INTRBASE, ORACLE, or SYBASE, if you are connected to SQL database servers.

When you are modifying an existing table, you cannot change the table type. To copy to a table of another type, use Table|Table Utilities|Export Records.

You can use the IDAPI Configuration Utility to specify which dBASE or Paradox table type to create and use. By default, the dBASE table type is set to dBASE for Windows. When you save your changes, dBASE validates that the selected field types apply to the current table type.


See Also

Table Designer Components

Table|Table Utilities|Export Records...


Field Name

See Also	Language

Specifies the name of the field in the table.

Enter or change the name of the field. Each field name in a table must be unique. You cannot make a name unique by

Adding a blank space at the end of the name

Changing the case of the name, for example from uppercase to lowercase

You must enter the field name before you can enter the type, width, or index for the field.

dBASE Tables

If you are working with a dBASE table, the field name has the following restrictions:

The name can be up to 10 characters in length.

The first character must be an alphabetic character.

The name can use alphanumeric characters and the underscore character.

The name cannot contain embedded blank characters.

The field name, _DBASELOCK, is reserved. This field stores multiuser lock information.

Paradox Tables

If you are working with a Paradox table, the field name has the following restrictions:

The name can be up to 25 characters in length.

The first character cannot be a space, unless it is enclosed in quotation marks.

The name cannot contain the following characters:

Brackets [ ], braces { }, or parentheses ( ).

The combination ->.

The # character by itself. You can combine # with other characters, as in the field name Phone #.

The name can contain embedded blank characters.


See Also

Table Designer Components


Language

CONVERT


Field Type

See Also

Specifies the type of the field in the table structure.

Enter or change the type of the field or use the drop-down button to choose from a list of available types.

dBASE Tables

If you are working with a dBASE table, you can specify one of the following field types:

Character fields accept letters, numbers, punctuation marks, and any other symbols, including spaces.

Numeric fields accept numeric data and optionally, a decimal point.

Float fields accept numeric data and optionally, a decimal point.

Logical fields accept T and F (for True or False or Y and N (for Yes and No). You can use any combination of T, F, Y, and N (uppercase or lowercase) when you enter data.

Date fields accept data in the format specified by the Date page of the IDAPI Configuration Utility.

Memo fields accept alphanumeric data.

OLE fields accept Object Linking and Embedding (OLE) documents.

Binary fields accept binary data in the form of images, sounds, and user-defined data.

Paradox Tables

If you are working with a Paradox table, you can specify one of the following field types:

Alpha contains letters, numbers, special symbols (such as %, &, #, and =), or any other printable character.

Number contains numbers in the range -10 ^ 307 to 10 ^ 308 of up to 15 significant digits. Number fields are best used when you want to perform calculations on the values in the field.

Money contains numbers in the range -10 ^ 307 to 10 ^ 308 of up to 15 significant digits. Money fields are exactly like number fields, but are formatted to display decimal places and a money symbol.

Date contains any valid date (including BC dates) to December 31, 9999.  Leap years and leap centuries are correctly handled and all dates are checked for validity.

Paradox Date fields contain data in the format specified by the Date page of the IDAPI Configuration Utility.

Short contains whole numbers in the range -32,767 to 32,767. Short fields do not allow the same formatting options as number fields, and should be used only by advanced users.

Memo contains any printable character.

Fmtmemo (formatted memo) recognizes and stores text attributes (different typefaces, styles, colors, and sizes) as well as formatting preferences (such as tabs, line returns, and alignment) and stores them with the data.

Binary contains data that cannot be interpreted. A common use of a binary field is to store sound.

Graphic contains pictures. You can create graphics in a painting or drawing application, or scan existing images and use them as values in a graphic field.

OLE contains objects placed in your table from other Windows applications that support OLE (Object Linking and Embedding) as a server. The advantage of using the OLE field type to place data is that, through OLE, you can access and make changes to the OLE object.

Time contains times of day, stored in milliseconds since midnight, and limited to 24 hours.

Timestamp contains both a date and time value. Rules for this field type are the same as those for date fields and time fields.

Long is a 32-bit signed integer. Contains whole numbers (nonfractional) with accuracy in the range 2147483647 to -2147483647 (+/- 2 ^ 31 - 1). Long integer fields require more space to store than short fields.

Logical contains values representing true or false (yes or no). Valid entries include T and F (case is not important).

Bytes contains data that cannot be read or interpreted. A common use of a bytes field is to store bar codes or magnetic strips. Unlike binary fields, bytes fields are stored in the Paradox table (rather than in the .MB file), allowing for faster access.

BCD contains numeric data in a BCD (Binary Coded Decimal) format. The BCD field type is provided primarily for compatibility with other applications that use BCD data.

Use BCD fields when you want to perform calculations with a higher level of precision than that available with the use of other numeric fields. Calculations on BCD fields are not performed as quickly as those on other numeric fields.

Autoincrement contains non-editable numbers. The first field begins with the number 1 and adds one number for each record in the table. Deleting a record does not change the field values of other records. A table can contain only one autoincrement field.


See Also

Table Designer Components

Data Types


Field Width

See Also

Specifies the width of the field.

dBASE Tables

Enter or change the width of the field for character, numeric, and floating point fields by specifying the maximum number of characters or digits the field can contain.

Character fields can be 254 characters.

Numeric and floating-point fields can be 20 digits, with up to 18 decimal places. The decimal point uses 1 digit in the width. Unlike dBASE IV, there is no difference in the way dBASE for Windows processes numeric or float data. In mathematical operations, dBASE for Windows provides the same precision level (19 digits) for both types.

The Table Designer automatically specifies a width for the following field types:

Logical fields have a width of 1 character.

Date fields have a width of 8 characters.

Memo, binary, and OLE fields have a width of 10 characters in the table. Data entered in memo and binary fields is not stored in the table; it is stored in the associated .DBT file. Data entered in OLE fields is stored in the .DBT file if the OLE document is embedded. Otherwise, the data is stored in the external file and the link information is stored in the .DBT file.

Paradox Tables

Enter or change the width of the field for alphanumeric, memo, formatted memo, binary, graphic, and OLE fields by specifying the maximum number of characters the field can contain.

Alpha fields can contain up to 255 characters.

Memo, formatted memo, binary, graphic, and OLE fields can contain up to 240 characters in the table, although the field entry is limited only by the disk space available on your system. Data entered in these fields is stored outside the table (in the .MB file).

Bytes can contain up to 255 characters.

BCD can contain up to 32 digits.

The field size is not applicable for all other field types.


See Also

Table Designer Components


Decimal

See Also

Specifies the number of decimal places for numeric and floating point fields.

dBASE Tables

Enter or change the value for the number of decimal places for numeric and floating-point fields. You cannot specify a decimal value for other field types.

Paradox Tables

Decimal is not applicable to Paradox tables.


See Also

Table Designer Components


Index

See Also

Specifies the indexed fields in the table. The indexed fields, also known as key fields, become individual index tags in the table index. See About Tables for more information about indexes.

dBASE Tables

In a dBASE table, you can index on character, numeric, floating point, or date field types. You cannot specify an index for memo, logical, binary, or OLE field types.

dBASE indexes created with the Table Designer are stored in an .MDX file with the same name as the table.

Select the type of index by using the drop-down button to choose from a list of available types. You can create the following types of dBASE indexes from the Table Designer:

None specifies that the field has no index.

Ascend specifies that the field has an ascending index. For example, a numeric field with an ascending index sorts 8, 9, 10, and so forth.

Descend specifies that the field has a descending index. For example, a numeric field with an descending index sorts 10, 9, 8, and so forth.

Paradox Tables

In a Paradox table, you can index on all field types except memo, binary, formatted memo, OLE, and graphic. The field you choose to become the primary key field must be the first field in the table structure. If the primary key will contain multiple field names, they must appear in succession in the table structure.

Paradox primary-key indexes created with the Table Designer are stored in a .PX file with the same name as the table.

Select the type of index by using the drop-down button to choose from a list of available types. You can choose the following Paradox index types from the Table Designer:

None specifies that the field has no index.

Primary specifies that this is a key field of the table. You can set the Index option to Primary on more than one field, but they must be consecutive in the structure.


See Also

Table Designer Components

Index Concepts


Display-Only Fields in the Table Designer
Display-Only Fields

See Also

The following fields in the Table Designer window display information about the table structure:

Updated displays the date that the data in the table was last modified.

Records displays the number of records in the table.

Bytes Used displays the size of the table in bytes.

Bytes Left displays the amount of space remaining for defining the table structure


See Also

Table Designer Components

.DBF Table Specifications


Table Designer Menus

The Table Designer has the following menus:

File Menu

Edit Menu

View Menu

Structure Menu

Properties Menu

Window Menu

Help Menu


Table Designer SpeedBar

The SpeedBar is the row of buttons beneath the menu bar. Each button represents a menu command. Click the button representing the command you want to execute.

Button	Action	Menu Equivalent
	Creates a new dBASE-related file	File|New
	Opens a dBASE-related file	File|Open
	Saves a table structure	File|Save
	Prints a table structure	File|Print
	Removes the selected text/object and places it on the Clipboard	Edit|Cut
	Copies the selected text/object onto the Clipboard	Edit|Copy
	Inserts the text/object into the active window	Edit|Paste
	Changes to the Table Records window	View|Table Records
	Changes to the Table Designer	View|Table Structure
	Adds a field to the end of the table	Structure|Add Field
	Inserts a field before the selected field	Structure|Insert Field
	Deletes the selected field	Structure|Delete Selected Field
	Switches to the Navigator window	Window|Navigator
	Switches to the Command window	Window|Command
	Opens the Form Expert	Help|Experts|Form Expert
	Opens the Interactive Tutors	Help|Interactive Tutors


Table Designer SpeedMenu

Use the Table Designer SpeedMenu to quickly perform a common operation in the Table Designer.

To use the Speed Menu, right-click anywhere in the Table Designer.

Choose from the following commands:

Table Structure Window Properties...

Cut

Copy

Paste

Add Field

Insert Field

Delete Selected Field


Edit Menu (Table Designer)

See Also

Use the Edit menu to perform editing operations and to copy or remove text.

The Edit menu works differently in each of the windows. The most common use of the Edit menu is to work with text, for example, to move text around or to delete text. For information about using the Edit menu in different windows, see Where the Edit Menu Works.

You can cut, copy, or paste text using the Clipboard. The Clipboard is a temporary storage area for information you want to move or copy from one location to another.

Choose from the following commands:

Undo or Redo

Cut

Copy

Paste

Delete

Select All


See Also

Designing Table Structures


File Menu (Table Designer)

See Also

Use the File menu to create new files, open and run existing files, and exit dBASE for Windows.

The New and Open commands manipulate the primary file types, such as tables, queries, and forms. The New command displays a menu allowing you to choose the type of file you want to create. The Open command lets you run or design an existing file.

You can open as many files as you like, and each appears in its own window. However, the Navigator and Command windows are unique and cannot be opened more than once.

From the Table Designer, you can also save, close, or abandon your changes to the current table structure, and print the current table structure or set up the printer.

Choose from the following commands:

New

Open...

Save

Save As...

Save and Close

Abandon and Close

Close

Print...

Printer Setup...

Exit

(closed file list)


See Also

Designing Table Structures


File | Save

See Also

Saves the active file using its current name and location.

If the active file does not have a name, this menu command displays a Save As dialog box. In the Table Designer, the dialog box displayed is the Save Table dialog box. In the Query Designer, the dialog box displayed is the Save File dialog box.

Shortcuts

SpeedBar:

Keyboard:	Ctrl+S


See Also

File Menu (Form Designer)

File Menu (OLE Viewer)

File Menu (Query Designer)

File Menu (Table Designer)

File Menu (Text Editor)

File|Abandon and Close

File|Close

File|Save and Close

File|Save As


File | Save As...

See Also

Saves the active file using a new name or location.

This menu command displays a Save As dialog box in which you specify the name and location of the file. In the Table Designer, the dialog box displayed is the Save Table dialog box. In the Query Designer, the dialog box displayed is the Save File dialog box.


See Also

File Menu (Form Designer)

File Menu (Query Designer)

File Menu (Table Designer)

File Menu (Text Editor)

File|Abandon and Close

File|Close

File|Save

File|Save and Close


Save As Dialog Box

Saves the current file using the name, location, and type that you specify.

Use the Save As dialog box to save a file under a new name or in a new location. Select the drive and directory in which to save your file, then specify a file name and type.

Dialog Box Options

File Name

Specifies the name of the file.

If the active file has never been saved, dBASE does not supply a file name. Enter the file name.

If the active file has previously been saved, dBASE uses the current file name as a default.

File Type

Specifies the types of files displayed in the File Name box. Select the type of file by using the drop-down button to choose it from the list of available file types.

Directory

Specifies the full path and directory in which to save the file. Choose the path and directory by double-clicking the appropriate directory. By default, the Save As dialog box uses the current directory.

Drives

Specifies the letter of the drive on which to save the file. Select the letter of the drive by using the drop-down button to choose it from the list of available drives. By default, the Save As dialog box uses the current drive.


File | Save and Close

See Also

Closes the active file and saves it using the current name and location.

If the active file does not have a name, this menu command displays a Save As dialog box. In the Table Designer, the dialog box displayed is the Save Table dialog box. In the Query Designer, the dialog box displayed is the Save File dialog box.

Shortcuts

Keyboard:	Ctrl+W


See Also

File Menu (Form Designer)

File Menu (OLE Viewer)

File Menu (Query Designer)

File Menu (Table Designer)

File Menu (Text Editor)

File|Abandon and Close

File|Close

File|Save

File|Save As


File | Abandon and Close

See Also

Closes the active file without saving it and abandons any changes without warning.

Shortcuts

Keyboard:	Ctrl+Q


See Also

File Menu (Form Designer)

File Menu (OLE Viewer)

File Menu (Query Designer)

File Menu (Table Designer)

File Menu (Text Editor)

File|Close

File|Save

File|Save and Close

File|Save As


Table Not Exclusive Dialog Box

Language

Prompts you to open a table exclusively before modifying its structure.

You must have exclusive use of a table to modify its structure.

Dialog Box Options

Open Exclusive

Attempts to reopen the table exclusively. If successful, the Table Designer appears and you can modify the table structure. If unsuccessful, a message box appears. You cannot open a table exclusively if another user or another session is using the table.

View Only

Opens the Table Designer and lets you view the table structure without changing it.


Language

SET EXCLUSIVE

USE


Select Database Dialog Box

Use the Select Database dialog box to choose a database in which to add a new table.

This dialog box lists all databases available of the specified type. Choose a database, log on to it, then press OK.

Dialog Box Options

Available Databases

Specifies which database to add the table to. Choose a database from the list. If no databases appear in the list, then this database type has no aliases defined in the IDAPI Configuration Utility. See the SQL documentation for how to assign a database alias.

Login

Opens the Open Database dialog box so you can log on to the specified database server. You must be logged on to the database before you can add tables to it. The OK button is unavailable if you have not logged on to the selected database.


Properties Menu (Table Designer)

See Also

Use the Properties menu to change the characteristics of the dBASE for Windows Desktop and the Table Designer window.

Choose from the following commands:

Desktop...

Table Structure Window...


See Also

Designing Table Structures


Properties | Table Structure Window...

See Also

Controls the display of grid lines in the field definition section of the Table Designer.

dBASE records the choices you make in this dialog box in the DBASEWIN.INI file.

Shortcuts

SpeedMenu:	Table Structure Window Properties...

Dialog Box Options

Horizontal Grid Lines

Displays horizontal grid lines in the field definition section. Check Horizontal Grid Lines to turn the display on.

Vertical Grid Lines

Displays vertical grid lines in the field definition section. Check Vertical Grid Lines to turn the display on.


See Also

Properties Menu (Table Designer)


Structure Menu (Table Designer)

See Also

Use the Structure menu in the Table Designer to modify or navigate a table structure. You can add, insert, and delete fields, move to a specific field in a table you are designing, or change the indexes associated with the table.

Choose from the following commands:

Add Field

Insert Field

Delete Field

Go to Field Number...

Manage Indexes...


See Also

Designing Table Structures


Structure | Add Field

See Also

Adds a new field to the end of the list in the Table Designer. Enter the field name, type, width, and index.

The default formatting for the field that you add is the following:

Field Type is Character

Width is 10

Index is None

Shortcuts

SpeedBar:

SpeedMenu:	Add Field

Keyboard:	Ctrl+A


See Also

Structure Menu (Table Designer)

Structure|Delete Field

Structure|Insert Field


Structure | Insert Field

See Also

Inserts a new field before the current field in the Table Designer. Enter the field name, type, width, and index.

The default formatting for the field that you insert is the following:

Field Type is Character

Width is 10

Index is None

Shortcuts

SpeedBar:

SpeedMenu:	Insert Field

Keyboard:	Ctrl+N


See Also

Structure Menu (Table Designer)

Structure|Add Field

Structure|Delete Field


Structure | Delete Selected Field

See Also

Deletes the current field in the table.

If you accidentally delete a field, choose File|Abandon and Close to restore the table to its original state.

Shortcuts

SpeedBar:

SpeedMenu:	Delete Selected Field

Keyboard:	Ctrl+U


See Also

Structure Menu (Table Designer)

Structure|Add Field

Structure|Insert Field


Structure|Go to Field Number
Structure | Go to Field Number...

See Also

Moves the insertion point to the specified field in the Table Designer.

Shortcuts

Keyboard:	Ctrl+G

Mouse:	Click the field.

Dialog Box Options

Field

Enter the field number you want to move to or select it with the Up arrow button and Down arrow button.


See Also

Structure Menu (Table Designer)


View Menu (Table Designer)

See Also

Use the View menu in the Table Designer to edit the data in the table or edit the table structure.

Choose from the following commands:

Table Records

Table Structure


See Also

Designing Table Structures


Displaying and Editing OLE Documents

An OLE (Object Linking and Embedding) document is data from an external Windows application that can be stored in a dBASE or Paradox table. Once the data is stored in the table, you can view it in the OLE Viewer window. You can also access the original application directly from dBASE for Windows to view and edit the data. You use the OLE Viewer window to store, open, modify, and delete a document embedded in or linked to a field in a dBASE or Paradox table.

OLE Viewer Concepts and Tasks

Choose from the following list for information about using the OLE Viewer:

Displaying and Editing OLE Documents - Overview

OLE Viewer Tasks

When to Use Binary and OLE Fields

OLE Viewer Tools

The OLE Viewer has menus and a SpeedBar associated with it. Choose from the following list for more information about these topics:

Components	Description of the OLE Viewer window

Menus	Lists and descriptions of all OLE Viewer menu commands

SpeedBar	Descriptions of the OLE Viewer SpeedBar options

SpeedMenu	List and description of the OLE Viewer SpeedMenu


Displaying and Editing OLE Documents - Overview

OLE (Object Linking and Embedding) is a Windows feature you can use to store a document from one application inside the document of another application. A document containing another document is called a compound document. For example, you could store a company logo graphic inside a Quattro Pro spreadsheet.

OLE Clients and Servers

An OLE document, also called an OLE object, can be a graphic image, a sound, a spreadsheet, a word processing document, or any other document created by an external application that is an OLE server. An OLE server is an application or DLL that is prepared to embed or link its documents in another application document.

dBASE for Windows is an OLE client because it can store other OLE application documents inside its documents. In dBASE for Windows, the document that stores another document is an OLE field in a table. When you work with OLE documents, they appear in the OLE Viewer or in an OLE object on a form. You use the OLE Viewer to view, open, modify, and delete an OLE document in a field.

When you install a Windows application that is an OLE server, it registers itself as an OLE server in the Windows registration database. You can see a list of all OLE servers in your Windows environment when you use the OLE Viewer by choosing Edit|Insert Object. Alternatively, by running REGEDIT.EXE /V from the Windows Program Manager, you see a list of all OLE servers.

OLE Fields

In dBASE for Windows, you can store any type of OLE document in the field of a table. Both dBASE and Paradox tables have a field type for OLE documents. The field type is simply called OLE. You cannot add OLE documents to an SQL table.

You can have one or more OLE fields with different names in your table. See Table Designer Components for information on field types and field names. When you edit the records in the table, you open the OLE field and view the OLE document in it using the OLE Viewer window.

You can store different types of OLE documents in different records. For example, if you have a table with an OLE field called OLEDoc, the first record could have a picture, the next record a sound, the third record a spreadsheet, and so on.

Once data is stored in an OLE field, you can modify it in the external application by double-clicking the OLE Viewer window or by choosing the last menu command on the Edit menu. The menu command is worded differently for different types of objects. For example Edit|Paintbrush Picture Object appears for Paintbrush bitmaps. When you double-click the OLE Viewer, the external application that created the object opens and the document appears.

Linking and Embedding

The name, Object Linking and Embedding, comes from the two ways you can store an external document:

Link it to the field. The OLE document remains in an external file. The OLE field of the table stores information about where to find the external file on the disk. As long as the external file remains in the same location, you have access and can update the OLE field to the most recent version. Linking saves disk space because the OLE document is not duplicated in the table.

Embed it directly into the field. The OLE document, or a portion of it, is duplicated and stored inside the OLE field of the table. When you embed the OLE document, it is copied in its current state. Any future changes to the original version of the OLE document are not reflected in the embedded OLE document. The embedded data is stored in the .DBT file associated with the table.

Package Objects

A package is an object embedded in the OLE field. It contains, or encapsulates, another OLE document. Activating the package in turn activates the OLE document inside the package. The OLE document can be either embedded or linked in the package.

The package appears in the OLE Viewer as an icon representing the File Manager Association for the file extension. For more information about file associations, see your Windows documentation.

Double-clicking the file icon runs the application associated with the file extension and opens the file. You can also choose Edit|Package Object to edit the package information or open the application and file.


OLE Viewer Tasks

See Also

Choose from the following tasks for more information about how to use the OLE Viewer:

Adding an OLE Document to a dBASE or Paradox Table

Embedding an OLE Document

Linking an OLE Document

Inserting a Package Object


See Also

Table Records Window Tasks

Image Viewer Tasks

Sound Player Tasks


Adding an OLE Document to a dBASE or Paradox Table

See Also

To add an OLE document to the field of a dBASE or Paradox table,

1.	Open a dBASE or Paradox table containing an OLE field. The sample table PICTURES.DBF contains an OLE field.

2.	Minimize dBASE for Windows or switch to Windows Program Manager.

3.	Start the external application and open the OLE document you want to add.

4.	Select a portion of the OLE document and choose Edit|Copy to copy it to the Clipboard.

5.	Return to dBASE for Windows by double-clicking its icon.

6.	Choose the OLE field, then double-click it or choose View|Field Contents to open the OLE Viewer.

7.	Choose Edit|Paste or Edit|Paste Link to either embed or link the OLE document to the OLE field.


See Also

OLE Viewer Tasks

Embedding an OLE Document

Linking an OLE Document

Inserting a Package Object

Edit|Copy

Edit|Paste

Edit|Paste Link

View|Field Contents


Embedding an OLE Document

See Also

To embed a new OLE document,

1.	Open a dBASE or Paradox table containing an OLE field. The sample table PICTURES.DBF contains an OLE field.

2.	Double-click an OLE field to open the OLE Viewer. Add a blank record if necessary with Table|Add Records.

3.	Choose Edit|Insert Object, then choose the external application you want to use.

4.	Create the OLE document in the external application.

5.	Choose File|Update and File|Exit in the external application to save the file and return to dBASE for Windows.

To embed an existing OLE document,

1.	Open a dBASE or Paradox table containing an OLE field. The sample table PICTURES.DBF contains an OLE field.

2.	Double-click an OLE field to open the OLE Viewer. Add a blank record if necessary with Table|Add Records.

3.	Minimize dBASE for Windows.

4.	Start the external application and open the OLE document you want to embed.

5.	Select a portion of the OLE document and choose Edit|Copy to copy it to the Clipboard.

6.	Return to dBASE for Windows by double-clicking its icon.

7.	Choose Edit|Paste.


See Also

OLE Viewer Tasks

Linking an OLE Document

Inserting a Package Object

Edit|Insert Object

Edit|Copy

Edit|Paste

Table|Add Records


Linking an OLE Document

See Also

To link a new OLE document,

1.	Open a dBASE or Paradox table containing an OLE field. The sample table PICTURES.DBF contains an OLE field.

2.	Double-click an OLE field to open the OLE Viewer. Add a blank record if necessary with Table|Add Records.

3.	Minimize dBASE for Windows or switch to Windows Program Manager.

4.	Start the external application and create the OLE document.

5.	Select all or a portion of the OLE document and choose Edit|Copy to copy it to the Clipboard.

6.	Return to dBASE for Windows by double-clicking its icon.

7.	Choose Edit|Paste Link.

To link an existing OLE document,

1.	Open a dBASE or Paradox table containing an OLE field. The sample table PICTURES.DBF contains an OLE field.

2.	Double-click an OLE field to open the OLE Viewer. Add a blank record if necessary with Table|Add Records.

3.	Minimize dBASE for Windows or switch to Windows Program Manager.

4.	Start the external application and open the OLE document you want to link.

5.	Select all or a portion of the OLE document and choose Edit|Copy to copy it to the Clipboard.

6.	Return to dBASE for Windows by double-clicking its icon.

7.	Choose Edit|Paste Link.


See Also

OLE Viewer Tasks

Embedding an OLE Document

Inserting a Package Object

Edit|Insert Object

Edit|Copy

Edit|Paste Link

Table|Add Records


Inserting a Package Object

See Also

To insert a package containing an embedded image or sound (OLE document) using the Navigator,

1.	Open a dBASE or Paradox table containing an OLE field. The sample table PICTURES.DBF contains an OLE field.

2.	Double-click an OLE field to open the OLE Viewer. Add a blank record if necessary with Table|Add Records.

3.	Choose Window|Navigator to open the Navigator window.

4.	Choose a file type, then choose a file from the file list.

5.	Drag the file icon from the Navigator to the OLE Viewer.

If you drag a dBASE for Windows table, query, form, or program to the OLE Viewer, it appears with the dBASE for Windows icon.

If you drag a sound or image to the OLE Viewer, it appears with the Sound Recorder or Paintbrush icon.

If you choose a file that is not associated with an external application, it appears with the Object Packager icon, but will not activate. See Edit|Object for information.

When you double-click the OLE Viewer, another copy of dBASE for Windows starts and the file runs.

To insert a package containing an embedded OLE document using Windows File Manager,

1.	Open a dBASE or Paradox table containing an OLE field. The sample table PICTURES.DBF contains an OLE field.

2.	Double-click an OLE field to open the OLE Viewer. Add a blank record if necessary with Table|Add Records.

3.	Open Windows File Manager and select the file you want to embed.

4.	Size the dBASE for Windows application window so that both File Manager and dBASE for Windows are visible.

5.	Drag the file icon from File Manager to the OLE Viewer.

If you drag a dBASE for Windows table, query, form, or program to the OLE Viewer, it appears with the dBASE for Windows icon.

If you drag a sound or image to the OLE Viewer, it appears with the Sound Recorder or Paintbrush icon.

If you choose a file that is not associated with an external application, it appears with the Object Packager icon, but will not activate. See Edit|Object for information.

When you double-click the OLE Viewer, another copy of dBASE for Windows starts and the file runs.

To insert a package containing an embedded or linked OLE document using Windows Object Packager,

1.	Open a dBASE or Paradox table containing an OLE field. The sample table PICTURES.DBF contains an OLE field.

2.	Double-click an OLE field to open the OLE Viewer. Add a blank record if necessary with Table|Add Records.

3. Choose Edit|Insert Object then choose Package from the list to open the Windows Object Packager.

4.	Minimize Windows Object Packager.

5.	Open the external application and open the OLE document you want to embed or link.

6.	Select a portion of the OLE document and choose Edit|Copy to copy it to the Clipboard.

7.	Return to Windows Object Packager by double-clicking its icon.

8.	Choose Edit|Paste to embed or Edit|Paste Link to link.

9.	Save the package and exit Windows Object Packager to return to dBASE for Windows.


See Also

OLE Viewer Tasks

Embedding an OLE Document

Linking an OLE Document

Edit|Insert Object

Edit|Object

Table|Add Records

Window|Navigator


OLE Viewer Components

See Also

You can access the OLE Viewer from two views in dBASE for Windows:

The Table Records window

A form window containing an OLE control

When in the Table Records window, you see an OLE icon for an OLE field.

The OLE icon indicates the field is storing an embedded or linked document. If the icon is blank, the field contains no data.

Opening the OLE Viewer

To open the OLE Viewer, do one of the following:

Double-click the OLE field.

Choose View|Field Contents.

Press F9.

What is in the Window?

The OLE Viewer displays the contents of the OLE field. The display is a representation of the OLE document stored in the OLE field. The representation might be a picture of the OLE document or an icon representing the application that created the OLE document.

The OLE Viewer contents correspond to the OLE field of the current record. If you move to another record, the window refreshes and displays the data for the current record.

The OLE Viewer Edit menu contains the commands you need to embed, link, display, and edit OLE documents.

If you double-click inside the OLE Viewer window, the default action occurs for the document type. For example, the default action for a Paintbrush picture is to open Windows Paintbrush so you can edit the picture. The default action is usually equivalent to editing or playing the OLE document.

Status Bar

The status bar displays the same information as the Table Records window, except the name of the current table is replaced with the type of OLE document (embedded or linked, plus the application that created it).


See Also

Table Records Window Components


OLE Viewer Menus

The OLE Viewer has the following menus:

File Menu

Edit Menu

Properties Menu

Window Menu

Help Menu


OLE Viewer SpeedBar

See Also

The SpeedBar is the row of buttons beneath the menu bar. Each button represents a menu command. Click the button representing the command you want to execute.

Button	Action	Menu Equivalent
	Creates a new dBASE-related file	File|New
	Opens a dBASE-related file	File|Open
	Removes the selected text/object and places it on the Clipboard	Edit|Cut
	Copies the selected text/object onto the Clipboard	Edit|Copy
	Inserts the text/object into the active window	Edit|Paste
	Opens and runs the selected file	Edit|Object
	Opens the selected file for design	Edit|Object
	Switches to the Navigator window	Window|Navigator
	Switches to the Command window	Window|Command
	Opens the Form Expert	Help|Experts|Form Expert
	Opens the Interactive Tutors	Help|Interactive Tutors


See Also

Displaying and Editing OLE Documents

Table Records Window SpeedBar


OLE Viewer SpeedMenu

See Also

Use the OLE Viewer SpeedMenu to quickly perform a common operation on the active OLE document.

To use the SpeedMenu, right-click in the OLE Viewer.

Choose from the following commands:

Cut

Copy

Paste

Paste Link

Insert Object...

Links...


See Also

Displaying and Editing OLE Documents

Table Records Window SpeedMenu


Edit Menu (OLE Viewer)

Use the Edit menu to perform editing operations and to copy or remove OLE documents. You can cut, copy, or paste OLE documents using the Clipboard.

The Edit menu works differently in each of the windows. For information about using the Edit menu in different windows, see Where the Edit Menu Works.

The last item on the Edit menu is the Object command. This name changes depending on the contents of the current OLE field.

Choose from the following commands:

Undo or Redo

Cut

Copy

Paste

Paste Link

Delete

Select All

Insert Object...

Links...

Object


Edit|Paste (OLE Viewer only)
Edit | Paste

See Also

Embeds the OLE document on the Clipboard into the OLE field of the current record.

This command inserts data previously put on the Clipboard by an external application. The OLE document or a representation of it appears in the OLE Viewer.

The contents of the Clipboard are not deleted when you paste, so you can paste the same document into several different records, as long as you do not perform any intervening operations, such as cut or copy.

To reverse the effect of this command, choose Edit|Undo.

The Paste command is not available if the Clipboard is empty or when what is on the Clipboard cannot be pasted into the OLE Viewer.

For information about using the Edit menu in different windows, see Where the Edit Menu Works.

Shortcuts

SpeedBar:

SpeedMenu:	Paste

Keyboard:	Ctrl+V


See Also

Edit Menu (OLE Viewer)

Embedding an OLE Document

Edit|Copy

Edit|Cut

Edit|Undo

Edit|Paste Link

Edit|Insert Object...


Edit | Paste Link

See Also

Links the OLE document referenced on the Clipboard to the OLE field of the current record.

This command links data previously put on the Clipboard by another application. The OLE document or a representation of it appears in the OLE Viewer.

The contents of the Clipboard are not deleted when you paste, so you can paste the same information into several different records, as long as you do not perform any intervening operations, such as cut or copy.

To reverse the effect of this command, choose Edit|Undo.

A linked object is stored in the original OLE document file of the external application. The external application copies information about the OLE document file to the Clipboard. When you choose Paste Link, the OLE field stores this information:

Full path and file name of the linked OLE document

Item identifier, such as a cell range or screen coordinates

Presentation data, such as a snapshot of the spreadsheet or bitmap

After you link the OLE document to an OLE field, whenever the document is changed in the external application, the changes are not necessarily updated in the OLE field.

Changes are updated when dBASE for Windows attempts to use the OLE document.

Changes are also updated automatically if dBASE for Windows, the external application, and the OLE document are in memory.

You can manually update the link using the Links dialog box. See Edit|Links for information.

The Paste Link command is not available if the Clipboard is empty or when what is on the Clipboard cannot be linked to an OLE field.

Note:	If you create an OLE document in an external application and copy it to the Clipboard, but the OLE Viewer Paste Link command is still dimmed, return to the external application and save the file first. Then copy it to the Clipboard and link it in the OLE Viewer with Paste Link.

Shortcuts

SpeedMenu:	Paste Link


See Also

Edit Menu (OLE Viewer)

Linking an OLE Document

Edit|Paste

Edit|Links...


Edit | Insert Object...

See Also

Selects the external application (OLE server) in which to create the OLE document.

This command opens the external application you choose. Create a new OLE document in the application, then choose File|Update and File|Exit in the external application to save your work and return to dBASE for Windows. The OLE document you create is embedded and saved in the OLE field. If you want to abandon your changes to the OLE field, choose Edit|Delete or Edit|Cut.

Shortcuts

SpeedMenu:	Insert Object...

Dialog Box Options

Object Type

Specifies an external application and type of document to embed in the OLE field. The list of object types depends on what OLE external applications you have installed in your Windows system. For more information about OLE external applications, see Displaying and Editing OLE Documents - Overview.


See Also

Edit Menu (OLE Viewer)

Displaying and Editing OLE Documents - Overview

Embedding an OLE Document

Inserting a Package Object

Linking an OLE Document


Edit | Links...

See Also

Refreshes established links and changes the characteristics of links.

This command is available only if the current OLE field contains a linked document. For information about linking a document, see Edit|Paste Link and Linking an OLE document.

If a linked OLE document changes in the external application, that change is not always reflected in the OLE field of a table. The change is automatically reflected only if both the external application and dBASE for Windows are in memory when the change occurs. To force the contents of a linked OLE field to refresh, use the Links menu command.

Shortcuts

SpeedMenu:	Links...

Dialog Box Options

Links

Displays the link for the current record. The information displayed includes the external application, document type, file name, item identifier (such as a cell range or screen coordinates), and update method.

Update

Specifies how the OLE field is updated, automatically or manually.

Automatic

Specifies that links be updated automatically. Changes are automatically reflected only if both the external application and dBASE for Windows are in memory when the change occurs. Otherwise, use the Update Now button to update the link.

Manual

Specifies that links be updated by using only the Update Now button.

Update Now

Refreshes the OLE Viewer contents to match the external OLE document. For example, if another user on a network changes the OLE document, the display of the document stored in the OLE field is out of date. Use Update Now to refresh it.

Cancel Link

Removes the link from the table. This converts a linked OLE document to static data that can no longer be edited.

Change Link...

Specifies a new location for the linked document or a new file to link to. Use this option to reconnect a broken link or create a new link. This option opens the Change Link dialog box and displays all files in the current directory by default. Specify the name and location of the OLE document. For general information about choosing files, see Open File dialog box.

The item identifier for the file you originally linked remains in effect. The OLE document you choose must be able to support the same item identifier. For example, if you link to a Paintbrush picture with an item identifier corresponding to a large square in the upper left portion of the bitmap file, the new OLE document must be able to accommodate the same coordinates. To change the item identifier, you must delete the link and create a new one.

Done

Completes your changes and closes the dialog box.

Activate

Executes the same default behavior for the OLE document as double-clicking the OLE Viewer. For more information, see OLE Viewer Components.

Edit

Opens the external application so you can edit the linked OLE document.


See Also

Edit Menu (OLE Viewer)

Linking an OLE Document

Edit|Paste Link


Edit | Object

See Also	Language

Performs actions on the OLE document in the OLE Viewer.

The Object menu command is worded differently for different types of OLE documents. For example, if the OLE document is a Paintbrush picture, the menu command is Paintbrush Picture Object.

If the external application supports more than one action for the document type, the Object menu command displays a cascading menu listing all the choices. For example, if the OLE document is a sound, the menu commands are Play Sound and Edit Sound.

The Object menu command typically provides choices for editing and displaying the data, and is sometimes equivalent to double-clicking the document or pressing F9 in the OLE Viewer window. The choices provided for each external application are set up in the Windows registration database. See Displaying and Editing OLE Documents - Overview for information on the registration database.

Package Objects

If your OLE field contains a package, you see two cascading menu items:

Activate Contents

Edit Package

Activate Contents opens the external application so you can edit the OLE document. This is equivalent to double-clicking in the OLE Viewer.

Edit Package opens the Windows Object Packager application. Use the Object Packager to edit the attributes of the package. For more information about package objects, see Displaying and Editing OLE Documents - Overview. For more information about the Object Packager, see your Windows documentation.

Shortcuts

SpeedBar:

Keyboard:	F9


See Also

Edit Menu (OLE Viewer)

Inserting a Package Object


Language

DoVerb( )


File Menu (OLE Viewer)

Use the File menu to create new files, open and run existing files, save objects, and exit dBASE for Windows.

The New and Open commands manipulate the primary file types, such as tables, queries, and forms. The New command displays a menu allowing you to choose the type of file you want to create. The Open command lets you run or design an existing file.

You can open as many files as you like, and each appears in its own window. However, the Navigator and Command windows are unique and cannot be opened more than once.

Choose from the following commands:

New

Open...

Save

Save and Close

Abandon and Close

Close

Exit

(closed file list)


Properties Menu (OLE Viewer)

Use the Properties menu to change the characteristics of the dBASE for Windows Desktop.

Desktop...


Language Reference

See Also

dBASE contains over 600 language elements that you can use to write applications. Using the online Language Reference, you can

Learn the basic language concepts

Get information about how each language element works, its required syntax, and code examples

Find out limits and specifications for files and operations

To find a language element, choose an item below or click the Search button.

Language Definition

Syntax Conventions

Alphabetic List

Categorical List

Classes

Properties

Unsupported Language Elements

INKEY( ) Values

READKEY( ) Values

Specifications


See Also

Copying Syntax and Examples from Help

Search Dialog Box

Language Elements


Syntax Conventions

The Language Reference uses specific symbols and conventions in presenting the syntax of dBASE language elements.Choose one of these topics for more information.

Syntax Notation

Guidelines to Interpreting the Syntax


Syntax Notation

See Also

The following table describes the symbols used in syntax:

Symbol	Description
[ ]	Indicates an optional item.
< >	Indicates an argument that you must supply; for example, <expN> indicates that you must enter a numeric expression.
{ }	Indicates a codeblock.
| |	Indicates a codeblock parameter list.
|	Indicates two or more mutually exclusive options for example, ON | OFF.
...	Indicates an item that can be repeated any number of times; for example, [, <field 2> WITH <exp 2> [ADDITIVE]...] indicates that you can specify more than one field to replace.
,	List item separator.
;	In a codeblock, separates each command statement. In a command line, indicates that the command statement continues on the next line.
Figure: The syntax for a typical command

Command Keywords shown in uppercase		Arguments shown enclosed in angle brackets	Each option is listed on a separate line; optional arguments shown enclosed in square brackets
Indentation is used to show separate options or alternate choices		Individual option selections are separated by the pipe (|) symbol
Unlike dBASE command and function keywords, which are shown in uppercase letters, dBASE for Windows property names are capitalized differently. Property names are camel-capped, that is, they contain both uppercase and lowercase letters if the name consists of more than one word. If the property is a method, the name is followed by parentheses. Examples of properties include OnAppend, OnRightMouseDown, Checked, Close( ).

These conventions help you differentiate the language elements; for example,

DELETE is a command.

Delete is a property.

DELETED( ) is a function.

Delete( ) is a method.

These typographical conventions are for readability only. When writing code, you can use any combination of uppercase  and lowercase letters.

Note:	You can abbreviate most keywords in the dBASE language to the first four characters; however, for clarity, this is not recommended. You must refer to classes and properties by their full name, since you can define your own custom classes and properties, and dBASE for Windows needs the full name to identify the correct one to use.


See Also

Guidelines to Interpreting the Syntax


Guidelines to Interpreting the Syntax

See Also

This topic tells you how to interpret some of the more complex syntax conventions.

Options are shown in alphabetical order except in cases where it is logical or required to provide them in another order, for example:

DEFINE <class name> <object name>
  [OF <container object>]
  [FROM <row, col> ...]

When creating a dBASE statement, you can usually include the options in any order.

The pipe symbol (|) is used to separate mutually exclusive options. If there are more options that can fit on a single line, additional options appear indented following the pipe symbol ending the first line, as shown in the following example:

MONO | COLOR | EGA25 | EGA43 | MONO43 |
VGA25 | VGA43 | VGA50

If a keyword precedes one of many alternative option keywords, each alternative keyword is shown on its own line indented from the keyword with which it is used:

PROMPT
  ARRAY <array> |
  FIELD <field> |
  FILES [LIKE <filename skeleton>] |
  STRUCTURE [IN <alias expC>]

In this example, you could select any of four different options, PROMPT ARRAY..., PROMPT FIELD..., PROMPT FILES..., or PROMPT STRUCTURE...

The brackets, [ ], indicate that the item is optional; sometimes, optional items appear nested in other optional items, as shown in the following example:

ACOPY(<source array name>, <target array name>
[, <starting element expN> [, <elements expN>
[, <target element expN>]]])

With ACOPY( ), you specify a list of arguments, each delimited with a comma. The third, fourth, and fifth arguments are optional. Notice that the third and fourth arguments do not have right brackets immediately after the argument. This means that in order to specify a value for the fourth argument, you must specify a value for the third argument. Similarly, in order to specify a value for the fifth argument, you must specify values for the previous two arguments. Contrast this syntax notation with the next one.

Sometimes, optional items appear nested in other optional items but are independent of each other, as shown in the following example:

 SET COLOR TO
[<standard text>]
[,[<enhanced text>]
[,[<perimeter>]
[,[<background>]]]]

Like the ACOPY( ) example, SET COLOR TO takes a list of optional arguments, each delimited with a comma. Notice that each argument is contained within its own pair of brackets. This means that you can specify any one of those arguments independently of the others. If you omit an argument from the list, mark its position in the list with a comma. For example, SET COLOR TO , , B means that the perimeter is set to the color blue.

Arguments for which you substitute a particular value or expression are shown enclosed in angle brackets. In many cases, instead of just specifying the type of data required (for example, <expC> or <expN>), the syntax provides a more descriptive argument name, such as:

<target element expN>


See Also

Syntax Notation


Specifications

Choose one of these topics for the specifications for dBASE for Windows files and operations.

.DBF Table Specifications

Index Specifications

Field Specifications

Multiuser Specifications

Procedure Specifications

File Specifications

Miscellaneous Specifications


.DBF Table Specifications

See Also

Item	dBASE IV	dBASE for

Description	Limit	Windows Limit

Maximum number of records	1 billion	1 billion
Maximum size of .DBF table file (in bytes)	2 billion	2 billion
Maximum record size (in bytes)	4000 (not including _DBASELOCK  field)	32,767 (including _DBASELOCK field)
Maximum number of fields in .DBF table file	255	1024


See Also

Specifications


Index Specifications

See Also

Item	dBASE IV	dBASE for

Description	Limit	Windows Limit

Maximum index key expression length (in bytes)	220	220
Maximum index FOR expression length (in bytes)	220	220
Maximum evaluated index key length (in bytes)	100	100
Maximum blocksize in .MDX index file (in bytes)	16,384	32,256 (default 1024)
Maximum number of index tags in .MDX index file	47	47
Fixed blocksize of  .NDX index file (in bytes)	512	512


See Also

Specifications


Field Specifications

See Also

Item	dBASE IV	dBASE for

Description	Limit	Windows Limit

Maximum size of character fields (in bytes)	254	254
Size of date fields (in bytes)	8	8
Size of logical fields (in bytes)	1	1
Maximum size of numeric fields (in digits)	20	20
Maximum size of  memo fields (in bytes); includes OLE and binary type fields	Memo fields limited only by available memory	Limited only by available memory
Maximum characters in field names	10	10
Numeric accuracy of type F numbers (digits)	15	19
Largest type F number	0.9xE+308	0.9xE+308
Smallest type F number	0.1xE-307	0.1xE-307
Numeric accuracy of type N numbers (digits)	20	19
Largest type N number	0.9xE+308	0.9xE+308
Smallest type N number	0.1xE-307	0.1xE-307


See Also

Specifications


Multiuser Specifications

See Also

Item	dBASE IV	dBASE for

Description	Limit	Windows Limit

Maximum number of locks (files and records)	200 total	100 per work area
Maximum number of reprocess counts	32,000	32,000
Maximum number of seconds for refresh	3600	3600


See Also

Specifications


Procedure Specifications

See Also

Item	dBASE IV	dBASE for

Description	Limit	Windows Limit

Maximum length of command line in programs (in bytes)	1024	4096
Maximum number of active .PRO files	32	147
Maximum size of a procedure (in bytes)	65,520	Limited only by available memory
Maximum number of procedures per file	963	193
Maximum number of open procedure files	1	Limited only by available memory


See Also

Specifications


File Specifications

See Also

Item	dBASE IV	dBASE for

Description	Limit	Windows Limit

Maximum number of open files (of all types)	99	250
Maximum number of open tables	40	225
Maximum number of open .DBT memo files per active .DBF table	1	1
Maximum number of open .MDX index files per active .DBF table	1 production .MDX plus additional non-production indexes allowed.	1 production .MDX plus additional non-production indexes allowed
Maximum number of open .NDX index files per active .DBF table	10	10
Maximum number of open .FMT format files per active .DBF table	1	1
Maximum width of a report	255 characters	22.75 inches
Maximum number of tables per report	9	225
Maximum number of reports per table	Unlimited	Unlimited
Maximum number of pages in a report	32,767	Unlimited
Maximum number of nested report group bands	44	Unlimited
Maximum number of fields in a report	Limited only by available memory	Unlimited


See Also

Specifications


Miscellaneous Specifications

See Also

Item	dBASE IV	dBASE for

Description	Limit	Windows Limit

Maximum number of lines in Text Editor	32,000	Unlimited
Maximum line length in Text Editor	1024	32,767
Maximum width of a form	80 characters	32767 pixels (the number of characters depends on the pixel width of the font)
Maximum number of rows in a form	32,767	32,767 pixels
Maximum command line length entered in the Command window	255	4096
Maximum number of lines stored in input pane of Command window	N/A	1000 lines
Maximum number of simultaneous sort levels	16	16
Maximum number of printer drivers	4	Unlimited
Maximum number of fonts per printer driver	5	9 (total maximum; not per driver)
Maximum number of work areas	40	225
Number of programmable function keys	29	29
Maximum memory variable size	32,767	32,767
Maximum number of array dimensions	2	255
Maximum elements per dimension	65,525	Unlimited
Maximum total size of array	Depends on available memory	Limited only by available memory


See Also

Specifications


INKEY( ) Values

See Also

Key	Return	Shift+Key	Ctrl+Key	Alt+Key

Pressed	Value	Return Value	Return Value	Return Value

0	48	Depends on keyboard	-404	-452
1	49	Depends on keyboard	-404	-451
2	50	Depends on keyboard	-404	-450
3	51	Depends on keyboard	-404	-449
4	52	Depends on keyboard	-404	-448
5	53	Depends on keyboard	0	-447
6	54	Depends on keyboard	-30	-446
7	55	Depends on keyboard	-404	-445
8	56	Depends on keyboard	-404	-444
9	57	Depends on keyboard	-404	-443
a	97	65	1	-435
b	98	66	2	-434
c	99	67	3	-433
d	100	68	4	-432
e	101	69	5	-431
f	102	70	6	-430
g	103	71	7	-429
h	104	72	8	-428
i	105	73	9	-427
j	106	74	10	-426
k	107	75	11	-425
l	108	76	12	-424
m	109	77	13	-423
n	110	78	14	-422
o	111	79	15	-421
p	112	80	16	-420
q	113	81	17	-419
r	114	82	18	-418
s	115	83	19	-417
t	116	84	20	-416
u	117	85	21	-415
v	118	86	22	-414
w	119	87	23	-413
x	120	88	24	-412
y	121	89	25	-411
z	122	90	26	-410
F1 (Ctrl+\)	28	-20	-10	-30
F2	-1	-21	-11	-31
F3	-2	-22	-12	-32
F4	-3	-23	-13	-33
F5	-4	-24	-14	-34
F6	-5	-25	-15	-35
F7	-6	-26	-16	-36
F8	-7	-27	-17	-37
F9	-8	-28	-18	-38
F10	-9	-29	-19	-39
F11	-544	-546	-548	-550
F12	-545	-547	-549	-551
Left arrow	19	-500	1	0
Right arrow	4	-501	6	0
Up arrow	5	5	5	0
Down arrow	24	24	24	0
Home (Ctrl+])	26	26	29	0
End	2	2	23	0
Tab	9	-400	0	0
Enter	13	0	-402	0
Esc (Ctrl+[)	27	27	-	-
Ins	22	0	0	0
Del	7	-502	7	7
Backspace	127	127	-401	-403
PgUp	18	18	31	0
PgDn	3	3	30	0


See Also

READKEY( ) Values

INKEY( )


READKEY( ) Values

See Also

Non-Updated	Updated	Key

Code Number	Code Number	Pressed	Description

0	256	Ctrl+S, Left arrow, Ctrl+H	Move back one character
	256	Backspace	Move back one character
1	257	Ctrl+D, Right arrow, Ctrl+L	Move forward one character
2	258	Ctrl+A, Ctrl+Left arrow	Move to beginning of previous word
3	259	Ctrl+F, Ctrl+Right arrow	Move to beginning of next word
4	260	Ctrl+E, Ctrl+K, Up arrow	Move back one field
5	261	Ctrl+J, Ctrl+X, Down arrow	Move forward one field
6	262	Ctrl+R, PgUp	Move back one screen
7	263	Ctrl+C, PgDn	Move forward one screen
12		Ctrl+Q,  Esc	Terminate without saving
	270	Ctrl+W, Ctrl+End	Terminate with save
15	271	Enter, Ctrl+M	Return or fill last record
16		Enter, Ctrl+M	Move to beginning of record in an APPEND window
33	289	Ctrl+Home	Menu display toggle
34	290	Ctrl+PgUp	Zoom out
35	291	Ctrl+PgDn	Zoom in
36	292	F1	Help function key


See Also

INKEY( ) Values

READKEY( )


Language Definition

The dBASE language is a structured programming language designed primarily for developing database applications. It consists of a collection of commands, functions, and classes that you use to create applications to store, manage, and process data.

dBASE for Windows adds many new language features, such as object-oriented programming extensions, designed specifically to simplify and speed up the development of applications for the Windows environment.

Choose from the list below for more information about how to work with the dBASE language:

Language Elements

dBASE Statements

Expressions

Data Types

Operators


Language Elements

See Also

You write programs with the built-in language elements that dBASE provides. dBASE for Windows provides virtually all of the language elements--commands, functions, system memory variables, and preprocessor directives--that dBASE IV supports, and more.

To simplify programming for the graphical Windows environment, dBASE for Windows provides classes that you use as templates for creating common Windows objects, such as pushbuttons, entry fields, and check boxes.

The following topics provide overviews of the standard language elements in dBASE for Windows:

Commands

Functions

Built-In Functions

User-Defined Functions

System Memory Variables

Preprocessor Directives

Classes

Custom Classes

Standard Classes


See Also

Language Definition


Commands, overview
Commands

See Also

Commands tell dBASE to perform certain actions. A statement often starts with a command (statements are sometimes called command statements). Although a statement can contain another language element, such as a function, it can contain only one command.

The following statement, for example, uses the ? command and the DATE( ) function to display the current date:

? DATE()

Most commands consist of options (sometimes called clauses) that you can use to tailor the command operation to accomplish specific tasks. With the USE command, for example, you can simply open a table, or add the EXCLUSIVE option to open the table exclusively.

USE mytable            && opens mytable.dbf

USE mytable EXCLUSIVE  && opens mytable.dbf exclusively

A statement can begin with either a command keyword or with one of several different implicit commands. Implicit commands include

A memory variable assignment, which is an implicit STORE command:

x=45  && same as STORE 45 TO x

A record number, which is an implicit GOTO command:

23    && same as GOTO 238


See Also

Language Elements


Functions, overview
Functions

See Also

dBASE recognizes two kinds of functions:

Built-in

User-defined

Functions return values and consist of a keyword followed by left and right parentheses. The parentheses can contain arguments that are passed to the function for processing. In the following statement, for example, the SQRT( ) function returns the square root of 36:

? SQRT(36)


See Also

Built-In Functions

Language Elements

User-Defined Functions


Built-In Functions

See Also

dBASE built-in functions generally perform arithmetic, text, date, logical, or conversion operations. Some functions return a value that you can query. RECNO( ), for example, returns the number of the current record. Some functions, such as RLOCK( ) and TRIM( ), perform an action and return a value.


See Also

Functions

User-Defined Functions


User-Defined Functions

See Also	Language

User-defined functions (UDFs) are functions you create and call in a program just as you would call a built-in function. To define a UDF, use the FUNCTION command followed by the name of the UDF, an optional parameter list, and the sequence of commands to execute when the UDF is called.


See Also

Built-In Functions

Functions


Language

FUNCTION


System Memory Variables, overview
System Memory Variables

See Also

System memory variables are memory variables that dBASE maintains automatically. These variables are typically used to specify environmental and printer settings and to control the format of printed and screen output.

At startup, dBASE initializes system memory variables to their defaults. The defaults for some system memory variables that control printer settings, such as _pdriver and _porientation, are determined by the Windows printer setup defaults.

To distinguish them from other memory variables, system memory variables begin with the underscore (_) character. (You cannot define memory variables that begin with an underscore.)

Like memory variables that you define, system memory variables follow the same scoping rules. When a program that contains privately declared system memory variables has finished running, the variables automatically revert to their original settings.

Unlike user-defined memory variables, however, system memory variables cannot be released from memory. You can only change and query their values.


See Also

Language Elements

Memory Variables


Preprocessor Directives, overview
Preprocessor Directives

See Also

Preprocessor directives are statements you insert in your dBASE programs to instruct the compiler how to compile the program. You can use them to replace text in a program, set up conditional compilation, or specify compiler options.

With these capabilities, you can, for example, maintain one code base and compile different portions of your code depending on the platform it runs on.

Preprocessor directives begin with a number sign (#).


See Also

Language Elements


Classes, overview
Classes

See Also

Classes are specifications, or templates, for creating objects. dBASE for Windows provides many standard classes that you can use to create common Windows objects, such as radio buttons, pushbuttons, and entry fields.

When you create an object, you create an instance of that object's class. The object will have the predefined attributes specified in the class. These attributes are called properties. Once you create an object, you can customize its characteristics by assigning values to the properties. Some object properties have code associated with them, and perform operations on the object. These properties are called methods.

As a programmer, you work with objects as collections of memory variables, where each property and method is a memory variable. This makes it easy for you to add properties and change the properties of an object instantly.

The following example shows how to create an entry field from the Entryfield class, and shows some of the properties you can set:

DEFINE ENTRYFIELD CustomerName OF CustomerForm;

  PROPERTY;

    Width 20.00,;

    Height 2.00,;

    Top 7,;

    Left 18,;

    FontSize 10.00,;

    DataLink "Customer->CustName"

    ...

As the example illustrates, it would be a simple matter to change the size of the entry field - just assign different values to the Width and Height properties.

Choose one of these topics for more information:

Custom Classes

Standard Classes


See Also

Custom Classes

Language Elements

Standard Classes


Custom Classes

See Also	Language

You can create new classes from scratch, or derive them from the standard classes. To do so, use the CLASS...ENDCLASS command. A class that is derived from another class is called a subclass; it inherits the properties and methods of the class it is based on. You can then customize the attributes of the subclass by adding, deleting, or changing properties.

The following example shows how to create a new class, Quitbutton, based on the standard Pushbutton class:

CLASS Quitbutton(f) OF PUSHBUTTON(f)

  this.text = "Quit"

  this.FontName = "Arial"

  this.FontBold = .T.

  this.FontSize = 12

  this.OnClick = {;QUIT}

  ...

ENDCLASS

Once you have defined a new class, you can create objects from it. The following example creates a button from the Quitbutton class and places it on the CustomerForm form:

DEFINE QUITBUTTON Quit OF CustomerForm;

PROPERTY;

    Width 10.00,;

    Top 18.00,;

    Height 2.00,;

    ...


See Also

Classes

Standard Classes


Language

CLASS...ENDCLASS


Standard Classes

See Also

Most of the standard classes that dBASE for Windows provides are specifications for standard Windows objects (also called controls) that you create and place on user-defined windows called forms. To create your own objects, you need to create the corresponding classes first (see Custom Classes for more information.)


See Also

Classes

Custom Classes


dBASE Statements

See Also

You write statements to tell dBASE the operations you want to perform. Statements have a general structure - most begin with a command keyword and usually contain options and arguments. The structure of a statement is called its syntax.

Choose one of the following topics for more information about statement elements:

Arguments

Names

Table and File Names

Aliases

Database Names

Field Names

Memory Variables

Arrays

Name Skeletons

Scope Options

For more information about the symbols and conventions used in syntax, choose the following topic:

Syntax Notation


See Also

Language Definition


Arguments

See Also

An argument is a word or sequence of words enclosed in angle brackets (< >) that identifies a part of the syntax you need to supply, such as <scope>, <memvar>, <field>, <filename> or <exp>. When entering an argument in a statement, do not enter the angle brackets.

You can specify either a literal value or an expression in place of any argument. The following shows part of the REPLACE command syntax, then an example of the values or expressions you can use with the command:

REPLACE command syntax:

REPLACE <field 1> WITH<exp 1> [ADDITIVE]
  [, <field 2> with <exp 2> [ADDITIVE]...]
  [ALL | REST | NEXT <expN> | RECORD <expN>]
  [FOR <condition 1>]
  ...

Example of statement:

REPLACE ZipCode WITH "54261" FOR ZipCode = "54260"

Choose a topic for more information about some of the common types of arguments you use in statements.

Names

Table and File Names

Aliases

Database Names

Field Names

Memory Variables

Arrays


See Also

dBASE Statements


Names

See Also

Some commands and functions require you to supply a name, such as a file name, table name, field name, memory variable name, and so on. Names can be up to 32 characters in length and are made up of any combination of letters, digits, and the underscore (_) character, with the following exceptions:

DOS file names have an 8-character limit (with a file extension of up to 3 characters) and must follow DOS naming conventions.

You can also specify a table, field, or memory variable name that includes spaces by delimiting the name with colon characters, for example, :new name:

Variable and field names must start with an alphabetic character.

Choose one of these topics for information about rules for specifying the different types of names:

Table and File Names

Aliases

Database Names

Field Names

Memory Variables

Arrays


See Also

Arguments


Table and File Names

See Also

Note:	Earlier versions of dBASE referred to tables or .DBF files as database files. In dBASE for Windows, the term database refers to a collection of tables. Database also refers to SQL databases that you access through the Borland SQL Link.

You can specify a file name as a literal or as a character expression that evaluates to a file name. You can also use the & macro substitution operator to specify the name of a file at run time.

In dBASE for Windows (and also in dBASE IV), you should use the more efficient method of indirect reference wherever you are asked to provide a file name. For example:

Mfile = "Client"     && Name of existing table
USE (Mfile)

A full file name consists of the drive and path where a file resides on disk, the file root name, and the file-name extension, that is,

[<drive>] [<path>] <root name> [ <file extension> ]

For example, you could enter

C:\DBASEWIN\SAMPLES\ANIMALS.DBF

The full directory and file name can be up to 79 characters. The drive, path, and file-name extension portion of the full file name are optional. All file-name restrictions follow DOS conventions.

When you know the location of a file relative to the current directory, you can use the DOS current (.) and parent (..) directory notation to specify the location. For example,

USE ..\clients

You can use wildcard characters ? or * in file names to specify a file-name skeleton for referencing any file names that match a given pattern. In most cases, dBASE displays the Open File dialog box to let you choose the particular table you want to open.


See Also

Macro Operator (&)

Name Skeletons

Names

Open File Dialog Box


Aliases

See Also	Language

An alias is an alternative name for an open table or the work area of an open table. When you access a table in dBASE for Windows, a work area (in memory) is used to open the table and any associated files such as an index file. Only one work area can be current at a time.

You use the alias in a statement to identify a work area and to access a table open in that work area. You can identify the work area by number (1 through 225), by letter (A through J), or by alias name. dBASE for Windows lets you open up to 225 tables at a time by allotting each open table its own unique work area.

When you open a table with USE, dBASE for Windows automatically establishes the table name as an alias for the table. (You can use the ALIAS( ) function to identify the alias for any open table.) If you prefer, you can specify your own alias, by providing a name of up to 32 characters, for example,

USE Clients ALIAS Contacts

Just as you can with file names, you can specify an alias as a literal or an expression. When a literal alias name might be confused with another name or command option, use a work area expression. The result of a work area expression identifies a work area containing the table you want to access. To avoid mistaking the name of a memory variable that contains a work area with a literal value, enclose the variable name in parentheses, as shown in the following example:

cAliasName = "Contacts"
SELECT(cAliasName)


See Also

Memory Variables

Names


Language

ALIAS( )


Database Names

See Also	Language

dBASE for Windows uses database names or aliases (assigned with the IDAPI Configuration Utility IDAPICFG.EXE) to specify a drive and directory location from which to access tables and files that are all related to the same application. (Refer to IDAPICFG.HLP for more information.)

You can also define database names to specify the location from which to access tables on a database server. To access database servers, you need to install the Borland SQL Link.

Using dBASE for Windows, you can have only one database current at a time (although multiple databases can be open at the same time). As you can with tables and work areas, you can specify a database name as a literal or an expression. For example, to use a memory variable to specify the name of a database to open, you could enter:

cDatabaseName = "MktgSqlServer"
OPEN DATABASE (cDatabaseName)

After opening databases, you can specify one of them as the current database using the SET DATABASE command.


See Also

Aliases

Memory Variables

Names


Language

SET DATABASE


Field Names

See Also

A field name is the name of one field, or item of information, contained in a record of a table. For example, LASTNAME might be the name of a field that contains the last names of clients. In each record in the table, a last name would be entered in the LASTNAME field.

A qualified field name includes a reference to an alias (designating the work area) and the field name in that aliased table. If the field is not in the table in the current work area, you need to qualify the field name with an alias. To qualify a field name, use the alias symbol (->) between the alias name and the field name, as shown in the following example:

Client->Lastname

In the preceding example, the expression specifies the LASTNAME field in the Client table.

Note:	When fields and memory variables have the same name, fields take precedence over memory variables. To distinguish the memory variable, prefix it with m->, for example m->Lastname.


See Also

Aliases

Memory Variables

Names


Memory Variables

See Also	Language

Memory variables are named locations in memory where you store data values: strings, numbers, dates, logical values, codeblocks, object references, or function pointers. You assign each of these values a name so that you can later retrieve them.

You can use these values to store user input, perform calculations, do comparisons, or define values that are used as arguments for other dBASE commands and functions. You can create a memory variable by simply assigning it a value or using the STORE command. The statements in the following example are equivalent:

cProduct = "dBASE for Windows"
STORE "dBASE for Windows" TO cProduct

The scope of memory variables is usually limited to the dBASE program or procedure file in which it is declared or defined. To explicitly define the scope, you can use the PUBLIC, PRIVATE, LOCAL, or STATIC commands.


See Also

Arrays

Names


Language

LOCAL

PUBLIC

PRIVATE

STATIC

STORE


Arrays

See Also	Language

dBASE for Windows lets you create a special set of memory variables called an array. An array is an n-dimensional table of values stored in memory. Each entry in the array is called an element, and each element in an array can be treated like a memory variable and can also be included in an expression.

To create an array, you can use the DECLARE command, or you can create an array as an object. When you use arrays in an expression, follow the same rules as those for memory variables. You can use an array element in any expression that accepts a memory variable, and you can store the same types of data in an array element as you can in a memory variable.


See Also

Memory Variables


Language

DECLARE


Name Skeletons

See Also

Name skeleton arguments let you specify wildcard characters ? and * as part of a character string to qualify field, file, or index names or to define a search string. For example, you could enter the following command to select all fields that begin with the c character:

SET FIELDS TO ALL LIKE c*

The * specifies that zero or more characters can appear in the position; the ? specifies that any single character can appear in the position within the string where the ? is located. A dBASE skeleton differs from a DOS skeleton in that the wildcard characters can appear anywhere and in any order, for example:

SET FIELDS TO ALL LIKE *name?


See Also

dBASE Statements


Scope Options

See Also

In commands that process records in a table, you can use a scope keyword to specify the number of records to process. All commands that include a <scope> option have a default scope, usually ALL or NEXT 1. The following table describes the keywords you can use for the scope argument.

Keyword	Description
ALL	Processes all records in the table starting with the first
REST	Starting with the current record, processes all subsequent records to the end of the table
NEXT <expN>	Starting with the current record in the table, processes the next <expN> number of records
RECORD <expN>	Processes only the record specified with <expN>
In addition, many commands that process records allow you to specify FOR and WHILE conditions, which further qualify the records to be processed. Records are processed in natural order or by the order specified by a master index, if one is in use. Also, records are qualified by any filter condition or query file in use.


See Also

dBASE Statements


Expressions

See Also

You use expressions to provide values for arguments in a command statement. A simple expression might be a single data item, such as a field name, a constant, or a memory variable name. For example, the implicit STORE command requires an expression for its argument:

Name = "Peter"

In that example, "Peter" is a character expression.

More complex expressions are formed by combining several data items with operators. You can create expressions with one or more of the following elements:

Field names

Memory variables, including system memory variables and arrays

Constants

Functions

Operators

Figure: An example of a complex expression in a statement

Command to print result	Functions	Memory variable	Literal character string
		Operators
Operators link each of these elements so that dBASE for Windows can evaluate the entire expression as a single unit.

When you combine fields, memory variables, constants, and the returned value of a function in an expression, they must be the same data type (except for dates, which can be added to a number). If necessary, you can use functions to convert elements of differing data types to one common type, usually character. The example in the previous illustration uses the STR( ) function to convert a number to a character value before concatenating it with a character string.


See Also

Arrays

Data Types

Field Names

Language Definition

Operators

Memory Variables

System Memory Variables


Data Types

See Also	Language

In dBASE, all data items are identified by type. The basic data items - fields, memory variables, constants, and functions - are assigned data types depending on how the item is created. For example, the type of expression you assign to a memory variable determines the  data type of the variable, and  the return value of a function defines its data type.

Note:	To find out the data type of an item, use the TYPE( ) function.

The following table lists the data types that dBASE for Windows supports and the value that the TYPE( ) function returns for each:

Data Type	TYPE( ) Returns
Character	C
Date	D
Numeric	N
Float	F
Logical	L
Memo	M
Binary	B
OLE	G
Bookmark	BM
Function-pointer	FP
Codeblock	CB
Object-reference	O


See Also

Language Definition

Memory Variables


Language

TYPE


Character Data

See Also	Language

Character data consists of any combination of letters, digits, spaces, and special symbols. In .DBF tables, a character field can be up to 254 characters; a character memory variable or expression can be up to 32,766 characters.

Character constants or literal character strings must be enclosed in matching single or double quotation marks or brackets, as shown in the following examples:

a = 'text'
b = "text"
c = [text]

You can also store an ASCII decimal value to a character string with the CHR( ) function. The following statements both create a character memory variable containing the letter A:

STORE "A" TO cLetter
STORE CHR(65) TO cLetter

You can nest character strings in a literal character string by enclosing the nested string in a different pair of delimiters. For example, the first statement displays the second:

? "This is a 'character' string"

This is a 'character' string

Note:	A literal character string cannot contain the null character (ASCII 0), the EOF character (ASCII 26), or the LF character (ASCII 10).


See Also

Data Types


Language

CHR( )


Date Data

See Also	Language

Date data provides a way to store a calendar date that is represented in a format such as mm/dd/yy. Internally, however, date data is always stored in the format yyyymmdd.

The size of a date variable or field is always eight bytes. dBASE for Windows validates date information whenever it is entered or changed. By default, the format for dates is set by the International option of the Windows Control Panel. You can override this format with the SET DATE command or with the DATE setting in the DBASEWIN.INI file.

You specify a literal date value by enclosing it within braces ({ }). You can also specify a date as a character string and convert it to a date type by using the CTOD( ) function. For example, {12/20/59} is the same as CTOD("12/20/59").

To enter a blank date, specify one of the following:

{ }

{  /  /  }

CTOD("  /  /  ")

You can subtract a date from another date. The result is a number that represents the the number of days between the dates. You can also add or subtract a number (representing a number of days) from a date. The result will also be a date.


See Also

Data Types


Language

CTOD( )

SET DATA


Numeric and Float Data

See Also

The numeric data type lets you perform mathematical operations (additions, multiplications, and other mathematical functions) on data.

When designing the structure of a table, you can specify numeric or float types for numeric fields. You can specify up to 20 digits with up to 18 decimal places for both numeric and float types.

Unlike dBASE IV, however, there is no difference in the way dBASE for Windows processes numeric or float data. In mathematical operations, dBASE for Windows provides the same precision level (19 digits) for both types. In dBASE IV, numeric and float data are processed differently--numeric type numbers can have precision of up to 20 digits and float numbers have precision of 15. In dBASE for Windows, the float type is maintained for backward compatibility with dBASE IV.

If you assign a number to a memory variable, the TYPE() function always returns N. The TYPE() function returns F for float fields only.

If you use very large or very small numbers, both numeric and float types display numbers in exponential scientific notation, such as .6E + 23.


See Also

Data Types


Logical Data

See Also

Logical fields and memory variables are stored as true (.T.) or false (.F.). Logical fields or variables accept T, t, Y, or y for true and F, f, N, or n or false. In statements or expressions, you must delimit logical values with periods (for example, STORE .T. to Mlogic).


See Also

Data Types


Memo Data

See Also

Memo data is any data stored in memo fields. A memo field is a variable-length field used to hold large blocks of characters (its size is limited only by available memory). Memo fields are typically used for text manipulation, although you can also store the contents of OLE fields, bitmaps, images, sound, or any other binary data in a memo field. (dBASE for Windows adds two new data types to specifically store OLE and binary data respectively.)

dBASE stores the actual memo data in an associated memo file, which has a .DBT file-name extension.


See Also

Data Types


Binary and OLE Data

See Also

dBASE for Windows adds two new data types, binary and OLE, to store binary and OLE data in table fields. It supports the standard binary type files including these file types:

.BMP

.PCX

.WAV


See Also

Data Types


Bookmark Data

See Also	Language

A bookmark is a reference to a specific record in a table. It is similar to the record pointer in dBASE.

dBASE supports bookmarks primarily for Paradox and SQL tables, which do not have record numbers. Because Paradox and SQL tables do not identify records by record number, you cannot, for example, use GOTO 23 to go to record 23, or use RLOCK("1, 2, 3") to lock records 1, 2, and 3.

Bookmarks let you earmark records so that you can navigate to and perform operations on them. To mark the current record, use BOOKMARK() to store the bookmark value to a memory variable.

The following example shows how to use bookmarks to access records in a Paradox table:

USE Contact.db                && Open a Paradox table
GO TOP                        && Go to the first record
bMark1= BOOKMARK()            && Mark the record
SKIP 2                        && Advance 2 records
bMark2 = BOOKMARK()           && Mark the record
? RLOCK("bMark1, bMark2", 1)  && Lock records 1
                              && and 2 in work area 1

GOTO bMark1                   && Go back to the
                              && first record

The bookmark value is a special unprintable data type. You cannot query a bookmark; if you assign a bookmark value to a memory variable, then query the value of the variable, dBASE simply returns "BookMark." The following example illustrates this:

Record_a = BOOKMARK()
? Record_a         && returns "BookMark"

You can, however, compare bookmark values in a table. Using operators, such as >, =, or <, you can compare BOOKMARK( ) values to determine the relative positions of two records in a table. The following example illustrates this:

USE Contact.db
GO TOP                 && Go to the first record
Record_a = BOOKMARK()
GO BOTTOM              && Go to the last record
Record_b = BOOKMARK()
? Record_a < Record_b  && Returns .T.

All commands and functions, such as RLOCK( ) and EDIT, that accept a record pointer argument also accept a bookmark.


See Also

Data Types

Operators


Language

BOOKMARK( )


Function-Pointer Data

See Also

As its name suggests, the function pointer is a reference to a function or procedure. Function pointers make it easy for you to define functions and procedures, then call them when needed.

All event properties, such as OnClick and OnOpen, in the standard objects are variables of either function pointer type or codeblock type. With a function pointer, you can assign a constant or variable reference that points to a function or procedure.

The following example shows how to specify a reference to the Go_Next procedure for the OnClick event property:

DEFINE PUSHBUTTON Nextbutton OF CustomerForm
  Property;

    OnClick Go_Next
...

PROCEDURE Go_Next
    IF .NOT. EOF()
      SKIP

    ELSE

      GO TOP
    ENDIF


See Also

Data Types


Codeblock Data

See Also

A codeblock is a logical grouping of one or more dBASE statements, or a dBASE expression. Like the function pointer, it is a means of executing dBASE statements, and is particularly useful when used with the event property of an object.

Unlike the function pointer, however, codeblocks are literal statements that you assign to the event property. A codeblock is a data type that contains dBASE code. Like other data types, you can assign a codeblock to a memory variable or pass it as a parameter.

dBASE for Windows provides two types of codeblocks: expression and statement.

Expression codeblocks can contain only dBASE expressions.

Statement codeblocks can contain one or more dBASE statements.


See Also

Data Types

Expression Codeblock

Statement Codeblock


Expression Codeblock

See Also

An expression codeblock can contain only dBASE expressions. The syntax and rules for writing an expression codeblock follow:

{[|<parameters>|] <expression>}

The braces, { }, are required.

If you pass parameters, they must be delimited by | |.

The following example shows how to assign an expression codeblock to the Valid event property:

DEFINE ENTRYFIELD Salary OF EmployeeForm;
  PROPERTY;
      Valid {Salary >= 10000}

...

The following example shows how to assign an expression codeblock with parameters to a memory variable; unlike the statement codeblock, a semicolon is not required after the parameter declaration:

AddNum = {|a,b| a+b}

To execute the codeblock, use the following:

AddNum(10+10)  & Returns 20


See Also

Codeblock Data

Statement Codeblock


Statement Codeblock

See Also

A statement codeblock can contain one or more dBASE statements. The syntax and rules for writing a statement codeblock follow:

{[|<parameters>|]; <statement> [; <statement> ...]}

The braces, { }, are required.

If you pass parameters, they must be delimited by | |.

Precede each statement with a semicolon (;).

The following example shows how to assign a statement codeblock to the OnClick event property:

DEFINE PUSHBUTTON Quitbutton OF CustomerForm;
  Property;
      OnClick {;QUIT}
...

The following example shows how to assign a statement codeblock with parameters to a memory variable:

AddNum = {|a,b|; ? a+b}

To execute the codeblock, use the following:

AddNum(10+10)  && Returns 20


See Also

Codeblock Data

Expression Codeblock


Object-Reference Data

See Also	Language

The object-reference data type provides a way to reference dBASE for Windows objects and the collection of variables they contain.

When you create an object, dBASE for Windows creates an object reference variable that refers to the object. Unlike other memory variables that actually contain a value, such as a character string, object reference variables contain a reference to the object, not the object itself.

When you assign one object reference variable to another, you do not duplicate the object; you simply have another reference to the same object.

The following example shows how you use the NEW operator to create a form object from the Form class (there are two ways to create objects; you can use the NEW operator or the DEFINE command):

CustomerForm = NEW Form() && CustomerForm is the
                          && object reference variable

Once you have created the form, you can set its properties by referencing the property variables. As discussed earlier, an object is a collection of variables, and each property is a variable.

The following example shows how you use the dot (.) operator to reference an object property:

CustomerForm.Text = "Customer Data"
CustomerForm.Width = 80.00
CustomerForm.Top = 2.00
CustomerForm.Left = 2.00
CustomerForm.Height = 24.75

As the example illustrates, you reference the object properties by specifying the object reference variable and the property variable.


See Also

Data Types

Object Operators


Language

DEFINE

Dot Operator

NEW Operator


Operators

See Also

An operator is a symbol or keyword that performs an operation on data or expressions. dBASE for Windows provides the following types of operators:

Assignment

Numeric

Relational

Logical

String

Object

NEW Operator

Index Operator

Dot Operator

Function

Call Operator

Member Call Operator

Index Call Operator

Scope Resolution

Macro

When you mix operators in a single expression, dBASE evaluates them in a predefined order. For information about this order, see Operator Precedence.

All operators require either one or two arguments, called operands. Those that require a single operand are called unary operators; those requiring two operands are called binary operators.

The following is an example of a unary operator, .NOT.:

lTrue = .T.
? .NOT. lTrue  && returns .F.

The following is an example of a binary operator, * :

? 7 * 7


See Also

Language Definition


Assignment Operators

See Also

dBASE provides the equals (=) operator to assign values of expressions to memory variables. For example, you can use the equals operator to store a character string:

x = "Store this string in x"

The assignment operator can be used with expressions of any data type.


See Also

Data Types

Expressions

Memory Variables

Operators


Numeric Operators

See Also

Numeric operators perform numeric calculations and generate numeric results. Here are the numeric operators that dBASE for Windows provides:

Operator	Description
+	Addition/unary positive
-	Subtraction/unary negative
*	Multiplication
/	Division
** or ^	Exponentiation
( )	Parentheses for grouping (to explicitly specify the order in which expressions are evaluated)
Numeric operators are used with numeric expressions. You can also use numeric operators with date expressions to subtract one date from another date and to add a number or subtract a number from a date (where the number represents a number of days).


See Also

Data Types

Expressions

Operators


Relational Operators

See Also	Language

Relational operators are used to compare two expressions of the same data type and generate a logical true (.T.) or false (.F.) result.  The operators can be used with character, numeric, and date expressions. Here are the relational operators that dBASE for Windows supports.

Operator	Description
<	Less than
>	Greater than
=	Equal to
==	Exactly equal to
<> or #	Not equal to
<= or =<	Less than or equal to
>= or =>	Greater than or equal to
$	Substring comparison
Character string comparisons are case-sensitive and are affected by the current language driver and the setting of the SET EXACT command.

When SET EXACT is OFF, character strings match if all characters in the string on the right of the equal (=) sign match the beginning characters in the string on the left; the string on the right can be shorter, but not longer, than the string on the left.

When SET EXACT is ON, the characters in both strings must be identical. Trailing blanks, however, are ignored.

The following example shows how the SET EXACT setting works:

SET EXACT OFF
? "abcde" = "abcd"  && returns .T.
? "abc" = ""        && returns .T.
? "abc" = "abcd"    && returns .F.
SET EXACT ON
?"abcde" = "abcd"   && returns .F.
? "abc" = "abc "    && returns .T.
                    && (trailing blanks ignored)

To impose an exact comparison whether SET EXACT is ON or OFF, use == instead of =.

The $ (contained in) string comparison operator compares two character strings to determine if the character string on the left is contained in the character string on the right. For example, A$B returns true if character string A is either identical to character string B or contained within B. You can specify a substring as a literal character string, a character memory variable, or a character or memo field.


See Also

Data Types

Expressions

Operators


Language

SET EXACT


Logical Operators

See Also

Logical operators are used to compare two logical expressions and generate a logical true (.T.) or logical false (.F.) result. The operators dBASE for Windows supports are the following:

Operator	Description
.AND.	Logical AND; returns true if both expressions are true.
.OR.	Logical OR; returns true if either of the expressions is true.
.NOT.	Logical NOT; returns false if expression is true, true if expression is false.
( )	Parentheses for grouping (to explicitly specify the order in which expressions are evaluated).


See Also

Data Types

Expressions

Operators


String Operators

See Also

String operators concatenate two or more character strings into a single character string. dBASE for Windows supports the following string operators:

Operator	Description
+	Concatenates two strings, leaving trailing spaces between the strings intact when the strings are joined
-	Concatenates two strings, moving trailing spaces in the first string to the end of the last string
( )	Parentheses for grouping (to explicitly specify the order in which expressions are evaluated)


See Also

Data Types

Expressions

Operators


Object Operators

See Also

Object operators are used to create and reference objects, properties, and methods (functions or codeblocks). dBASE for Windows supports the following object operators:

Operator	Description
NEW	Creates a new instance of an object
[index-ref]	Index or array index operator which accesses the contents of an object through a value
. (dot)	Dot operator which accesses the contents of an object through an identifier name
Choose one of these topics for more information:

NEW Operator

Index Operator

Dot Operator


See Also

Operators


NEW Operator

See Also	Language

The NEW operator creates an object of a specified class.

The following is the syntax for the NEW operator:

<object name> = NEW <class name>([<parameters>])

The following example shows how to use the NEW operator to create a form from the Form class. By default, dBASE creates an object reference variable with the same name you give the form (CustomerForm in this example).

CustomerForm = NEW Form()

The object exists as long as there are references to it.

Note:	The DEFINE command is another way to create an object.


See Also

Object Operators


Language

DEFINE


Index Operator

See Also

The index operator, [ ], accesses the properties or methods of an object through a value, which is usually a number. The following shows the syntax for using the index operator (often called the array index operator):

<object reference>[<expN>]

You typically use the index operator to reference elements of array objects, as shown in the following example:

TArray = NEW Array(20)  && Create a new array
                        && object with 20 elements
TArray[1] = 10          && Change the value of
                        && the 1st element to 10
  ? TArray[1]           && Returns 10


See Also

Object Operators


Dot Operator

See Also

The dot operator, (.), accesses the properties or methods of an object through a name. The following shows the syntax for using the dot operator:

<object reference>.[<object reference>.]<property name>

The dot operator is the most common way to refer to the object properties or methods. The following statements illustrate how you use it to assign values:

DEFINE FORM CustFrm          && Create a new
                             && form object
CustFrm.Text = "Customers"   && Set the Text
                             && property of CustFrm
  CustFrm.OnOpen = OpenProc  && Set the OnOpen
                             && event property of CustFrm

If an object contains another object, you can access the child object properties by building a path of object references leading to the property, as the following statements illustrate:

DEFINE ENTRYFIELD NameField OF CustFrm
  && Create an entry field in the CustFrm form
CustFrm.NameField.Width = 20
  && Set the Width property of NameField in CustFrm


See Also

Object Operators


Function Operators

See Also

Function operators are used to call functions and procedures. dBASE for Windows supports the following object operators:

Operator	Description
<fp>([params])	Call operator; calls a function associated with a function-pointer <fp>
<obj-ref>.code-ref([params])	Member call operator; calls the function or codeblock associated with a specified code-reference variable
<obj-ref>[<exp>](<params>)	Index call operator; similar to member call operator but calls the function or codeblock with an index
Choose one of the following topics for more information:

Call Operator

Member Call Operator

Index Call Operator


See Also

Operators


Call Operator

See Also

The call operator, ( ), calls a procedure or codeblock associated with a specified function-pointer or codeblock variable. It also passes any specified parameters to the procedure or codeblock. The following is the syntax for the call operator:

<function pointer|codeblock variable>([parameters])

The following statements are examples of how you use the call operator to call a procedure associated with a function pointer:

? Square(10)        && Calls procedure Square; returns 100
? TYPE("Square")    && Returns FP; Square is a constant of type function pointer
  Calc = Square     && Creates a variable of type function pointer
  ? Calc(7)         && Calls procedure Square; returns 49

  PROCEDURE Square
  PARAMETERS n
  RETURN n*n

The following statements show how you use the call operator to call a codeblock:

x = {|z| z + 1}  && Creates a variable of type codeblock
? x(6)           && Calls the codeblock stored in the variable


See Also

Codeblock

Function Operators

Function-Pointer

Index Call Operator

Member Call Operator


Member Call Operator

See Also

Like the call operator, the member call operator calls the procedure or codeblock associated with a specified function-pointer or codeblock variable. The difference is that the function-pointer or codeblock variable is contained within an object. In addition, when you call the procedure or codeblock, dBASE creates a special object reference variable called this. The following is the syntax for the member call operator:

<object reference>.<function pointer|codeblock variable>([parameters])

The following example shows how to use the member call operator:

x = NEW OBJECT()     && Creates a new object
x.Proc = DisplayVal  && Assigns procedure to variable of fp type
x.Val = 7            && Assigns a number to the Val variable
? x.Proc()           && Calls procedure in fp variable in x, returns 7

PROCEDURE DisplayVal
RETURN this.val

As the example illustrates, the this variable (like the object reference variable x) references the object. In fact, in the procedure definition, using RETURN x.val gives the same results as RETURN this.val. The difference is that using x hard codes the object reference; you would be able to return val only to object x. With the this variable, you can use the procedure as is in any other object.


See Also

Call Operator

Codeblock

Function Operators

Function-Pointer

Index Call Operator


Index Call Operator

See Also

The index call operator works the same way as the member call operator but calls the procedure or codeblock with an index value. As with the member call operator, dBASE creates a special object reference variable called this when the procedure or codeblock is called.The following is the syntax for the index call operator:

<function pointer|codeblock variable>[expN]([parameters])

You can access unnamed members of a class using the index, just as you would refer to array elements:

x = NEW ARRAY()  && Creates a new array object
x[1] = MyProc    && Assigns the procedure to array element 1
x.val = 10     && Assigns a number to the Val variable
? x[1]()       && Calls procedure stored in element 1, returns 10

PROCEDURE MyProc
RETURN this.val


See Also

Call Operator

Function Operators

Index Call Operator

Member Call Operator


Scope Resolution Operator

See Also

The scope resolution operator (::) lets you reference methods in a class. This is useful if you have built a hierarchy of classes and you want to call a method from a superclass. You can, for example, modify an inherited method in a subclass by calling the method directly from the superclass, then adding to its behavior in the subclass.

The following is the syntax for using the scope resolution operator:

<class name> | class | super :: <method name>

As the syntax indicates, you can refer to the superclass by its class name, or one of the keywords, class or super.

class references the current class (the class being declared).

super references the superclass of the current class.

The following example shows how the BeepMove pushbutton accesses the BeepProc procedure from its superclass, BeepButton, then adds new functionality to it:

CLASS BeepButton(form) OF MyButton(form)

  this.text = "Beep"

  this.Onclick = BeepProc

PROCEDURE BeepProc

    ? CHR(7)

  RETURN

ENDCLASS

CLASS BeepMove(form) OF BeepButton(form)
  this.text = "Beep and Move"   && Overrides Text property of
                                && superclass

    PROCEDURE OnClick
     super::BeepProc()          && References the BeepProc method of
                                && superclass
     this.Left = this.Left+1    && Adds functionality to OnClick
    RETURN
ENDCLASS

Note:	The super::BeepProc( ) statement is the same as BeepButton::BeepProc( ).

With the scope resolution operator, you can also call a method from a class. As with any procedure, the class declaration must be in the same program file as the call statement, or be loaded as a procedure file with SET PROCEDURE. The following example illustrates how you use the scope resolution operator to call a method in a class:

? MyClass::SayHello()  && Calls the method in MyClass; prints Hello

CLASS MyClass
  PROCEDURE SayHello
    ? "Hello"
  RETURN .T.
ENDCLASS


See Also

Operators


Macro Operator (&)

See Also

Sometimes it is impossible to know what arguments to use in a command line until your program is running. For instance, you might write a subroutine that processes records in a table based on a criteria entered by the user, such as State = "MI". In this case, you cannot enter the criteria in your source code because you do not know what it will be. In addition, some commands, such as FIND, require literal values as arguments, and you usually do not know what value to enter until run time. For these situations, dBASE provides the macro operator (&).

The macro operator substitutes the contents of a character memory variable in place of the variable name in a command line. In this way, you can store command-line arguments to character variables, and extract the arguments with the macro operator at run time. This process is called macro substitution or macro expansion.

You perform macro substitution by placing the macro operator (&) directly before the variable name in a command line. At run time, dBASE evaluates the contents of the character variable, and substitutes the result in place of the ampersand and variable name.

Here is the syntax for using the macro operator:

&<character memory variable>[.]

The optional period (.) at the end of the variable name identifies the end of the variable name. The period is sometimes called the macro terminator. Use the period when you need to distinguish the variable name from text that follows it in the command line.

Here are some examples of typical uses of macro expansion:

** code code code

* DO WHILE &cCondition
** code code code

You can use macro substitution only for command arguments. The variable you expand cannot contain the entire command, or any command keywords, such as FOR or WHILE.

dBASE for Windows makes some former uses of the macro operator, such as setting color codes, unnecessary. For instance, the COLOR option of @...SAY/GET requires a literal string for the color codes. In dBASE for Windows, you specify colors for text and entry field objects (the counterparts to SAYs and GETs) by setting properties that accept a character expression.

DEFINE FORM MyForm

DEFINE TEXT MyText OF MyForm PROPERTY;
  color ...
DEFINE ENTRYFIELD MyEntry OF MyForm PROPERTY;
  color ...

Since dBASE performs macro substitution at run time, macros cannot expand into preprocessor directives, which are evaluated at compile time.


See Also

Operators


Operator Precedence

See Also

You can combine several different operators in a single expression. The way in which dBASE for Windows will evaluate an expression is determined by the order in which different operators are evaluated. The following table lists the precedence in which dBASE for Windows evaluates operators.

Operator	Description
( )	Parentheses grouping, all expressions
[ ]	Field name, character memory variable, and array indexing
->	Alias symbol
. (dot)	Dot operator
NEW	New object operator
+, -	Unary plus (+) and (-) signs
**, ^	Exponentiation
*, /	Multiplication and division
+, -	Addition and subtraction
=, <>, <, <=, >, >=, $	Relational operators
.NOT., .AND, .OR.	Logical operators
You can use parentheses to group expressions and explicitly specify the order in which you want expressions evaluated. If you nest parentheses, expressions in the innermost parentheses are evaluated first.


See Also

Operators


Alphabetic List of the Language

Categorical List

!	#define
#if	#ifdef
#ifndef	#include
#pragma	#undef
&&	*
?	??
???	@...CLEAR
@...FILL	@...SAY...GET
@...SCROLL	@...TO
_alignment	_app
_box	_curobj
_dbwinhome	_indent
_lmargin	_padvance
_pageno	_pbpage
_pcolno	_pcopies
_pdriver	_pecode
_peject	_pepage
_pform	_plength
_plineno	_ploffset
_porientation	_ppitch
_pquality	_pscode
_pspacing	_pwait
_rmargin	_tabs
_wrap
A
ABS( )	ACCEPT
ACCESS( )	ACOPY( )
ACOS( )	ACTIVATE MENU
ACTIVATE POPUP	ACTIVATE SCREEN
ACTIVATE WINDOW	ADEL( )
ADIR( )	AELEMENT( )
AFIELDS( )	AFILL( )
AGROW( )	AINS( )
ALEN( )	ALIAS( )
ANSI( )	APPEND
APPEND AUTOMEM	APPEND FROM
APPEND FROM ARRAY	APPEND MEMO
ARESIZE( )	ASC( )
ASCAN( )	ASIN( )
ASORT( )	ASSIST
ASUBSCRIPT( )	AT( )
ATAN( )	ATN2( )
AVERAGE
B
BAR( )	BARCOUNT( )
BARPROMPT( )	BEGINTRANS( )
BEGIN...END TRANSACTION	BINTYPE( )
BITAND( )	BITLSHIFT( )
BITOR( )	BITRSHIFT( )
BITSET( )	BITXOR( )
BLANK	BOF( )
BOOKMARK( )	BROWSE
C
CALCULATE	CALL
CALL( )	CANCEL
CATALOG( )	CD
CDOW( )	CEILING( )
CENTER( )	CERROR( )
CHANGE	CHANGE( )
CHARSET( )	CHOOSEPRINTER( )
CHR( )	CLASS...ENDCLASS
CLASS ARRAY	CLASS BROWSE
CLASS CHECKBOX	CLASS COMBOBOX
CLASS DDELINK	CLASS DDETOPIC
CLASS EDITOR	CLASS ENTRYFIELD
CLASS FORM	CLASS IMAGE
CLASS LINE	CLASS LISTBOX
CLASS MENU	CLASS OBJECT
CLASS OLE	CLASS PUSHBUTTON
CLASS RADIOBUTTON	CLASS RECTANGLE
CLASS SCROLLBAR	CLASS SPINBOX
CLASS TEXT	CLEAR
CLEAR ALL	CLEAR AUTOMEM
CLEAR FIELDS	CLEAR GETS
CLEAR MEMORY	CLEAR MENUS
CLEAR POPUPS	CLEAR PROGRAM
CLEAR SCREENS	CLEAR TYPEAHEAD
CLEAR WINDOWS	CLOSE ALL
CLOSE ALTERNATE	CLOSE DATABASES
CLOSE FORMAT	CLOSE FORMS
CLOSE INDEXES	CLOSE PRINTER
CLOSE PROCEDURE	CLOSE TABLES
CMONTH( )	COL( )
COMMIT( )	COMPILE
COMPLETED( )	CONTINUE
CONVERT	COPY
COPY BINARY	COPY FILE
COPY INDEXES	COPY MEMO
COPY STRUCTURE	COPY TABLE
COPY TAG	COPY TO ARRAY
COPY TO...STRUCTURE EXTENDED	COS( )
COUNT	CREATE
CREATE...FROM	CREATE...STRUCTURE EXTENDED
CREATE APPLICATION	CREATE CATALOG
CREATE COMMAND	CREATE FILE
CREATE FORM	CREATE LABEL
CREATE MENU	CREATE QUERY
CREATE REPORT	CREATE SCREEN
CREATE SESSION	CREATE VIEW
CREATE VIEW...FROM ENVIRONMENT	CTOD( )
D
DATABASE( )	DATE( )
DAY( )	DBERROR( )
DBF( )	DBMESSAGE( )
DEACTIVATE MENU	DEACTIVATE POPUP
DEACTIVATE WINDOW	DEBUG
DECLARE	DEFINE
DEFINE BAR	DEFINE BOX
DEFINE COLOR	DEFINE MENU
DEFINE PAD	DEFINE POPUP
DEFINE WINDOW	DELETE
DELETE FILE	DELETE TABLE
DELETE TAG	DELETED( )
DESCENDING( )	DEXPORT
DGEN( )	DIFFERENCE( )
DIR/DIRECTORY	DISKSPACE( )
DISPLAY	DISPLAY COVERAGE
DISPLAY FILES	DISPLAY HISTORY
DISPLAY MEMORY	DISPLAY STATUS
DISPLAY STRUCTURE	DISPLAY USERS
DMY( )	DO
DO...UNTIL	DO CASE
DO WHILE	DOS
DOW( )	DTOC( )
DTOR( )	DTOS( )
E
EDIT	EJECT
EJECT PAGE	ELAPSED( )
EMPTY( )	EOF( )
ERASE	ERROR( )
EXP( )	EXPORT
EXTERN
F
FCLOSE( )	FCREATE( )
FDATE( )	FDECIMAL( )
FEOF( )	FERROR( )
FFLUSH( )	FGETS( )
FIELD( )	FILE( )
FIND	FIXED( )
FKLABEL( )	FKMAX( )
FLDCOUNT( )	FLDLIST( )
FLENGTH( )	FLOAT( )
FLOCK( )	FLOOR( )
FLUSH	FOPEN( )
FOR( )	FOR...NEXT
FOUND( )	FPUTS( )
FREAD( )	FSEEK( )
FSIZE( )	FTIME( )
FUNCTION	FUNIQUE( )
FV( )	FWRITE( )
G
GENERATE	GETCOLOR( )
GETDIRECTORY( )	GETENV( )
GETEXPR( )	GETFILE( )
GETFONT( )	GO
H
HELP	HOME( )
HTOI( )
I
ID( )	IF
IIF( )	IMPORT
INDEX	INKEY( )
INPUT	INSERT
INSERT AUTOMEM	INSPECT( )
INT( )	ISALPHA( )
ISBLANK( )	ISCOLOR( )
ISLOWER( )	ISMARKED( )
ISMOUSE( )	ISTABLE( )
ISUPPER( )	ITOH( )
J
JOIN
K
KEY( )	KEYBOARD
KEYMATCH( )
L
LABEL FORM	LASTKEY( )
LDRIVER( )	LEFT( )
LEN( )	LENNUM( )
LIKE( )	LINENO( )
LIST	LIST COVERAGE
LIST FILES	LIST HISTORY
LIST MEMORY	LIST STATUS
LIST STRUCTURE	LIST USERS
LISTCOUNT( )	LISTSELECTED( )
LKSYS( )	LOAD
LOAD DLL	LOCAL
LOCATE	LOCK( )
LOG( )	LOG10( )
LOGOUT	LOOKUP( )
LOWER( )	LTRIM( )
LUPDATE( )
M
MAX( )	MCOL( )
MD	MDOWN( )
MDX( )	MDY( )
MEMLINES( )	MEMORY( )
MENU( )	MESSAGE( )
MIN( )	MKDIR
MLINE( )	MOD( )
MODIFY APPLICATION	MODIFY COMMAND
MODIFY FILE	MODIFY FORM
MODIFY LABEL	MODIFY MENU
MODIFY QUERY	MODIFY REPORT
MODIFY SCREEN	MODIFY STRUCTURE
MODIFY VIEW	MONTH( )
MOVE WINDOW	MROW( )
MSGBOX( )
N
NDX( )	NETWORK( )
NEXTKEY( )	NOTE
O
OEM( )	ON BAR
ON ERROR	ON ESCAPE
ON EXIT BAR	ON EXIT MENU
ON EXIT PAD	ON EXIT POPUP
ON KEY	ON MENU
ON MOUSE	ON NETERROR
ON PAD	ON PAGE
ON POPUP	ON READERROR
ON SELECTION BAR	ON SELECTION FORM
ON SELECTION MENU	ON SELECTION PAD
ON SELECTION POPUP	OPEN DATABASE
OPEN FORM	ORDER( )
OS( )
P
PACK	PAD( )
PADPROMPT( )	PARAMETERS
PAYMENT( )	PCOL( )
PCOUNT( )	PI( )
PLAY MACRO	PLAY SOUND
POPUP( )	PRINTJOB...ENDPRINTJOB
PRINTSTATUS( )	PRIVATE
PROCEDURE	PROGRAM( )
PROMPT( )	PROPER( )
PROTECT	PROW( )
PUBLIC	PUTFILE( )
PV( )
Q
QUIT
R
RANDOM( )	RAT( )
READ	READKEY( )
READMODAL( )	RECALL
RECCOUNT( )	RECNO( )
RECSIZE( )	REDEFINE
REFRESH	REINDEX
RELATION( )	RELEASE
RELEASE AUTOMEM	RELEASE DLL
RELEASE MENUS	RELEASE MODULES
RELEASE OBJECT	RELEASE POPUPS
RELEASE SCREENS	RELEASE WINDOWS
RENAME	RENAME TABLE
REPLACE	REPLACE AUTOMEM
REPLACE BINARY	REPLACE FROM ARRAY
REPLACE MEMO	REPLACE MEMO...FROM
REPLACE OLE	REPLICATE( )
REPORT FORM	RESET
RESOURCE( )	RESTORE
RESTORE IMAGE	RESTORE MACROS
RESTORE SCREEN	RESTORE WINDOW
RESUME	RETRY
RETURN	RIGHT( )
RLOCK( )	ROLLBACK
ROLLBACK( )	ROUND( )
ROW( )	RTOD( )
RTRIM( )	RUN
RUN( )
S
SAVE	SAVE MACROS
SAVE SCREEN	SAVE WINDOW
SCAN	SECONDS( )
SEEK	SEEK( )
SELECT	SELECT( )
SET	SET( )
SETTO( )	SET ALTERNATE
SET AUTOSAVE	SET BELL
SET BLOCKSIZE	SET BORDER
SET CARRY	SET CATALOG
SET CENTURY	SET CLOCK
SET COLOR	SET COLOR OF
SET COLOR TO	SET CONFIRM
SET CONSOLE	SET COVERAGE
SET CUAENTER	SET CURRENCY
SET CURSOR	SET DATABASE
SET DATE	SET DATE TO
SET DBTRAP	SET DBTYPE
SET DEBUG	SET DECIMALS
SET DEFAULT	SET DELETED
SET DELIMITERS	SET DESIGN
SET DEVELOPMENT	SET DEVICE
SET DIRECTORY	SET DISPLAY
SET ECHO	SET EDITOR
SET ENCRYPTION	SET ESCAPE
SET EXACT	SET EXCLUSIVE
SET FIELDS	SET FILTER
SET FORMAT	SET FULLPATH
SET FUNCTION	SET HEADINGS
SET HELP	SET HELP ON|OFF
SET HISTORY	SET HOURS
SET IBLOCK	SET INDEX
SET INSTRUCT	SET INTENSITY
SET KEY	SET KEY TO
SET LDCHECK	SET LIBRARY
SET LOCK	SET MARGIN
SET MARK	SET MBLOCK
SET MEMOWIDTH	SET MESSAGE
SET MOUSE	SET NEAR
SET ODOMETER	SET ORDER
SET PATH	SET PAUSE
SET PCOL	SET POINT
SET PRECISION	SET PRINTER
SET PROCEDURE	SET PROW
SET REFRESH	SET RELATION
SET REPROCESS	SET SAFETY
SET SCOREBOARD	SET SEPARATOR
SET SKIP	SET SPACE
SET SQL	SET STATUS
SET STEP	SET TALK
SET TIME	SET TITLE
SET TOPIC	SET TRAP
SET TYPEAHEAD	SET UNIQUE
SET VIEW	SET WINDOW OF MEMO
SET WP	SHELL( )
SHOW MENU	SHOW OBJECT
SHOW POPUP	SIGN( )
SIN( )	SKIP
SLEEP	SORT
SOUNDEX( )	SPACE( )
SQLERROR( )	SQLEXEC( )
SQLMESSAGE( )	SQRT( )
STATIC	STORE
STORE AUTOMEM	STORE MEMO
STR( )	STUFF( )
SUBSTR( )	SUM
SUSPEND
T
TAG( )	TAGCOUNT( )
TAGNO( )	TAN( )
TARGET( )	TEXT
TIME( )	TOTAL
TRANSFORM( )	TRIM( )
TYPE	TYPE( )
U
UNIQUE( )	UNLOCK
UPDATE	UPDATED( )
UPPER( )	USE
USER( )
V
VAL( )	VALIDDRIVE( )
VARREAD( )	VERSION( )
W
WAIT	WINDOW( )
WORKAREA( )
Y
YEAR( )
Z
ZAP


Categorical List of the Language

Alphabetic List

The following list of categories will help you learn what language elements are available to perform programming tasks. Each category is a group of commands and functions based on their purpose.

Classes	Colors and Fonts
Date and Time Data	dBASE IV Menus
dBASE IV Windows	Disk and File Utilities
Environment	Error Handling and Debugging
Expressions and Type Conversion	Fields and Records
Forms	Input/Output
Keyboard and Mouse Events	Low-Level Access
Memory Variables	Numeric Data
Objects	Preprocessor
Printing	Programs
Shared Data	String Data
Table Basics	Table Organization
Windows Programming


Colors and Fonts Language Elements

See Also	Example

Use the following language elements to control screen color and character fonts.

DEFINE COLOR

GETCOLOR( )

GETFONT( )

ISCOLOR( )

SET COLOR OF

SET COLOR TO


See Also

Categorical List of the Language


Example of Colors and Fonts Language Elements

The following program code sets the color of displayed text, GET areas, and the results pane of the Command window:

OldColors = SET("ATTRIBUTE")
DEFINE COLOR Col_Yellow 255, 255, 0
* Define yellow
DEFINE COLOR Col_green 0, 255, 0
* Equivalent to G
SET COLOR OF NORMAL TO Col_Yellow/B
SET COLOR OF FIELDS TO B/Col_green
CLEAR
Today = DATE()
@ 5,10 SAY "Hello, today is " GET TODAY
READ
SET COLOR TO &Oldcolors


Date and Time Data Language Elements

See Also	Example

Use the following language elements to format, display, and keep track of date and time information.

CDOW( )

CMONTH( )

DATE( )

DAY( )

DMY( )

DOW( )

ELAPSED( )

MDY( )

MONTH( )

SECONDS( )

SET CENTURY

SET DATE

SET DATE TO

SET MARK

SET TIME

TIME( )

YEAR( )


See Also

Categorical List of the Language


Examples of Date and Time Data Language Elements

The first line of the following program code parses the hour, minute and second characters of the string returned by TIME( ) to calculate the number of seconds elapsed between midnight and the current time. The second line illustrates that SECONDS( ) returns the same value.

? TIME(),(VAL(SUBSTR(TIME(), 1, 2)) * 3600) + ;
   (VAL(SUBSTR(TIME(), 4, 2)) * 60) + ;
   VAL(SUBSTR(TIME(), 7, 2))
? SECONDS()

The following program code performs these tasks:

Uses CDOW( ) and CMONTH( ) to return the name of the day and the name of the month of a date value

Uses DAY( ) and MONTH( ) to return the number of the day and the month of the date value

Uses DOW( ) to return the number of the day in the week

Uses DMY( ) and MDY( ) to change the order in which the day and month are displayed

Uses SET DATE to format the data according to two different national standards

Uses SET CENTURY to show all four digits of the year

Uses SET MARK to change the delimiter that divides the day, month, and year

Uses YEAR( ) to return the year.

mDate = {06/01/94}
SET CENTURY OFF  && Display year with two digits
? CDOW(mDate)    && Returns Wednesday
? DOW(mDate)     && Returns 4
? CMONTH(mDate)  && Returns June
? MONTH(mDate)   && Returns 6
? DAY(mDate)     && Returns 1
? DMY(mDate)     && Returns 1 June 94
? MDY(mDate)     && Returns June 01, 94
SET CENTURY ON   && Display year with four digits
? mDate          && Returns 06/01/1994
? MDY(mDate)     && Returns June 01, 1994
SET DATE JAPAN
? mDate          && Returns 1994/06/01
SET DATE ITALIAN
? mDate          && Returns 01-06-1994
SET MARK TO "*"
? mDate          && Returns 01*06*1994
SET CENTURY OFF
? YEAR(mDate)    && Returns 1994 because YEAR()
                 && ignores SET CENTURY setting

The following program code performs these tasks:

Uses TIME( ) to store the current time in two memory variables (mStart and mEnd) at different times

Uses ELAPSED( ) to return the number of seconds between the two times and calculates the number of hours elapsed

mStart = TIME()  && Store the current time
DO LongRoutine
mEnd = TIME()    && Store the time after
                 && executing some code
* Convert seconds to hours
mDuration = ELAPSED(mEnd,mStart) / 3600
? mDuration      && Display hours elapsed


dBASE IV Menus Language Elements

See Also	Example

The following language elements create dBASE IV bar menus and popup menus. dBASE for Windows supports these language elements for compatibility with dBASE IV.

ACTIVATE MENU

ACTIVATE POPUP

BAR( )

BARCOUNT( )

BARPROMPT( )

CLEAR MENUS

CLEAR POPUPS

DEACTIVATE MENU

DEACTIVATE POPUP

DEFINE BAR

DEFINE MENU

DEFINE PAD

DEFINE POPUP

MENU( )

ON BAR

ON EXIT BAR

ON EXIT MENU

ON EXIT PAD

ON EXIT POPUP

ON MENU

ON PAD

ON POPUP

ON SELECTION BAR

ON SELECTION MENU

ON SELECTION PAD

ON SELECTION POPUP

PAD( )

PADPROMPT( )

POPUP( )

PROMPT( )

RELEASE MENUS

RELEASE POPUPS

SHOW MENU

SHOW POPUP


See Also

Categorical List of the Language


Examples of dBASE IV Menus Language Elements

The following program code uses DEFINE MENU to create a menu, then displays it in a dBASE IV window.

DEFINE WINDOW A FROM 5,10 TO 20,65;
    COLOR W+/B, RG+/RB+, R+/GB
DEFINE MENU Main;
    MESSAGE "Table Maintenance"
DEFINE PAD Add OF Main PROMPT "Add Records";
    AT 4,3 MESSAGE "Add new records"
DEFINE PAD Search OF Main PROMPT "Search File";
    AT 4,16 MESSAGE "Search for record"
DEFINE PAD Print OF Main PROMPT "Print";
    AT 4,29 MESSAGE "Print a report"
DEFINE PAD Exit OF Main PROMPT "Quit";
    AT 4,49 MESSAGE "Leave the program"

ON SELECTION PAD Add OF Main DO AddRec
ON SELECTION PAD Search OF Main DO SeekRec
ON SELECTION PAD Print OF Main DO Prt_Rpt
ON SELECTION PAD Exit OF Main DO ExitMain
CLEAR
ACTIVATE WINDOW A
ACTIVATE MENU Main

PROCEDURE ExitMain
DEACTIVATE WINDOW A  && Clears window from screen
DEACTIVATE MENU      && Clears menu from screen
CLEAR WINDOWS        && Clears window from memory
CLEAR MENUS          && Clears menu from memory
RETURN

PROCEDURE AddRec
KEYBOARD " "         && Demo purposes only
RETURN

PROCEDURE SeekRec
KEYBOARD " "         && Demo purposes only
RETURN

PROCEDURE Prt_Rpt
KEYBOARD " "         && Demo purposes only
RETURN

The following program code creates a popup menu and assigns actions to its selections.

* Sort Program
DEFINE POPUP Sort_pop FROM 2,2
DEFINE BAR 1 OF Sort_pop;

       PROMPT "Select Sort Order";
       SKIP                  && Line not selectable
DEFINE BAR 2 OF Sort_pop;

       PROMPT "*****************";
       SKIP                  && Line not selectable
DEFINE BAR 3 OF Sort_pop PROMPT "Ascending";
    MESSAGE "Sort the Country table in " +;

            "ascending order"
DEFINE BAR 4 OF Sort_pop PROMPT "Descending";
    MESSAGE "Sort the Country table in " +;

            "descending order"
DEFINE BAR 5 OF Sort_pop PROMPT "Exit program"
ON SELECTION POPUP Sort_pop DO Sort_proc

USE COUNTRY EXCLUSIVE
SET SAFETY OFF
SET TALK OFF
CLEAR
ACTIVATE POPUP Sort_pop
CLOSE ALL
SET TALK ON
SET SAFETY ON

PROCEDURE Sort_proc
IF BAR() = 3
    INDEX ON Name TAG Acountry
ELSEIF BAR() = 4
    INDEX ON Name TAG Dcountry DESCENDING
ELSEIF BAR() = 5
    DEACTIVATE POPUP  && Returns to line following
                      && ACTIVATE POPUP Sort_pop
                      && in the main program
ENDIF
BROWSE


dBASE IV Windows Language Elements

See Also	Example

The following language elements create and control dBASE IV windows. dBASE for Windows supports these language elements for compatibility with dBASE IV.

ACTIVATE WINDOW

CLEAR WINDOWS

DEACTIVATE WINDOW

DEFINE WINDOW

MOVE WINDOW

RELEASE WINDOWS

RESTORE WINDOW

SAVE WINDOW

WINDOW( )


See Also

Categorical List of the Language


Example of dBASE IV Windows Language Elements

The following program code opens three tiled windows, A, B, and C. A Table Records window is opened in windows B and C.

SELECT A
USE COMPANY
SELECT B
USE CONTACT
CLEAR
DEFINE WINDOW A FROM 1, 1 TO 15, 40 DOUBLE
DEFINE WINDOW B FROM 5, 5 TO 18, 60 DOUBLE
DEFINE WINDOW C FROM 10, 10 TO 23, 50 DOUBLE
ACTIVATE WINDOW A, B, C
BROWSE FIELDS COMPCODE, CONTACT
DEACTIVATE WINDOW C        && Cleared from screen
SELECT A
BROWSE FIELDS COMPANY, YTD_SALES
DEACTIVATE WINDOW B        && Cleared from screen
WAIT "Window A remains open"
DEACTIVATE WINDOW ALL      && Windows still exists
WAIT "No windows are open"
CLEAR WINDOWS              && Cleared from memory
CLEAR                      && Clear screen
RETURN


Disk and File Utilities Language Elements

See Also	Example

Use the following language elements to manage resources on your disk, such as files, directories, and unused storage space.

!

CD

COPY FILE

CREATE FILE

_dbwinhome

DELETE FILE

DIR/DIRECTORY

DISKSPACE( )

DISPLAY FILES

DOS

ERASE

FDATE( )

FILE( )

FSIZE( )

FTIME( )

FUNIQUE( )

GETDIRECTORY( )

GETENV( )

GETFILE( )

HOME( )

LIST FILES

MD

MKDIR

MODIFY FILE

OS( )

PUTFILE( )

RENAME

RUN

RUN( )

SET DEFAULT

SET DIRECTORY

SET PATH

TYPE

VALIDDRIVE( )


See Also

Categorical List of the Language


Examples of Disk and File Utilities Language Elements

The following program code saves the current directory to a variable, then uses SET DIRECTORY to change directories and examine files.

* This example assumes that
* directories were created by:
* MD D:\PROJECT
* MD D:\PROJECT\PROGRAMS
* MD D:\PROJECT\DATA
* MD C:\EDITOR

Olddir = SET("DIRECTORY")  && Original Directory
SET DIRECTORY TO D:\PROJECT\DATA
DIR                        && Displays DBFs
SET DIRECTORY TO D:\PROJECT\PROGRAMS
DIR *.PRG                  && Display the programs
SET DIRECTORY TO ..
* Moves from D:\PROJECT\PROGRAMS to D:\PROJECT
DIR *.*
SET DIRECTORY TO C:\EDITOR && C:\EDITOR
DIR *.DOC
SET DIRECTORY TO &Olddir   && Return

The following program code uses DIR to list files from different directories:

DIR  && Shows all tables in current subdirectory
DIR ON B: && Shows all tables on B drive
DIR A:    && Shows all tables on A drive
DIR *.PRG && Shows all program files
DIR LIKE *.* ON C:\DBASE
* Shows all files on C:\DBASE


Environment Language Elements

See Also	Example

Use the following language elements to change or monitor the operating environment in which your applications run.

CHARSET( )

CLEAR

CLEAR ALL

CREATE SESSION

DISPLAY MEMORY

DISPLAY STATUS

LDRIVER( )

LIST MEMORY

LIST STATUS

MEMORY( )

SET

SET BELL

SET BORDER

SET CONFIRM

SET CONSOLE

SET DESIGN

SET DISPLAY

SET EDITOR

SET FULLPATH

SET INTENSITY

SET LDCHECK

SET MESSAGE

SET ODOMETER

SET SAFETY

SET TALK

SET WP

SET( )

SETTO( )

SHELL( )

VERSION( )


See Also

Categorical List of the Language


Example of Environment Language Elements

The following code creates a custom class named SHELL from the standard class Form, then creates an instance of the new class (a form). When the user double-clicks the form with the right mouse button, the dBASE application window disappears, making the form appear independent of the dBASE session. Double-clicking the form with the left mouse button restores the dBASE application window.

LOCAL f
f = NEW SHELL()
f.Open()

CLASS SHELL OF FORM
   this.OnRightDblClick = {SHELL(.T.)}
   this.OnLeftDblClick = {SHELL(.F.)}
   this.EscExit = .T.
   * Set MDI=.t. to see effect with mdi
   this.MDI = .f.
   this.Text = "Shell Test .t."
   this.Width =        48.00
   this.Top =          2.00
   this.Left =         2.00
   this.Height =       15.00
   this.Minimize = .F.
   this.Maximize = .F.
ENDCLASS


Error Handling and Debugging Language Elements

See Also	Example

Use the following language elements to diagnose and recover from error conditions that occur during run time or compile time.

CERROR( )

DBERROR( )

DBMESSAGE( )

DEBUG

DISPLAY COVERAGE

ERROR( )

GENERATE

LINENO( )

LIST COVERAGE

MESSAGE( )

ON ERROR

ON READERROR

PROGRAM( )

RESUME

RETRY

SET COVERAGE

SET ECHO

SET STEP

SQLERROR( )

SQLMESSAGE( )

SUSPEND


See Also

Categorical List of the Language


Example of Error Handling and Debugging Language Elements

The following program code uses ON ERROR to open a form when a run-time error occurs. (A function call to Company( ) causes an error because the Company( ) function does not exist.)

ON ERROR DO ErrHndlr WITH;

   ERROR(), MESSAGE(), PROGRAM(), LINENO()
USE Clients
? Company()
RETURN

PROCEDURE ErrHndlr
PARAMETERS nERRORno, cErrMessage, cProgram, nLineNo
DEFINE FORM HeadsUp from 10, 25 TO 20, 50
DEFINE TEXT Line1 OF HeadsUp AT 2, 2 ;
  PROPERTY Text "An Error has occurred",;
  Width 22
DEFINE TEXT Line2 OF HeadsUp AT 4, 2;
  PROPERTY Text "Error: "+cErrMessage,;
  Width 22
DEFINE TEXT Line3 OF HeadsUp AT 5, 2;
  PROPERTY Text "Number: "+STR(nErrorno),;
  Width 22
DEFINE TEXT Line4 OF HeadsUp AT 6, 2;
  PROPERTY Text "Program: "+cProgram,;
  Width 22
DEFINE TEXT Line5 OF HeadsUp AT 7, 2;
  PROPERTY Text "Line #: "+STR(nLineno),;
  Width 22
OPEN FORM HeadsUp


Expressions and Type Conversion Language Elements

See Also	Example

Use the following language elements to create expressions or convert values from one type to another.

ASC( )

CHR( )

CTOD( )

DTOC( )

DTOS( )

EMPTY( )

FLOAT( )

GETEXPR( )

HTOI( )

ISBLANK( )

ITOH( )

MAX( )

MIN( )

STR( )

TYPE( )

VAL( )


See Also

Categorical List of the Language


Examples of Expressions and Type Conversion Language Elements

The following example uses ASC( ) to determine the ASCII value of a specified character:

SET TALK OFF
Plus_minus = CHR(241)
? "The ASCII value of "+Plus_minus+" is "
?? + LTRIM(STR(ASC(Plus_minus), 3, 0))

The following program code uses DTOC( ) to convert a date value to a character string so it can be concatenated with a character field (Client_ID) in an array element. The program also converts and concatenates a numeric value (StartBal) to character with STR( ).

SET TALK OFF
USE Clients
DECLARE String[RECCOUNT()]
Cnt = 1
SCAN
  STRING[Cnt] = Client_ID+"*"+DTOC(BalDate)+"*"+;
                LTRIM(STR(StartBal,7,2))
  Cnt = Cnt + 1
ENDSCAN
* The following FOR...NEXT loop verifies
* the contents of the array.
FOR i = 1 TO RECCOUNT()
  ? STRING[i] AT 10
NEXT i

The following program code displays the 255 characters that are possible with ASCII, ANSI, and OEM formats:

FOR i = 1 to 255
  ASCII=CHR(i)
  ? i, ASCII, ANSI(ASCII), OEM(ASCII)
  * The next 3 commands cause a pause
  * every 10 lines
  IF MOD(i,10) = 0
    WAIT
  ENDIF
NEXT i


Fields and Records Language Elements

See Also	Example

Use the following language elements to evaluate fields and records, extract data from them, modify the information they contain, and append or delete records.

APPEND

APPEND AUTOMEM

APPEND FROM ARRAY

APPEND MEMO

BINTYPE( )

BLANK

BOF( )

BOOKMARK( )

BROWSE

CHANGE

CLEAR AUTOMEM

CLEAR FIELDS

COPY BINARY

COPY MEMO

COPY TO ARRAY

COUNT

DELETE

DELETED( )

EDIT

EOF( )

FDECIMAL( )

FIELD( )

FLDCOUNT( )

FLDLIST( )

FLENGTH( )

FLUSH

GO

INSERT

INSERT AUTOMEM

LUPDATE( )

MEMLINES( )

MLINE( )

PACK

RECALL

RECCOUNT( )

RECNO( )

RECSIZE( )

RELEASE AUTOMEM

REPLACE

REPLACE AUTOMEM

REPLACE BINARY

REPLACE FROM ARRAY

REPLACE MEMO

REPLACE MEMO...FROM

REPLACE OLE

SET AUTOSAVE

SET BLOCKSIZE

SET CARRY

SET DELETED

SET FIELDS

SET MBLOCK

SET MEMOWIDTH

SET WINDOW OF MEMO

SKIP

STORE AUTOMEM

STORE MEMO

ZAP


See Also

Categorical List of the Language


Examples of Fields and Records Language Elements

The following program code uses APPEND BLANK to add a blank record at the end of a table:

USE CLIENTS
? RECCOUNT()      && Returns number of
                  && records in table
APPEND BLANK
? RECCOUNT()      && Returns previous
                  && number plus 1
EDIT              && Opens new record
                  && for data entry

The following example uses SET FIELDS ON and OFF to alternate between a fields list (declared with SET FIELDS TO) and a table in the current work area.

SELECT 1
USE Contact Order CompCode
SELECT 2
USE Company
SET RELATION TO CompCode INTO Contact
SET FIELDS TO Contact->CompCode, Company->Company, ;
   Contact->Contact, Company->Phone
SET FIELDS OFF
BROWSE              && Company displayed in Browse
SET FIELDS ON
BROWSE              && Fields list displayed
CLEAR FIELDS

The following program code uses APPEND AUTOMEM to add a new record to CLIENTS.DBF, replacing the content of fields in the table with values held in automem variables. In this case, the new record will be blank because CLEAR AUTOMEM is issued just prior to APPEND AUTOMEM.

SET TALK OFF
STORE " " TO Answer
USE Clients
? RECCOUNT()
DO WHILE UPPER(Answer) <> "Q"
   CLEAR AUTOMEM
   APPEND AUTOMEM
   ACCEPT "Press Q to Quit, Enter to Continue ";
          TO Answer
   ? RECCOUNT()
ENDDO


Forms Language Elements

See Also	Example

Use the following language elements to create, design, modify, and use forms.

CREATE APPLICATION

CREATE FORM

CREATE MENU

CREATE SCREEN

_curobj

MODIFY APPLICATION

MODIFY FORM

MODIFY SCREEN

MODIFY MENU

MSGBOX( )

ON SELECTION FORM

OPEN FORM

READMODAL( )

SET CUAENTER


See Also

Categorical List of the Language


Examples of Forms Language Elements

The following program code defines four forms and uses the syntax options of the OPEN FORM command to establish an initial focus order:

DEFINE FORM Opn1
DEFINE FORM Opn2 AT 4, 4
DEFINE FORM Opn3 AT 8, 8
DEFINE FORM Opn4 AT 12, 12
OPEN FORM Opn4, Opn1, Opn3, Opn2

The following program code defines a form and a list box for selecting an aircraft model. The program uses ON SELECTION FORM to call a UDF when the user presses Enter. The UDF displays a graphic image from a binary field in the selected record.

CLOSE ALL
SET TALK OFF
SET PROCEDURE TO PROGRAM(1) ADDITIVE
USE Aircrdb ORDER Aircraft IN SELECT()
SELECT Aircrdb
DEFINE FORM AC               ;
   PROPERTY                  ;
      Top 5,                 ;
      Left 2,                ;
      Height 13,             ;
      Width 30,              ;
      Text "Aircraft",       ;
      Sizeable .T.
DEFINE LISTBOX Model OF AC             ;
   PROPERTY                            ;
      Top 2,                           ;
      Left 10,                         ;
      Height 7,                        ;
      Width 18,                        ;
      DataSource "FIELD AIRCRDB->AIRCRAFT"
ON SELECTION FORM AC Photo
OPEN FORM AC

FUNCTION Photo
  RESTORE IMAGE FROM BINARY IMAGE
RETURN .T.


Input/Output Language Elements

See Also	Example

Use the following language elements to perform input and output operations. Most of these language elements (such as @...SAY...GET) are included for compatibility with dBASE IV and dBASE III PLUS, and are not designed for Windows programming.

?

??

@...CLEAR

@...FILL

@...SAY...GET

@...SCROLL

@...TO

ACCEPT

ACTIVATE SCREEN

CLEAR GETS

CLEAR SCREENS

COL( )

CREATE LABEL

CREATE REPORT

INPUT

LABEL FORM

MODIFY LABEL

MODIFY REPORT

READ

RELEASE SCREENS

REPORT FORM

RESTORE SCREEN

ROW( )

SAVE SCREEN

SET ALTERNATE

SET DELIMITERS

SET DEVICE

SET FORMAT

SET HEADINGS

SET SPACE

TEXT

UPDATED( )

VARREAD( )

WAIT


See Also

Categorical List of the Language


Example of Input/Output Language Elements

The following program code uses @...SAY...GET for data entry. It uses the PICTURE, COLOR, VALID ERROR and MESSAGE options to enhance the screen and validate the data. The program uses relative row addressing with ROW( ) and COL( ) to place the SAYs and GETs on the screen. Then it executes a READ to activate the GETs.

To create a data input format that is more suited to the Windows environment, use forms and entryfields.

Firstname = SPACE(10)
Lastname = SPACE(20)
Address = SPACE(25)
CLEAR  && Clear the screen
@ 0, 0 SAY "PERSONNEL INFORMATION";
  COLOR W+/G
@ 5, 10 SAY "First name "
@ ROW(), COL();
  GET Firstname;
  PICTURE "!XXXXXXXXX";
  MESSAGE "Enter your first name"
@ 7, 10 SAY "Last name  ";
  GET Lastname;
  VALID REQUIRED (.NOT. EMPTY(Lastname));
  ERROR "You must enter a last name"
@ ROW() + 2, 10 SAY "Address    ";
  GET Address PICTURE "@!"
READ


Keyboard and Mouse Events Language Elements

See Also	Example

Use the following language elements to interpret, detect, or simulate keyboard input and mouse events. Some of these language elements (such as READKEY( )) are included for compatibility with dBASE IV and dBASE III PLUS, and are not designed for Windows programming.

CLEAR TYPEAHEAD

FKLABEL( )

FKMAX( )

INKEY( )

ISMOUSE( )

KEYBOARD

LASTKEY( )

MCOL( )

MDOWN( )

MROW( )

NEXTKEY( )

ON ESCAPE

ON KEY

ON MOUSE

READKEY( )

SET CURSOR

SET ESCAPE

SET FUNCTION

SET KEY

SET MOUSE

SET TYPEAHEAD


See Also

Categorical List of the Language


Examples of Keyboard and Mouse Events Language Elements

The following program code draws a box on the screen, displays a prompt followed by a GET, then executes READ. If the user clicks the left mouse button while the READ is active, the CheckMous procedure displays a message saying where the user clicked.

To process mouse events in ways that are more suited to the Windows environment, use mouse event properties like OnLeftMouseDown and OnRightMouseDown.

ON MOUSE DO CheckMous
CLEAR
@ 2, 5 TO 4, 10  && Draw a box
Ans = " "
@ 10, 0 SAY ;
  "Click the mouse. Press any key when done" ;
   GET Ans
READ
ON MOUSE  && Reset ON MOUSE

PROCEDURE CHECKMOUS
r = MROW()  && Mouse row
c = MCOL()  && Mouse col
IF (r >= 2 .AND. r <= 4) .AND.;

   (c >= 5 .AND. c <= 10)
  @ 11, 0 SAY "You clicked in the box"
ELSE
  @ 11, 0 SAY "You clicked outside the box"
ENDIF


Low-Level Access Language Elements

See Also	Example

Use the following language elements to manipulate files at the bit level.

FCLOSE( )

FCREATE( )

FEOF( )

FERROR( )

FFLUSH( )

FGETS( )

FOPEN( )

FPUTS( )

FREAD( )

FSEEK( )

FWRITE( )


See Also

Categorical List of the Language


Examples of Low-Level Access Language Elements

The following example uses FCLOSE( ) to close the README.TXT file after adding text:

IF FILE("C:\DBASEWIN\README.TXT")
Handle = FOPEN("README.TXT","RW") && Read-Write
FSEEK(Handle,0,2)                 && Move to EOF
FPUTS(Handle,"The End")           && Write to file
  IF .NOT. FCLOSE(Handle)         && Try to close
    ? "Couldn't close the file"
    ? "The DOS error number is:", FERROR()
  ENDIF
ENDIF

This example compares the date and time stamps of COMPANY.DBF with the date and time stamps of a backup copy on the B drive. If the backup copy is dated earlier than the current table, a backup is recommended.

IF FDATE("B:COMPANY.DBF") < FDATE("COMPANY.DBF");
   .AND.;
   FTIME("B:COMPANY.DBF") < FTIME("COMPANY.DBF")
   ? "Time to do a backup"
   Difference = ;
   FDATE("COMPANY.DBF") - FDATE("B:COMPANY.DBF")
   ? Difference, " days since last backup"
   WAIT
ENDIF

The following example uses FWRITE( ) within a SCAN loop to write the contents of the Name field in ANIMALS.DBF to a text file. The program then uses FGETS( ) within a DO WHILE .NOT. FEOF( ) loop to display the contents of the text file to the Command window.

nFile = "ANIMALS.TXT"
nHandle = FCREATE(nFile,"RW")   && Create text file
SET PATH TO C:\DBASEWIN\SAMPLES && Access SAMPLES

                                && directory
USE ANIMALS
* Input data
SCAN

  * Concatenate Name field contents

  * plus CR/LF to text file.
  FWRITE(nHandle,Trim(Name)+CHR(13)+CHR(10))
ENDSCAN

FSEEK(nHandle,0,0)           && File pointer to
                             && top of file
CLEAR                        && Clear results pane
                             && of Command window
DO WHILE .NOT. FEOF(nHandle)
   ? FGETS(nHandle)          && Display line
ENDDO
FCLOSE(nHandle)              && Close Animals.TXT


Memory Variables Language Elements

See Also	Example

Use the following language elements to create, access, and manage memory variables and arrays.

ACOPY( )

ADEL( )

ADIR( )

AELEMENT( )

AFIELDS( )

AFILL( )

AGROW( )

AINS( )

ALEN( )

ARESIZE( )

ASCAN( )

ASORT( )

ASUBSCRIPT( )

CLEAR MEMORY

DECLARE

LOCAL

PRIVATE

PUBLIC

RELEASE

RESTORE

SAVE

STATIC

STORE


See Also

Categorical List of the Language


Examples of Memory Variables Language Elements

The following program code uses PUBLIC, PRIVATE, LOCAL, and STATIC to create memory variables.

PUBLIC mName          && Declare mName as public
mName = SPACE(30)     && Give mName specific value
PRIVATE nCost         && Doesn't yet have a value
nCost = 500           && nCost initialized to 500
PUBLIC mCode, mDesc   && Declare two variables
LOCAL cName           && Doesn't yet have a value
STATIC lFinished      && Initialized as .F.
STATIC nTotal = 1000  && Only Static variables can
                      && be declared and
                      && initialized to a specific
                      && value in single statement

The following program code performs these tasks:

Creates an array object with DECLARE

Inserts 0 in all array object elements with AFILL( )

Copies table data into the array object elements

Sorts the new contents with ASORT( )

USE <filename> EXCLUSIVE   && EXCL ensures access
                           && to all records in a
                           && multiuser environment
nRecords = RECCOUNT( )
DECLARE aArray[nRecords,3] && 1 row for each
                           && record and 3 columns
AFILL(aArray,0)            && Put 0 in all elements
GO TOP
nRec = 1
SCAN
aArray[nRec,1] = Salary
aArray[nRec,2] = Years_here
aArray[nRec,3] = Age
nRec = nRec + 1
ENDSCAN
USE                  && Allow other users access
                     && to the table
ASORT(aArray)        && With ASORT(), all elements
                     && must be the same data type.
                     && That's why we used AFILL( )
? aArray[nRecords,1] && Highest salary is in the
                     && first column of last row
ASORT(aArray,3)      && Sort by age (column 3)
? aArray[1,3]        && Returns youngest
? aArray[nRecords,3] && Returns oldest


Numeric Data Language Elements

See Also	Example

Use the following language elements to perform mathematical operations on numeric values and to determine their accuracy, format, and appearance.

ABS( )

ACOS( )

ASIN( )

ATAN( )

ATN2( )

CEILING( )

COS( )

DTOR( )

EXP( )

FLOOR( )

FV( )

INT( )

LENNUM( )

LOG( )

LOG10( )

MOD( )

PAYMENT( )

PI( )

PV( )

RANDOM( )

ROUND( )

RTOD( )

SET CURRENCY

SET DECIMALS

SET POINT

SET PRECISION

SET SEPARATOR

SIGN( )

SIN( )

SQRT( )

TAN( )


See Also

Categorical List of the Language


Examples of Numeric Data Language Elements

The following program code creates a pushbutton that uses PV( ) to calculate the present value of an investment:

DEFINE PUSHBUTTON Results OF THIS AT 11, 18;
   PROPERTY Text "Loan Amount", Width 15,;
   OnClick;

  {;myResult="You can afford to borrow $"+;
   LTRIM(STR(PV(Form.Amnt.Value,;
   (Form.Int.Value/100)/12,Form.Pymts.Value),13,2));
   ; Form.PV.Text=myResult},;
   Height 2, ColorNormal "N/W"

The following program code creates a pushbutton that uses PAYMENT( ) to calculate the periodic payment necessary to pay a debt:

  DEFINE PUSHBUTTON Results OF THIS AT 10,18;
   PROPERTY Text "Payment",;
   OnClick {;myResult="Your payment will be: $" + ;
   LTRIM(STR(PAYMENT(Form.Princ.Value,;
   (Form.Int.Value/100)/12,Form.Pay.Value),13,2));
   ; Form.FV.Text = MyResult},;
   Height 2, ColorNormal "N/W", Width 10

The following example uses COS( ) and DTOR( ) to compute the length of a rafter after room width and roof angle have been entered by the user:

SET PROCEDURE TO PROGRAM(1) ADDITIVE
f = NEW Rafter()
f.OPEN()
CLASS Rafter OF FORM
  this.Top=2
  this.Left=2
  this.Width=30
  this.Height=12
  this.Text = "Rafter Computer"
DEFINE ENTRYFIELD Room OF THIS AT 2, 22;
  PROPERTY Picture "999", Value 0, Width 4
DEFINE ENTRYFIELD Angle OF THIS at 4, 22;
  PROPERTY Picture "99", Value 0, Width 4
DEFINE ENTRYFIELD RaftLength OF THIS AT 6, 22;
  PROPERTY Width 6, Value 0,;
    OnGotFocus Results
DEFINE TEXT Ln1 OF THIS AT 2, 3;
  PROPERTY Text "Enter Width of Room:",;
    Width 15
DEFINE TEXT Ln2 OF THIS AT 4, 3;
  PROPERTY Text "Enter Angle of Rise:",;
    Width 15
DEFINE TEXT Ln3 OF THIS AT 6, 3;
  PROPERTY Text "Cut Rafter to this length:",;
    Width 18, ColorNormal "R/W"
DEFINE PUSHBUTTON Exit OF THIS AT 9, 11;
  PROPERTY TEXT "Exit", OnClick {;Form.Close()}
ENDCLASS

FUNCTION Results
Form.RaftLength.Value =;

     LTRIM(STR((Form.Room.Value/2);
  /COS(DTOR(Form.Angle.Value)), 6, 2))
RETURN .T.


Objects Language Elements

See Also	Example

Use the following language elements to create, access, and evaluate objects and to create custom classes.

_app

CLASS...ENDCLASS

DEFINE

INSPECT( )

LISTCOUNT( )

LISTSELECTED( )

PLAY SOUND

REDEFINE

RELEASE OBJECT

RESTORE IMAGE

SHOW OBJECT


See Also

Categorical List of the Language


Examples of Objects Language Elements

The following program code uses CLASS...ENDCLASS to define a custom class. The object derived from this class is a form that displays images from a table.

LOCAL f
f = NEW PICTURES()
f.Open()

CLASS PICTURES OF FORM
  this.EscExit = .T.
  this.View = "PICTURES.QBE"
  this.ColorNormal = "BG/B"
  this.Text = "Pictures Form"
  this.Width =         76.00
  this.Top =          0.00
  this.Left =          0.00
  this.Height =         30.00
  this.Minimize = .F.
  this.Maximize = .F.
  this.OnOpen = {;create session}

  DEFINE PUSHBUTTON SOUND OF THIS;
    PROPERTY;
      OnClick;

      {;PLAY SOUND BINARY PICTURES->SOUND},;
      Text "Sound",;
      Width         18.00,;
      Top          5.00,;
      Left          1.00,;
      Height          3.00,;
      FontSize         16.00,;
      FontName "Courier"

  DEFINE LISTBOX THINGS OF THIS;
    PROPERTY;
      ColorNormal "bg+/b",;
      Width         18.50,;
      Top         11.42,;
      Left          0.75,;
      Height          5.50,;
      DataSource "FIELD NAME",;
      ColorHighLight "W+/B",;
      FontSize         11.25,;
      FontName "Fixedsys",;
      ID        800

  DEFINE IMAGE PICTURE OF THIS;
    PROPERTY;
      Width         55.00,;
      Top          5.00,;
      Left         20.00,;
      Height         24.00,;
      DataSource "BINARY PICTURES->BITMAP",;
      ID         88

  DEFINE TEXT TITLE OF THIS;
    PROPERTY;
      ColorNormal "gr+/b",;
        Text "Sights and Sounds",;
        Width         59.50,;
        Top          0.00,;
        Left         20.00,;
        Height          4.30,;
        FontSize         32.00,;
        FontName "Serif"
ENDCLASS

PROCEDURE Sound_OnClick
PLAY SOUND Binary Pictures->Sound

PROCEDURE ClosePictures
USE IN Pictures
FORM.CLOSE()

The following program code defines a form containing a list box that displays names from a table. The Multiple property of the list box is set to true (.T.), allowing the user to select more than one list box prompt. The OnRightMouseDown property of the form calls a procedure named Checked. This procedure uses LISTCOUNT( ) and LISTSELECTED( ) to display all selected prompts in the Command window results pane after each right click event.

USE Animals.DBF
SET PROCEDURE TO PROGRAM(1) ADDITIVE
f = NEW ENTRY()
f.OPEN()
CLASS Entry OF FORM
  this.Top = 2
  this.Left = 2
  this.Width = 35
  this.Height = 20
  this.Text = "Animals of the World"
  this.OnRightMouseDown = Checked
  DEFINE LISTBOX LB1 OF THIS;
    PROPERTY;
      DataSource "FIELD Animals->Name",;
      Top 4,;
      Left 6,;
      Width 20,;
      Height 12,;
      Multiple .T.,;
      Name "LB1"
ENDCLASS

PROCEDURE Checked
FOR i=1 TO LISTCOUNT(Form.LB1)
  ? LISTSELECTED(Form.LB1,i)
NEXT i
RETURN


Preprocessor Language Elements

See Also	Example

Use the following preprocessor directives to control the way dBASE compiles your programs.

#define

#if

#ifdef

#ifndef

#include

#pragma

#undef


See Also

Categorical List of the Language


Examples of Preprocessor Language Elements

The following program code sets up conditional compilation for debugging purposes. If an identifier called DEBUG has been defined, the debugging code is compiled; otherwise, DO MyProcedure is compiled.

* Test for existence of Debug identifier.
#ifdef Debug        && If Debug exists.
SET ALTERNATE TO DEBUG.TXT
SET ALTERNATE ON  && Opens alternate output file
LIST STATUS       && Lists current environment
LIST MEMORY       && to that file.
SET ALTERNATE TO
SET ALTERNATE OFF
#else               && If Debug doesn't exist
DO MyProcedure    && compile this code
#endif

The following program code uses an identifier and a procedure that seem to do the same thing. However, note the different results that are returned when the parameters passed contain an expression (in this case, nValue1 + 2).

PROCEDURE CenterProc(num1,num2)
Answer = Num1 * Num2
RETURN answer
#define Center_Val(Num1, Num2);
        CENTER(LTRIM(STR(Num1 * Num2)))
nValue1 = 12
nValue2 = 24
? CenterProc(nValue1, nValue2) && Centers '288'
                               && (12*24)
? Center_Val(nValue1, nValue2) && Centers '288'
* Next, the procedure evaluates nValue1 + 2
* before performing the calculation
? CenterProc(nValue1+2, nValue2) && Centers '366'
                                 &&((12 + 2) * 24)
* However, the identifier does not evaluate
* nValue1+2 before performing the calculation
* So, mathematical order of precedence
* (multiplication before addition) leads to
* a different result
? Center_Val(nValue1+2,nValue2) && centers '576'
                                && (12+2*24), which
                                && is evaluated as
                                && (12+(2*24))


Printing Language Elements

See Also	Example

Use the following language elements to control, direct, modify, and format output sent to a printer or a file.

???

_alignment

_box

CHOOSEPRINTER( )

DEFINE BOX

EJECT

EJECT PAGE

_indent

_lmargin

ON PAGE

_padvance

_pageno

_pbpage

PCOL( )

_pcolno

_pcopies

_pdriver

_peject

_pepage

_pform

_plength

_plineno

_ploffset

_porientation

_ppitch

_pquality

PRINTJOB...ENDPRINTJOB

PRINTSTATUS( )

PROW( )

_pspacing

_rmargin

SET MARGIN

SET PCOL

SET PRINTER

SET PROW

_tabs

_wrap


See Also

Categorical List of the Language


Examples of Printing Language Elements

The following program code uses PRINTJOB to print one line of text, making three copies:

_pcopies = 3        && 3 copies
_peject = "none"    && No page eject
_plineno = 0        && initialized to 0
SET PRINTER ON
PRINTJOB
? "A one line print job"
?
ENDPRINTJOB
CLOSE PRINTER     && initiate printing
* prints:
* A one line print job
*
* A one line print job
*
* A one line print job
*

The following program code makes a line of text wrap within a left margin of 5 and a right margin of 20. The first line of the wrapped text is indented by 3 columns.

_indent = 3            && Set the indentation
Savewrap = _wrap       && Save last wrap setting
_wrap = .t.            && _alignment requires this
Savelmargin = _lmargin && Save alignment setting
_lmargin = 5
Savermargin = _rmargin && Save last alignment value
_rmargin = 20
? "New York, Chicago and Boston are "+;
  "cold in wintertime."
* Now the text wraps around between

* columns 5 and 20.
*
*        New York,
*     Chicago and
*     Boston are cold
*     in wintertime.
*
_rmargin = Savermargin   && Restore previous margin
_lmargin = Savelmargin   && Restore previous margin
_wrap = Savewrap         && Reset wrap


Programs Language Elements

See Also	Example

Use the following language elements to develop application programs, execute programs and subroutines, perform looping and branching operations, and terminate program execution.

&&

*

CANCEL

CLEAR PROGRAM

COMPILE

CREATE COMMAND

DO

DO CASE

DO WHILE

DO...UNTIL

FOR...NEXT

FUNCTION

IF

IIF( )

MODIFY COMMAND

NOTE

PARAMETERS

PCOUNT( )

PROCEDURE

QUIT

RETURN

SCAN

SET DEVELOPMENT

SET LIBRARY

SET PROCEDURE

SLEEP


See Also

Categorical List of the Language


Examples of Programs Language Elements

The following program code performs these tasks:

Uses PROCEDURE to declare a procedure named ToString

Uses PARAMETER to declare the parameter the procedure receives from the calling routine

Uses a DO CASE...ENDCASE statement to decide which  value to place in a variable

Uses RETURN to send the AString value to the calling routine and terminate execution of the procedure.

PROCEDURE ToString
PARAMETER NotAString
LOCAL AString
DO CASE
* Numeric or floating point?
CASE TYPE("NotAString")$ "NF"
AString = STR(NotAString,2)
CASE TYPE("NotAString") = "L"  && Logical
IF NotAString
AString = "True"
ELSE
AString = "False"
ENDIF
CASE TYPE("NotAString") = "C"  && Character
AString = NotAString
OTHERWISE                      && None of above
AString = "?"
ENDCASE
AString = LTRIM(RTRIM(AString))
AString = AString+" "
RETURN AString

The following program code performs these tasks:

Uses the looping command SCAN...ENDSCAN to move from record to record in a table

Evaluates the contents of a field named Salesper with a DO CASE...ENDCASE statement, determining which table to open in work area 2.

Uses DO to execute a program or procedure named Changes.

* UPDATES.PRG
SET TALK OFF
USE Customer INDEX Salespers
SCAN
DO CASE
CASE Salesper = "S-12"
SELECT 2
USE S12
CASE Salesper = "L-5"
SELECT 2
USE L5
CASE Salesper = "J-25"
SELECT 2
USE J25
ENDCASE
DO Changes
SELECT 1
ENDSCAN
CLOSE ALL
SET TALK ON


Shared Data Language Elements

See Also	Example

Use the following language elements to manage fields, records, and tables in a multiuser environment.

BEGINTRANS( )

CHANGE( )

COMMIT( )

CONVERT

FLOCK( )

ID( )

LKSYS( )

LOCK( )

NETWORK( )

ON NETERROR

RLOCK( )

ROLLBACK( )

SET EXCLUSIVE

SET LOCK

SET REFRESH

SET REPROCESS

UNLOCK


See Also

Categorical List of the Language


Examples of Shared Data Language Elements

The following program code begins a transaction with BEGINTRANS( ). It opens COMPANY.DBF and attempts to change all YTD_SALES to 0. ON ERROR detects any error which might occur. In particular, it determines if another user has locked any record in COMPANY.DBF. If an error occurs, ROLLBACK( ) resets all values. Otherwise, COMMIT( ) writes the changes to table.

CLOSE ALL
SET PROCEDURE TO PROGRAM(1) ADDITIVE
SET EXCLUSIVE OFF

BEGINTRANS()

TransErr = .f.
ON ERROR DO TransErr    && Activates ON ERROR trap

USE L:\MULTIUSE\COMPANY
REPLACE ALL Ytd_Sales WITH 0
ON ERROR                && Disables ON ERROR

IF TransErr
  ? "Rollback"
  ROLLBACK()            && restore data
ELSE
  ? "Commit"
  COMMIT()              && save changes
ENDIF

PROCEDURE TransErr
WAIT "Warning: Transaction Fails"
TransErr=.t.

The following program code loops until it can lock the 10th record with RLOCK( ) or until the user decides to stop trying. If the user is successful, a subroutine is called to update the record:

RecordWasRead = .t.
SET REPROCESS TO 20  && Try to lock 20 times
USE Company
GO 10
Again = .t.
DO WHILE Again
  IF RLOCK()         && Can dBASE Lock the file?
    DO CompMod       && Update this record
    Again = .f.
    UNLOCK           && Allow other users to
                     && change the file.
  ELSE               && RLOCK() returns .F.
    CLEAR
    Wait "Record lock failed. Try again? (Y/N) ";
      to mRetry
    IF UPPER(mRetry)="N"
      Again = .f.
    ENDIF
    RecordWasRead = .f.
  ENDIF
ENDDO
USE
SET REPROCESS TO 0  && The default


String Data Language Elements

See Also	Example

Use the following language elements to evaluate, measure, align, or alter character strings.

ANSI( )

AT( )

CENTER( )

DIFFERENCE( )

ISALPHA( )

ISLOWER( )

ISUPPER( )

LEFT( )

LEN( )

LIKE( )

LOWER( )

LTRIM( )

OEM( )

PROPER( )

RAT( )

REPLICATE( )

RIGHT( )

RTRIM( )

SET EXACT

SOUNDEX( )

SPACE( )

STUFF( )

SUBSTR( )

TRANSFORM( )

TRIM( )

UPPER( )


See Also

Categorical List of the Language


Examples of String Data Language Elements

The following program code performs these tasks:

Uses UPPER( ) to convert all characters in a string to upper case

Uses LEFT( ) and RIGHT( ) to return the first and last character of a string, respectively

Uses SUBSTR( ) to return a portion of a string

mState = "California"
mCity = "Scotts Valley"
mZip =  "95066"
* Return CA
? UPPER(LEFT(mState,1)+RIGHT(mState,1))
* Return 95
? SUBSTR(mZip,1,2)
Reverse = SUBSTR(mCity,8,6) + " " +;
          SUBSTR(mCity,1,6)
? Reverse                  && Returns Valley Scotts

The following program code performs these tasks:

Uses SOUNDEX( ) to build an index that orders records on the phonetic sound of company names

Uses SOUNDEX( ) to seek records while this index is active

Uses DIFFERENCE( ) to determine which records to list with LIST

USE ACCOUNTS
INDEX ON SOUNDEX(Company) TAG SoundComp
INDEX ON Company TAG Company
IF SEEK(Form.CoName.Value) && Does company exist?
   ? Accounts->Company     && Yes, display it.
ELSE                       && Find similar names
   SET ORDER TO SoundComp  && Use SOUNDEX() index
   IF SEEK(SOUNDEX(Form.CoName.Value))
      SELECT (Accounts)
      LIST LastName WHILE;
         DIFFERENCE(Company, Form.CoName.Value) > 2
   ELSE                    && No similar names
      ? "There are no company names ";
        "similar to the one you are ";
        "seeking."
   ENDIF
ENDIF


Table Basics Language Elements

See Also	Example

Use the following language elements to create, open, identify, and manage tables or catalogs.

ALIAS( )

APPEND FROM

CATALOG( )

CLOSE...

COPY

COPY STRUCTURE

COPY TABLE

COPY TO...STRUCTURE EXTENDED

CREATE

CREATE CATALOG

CREATE...FROM

CREATE...STRUCTURE EXTENDED

DATABASE( )

DBF( )

DELETE TABLE

DISPLAY STRUCTURE

IMPORT

ISTABLE( )

LIST STRUCTURE

MODIFY STRUCTURE

OPEN DATABASE

REFRESH

RENAME TABLE

SELECT

SELECT( )

SET CATALOG

SET DATABASE

SET DBTYPE

SET TITLE

SQLEXEC( )

USE

WORKAREA( )


See Also

Categorical List of the Language


Examples of Table Basics Language Elements

The following program code uses SELECT to switch from one table to another:

PUBLIC table1, table2
USE CONTACT EXCLUSIVE IN SELECT()
INDEX ON CompCode TAG CompCode
Table1 = ALIAS()

USE COMPANY IN SELECT()
Table2 = ALIAS()

SELECT COMPANY
COPY STRUCTURE TO CNTCTLST;
   FIELDS CONTACT->CompCode, ;
   COMPANY->Company, CONTACT->Contact, ;
   COMPANY->Street1, COMPANY->Street2, ;
   COMPANY->City, COMPANY->State_Prov,;
   COMPANY->Zip_P_Code
USE CNTCTLST IN SELECT()
Table3 = ALIAS()
APPEND
SELECT &Table1
? ALIAS(),DBF(), WORKAREA()
SELECT &Table3
? ALIAS(),DBF(), WORKAREA()
SELECT &Table2
? ALIAS(),DBF(), WORKAREA()
SELECT 3
? ALIAS(),DBF(), WORKAREA()
SELECT 1
? ALIAS(),DBF(), WORKAREA()
SELECT 2
? ALIAS(),DBF(), WORKAREA()
CLOSE ALL

The following program code uses COPY TO...STRUCTURE EXTENDED to create the table NAMES.DBF, which contains the structure of CLIENTS.DBF as its records. The structure is then altered by deleting all records beyond the one representing the field named Zip. CREATE is then used to make a new table with the reduced structure, and records from CLIENTS.DBF are appended. (Creating a new table with COPY TO...STRUCTURE EXTENDED is also a useful tool for correcting .DBF file corruption.)

SET TALK OFF
SET SAFETY OFF
USE CLIENTS
COPY TO Names STRUCTURE EXTENDED
USE NAMES EXCLUSIVE
DELETE FOR RECNO() > 7  && The seventh field is Zip
PACK
CREATE NAMES2 FROM NAMES
DISPLAY STRUCTURE       && NAMES2 currently in use
? ALIAS()+" has "+LTRIM(STR(RECCOUNT()))+;
  " records at this point."
WAIT
APPEND FROM Clients
?
? ALIAS()+" has " + LTRIM(STR(RECCOUNT()))+;
  " records now."
WAIT
GO TOP
BROWSE


Table Organization Language Elements

See Also	Example

Use the following language elements to perform searches through table files and to list, evaluate, and organize records.

AVERAGE

CALCULATE

CONTINUE

COPY INDEXES

COPY TAG

CREATE QUERY

CREATE VIEW

CREATE VIEW...FROM ENVIRONMENT

DELETE TAG

DESCENDING( )

DISPLAY

FIND

FOR( )

FOUND( )

INDEX

JOIN

KEY( )

KEYMATCH( )

LIST

LOCATE

LOOKUP( )

MDX( )

MODIFY QUERY

MODIFY VIEW

NDX( )

ORDER( )

REINDEX

RELATION( )

SEEK

SEEK( )

SET FILTER

SET IBLOCK

SET INDEX

SET KEY TO

SET NEAR

SET ORDER

SET RELATION

SET SKIP

SET UNIQUE

SET VIEW

SORT

SUM

TAG( )

TAGCOUNT( )

TAGNO( )

TARGET( )

TOTAL

UNIQUE( )

UPDATE


See Also

Categorical List of the Language


Examples of Table Organization Language Elements

The following program code uses LOCATE and CONTINUE to find companies that are not in California:

USE COMPANY
LOCATE FOR Company <> "CA"
* After LOCATE, use CONTINUE
IF EOF()
  ? "No companies found"
ENDIF
DO WHILE .NOT. EOF()
   ? Company, State_Prov
   CONTINUE
ENDDO

The following program code uses INDEX ON to create index tags for the current table:

USE CLIENTS EXCLUSIVE
INDEX ON Company TAG Company
* Creates an index by Company
BROWSE TITLE "Indexed by Company"
INDEX ON State_Prov+City ;
   TAG StateCity DESCENDING
* Combine State and City index
BROWSE TITLE "Indexed by State & City Descending"
INDEX ON City;
   TAG CA ;
   FOR State_Prov = "NY" && Only cities in New York
BROWSE TITLE "Indexed by City, NY only"


Windows Programming Language Elements

See Also	Example

Use the following language elements to perform bitwise operations on numeric values, to use the Help system, and to use resources stored in dynamic link library files (.DLL).

BITAND( )

BITLSHIFT( )

BITOR( )

BITRSHIFT( )

BITSET( )

BITXOR( )

EXTERN

HELP

LOAD DLL

RELEASE DLL

RESOURCE( )

SET HELP

SET TOPIC


See Also

Categorical List of the Language


Examples of Windows Programming Language Elements

The following program code gets information from the Windows function GetVersion( ), which returns the major and minor DOS and Windows versions as a CLONG. The "High Byte of the High Word" contains the major DOS version, and the "Low Byte of the High Word" contains the minor DOS version. The "High Byte of the Low Word" specifies the minor version of Windows and the "Low byte of the Low Word" specifies the major Windows version. The Bit functions BITAND( ) and BITRSHIFT( ) are used to extract the proper values.

FUNCTION GVer
PARAMETER VerType
#define HiWord(x) (BITRSHIFT(BITAND;
  (x,4294901760),16))
#define LoWord(x) (BITAND(x,65535))
#define HiByte(x) (LTRIM(STR(BITRSHIFT(BITAND;
  (x,65280), 8))))
#define LoByte(x) (LTRIM(STR(BITAND(x,255))))
EXTERN CLONG GetVersion()  krnl386.exe
z = GetVersion()
IF UPPER(verType)="DOS"
  RETURN HiByte(HiWord(z))+"."+LoByte(HiWord(z))
ENDIF
IF LEFT(UPPER(verType),3)="WIN"
  RETURN  LoByte(LoWord(z))+"."+HiByte(LoWord(z))
ENDIF

The following program code shows how RESOURCE( ) can be used to change languages for international applications:

#define ENGLISH 1
#define SPANISH 2
ApLanguage = SPANISH
MyGreeting = RESOURCE(SPANISH,GREETING.DLL)
CLEAR
? MyGreeting


Classes

See Also	Example

Use the following classes to create objects.

CLASS ARRAY

CLASS BROWSE

CLASS CHECKBOX

CLASS COMBOBOX

CLASS DDELINK

CLASS DDETOPIC

CLASS EDITOR

CLASS ENTRYFIELD

CLASS FORM

CLASS IMAGE

CLASS LINE

CLASS LISTBOX

CLASS MENU

CLASS OBJECT

CLASS OLE

CLASS PUSHBUTTON

CLASS RADIOBUTTON

CLASS RECTANGLE

CLASS SCROLLBAR

CLASS SPINBOX

CLASS TEXT


See Also

Categorical List of the Language

Properties


Examples of Classes

The following program code creates check boxes that offer different ways to execute the LIST command.

USE ?
DEFINE FORM ListForm PROPERTY MDI .F.
DEFINE PUSHBUTTON Lister OF ListForm ;
       PROPERTY ;
       Text "List", ;
       Top  10, ;
       Left 15, ;
       OnClick  ListClick
NEW bigBox(ListForm,"Include record numbers")
NEW bigBox(ListForm,"Send to printer")
ListForm.Checkbox1.Top = 2
ListForm.Checkbox2.Top = 6
READMODAL(ListForm)

CLASS bigBox(f,lcText) OF CHECKBOX(f)
      this.FontName = "Arial"
      this.FontSize = 16
      this.Text     = SPACE(2) + lcText
      this.Width    = LEN(lcText) * 2
      this.Left     = 2
      this.Value    = .F.
ENDCLASS

FUNCTION ListClick
   IF Form.Checkbox1.Value    && Include record;
                                 numbers
      IF Form.Checkbox2.Value && to printer
         LIST TO PRINTER
      ELSE
         LIST
      ENDIF
   ELSE                       && No record numbers
      IF Form.Checkbox2.Value && to printer
         LIST OFF TO PRINTER
      ELSE
         LIST OFF
      ENDIF
   ENDIF
   FORM.CLOSE()
RETURN 0

The following program code defines a form that displays two fields from CONTACT.DBF. The form also displays three alternative pushbutton sets that move the record pointer or terminate execution:

SET PROCEDURE TO BUTTONS.CC ADDITIVE
* Makes available custom objects PREVBUTTON,
* NEXTBUTTON and CANCELBUTTON
LOCAL f
f = NEW EntryForm()
f.OPEN()
CLASS EntryForm OF FORM
  this.Top = 2
  this.Left = 2
  this.Width = 36
  this.Height = 27
  this.View = "Contact.DBF"
  this.Text = "Class Pushbutton Demo"
  DEFINE ENTRYFIELD CompCode OF THIS;
    PROPERTY;
      Width 5,;
      Top 1,;
      Left 2,;
      Height 1.5,;
      FontBold .T.,;
      DataLink "COMPCODE"
  DEFINE ENTRYFIELD Contact OF THIS;
    PROPERTY;
      Width 22,;
      Top 1,;
      Left 12,;
      Height 1.5,;
      FontBold .T.,;
      DataLink "CONTACT"
  DEFINE PUSHBUTTON Reverse OF THIS;
    PROPERTY;
      OnClick {;SKIP-1},;
      Text "&Previous",;
      Top  4,;
      Left 5,;
      Width 12,;
      Height 2.5,;
      Group .T.,;
      FontSize 8,;
      FocusBitmap "Resource #104 DBAS0009.DLL",;
      DownBitmap "Resource #104 DBAS0009.DLL",;
      UpBitmap "Resource #104 DBAS0009.DLL"
  DEFINE PUSHBUTTON NxtRcd OF THIS;
    PROPERTY;
      OnClick {;SKIP},;
      Text "&Next",;
      Top  4,;
      Left 19,;
      Width 12,;
      Height 2.5,;
      Group .T.,;
      FontSize 8,;
      FocusBitmap "Resource #100 DBAS0009.DLL",;
      DownBitmap "Resource #100 DBAS0009.DLL",;
      UpBitmap "Resource #100 DBAS0009.DLL"
  DEFINE PUSHBUTTON Cx OF THIS;
    PROPERTY;
      OnClick {;Form.Close()},;
      Text "&Cancel",;
      Top  7,;
      Left 12,;
      Height 2.5,;
      Width 12,;
      Group .T.,;
      FontSize 8,;
      FocusBitmap "Resource #28 DBAS0009.DLL",;
      DownBitmap "Resource #29 DBAS0009.DLL",;
      UpBitmap "Resource #28 DBAS0009.DLL"
  DEFINE LINE Ln1 OF THIS;
    PROPERTY Left 7, Top 11, Width 4,;
      Bottom 11, Right 29, ColorNormal "RB/W"
  DEFINE PUSHBUTTON Back OF THIS AT 13,7;
    PROPERTY Text "&Back", Height 2,;
      OnClick {;SKIP-1}, FontBold .T.
  DEFINE PUSHBUTTON Next OF THIS AT 13,21;
    PROPERTY TEXT "&Next", Height 2,;
      OnClick {;SKIP}, FontBold .T.
  DEFINE PUSHBUTTON Exit OF THIS AT 16,14;
    PROPERTY Text "&Exit", Height 2,;
      OnClick {;Form.Close()}, FontBold .T.
  DEFINE LINE Ln2 OF THIS;
    PROPERTY Left 7, Top 19, Width 4,;
      Bottom 19, Right 29, ColorNormal "RB/W"
  DEFINE PREVBUTTON PriorRecord OF THIS;
    PROPERTY;
      Top 21 ,;
      Left 6
  DEFINE NEXTBUTTON NextRecord OF THIS;
    PROPERTY;
      Top 21,;
      Left 20
  DEFINE CANCELBUTTON Cy OF THIS;
    PROPERTY;
      Top  24,;
      Left 13
ENDCLASS


Properties

See Also	Example

The standard classes that dBASE for Windows provides have over 170 properties, many of which are shared in common by several classes. Use these properties to change object characteristics, to make objects respond to events, and to perform actions.

Properties that perform actions are followed by parentheses, and are called methods.

ActiveControl	Add( )
Advise( )	Alias
Alignment	Append
AutoSize	Before
Border	BorderStyle
Bottom	Checked
ClassName	Close( )
ColorHighlight	ColorNormal
Count( )	CurSel
DataLink	DataSource
Default	Delete
Delete( )	Dimensions
Dir( )	DisabledBitmap
DoVerb( )	DownBitmap
Element( )	Enabled
EscExit	Execute( )
Fields	Fields( )
FieldWidth	Fill( )
First	FocusBitmap
Follow	FontBold
FontItalic	FontName
FontSize	FontStrikeOut
FontUnderline	Function
GetTextExtent( )	Group
Grow( )	Height
HelpFile	HelpID
hWnd	ID
Initiate( )	Insert( )
Key	Left
LineNo	LinkFileName
Maximize	MaxLength
MDI	MenuFile
Minimize	Mode
Modify	MousePointer
Move( )	Moveable
Multiple	Name
NextCol( )	NextObj
NextRow( )	Notify( )
OldStyle	OleType
OnAdvise	OnAppend
OnChange	OnClick
OnClose	OnExecute
OnGotFocus	OnHelp
OnLeftDblClick	OnLeftMouseDown
OnLeftMouseUp	OnLostFocus
OnMiddleDblClick	OnMiddleMouseDown
OnMiddleMouseUp	OnMouseMove
OnMove	OnNavigate
OnNewValue	OnOpen
OnPeek	OnPoke
OnRightDblClick	OnRightMouseDown
OnRightMouseUp	OnSelChange
OnSelection	OnSize
OnUnadvise	Open( )
Parent	PatternStyle
Peek( )	Pen
Picture	Poke( )
Print( )	RangeMax
RangeMin	RangeRequired
ReadModal( )	Reconnect( )
Release( )	Resize( )
Right	ScaleFontName
ScaleFontSize	Scan( )
ScrollBar	SelectAll
Selected( )	Separator
Server	ServerName
SetFocus( )	ShortCut
ShowDeleted	ShowHeading
ShowRecNo	Size
Sizeable	Sort( )
Sorted	SpeedBar
SpinOnly	StatusMessage
Step	Style
Subscript( )	SysMenu
TabStop	Terminate( )
Text	Timeout
Toggle	Top
Topic	Unadvise( )
UpBitmap	Valid
ValidErrorMsg	ValidRequired
Value	Vertical
View	Visible
When	Width
WindowState	Wrap


See Also

Categorical List of the Language

Classes


Example of Properties

The following program code creates four forms. Each form is an instance of a different custom class, and gets its characteristics from the values specified for its properties.

* MAILORDR.PRG
LOCAL F
F = NEW FULLTIME()
F.Open()
P = NEW PARTTIME()
P.Open()
C = NEW CUSTOMER()
C.Open()
R = NEW PROSPECT()
R.Open()

***-------- CLASS: BaseForm --------***
CLASS BASEFORM OF FORM
   this.Text = "Form"
   this.Width =         57.25
   this.Top =          0.05
   this.Left =          2.00
   this.Height =         24.58
   this.Minimize = .F.
   this.Maximize = .F.
   this.HelpFile = ""
   this.HelpId = ""
   DEFINE TEXT TF_NAME OF THIS;
       PROPERTY;
         ColorNormal "N/W",;
         Text "Name",;
         Width          5.00,;
         Top          3.25,;
         Left          7.50,;
         Height          1.08,;
         Border .F.
   DEFINE TEXT TF_ADDRESS OF THIS;
       PROPERTY;
         ColorNormal "N/W",;
         Text "Address",;
         Width          6.50,;
         Top          5.42,;
         Left          6.00,;
         Height          1.17,;
         Border .F.
   DEFINE TEXT TF_CITY OF THIS;
       PROPERTY;
         ColorNormal "N/W",;
         Text "City",;
         Width          5.00,;
         Top          9.58,;
         Left         13.12,;
         Height          1.08,;
         Border .F.
   DEFINE TEXT TF_STATE OF THIS;
       PROPERTY;
         ColorNormal "N/W",;
         Text "State",;
         Width          5.00,;
         Top          9.58,;
         Left         34.00,;
         Height          1.08,;
         Border .F.
   DEFINE TEXT TF_ZIP OF THIS;
       PROPERTY;
         ColorNormal "N/W",;
         Text "Zipcode",;
         Width          6.62,;
         Top          9.50,;
         Left         41.12,;
         Height          1.17,;
         Border .F.
   DEFINE ENTRYFIELD EF_NAME OF THIS;
       PROPERTY;
         ColorNormal "",;
         Width         37.50,;
         Top          3.17,;
         Left         12.75,;
         Height          1.42,;
         Border .T.,;
         Value "",;
         ColorHighLight ""
   DEFINE ENTRYFIELD EF_ADDRESS OF THIS;
       PROPERTY;
         ColorNormal "",;
         Width         37.25,;
         Top          5.25,;
         Left         12.75,;
         Height          1.42,;
         Border .T.,;
         Value "",;
         ColorHighLight ""
   DEFINE ENTRYFIELD EF_CITY OF THIS;
       PROPERTY;
         ColorNormal "",;
         Width         18.00,;
         Top          7.75,;
         Left         12.75,;
         Height          1.33,;
         Border .T.,;
         Value "",;
         ColorHighLight ""
   DEFINE ENTRYFIELD EF_STATE OF THIS;
       PROPERTY;
         ColorNormal "",;
         Width          3.00,;
         Top          7.75,;
         Left         34.12,;
         Height          1.33,;
         Border .T.,;
         Value "",;
         ColorHighLight ""
   DEFINE ENTRYFIELD EF_ZIP OF THIS;
       PROPERTY;
         ColorNormal "",;
         Width          8.75,;
         Top          7.67,;
         Left         41.00,;
         Height          1.42,;
         Border .T.,;
         Value "",;
         ColorHighLight ""
ENDCLASS

***-------- CLASS: Employee --------***
CLASS EMPLOYEE OF BASEFORM
   DEFINE ENTRYFIELD EF_RATE OF THIS;
       PROPERTY;
         ColorNormal "",;
         Width          8.75,;
         Top         14.92,;
         Left         12.62,;
         Height          1.42,;
         Border .T.,;
         Value "",;
         ColorHighLight ""
ENDCLASS

***-------- CLASS: PartTime --------***
CLASS PARTTIME OF EMPLOYEE
   this.text = "Part Time Employee Information"
   DEFINE TEXT TF_SALARY OF THIS;
       PROPERTY;
         ColorNormal "N/W",;
         Text "Hourly Rate",;
         Width         10.25,;
         Top         14.92,;
         Left          1.25,;
         Height          1.25,;
         Border .F.
   DEFINE TEXT TF_BI_MONTHLY OF THIS;
       PROPERTY;
         ColorNormal "N/W",;
         Text "Gross Pay per Pay Period",;
         Width         18.88,;
         Top         14.75,;
         Left         32.88,;
         Height          1.50,;
         Border .F.
   DEFINE TEXT TF_PAYAMT OF THIS;
       PROPERTY;
         ColorNormal "N/W*",;
         Text "",;
         Width          7.25,;
         Top         17.00,;
         Left         38.75,;
         Height          1.17,;
         Border .T.
   DEFINE TEXT TF_HOURS OF THIS;
       PROPERTY;
         ColorNormal "N/W",;
         Text "Hours",;
         Width          5.00,;
         Top         17.92,;
         Left          4.50,;
         Height          1.08,;
         Border .F.
   DEFINE ENTRYFIELD EF_HOURS OF THIS;
       PROPERTY;
         ColorNormal "",;
         Width          8.75,;
         Top         17.67,;
         Left         12.88,;
         Height          1.42,;
         Border .T.,;
         Value "",;
         ColorHighLight ""
  DEFINE PUSHBUTTON PB_CALCPAY OF THIS;
       PROPERTY;
         OnClick CLASS::PB_CALCPAY_ONCLICK,;
         ColorNormal "N/W",;
         Text "Calculate Pay",;
         Width         16.12,;
         Top         21.08,;
         Left         39.25,;
         Height          3.17,;
         Group .T.
Procedure PB_CALCPAY_OnClick
TEXTPAY = STR(VAL(FORM.EF_RATE.VALUE) * VAL(FORM.EF_HOURS.VALUE))
FORM.TF_PAYAMT.TEXT = TEXTPAY
ENDCLASS

***-------- CLASS: FullTime --------***
CLASS FULLTIME OF EMPLOYEE
   this.text = "Full Time Employee Information"
   this.left = 60.00
   DEFINE TEXT TF_SALARY OF THIS;
       PROPERTY;
         ColorNormal "N/W",;
         Text "Annual Salary",;
         Width         10.25,;
         Top         14.92,;
         Left          1.25,;
         Height          1.25,;
         Border .F.
   DEFINE TEXT TF_BENIES OF THIS;
       PROPERTY;
         ColorNormal "N/W",;
         Text "Benefits",;
         Width          6.62,;
         Top         18.83,;
         Left          2.62,;
         Height          1.08,;
         Border .F.
   DEFINE CHECKBOX CB_HEALTH OF THIS;
       PROPERTY;
         ColorNormal "N/W",;
         Text "Medical Insurance",;
         Width         16.88,;
         Top         19.08,;
         Left         12.50,;
         Height          1.58,;
         Value .F.,;
         Group .T.
   DEFINE CHECKBOX CB_DENTAL OF THIS;
       PROPERTY;
         ColorNormal "N/W",;
         Text "Dental Insurance",;
         Width         16.00,;
         Top         21.08,;
         Left         12.50,;
         Height          1.58,;
         Value .F.,;
         Group .T.
   DEFINE CHECKBOX CB_401K OF THIS;
       PROPERTY;
         ColorNormal "N/W",;
         Text "401K Plan",;
         Width         11.12,;
         Top         22.92,;
         Left         12.50,;
         Height          1.58,;
         Value .T.,;
         Group .T.
   DEFINE TEXT TF_BI_MONTHLY OF THIS;
       PROPERTY;
         ColorNormal "N/W",;
         Text "Gross Pay per Pay Period",;
         Width         18.88,;
         Top         14.83,;
         Left         32.88,;
         Height          1.50,;
         Border .F.
   DEFINE TEXT TF_PAYAMT OF THIS;
       PROPERTY;
         ColorNormal "N/W*",;
         Text "",;
         Width          7.25,;
         Top         17.00,;
         Left         38.75,;
         Height          1.17,;
         Border .T.
DEFINE PUSHBUTTON PB_CALCPAY OF THIS;
       PROPERTY;
         OnClick CLASS::PB_CALCPAY_ONCLICK,;
         ColorNormal "N/W",;
         Text "Calculate Pay",;
         Width         16.12,;
         Top         21.08,;
         Left         39.25,;
         Height          3.17,;
         Group .T.

PROCEDURE PB_CALCPAY_OnClick
form.TF_PAYAMT.TEXT = STR(VAL(form.EF_RATE.VALUE)/26)
RETURN
ENDCLASS

***-------- CLASS: Customer --------***
CLASS CUSTOMER OF BASEFORM
   this.text = "Customer Information"
   this.top = 27
   DEFINE LINE LINE1 OF THIS;
       PROPERTY;
         ColorNormal "N",;
         Width          1,;
         Top         12.83,;
         Left          1.25,;
         Bottom         12.83,;
         Right         56.00
   DEFINE TEXT TF_NUMORDERS OF THIS;
       PROPERTY;
         ColorNormal "N/W",;
         Text "Number of Orders",;
         Width         12.62,;
         Top         14.75,;
         Left          3.38,;
         Height          1.42,;
         Border .F.
   DEFINE ENTRYFIELD EF_NUMORDERS OF THIS;
       PROPERTY;
         ColorNormal "",;
         Width          6.75,;
         Top         14.67,;
         Left         16.75,;
         Height          1.42,;
         Border .T.,;
         Value "",;
         ColorHighLight ""
ENDCLASS

***-------- CLASS: Prospect --------***
CLASS PROSPECT OF CUSTOMER
   this.text = "Prospect Information"
   this.left = 60.00
   DEFINE TEXT TF_EXPECTED OF THIS;
       PROPERTY;
         ColorNormal "N/W",;
         Text "Expected",;
         Width          7.88,;
         Top         16.00,;
         Left          3.62,;
         Height          1.08,;
         Border .F.
   DEFINE TEXT TF_BUSTYPE OF THIS;
       PROPERTY;
         ColorNormal "N/W",;
         Text "Business Type",;
         Width         12.25,;
         Top         19.00,;
         Left          3.25,;
         Height          1.17,;
         Border .F.
   DEFINE ENTRYFIELD EF_BUSTYPE OF THIS;
       PROPERTY;
         ColorNormal "",;
         Width         24.62,;
         Top         19.00,;
         Left         16.75,;
         Height          1.42,;
         Border .T.,;
         Value "",;
         ColorHighLight ""
ENDCLASS


Unsupported Language Elements

Alphabetic List	Categorical List

The following are dBASE IV language elements that are unsupported in dBASE for Windows.

Element	If Used, dBASE for Windows...
_pecode	Returns a null string
_pscode	Returns a null string
_pwait	Returns .F.
ACCESS( )	Returns 0
ASSIST	Returns a warning
BEGIN...    END TRANSACTION	Returns a warning
CALL	Returns a warning
CALL( )	Returns a warning
COMPLETED( )	Returns .T.
DEXPORT	Returns a warning
DGEN( )	Returns 0
DISPLAY/LIST HISTORY	Ignores this command
DISPLAY/LIST USERS	Ignores this command
EXPORT	Returns a warning
FIXED( )	Returns the value that was passed to it
ISMARKED( )	Returns .F.
LOAD	Returns a warning
LOGOUT	Ignores this command
PLAY MACRO	Returns a warning
PROTECT	Ignores this command
RELEASE MODULES	Returns a warning
RESET	Returns a warning
RESTORE MACROS	Returns a warning
ROLLBACK	Returns a warning
SAVE MACROS	Returns a warning
SET CLOCK	Returns a warning
SET COLOR ON | OFF	Returns a warning
SET DBTRAP	Returns a warning
SET DEBUG	Returns a warning
SET ENCRYPTION	Returns a warning
SET HELP ON | OFF	Returns a warning
SET HISTORY	Returns a warning
SET HOURS	Returns a warning
SET INSTRUCT	Returns a warning
SET PAUSE	Returns a warning
SET SCOREBOARD	Returns a warning
SET SQL	Returns a warning
SET STATUS	Returns a warning
SET TRAP	Returns a warning
USER( )	Returns a null string


Using Local SQL

Local SQL lets users apply SQL statements to local tables through the SQL Editor. Just as it "passes" SQL statements directly to the server for processing against SQL server data, the SQL Editor "passes" Local SQL statements to dBASE for processing against Paradox or dBASE tables. However, instead of using the SQL syntax of a particular SQL server (as with passthrough SQL), Local SQL queries use SQL89 syntax.

All Local SQL statements are invoked through the dBASE SQLEXEC( ) command.

The SQL Editor converts SQL Data Definition Language (DDL) statements directly into calls that dBASE interprets. It also converts SQL Data Manipulation Language (DML) statements into syntax that can be processed by dBASE.

Choose from the following list for more information about Local SQL:

Supported Syntax

Supported Syntax: Examples

Syntax Not Supported

Data Type Mappings for CREATE


Supported Syntax

Examples	Syntax Not Supported

DML

Statements:	SELECT, UPDATE, INSERT, DELETE

Clauses:	WHERE, ORDER BY, GROUP BY, HAVING

Aggregates:	SUM, AVG, MIN, MAX, COUNT

Operators:	+, -, *, /, =, <>, is null

DDL

create table

CREATE index

DROP INDEX

DROP TABLE

Rules for Table Names

Table names that include a period (.) must be placed within single or double quotation marks. For example:

SELECT * FROM 'C:\SAMPLE.DAT\TABLE'
SELECT * FROM "TABLE.DBF"

Table names that are also SQL keywords must be placed within quotation marks. For example:

SELECT PASSID FROM "PASSWORD"

You can use an IDAPI alias to reference a local table name; for example, 'ALIASNAME:TABLENAME.' This makes it possible to execute heterogeneous joins.

Note:	Whenever you reference a local table, your transaction is automatically assumed to be Local SQL, and the syntax is treated accordingly. If you reference an SQL table, your transaction is assumed to be passthrough SQL.

Rules for Field Names

Field names that include spaces must be placed within single or double quotation marks. For example:

SELECT "EMP ID" FROM EMPLOYEE

Field names that include spaces should be referenced by table name or table alias. Use the format TABLE."FIELDNAME". For example:

EMPLOYEES."EMP ID"

Field names that are also SQL keywords must be placed within quotation marks. For example:

SELECT "DATE" FROM TABLE


Supported Syntax: Examples

Description

Statement	Examples	Notes
CREATE	create table parts   ( part_no char(6),   part_name char(20)	See Data Type Mappings for CREATE
	create table parts   ( part_no char(6),   part_name char(20) )
DELETE	delete from goods    where part_no = 'aa0093'
DROP	drop index parts.part_no	Syntax for DROP INDEX is tablename.indexname. To drop the primary index, use tablename.primary
INSERT	insert into goods    ( part_no, city )   values ( 'aa0094',    'San Jose' )
GROUP	select part_no,    sum( quantity ) as PQTY   from parts    group by part_no	Aggregates in the SELECT clause must have a GROUP BY if a project field also exists.
	select country from   customer   group by country having   sum(cust_no) >= 3
JOIN	select distinct   p.part_no, p.quantity,   g.city   from parts p, goods g   where p.part_no =   g.part_no    and p.quantity > 20   order by p.quantity,   g.city, p.part_no
JOIN using Alias	select distinct   c.cust_no, c.state,   o.order_no, l.price   from   :Local_alias:customer.db c,   :IB_alias:order o,   :SYB_alias:lineitem l    where o.cust_no =   c.cust_no and    o.order_no = i.order_no	Fields must be referenced by alias or table name; e.g.:  SELECT table1.field1, table2.field2 ...
SELECT	select part_no from parts   where part_no > 543
	select customer_no from   c:\data\customer.dbf   where last_name = 'Johnson'
	select distinct customer_no   from c:\data\customer   order by customer+no   descending	When you use the DESCENDING keyword in the ORDER BY clause, you must also specify DISTINCT.
UPDATE	update goods set city =   'Aptos'   where goods.city = 'Scotts   Valley'


Syntax Not Supported

Supported Syntax

Statement	Examples	Notes
CREATE	create view orders    ( order_no char(10), cust_no   char(10) )	Views are not supported.
JOIN	parts join inventory on   parts.part_no =   inventory.part_no	The JOIN keyword is not supported. However, equivalent statements written with the SELECT clause are supported.
	select from parts, customer	Joins in which fields from each table are involved in some type of equality check require a WHERE clause.
SELECT	select p.part_no from parts p    where p.quantity in ( select   i.quantity from inventory i   where  i.part_no = 'aa9393' )	Nested queries are not supported.
Granting privileges is not supported.


Data Type Mappings for CREATE

SQL Syntax	IDAPI Logical	Paradox	dBASE

SMALLINT	fldINT16	fldPDXSHORT	fldDBNUM

INT	fldINT32	fldPDXLONG	fldDBNUM

DECIMAL(x,y)~	fldBCD	fldPDXBCD	N/A

NUMERIC(x,y)~	fldFLOAT	fldPDXNUM	fldDBNUM(x,y)

FLOAT(x,y)~	fldFLOAT	fldPDXNUM	fldDBFLOAT(x,y)

CHARACTER(n)~	fldZSTRING	fldPDXALPHA	fldDBCHAR

DATE	fldDATE	fldPDXDATE	 fldDBDATE

BOOLEAN	fldBOOL	fldPDXBOOL	fldDBBOOL

BLOB(n,s)~	fldBLOB	fldPDX	fldDB

[subtypes]

TIME	fldTIME	fldPDXTIME	N/A

TIMESTAMP	fldTIMESTAMP	fldPDXTIMESTAMP	N/A

MONEY	fldFLOAT,	fldPDXMONEY	fldDBFLOAT(20,4)

fldstMONEY

AUTOINC	fldINT32,	fldPDXAUTOINC	N/A

fldstAUTOINC

BYTES(n)	fldBYTES(n)	fldPDXBYTES	fldDBBYTES

Parameters

x = precision; if omitted, precision defaults to driver parameters

y = scale; if omitted, scale defaults to zero (0)

n = length; if omitted, length defaults to 1

s = subtype; if a blob subtype is omitted, the subtype defaults to Memo


SQL89 syntax

SQL89 is the 1989 standard for SQL syntax. Many outside sources are avilable for further information about SQL syntax. An example is A Guide to the SQL Standard by C.J. Date.


local tables

Database tables that do not reside on a database server; for example, Paradox or dBASE tables.


heterogeneous joins

Joins of more than one table type; for example, a Paradox table, a dBASE table, and an InterBase table.


BLOB subtypes

Subtype	Paradox	dBASE

fldstMEMO	fldPDXMEMO	fldDBMEMO

fldstBINARY	fldPDXBINARY	fldDBBINARY

fldstFMTMEMO	fldPDXFMTMEMO	N/A

fldstOLEOBJ	fldPDXOLEBLOB	fldDBOLEBLOB

fldstGRAPHIC	fldPDXGRAPHIC	N/A


#define

See Also	Example	Portability	Preprocessor

Defines an identifier (name) for use in controlling program compilation, defining constants, or creating inline functions.

Syntax

#define <identifier> [<replacement text>]

#define <identifier>(<parameter list>) <replacement text with parameters>

<identifier>

A name. It identifies the text to replace if <replacement text> is supplied. The name must start with an alphabetic character and can contain any combination of alphabetic or numeric characters, uppercase or lowercase letters. The identifier is not case-sensitive.

(<parameter list>)

Parameter names that correspond to arguments passed to an inline function (pseudo function) that you create with #define <identifier> (<parameter list>) <replacement text>. If you specify multiple parameters, separate each with a comma.

<replacement text>

The text that replaces all occurrences of <identifier>. If you specify <replacement text>, the preprocessor scans each source code line for identifiers and replaces each one it encounters with the specified replacement text. <replacement text> can be any text that is part of a dBASE program, such as a string, variable name, or series of commands.

Description

The #define directive defines an identifier and optionally lets you replace text in a program before compilation. Each #define definition must begin on a new line and is limited to 4096 characters.

Identifiers are available only to the program in which they are defined. To define identifiers for use in multiple programs, use #include. To remove an identifier so that it is no longer used as a preprocessor directive, use #undef.

Typically, use the #define directive for the following purposes:

to declare an identifier with no replacement text, so you can use it with the #ifdef or #ifndef directive.

to declare an identifier and assign replacement text to represent a constant value or a complex expression, so you can use it with the #if directive.

to create an inline function (pseudo function).

#define statements override memory variables, built-in commands and functions, and any other element having the same name as <identifier>. This is shown in the following examples.

* Overriding a memory variable
#define mValue 10
mValue = 25   && dBASE returns an error
              && because mValue is a constant
mVariable = 25
#define mVariable 10
? mVariable   && displays 10

* Overriding a built-in function
#define upper(x) "? 'bad idea' "  && UPPER( ) is a
                                  && built-in function
? upper("mvar")                   && returns 'bad idea'

For more information about using the #define directive, see Chapter 7 in the Programmer's Guide.

Declaring identifiers

Defining an identifier without replacement text lets you use it with the #ifdef or #ifndef directive to test if the identifier exists. This is useful for setting conditions to either include or exclude code for compilation, as in the following example.

#define firstrun
...

#ifdef firstrun
   <compile these program setup statements>
   <for example, include debugging commands>
#endif

If you later modify your program so you do not need to compile the program setup statements, remove or comment the #define statement.

Declaring identifiers to represent constants

Assign an identifier to represent a constant value or expression when you want the preprocessor to search for and replace all instances of the identifier with the specified value or expression before compilation. This is shown in the following example.

#define cCompany "dSolutions, Inc."
...
? cCompany     && displays "dSolutions, Inc."

This search-and-replace capability, known as macro expansion, can streamline your code and improve its readability because you can use a single identifier to represent a frequently used constant or a complex expression. In addition, if you need to change the value of a constant in your program, you need to change only the constant definition and not every occurrence of the constant.

To replace an identifier only in parts of a program, insert #undef <identifier> into your program where you want the search-and-replace process to stop.

Creating inline functions

When the preprocessor encounters a function call that matches the function definition, it replaces the function call with the replacement text, inserting the arguments of the function call into the replacement text. This is shown in the following example.

#define Avg(num1,num2) (num1+num2)/2
...
nNumber1=20
nNumber2=40
? Avg(nNumber1,nNumber2)   && displays 30

Unlike standard dBASE user-defined functions (UDFs), the number of arguments passed from a function call must match the number of parameters defined in your #define statement.

Note:	There are important differences between how dBASE evaluates inline functions and user-defined functions (UDFs). If you don't understand these differences, your inline functions might not return the values you expect. For best results, always enclose the replacement text in parentheses to ensure the proper order of evaluation. For more information, see Chapter 7 in the Programmer's Guide.

Nesting preprocessor macros

You can nest preprocessor macros; that is, a macro can expand into another macro. The following example shows how the third macro definition depends on the first two:

#define K_CR CHR(13)
#define K_LF CHR(10)
#define K_CRLF K_CR + K_LF


#define Example

The following examples use #define to specify font parameters so that a desired font can be called by a single identifier:

#define BIGFONT fontname "Roman",fontheight 20,;
  fontwidth 22
#define TEXTFONT fontname "Roman",fontheight 11,;
  fontwidth 6
#define ENTRYFONT fontname "Roman",fontheight 16,;
  fontitalic .t.

The following examples use #define to specify a function that trims all values passed as parameters and set a predetermined field list.

#define ALLTRIM(x) LTRIM(RTRIM(x))
#define FIELDLIST "Flight_no,Origin,Dest,Date,;
  Departure,Arrival,Price"


Portability

Not supported in dBASE III PLUS.


See Also

#if

#ifdef

#ifndef

#include

#undef


#if

See Also	Example	Portability	Preprocessor

Controls conditional compilation of code based on the value of an identifier assigned with #define.

Syntax

#if <condition>
<statements 1>
[#else
<statements 2>]
#endif

<condition>

A logical expression, using an identifier you have defined, that evaluates to true or false.

<statements 1>

One or more program lines consisting of any combination of commands, functions, and preprocessor directives. These lines are compiled if <condition> evaluates to true.

#else <statements 2>

Specifies the program lines to compile if <condition> evaluates to false.

Description

Use the #if directive to conditionally compile sections of source code based on the value of <identifier>. Two other directives, #ifdef and #ifndef, are also used to conditionally include or exclude code for compilation. Unlike the #if directive, however, they test only for the existence of an identifier, not for its value.

Conditional compilation is useful when maintaining different versions of the same program or for debugging. This is shown in the following example.

# define mInvmod = "incomplete"
...
#if mInvmod="complete"
   <Inventory module commands here>
#else
   mMessage = "Inventory not ready to compile"
#endif

For more information about using the #if directive, see Chapter 7 in the Programmer's Guide.


#if Example

The following example uses #if/#else to determine if a preprocessor directive containing a field list has been declared, and if not, uses #define to specify a field list:

#define FIELDLIST "Company, Contact, Phone"
*
*
*  additional program
*
CLEAR
USE Clients
#if FIELDLIST = "Company, Contact, Phone"
  LIST TO PRINT
#else
  #define FIELDLIST "Company, Contact, Phone"
  LIST TO PRINT
#endif


Portability

Not supported in dBASE III PLUS or dBASE IV, but supported in the dBASE Compiler for DOS.


See Also

#define

#ifdef

#ifndef


#ifdef

See Also	Example	Portability	Preprocessor

Controls conditional compilation of code based on the existence of an identifier assigned with #define or the existence of the __dbasewin__ identifier.

Syntax

#ifdef <identifier>
<statements 1>
[#else
<statements 2>]
#endif

<identifier>

The identifier to test for existence. <identifier> is defined with the #define directive.

<statements 1>

One or more program lines consisting of any combination of commands, functions, and preprocessor directives. These lines are compiled if <identifier> has been defined.

#else <statements 2>

Specifies the program lines to compile if <identifier> has not been defined.

Description

Use the #ifdef directive to conditionally compile sections of source code. If you have defined <identifier> with #define, the code you specify with <statements 1> is compiled; otherwise, the code following #else is compiled.

Conditional compilation is useful when maintaining different versions of the same program or for debugging purposes. This is shown in the following example.

#define InvMod
#ifdef InvMod
  <Inventory module commands here>
#else
  mMessage = "Inventory not ready to compile"
#endif

To determine whether dBASE for Windows or a prior version of dBASE is currently running, use #ifdef with the __dbasewin__ identifier, as shown in the following example.

#ifdef __dbasewin__
  < code specific to dBASE for Windows>
#else
  <code specific to prior versions of dBASE>
#endif

For more information about using the #ifdef directive, see Chapter 7 in the Programmer's Guide.


#ifdef Example

The following example uses #ifdef to determine if a desired font has been defined prior to printing. If not, the font is defined and printing is initiated.

#ifdef BIGFONT
  LIST TO PRINT
#else
  #define BIGFONT fontname "Roman",;
    fontheight 20,fontwidth 22
  LIST TO PRINT
#endif

Portability

Not supported in dBASE III PLUS.


See Also

#define

#if

#ifndef


#ifndef

See Also	Example	Portability	Preprocessor

Controls conditional compilation of code based on the existence of an identifier assigned with #define.

Syntax

#ifndef <identifier>
<statements 1 >
[#else
<statements 2>]
#endif

<identifier>

The identifier to test for existence. <identifier> is defined with the #define directive.

<statements 1>

One or more program lines consisting of any combination of commands, functions, and preprocessor directives. These lines are compiled if <identifier> has not been defined.

#else <statements 2>

Specifies the program lines to compile if <identifier> has been defined.

Description

Use the #ifndef directive to conditionally compile sections of source code. If you haven't defined <identifier> with #define, the code you specify with <statements 1> is compiled; otherwise, the code following #else is compiled.

Conditional compilation is useful when maintaining different versions of the same program or for debugging. This is shown in the following example.

#ifndef InvMod
  mMessage = "Inventory not ready to compile"
#else
  <Inventory module commands here>
#endif

For more information about using the #ifndef directive, see Chapter 7 in the Programmer's Guide.


#ifndef Example

The following example uses #ifndef to determine if a desired font has not been defined, and if not, defines the font with #define. The #else portion serves to confirm that the font is correctly defined by first undefining and then defining "BIGFONT".

#ifndef BIGFONT
  #define BIGFONT fontname "Roman",;
    fontheight 20,fontwidth 22
#else
  #undef BIGFONT
  #define BIGFONT fontname "Roman",;
    fontheight 20,fontwidth 22
#endif


Portability

Not supported in dBASE III PLUS.


See Also

#define

#if

#ifdef


#include

See Also	Example	Portability	Preprocessor

Inserts the contents of the specified source file (known as an include or header file) into the current program file at the location of the #include statement.

Syntax

#include <filename>| "<filename>"

<filename> | "<filename>"

The name of the file, optionally including a full or partial path, whose contents are to be inserted into the current program file. You can specify the file name within or without quotes. An include file typically has an .h file-name extension.

If you specify <filename> without a path, the preprocessor uses the following search order:

1.	It searches the current directory for the file exactly as you have specified it.

2.	If you omitted the .h file-name extension, it adds the extension and searches the current directory.

3.	If it cannot find the file in the current directory, it looks in <home directory>\ INCLUDE. (The home directory is the one in the _dbwinhome system memory variable.)

4.	If it cannot find the file in the current directory or <home directory>\INCLUDE, it looks in the directory you specify in DOS with the INCLUDE environment variable.

Description

Identifiers are typically available only to the program in which they are defined. To use a single set of identifiers in multiple programs, save the #define statements in a file, then use the #include directive to define the identifiers in additional programs. The file containing the #define statements is called an include file. For example, an include file named IDENT.H might contain the following directives:

#define cCompany="dSolutions, Inc."
#define nSales=40000
#define cHomeState="TX"

Each program that needs access to these identifiers would contain the following line:

#include ident.h

An advantage of having all the #define statements in one file is the ease of maintenance. If you need to modify any of the #define statements, you need only change the include file; the program files that use the #define statements remain unchanged. After you modify the include file, recompile your program file for the changes to take effect.

For example, if you later need to change the home state value in the previous example from "TX" to "WA" throughout your application, you need to change the #define statement only in IDENT.H.

For more information about include files, see Chapter 7 in the Programmer's Guide.


#include Example

The following example inserts the contents of a user defined setup file in the currently running dBASE program. The file "setup.h" can contain #define identifier definitions that are common to several programs the user runs:

#include "c:\dbasewin\setup\setup.h"


Portability

Not supported in dBASE III PLUS or dBASE IV, but supported in the dBASE Compiler for DOS.


See Also

#define

GETFILE( )


#pragma

See Also	Example	Portability	Preprocessor

Sets compiler options.

Syntax

#pragma <coverage(on | off)>

#pragma <coverage(on | off)>

Includes or excludes coverage analysis, which provides information about which program lines are executed.

Description

Use #pragma coverage(on) in your program to start coverage analysis each time you run the program, instead of executing SET COVERAGE ON in the Command window before compiling and running the program.

This is also the only way to start coverage analysis from within a program; if you issue SET COVERAGE ON in a program, dBASE does not create or update a coverage file for that program. For more information about coverage files, see SET COVERAGE.

For more information about preprocessor directives, see Chapter 7 in the Programmer's Guide.


#pragma Example

The following example uses #pragma to set coverage on for a debugging session:

#ifdef DEBUG
  #pragma coverage(on)
#else
  #pragma coverage(off)
#endif


Portability

Not supported in dBASE IV or dBASE III PLUS.


See Also

#define

SET COVERAGE


#undef

See Also	Example	Portability	Preprocessor

Removes the current definition of the specified identifier previously defined with #define.

Syntax

#undef <identifier>

<identifier>

The identifier whose definition is to be removed.

Description

The #undef directive removes the definition of an identifier previously defined with the #define directive. If you use #define with <replacement text>, the preprocessor replaces all instances of the identifier with the replacement text from the point it encounters that #define until it encounters an #undef specifying the same identifier. Therefore, to replace an identifier only in parts of a program, insert #undef <identifier> into your program where you want the search-and-replace process to stop.


#undef Example

See #ifndef for an example of using #undef.


Portability

Not supported in dBASE III PLUS.


See Also

#define


_alignment

See Also	Example	Portability	Printing

Left-aligns, right-aligns, or centers ? and ?? command output within margins specified by _lmargin and _rmargin when _wrap is true.

Syntax

_alignment = <expC>

<expC>

The character expression "LEFT", "CENTER", or "RIGHT". You can enter <expC> in any combination of uppercase and lowercase letters.

Default

The default for _alignment is "LEFT".

Description

Use _alignment to left-align, right-align, or center output from the ? and ?? commands between the margins you set with _lmargin and _rmargin. The _alignment setting is effective only when _wrap is true (.T.).

To control the alignment of text within a field, use the "B," "I," and "J" format options with the PICTURE or FUNCTION options of an @...SAY statement. For information about format options, see Picture and Function.


_alignment Example

The following example sets wrap on and then prints in the three different alignments: left, center, and right:

savewrap=_wrap       && save last wrap setting
_wrap=.t.           && must be .t. for alignment
savealign=_alignment && save last alignment setting
_alignment="LEFT"
? "Hello LEFT"
_alignment="RIGHT"
? "Hello RIGHT"
_alignment="CENTER"
? "Hello CENTER"
_alignment=savealign && reset
_wrap=savewrap       && reset


Portability

Not supported in dBASE III PLUS.


See Also

?

??

@...SAY...GET

_lmargin

_rmargin

_wrap

SET MARGIN


_app

See Also	Example	Objects

Contains an object reference to the application object, which is the active dBASE session.

Syntax

_app.<property name> = <new value>

<property name>

The application object property that you change.

<new value>

The value you give to the application object property.

Description

Use _app to access and control the application object.

The application object is the current dBASE session. It has four properties, DdeServiceName, ClassName, Insert, and OnInitiate. The application object also contains an object called FrameWin, which is the dBASE application  window.

DdeServiceName

Use the DdeServiceName property to let a client application establish a DDE link to a particular dBASE session when multiple dBASE sessions exist.

The value you specify with DdeServiceName is the name of a dBASE application object. Any active dBASE session is an application object; when you start a dBASE session, you are actually creating an instance of a dBASE application object.

For example, when you start two dBASE sessions, you create two dBASE application objects. Setting the DdeServiceName property of one application object to "NEWSERV" (or some other unique name) lets an external application like Quattro Pro distinguish between the two sessions. You use the _app system memory variable to reference and set the DdeServiceName property of one of the sessions:

_app.DdeServiceName = "NEWSERV"

To create a DDE link to the NEWSERV session, Quattro Pro could execute the following {INITIATE} request:

{INITIATE  "NEWSERV", "MyTopic", CHANNEL}

To create a DDE link to the other session (whose DdeServiceName property still contains the default value "DBASEWIN"), Quattro Pro could execute the following {INITIATE} request:

{INITIATE  "DBASEWIN", "MyTopic", CHANNEL}

ClassName

ClassName identifies the application object's class (APPLICATION). Classname is a read-only property.

Insert

Determines if Insert is on or off. When you set Insert to true (.T.), Insert is on.

OnInitiate

Executes an initiation-handler subroutine. You write this routine to create DDETopic objects, which handle DDE server events. OnInitiate executes the subroutine whenever a client application requests a DDE link with the dBASE session. For more information, see CLASS DDETOPIC and Chapter 26 in the Programmer's Guide.

The FrameWin object

The dBASE application window. This object contains five properties, Visible, ClassName, hWnd, Text, and WindowState.

Visible

Determines whether the dBASE application window is visible or hidden. You set Visible to false (.F.) when you want to display non-MDI forms without displaying the dBASE environment.

ClassName

ClassName identifies the application object's class (FRAMEWINDOW).

hWnd

Returns the dBASE Frame Window's object handle. External functions written in other languages such as C, Pascal, or ASM use this handle to identify the object. These external functions are usually stored in Dynamic Link Library (DLL) files. For example, you can pass the object handle of the dBASE Frame Window as a parameter to an external function, perhaps allowing the function to open or close the window.

hWnd is a read-only value.

For more information on DLL files and external functions, see EXTERN and Chapter 25 in the Programmer's Guide.

Text

Specifies a character string to display in the title bar of the dBASE application  window. For more information, see the description of the Text property.

WindowState

Determines if the dBASE application  window is minimized, maximized, or displayed in its original size. For more information, see WindowState.


_app Example

The following command, placed at the beginning of an application program, would change the text in the upper-center of the dBASE application  window to a company name:

_app.FrameWin.Text = "National Federal Bank"

To remove the dBASE environment  from the screen:

_app.FrameWin.Visible = .F.

To set Insert Off for your application:

_app.Insert = .F.

Since the ClassName property is read-only, access it as follows:

IF _app.ClassName = "APPLICATION"  && Returns .T.
  * perform action
ENDIF
  * or
? _app.ClassName  && Returns the string "APPLICATION"
  * or
mVar = _app.ClassName  && Initializes variable


See Also

CLASS DDETOPIC

EXTERN

LOAD DLL

RESOURCE( )


_box

See Also	Example	Portability	Printing

Controls whether dBASE displays dBASE IV DEFINE BOX boxes in ? command output.

Syntax

_box = <expL>

<expL>

The logical expression true or false in the form .T. or .F., respectively.

Default

The default for _box is .F.

Description

Use _box to control the display of boxes created with the dBASE IV command DEFINE BOX. If you set _box to true (.T.), dBASE displays the boxes in the background of streaming output from the ? command.

You can control the exact moment to display or print a box with _box. For example, you can interrupt the printing of a box by setting _box to false (.F.) before it has finished printing. When you set _box to .T. later, the rest of the box prints.


_box Example

_box is used only in conjunction with DEFINE BOX. See the example in DEFINE BOX.


Portability

Not supported in dBASE III PLUS.


See Also

ACTIVATE WINDOW

DEFINE BOX


_curobj

See Also	Example	Portability	Forms

Identifies the position of the currently-selected object in the tabbing order of the active form.

Syntax

_curobj = <expN>

Description

_curobj holds a number identifying the position of the selected object.

A related form property , ActiveControl, returns the name of the object that currently has input focus.


_curobj Example

The following example defines a form that contains four objects. The OnGotFocus property is used to display the current object number at the Command window Results pane when an object gains focus:

USE Contact.DBF
CLEAR
LOCAL f
f=NEW ENTRY()
f.OPEN()
CLASS Entry OF FORM
  this.Top=2
  this.Left=2
  this.Width=36
  this.Height=8
  this.Text= "Contact.DBF"
  this.StatusMessage="_curobj in Command window"
  DEFINE ENTRYFIELD CompCode OF THIS AT 2,2;
    PROPERTY Width 5, Height 1.5,;
      DataLink "COMPCODE", OnGotFocus {;?_curobj}
  DEFINE ENTRYFIELD Contact OF THIS AT 2,12;
    PROPERTY Width 22, Height 1.5,;
    DataLink "CONTACT", OnGotFocus {;?_curobj}
  DEFINE PUSHBUTTON Back OF THIS AT 5,9;
    PROPERTY Text "Back", Height 2,;
      OnClick {;SKIP-1},;
      OnGotFocus {;?_curobj}
  DEFINE PUSHBUTTON Next OF THIS AT 5,19;
    PROPERTY TEXT "Next", Height 2,;
      OnClick {;SKIP},;
      OnGotFocus {;?_curobj}
ENDCLASS


Portability

Not supported in dBASE IV or dBASE III PLUS.


See Also

ActiveControl


_dbwinhome

See Also	Example	Portability	Disk and File Utilities

Contains the path to the dBASE home directory.

Syntax

? _dbwinhome

Description

Use _dbwinhome to identify the root directory (also called the home directory) in which dBASE files are installed. When you install dBASE, the installation program (by default) installs dBASE files in the DOS directory \DBASEWIN, and creates subdirectories such as \BIN and \SAMPLES under \DBASEWIN. _dbwinhome returns the name of the home directory (in this case, DBASEWIN.) _dbwinhome returns the full path name whether SET FULLPATH is ON or OFF.

To identify where the currently running version of DBASEWIN.EXE is located, use HOME( ).


_dbwinhome Example

_DBWINHOME would only change if dBASE were reinstalled in a different directory:

? _dBWINHOME && e.g. D:\DBASEWIN
* dBASE is installed in the DBASEWIN subdirectory
* of the D drive.


Portability

Not supported in dBASE IV or dBASE III PLUS.


See Also

CD

HOME( )

MKDIR

SET DIRECTORY

SET FULLPATH

SET PATH


_indent

See Also	Example	Portability	Printing

Specifies the number of columns to indent the first line of a paragraph of ? command output when _wrap is true.

Syntax

_indent = <expN>

<expN>

The column number, relative to the left margin, where the first line of a new paragraph begins. You can specify a fractional number for <expN> to position output accurately with a proportional font.

Default

The default for _indent is 0.

Description

Use _indent to specify where the first line of a new paragraph begins relative to the left margin. (Specify the left margin with _lmargin.) The _indent setting is effective only when _wrap is true (.T.).

When you direct ? output to the printer, dBASE maps each character according to the coordinate plane, a two-dimensional grid. The coordinate plane is divided into character cells whose widths depend on the value of _ppitch. See the table in the description of _ppitch, which lists _ppitch values. The height of each character cell is determined by the size of the font. For more information about the coordinate plane, see Chapter 16 in the Programmer's Guide.

If you change the value of _indent, dBASE takes the current value of _ppitch into consideration when calculating the cell width of the coordinate plane. This happens regardless of whether you are printing with proportional or monospaced fonts. If you issue ? without the STYLE option and use only integer coordinates, dBASE uses a monospaced font, and all output appears exactly the same as in dBASE IV.

To indent the first line of a paragraph, use a value greater than 0. For example, to begin the line five columns to the right of the left margin, set _indent to 5. To create a hanging indent (sometimes called an outdent), use a negative value. For example, to begin the first line five columns to the left of the left margin, set _indent to -5. Using the default value of 0 (no indent or outdent) aligns all lines in a paragraph to the left margin. The sum of _lmargin and _indent must be greater than 0 and less than _rmargin.


_indent Example

The following example sets wrap on and indents the first line of a text that wraps around:

_indent=3              && set the indentation
savewrap=_wrap         && save last wrap setting
_wrap=.t.              && must be .t. for alignment
savelmargin=_lmargin   && save last alignment setting
_lmargin=5
savermargin=_rmargin   && save last alignment setting
_rmargin=20
? "New York, Chicago and Boston are "+;
  "cold in wintertime."
* Now the text wraps around between columns 5 and 20
*
*        New York,
*     Chicago and
*     Boston are cold
*     in wintertime.
*
_rmargin=savermargin   && restore the previous margin
_lmargin=savelmargin   && restore the previous margin
_wrap=savewrap         && reset wrap


Portability

Not supported in dBASE III PLUS.


See Also

?

??

_alignment

_lmargin

_ploffset

_rmargin

_wrap

SET MARGIN


_lmargin

See Also	Example	Portability	Printing

Defines the left margin for ? and ?? command output when _wrap is true.

Syntax

_lmargin = <expN>

<expN>

The column number of the left margin. The valid range is 0 to 254, inclusive. You can specify a fractional number for <expN> to position output accurately with a proportional font.

Default

The default for _lmargin is 0.

Description

Use _lmargin to set the left margin for ? and ?? command output. If you are sending output to a printer, _lmargin sets the left margin from the _ploffset (page left offset) column. For example, if _ploffset is 10 and _lmargin is 5, output prints from the 15th column. The _lmargin setting is effective only when _wrap is true (.T.).

When you direct output to the printer, dBASE maps each character according to the coordinate plane, a two-dimensional grid. The coordinate plane is divided into character cells whose widths depend on the value of _ppitch. See the table in the description of _ppitch, which lists _ppitch values. The height of each character cell is determined by the size of the font. For more information about the coordinate plane, see Chapter 16 in the Programmer's Guide.

If you change the value of _lmargin, dBASE takes the current value of _ppitch into consideration when calculating the cell width of the coordinate plane. This happens regardless of whether you are printing with proportional or monospaced fonts. If you issue ? without the STYLE option and use only integer coordinates, dBASE uses a monospaced font, and all output appears exactly the same as in dBASE IV.

If you use _indent to specify the indentation of the first line of each paragraph, the combined values of _lmargin and _indent must be less than the value of _rmargin.


_lmargin Example

The following example uses _lmargin. It sets wrap on and then changes the left margin and displays text:

_wrap=.t.             && must be .t. for _lmargin
_lmargin=0
? "01234567890"
_lmargin=5
? "Changing the margin"
* produces:
* 01234567890
*      Changing the margin


Portability

Not supported in dBASE III PLUS.


See Also

?

??

_alignment

_indent

_ploffset

_rmargin

_wrap

SET MARGIN

Style


_padvance

See Also	Example	Portability	Printing

Determines whether the printer advances the paper of a print job with a formfeed or with linefeeds.

Syntax

_padvance = <expC>

<expC>

The character expression "FORMFEED" or "LINEFEEDS".

Default

The default for _padvance is "FORMFEED".

Description

Use _padvance to specify whether dBASE advances the paper to the top of the next sheet one sheet at a time using a formfeed character, or one line at a time using linefeed characters. If you use the default "FORMFEED" setting, the paper advances according to the printer's default form length setting.

Tractor-feed printers (such as dot matrix printers) generally use a "LINEFEEDS" setting, while form feed printers (such as laser printers) generally use a "FORMFEED" setting.

Note:	Sending CHR(12) to the printer always issues a formfeed, even if you set _padvance to "LINEFEEDS".

Use the "LINEFEEDS" setting if you change the length of the paper or want to print a different number of lines than the default form length of the printer without adjusting its setting. For example, to print short pages, such as checks that are 20 lines long, set _plength to the length of the output (20 in this example) and _padvance to "LINEFEEDS."

The number of linefeeds dBASE uses to reach the top of the next page depends on whether you issue an eject during streaming or non-streaming output mode. For more information about streaming and non-streaming output, see Chapter 24 in the Programmer's Guide.

An eject occurs during streaming output mode when you issue

EJECT PAGE without an ON PAGE handler

EJECT PAGE with an ON PAGE handler when the current line position is past the ON PAGE line

PRINTJOB or ENDPRINTJOB and _peject causes an eject

In these cases, dBASE calculates the number of linefeeds to send to the print device using the formula _plength - _plineno.

An eject occurs in nonstreaming output mode when you issue:

EJECT

SET DEVICE TO PRINTER and force a page eject with the @ command

In these cases, dBASE calculates the number of linefeeds to send to the print device using the formula _plength - MOD(PROW(), _plength).


_padvance Example

There are two _padvance settings:

_padvance="FORMFEED"
_padvance="LINEFEEDS"


Portability

Not supported in dBASE III PLUS.


See Also

_peject

_plength

EJECT

EJECT PAGE

PRINTJOB...ENDPRINTJOB

ON PAGE

SET DEVICE


_pageno

See Also	Example	Portability	Printing

Determines or sets the current page number.

Syntax

_pageno = <expN>

<expN>

An integer from 1 to 32,767, inclusive.

Description

Use _pageno to number pages of streaming output from commands such as ?, ??, and LIST. For more information about streaming and non-streaming output, see Chapter 24 in the Programmer's Guide.

With _pageno, you can determine the current page number or set the page number to a specific value. Use it to print page numbers in a report or, when combining documents, to assign an incremented number to the first page of the second document.

A page break occurs when the value of _plineno (the line number count) becomes greater than the value of _plength (the currently defined printed page length in lines). At each page break of streaming output, dBASE automatically increments the value of _pageno.


_pageno Example

This example prints 100 lines of output and prints a heading on line 1 of each page:

SET TALK OFF
SET PRINTER ON
_pageno=1
FOR i=1 TO 100
  IF _plineno=1  && At first line of page
    ? "Top of Page ",_pageno
  ENDIF
  ? "Line",i
NEXT i
SET PRINTER TO
CLOSE PRINTER
SET TALK ON


Portability

Not supported in dBASE III PLUS.


See Also

?

??

_pbpage

_pepage

_plength

_plineno

LIST

ON PAGE


_pbpage

See Also	Example	Portability	Printing

Specifies the page number of the first page PRINTJOB prints.

Syntax

_pbpage = <expN>

<expN>

The page number at which to begin printing. The valid range is 1 to 32,767, inclusive. Specify a positive integer for <expN>.

Default

The default for _pbpage is 1.

Description

Use _pbpage to begin printing a print job at a specific page number. Pages with numbers less than _pbpage do not print. To stop printing at a specific page number, use _pepage.

If you set _pbpage to a value greater than _pepage, dBASE returns an error.


_pbpage Example

This example uses _pbpage to omit a page of a report. It outputs 100 lines and prints the page and line number on each line as in the example for _plineno. Here, the beginning page number is set to 2 so that page 1 does not print:

_pageno=1
_pbpage=2       && begin on page 2
SET PRINTER ON
PRINTJOB
FOR i=1 TO 100
  ?? "Page",_pageno," Line",_plineno
  ?                    && now force a linefeed
NEXT i
ENDPRINTJOB
SET PRINTER OFF
CLOSE PRINTER          && start printing


Portability

Not supported in dBASE III PLUS.


See Also

_pageno

_pepage

PRINTJOB...ENDPRINTJOB


_pcolno

See Also	Example	Portability	Printing

Identifies or sets the current column number of streaming output.

Syntax

_pcolno = <expN>

<expN>

The column number at which to begin printing. The valid range is 0 to 255, inclusive. You can specify a fractional number for <expN> to position output accurately with a proportional font.

Default

The default for _pcolno is 0.

Description

Use _pcolno to position printing streaming output from commands such as ?, ??, and LIST. For more information about streaming output, see Chapter 24 in the Programmer's Guide.

When you direct output to the printer, dBASE maps each character according to the coordinate plane, a two-dimensional grid. The coordinate plane is divided into character cells whose widths depend on the value of _ppitch. See the table in the description of _ppitch, which lists _ppitch values. The height of each character cell is determined by the size of the font. For more information about the coordinate plane, see Chapter 16 in the Programmer's Guide.

If you change the value of _pcolno, dBASE takes the current value of _ppitch into consideration when calculating the cell width of the coordinate plane. This happens regardless of whether you are printing with proportional or monospaced fonts. If you issue ? without the STYLE option and use only integer coordinates, dBASE uses a monospaced font, and all output appears exactly the same as in dBASE IV.

The PCOL( ) function also returns the current printhead position of the printer, but if SET PRINTER is OFF, the PCOL( ) value does not change. _pcolno, on the other hand, returns or assigns the current position in the streaming output regardless of the SET PRINTER setting.


_pcolno Example

This example displays the numbers 1 through 5. It uses _pcolno to position the numbers so that each number begins at its own position:

SET TALK OFF
FOR i=1 to 5
  _pcolno=i      && set the column position
  string=ltrim(str(i))
  * convert i to a single character
  ?? string
  ?
NEXT I
SET TALK ON
* the output looks like this
* 1
*  2
*   3
*    4
*     5


Portability

Not supported in dBASE III PLUS.


See Also

?

_plineno

_rmargin

PCOL( )

SET DEVICE

SET PRINTER


_pcopies

See Also	Example	Portability	Printing

Specifies the number of copies to print for a PRINTJOB.

Syntax

_pcopies = <expN>

<expN>

The number of copies to print. The valid range is 1 to 32,767, inclusive. Specify a positive integer for <expN>.

Default

The default for _pcopies is 1.

Description

Use _pcopies to print a specific number of copies of a print job. You can assign a value to _pcopies in the Command window or in a program. The value of _pcopies has an effect only when you send a print job to the printer by issuing PRINTJOB. In a program, assign a value to _pcopies before issuing PRINTJOB.


_pcopies Example

This example uses _pcopies to print the print job three times:

_pcopies=3         && Three copies
SET PRINTER ON
PRINTJOB
? "Very Small Report"
ENDPRINTJOB
SET PRINTER OFF
CLOSE PRINTER      && start the printer


Portability

Not supported in dBASE III PLUS.


See Also

PRINTJOB...ENDPRINTJOB


_pdriver

See Also	Example	Portability	Printing

Identifies the current printer driver or activates a new driver.

Syntax

_pdriver = <expC>

<expC>

The name of the printer driver to activate.

Default

The default for _pdriver is the printer driver you specify with the Windows Control Panel. If you haven't specified a printer driver with the Control Panel, the value of _pdriver is an empty string ("").

Description

Use _pdriver to identify the current printer driver or to activate an installed driver. (To install a new printer driver, use the Windows Control Panel.)

The _pdriver value contains two elements separated by a comma: the base file name of the Windows driver file and the name of the printer as it appears in WIN.INI. The current driver might not identify a printer name, in which case, _pdriver contains only the driver file name. For example, if the current printer driver is for the HP Laserjet IIISi PostScript printer, _pdriver may contain the value "pscript,HP LaserJet IIISi PostScript". To activate this driver, issue the command _pdriver = "pscript,HP LaserJet IIISi PostScript".

To activate a driver from within dBASE,  it may be easier to use CHOOSEPRINTER( ) than to assign a value to _pdriver. To activate a driver in Windows, use the Printers program of the Windows Control Panel. CHOOSEPRINTER( ) opens the Print Setup dialog box, in which you can also select options such as paper size, source, and orientation (portrait or landscape). In the Windows Control Panel, you can choose Setup to select these options.


_pdriver Example

Use _pdriver to determine the current print driver:

? _pdriver
* With an Epson FX 80, the response is:
*       EPSON9,Epson FX-80
* With an HP Laserjet running postscript, the
* response is:
*       pscript,HP LaserJet IIISi PostScript

You can set the print driver with _pdriver:

_pdriver="pscript"


Portability

Not supported in dBASE III PLUS. Only Windows printer driver names are supported; driver names used with dBASE IV are not supported.


See Also

_pform

_ppitch

_pquality

CHOOSEPRINTER( )

SET PRINTER


_peject

See Also	Example	Portability	Printing

Determines whether dBASE ejects a sheet of paper before and after a PRINTJOB.

Syntax

_peject= <expC>

<expC>

The character expression "before", "after", "both", or "none".

Default

The default for _peject is "before", which tells the printer to eject a sheet of paper before starting the print job.

Description

Use _peject to specify if and when the printer should eject a sheet of paper. Assign a new value to _peject (and to any other system memory variable) before issuing PRINTJOB in a program to make the new value affect the print job.

The following table describes _peject options.

<expC>	Result
"before"	Eject sheet before printing the first page
"after"	Eject sheet after printing the last page
"both"	Eject sheet before and after the print job
"none"	Do not eject sheet before or after the print job
Note:	The _peject system memory variable is distinct from the EJECT command, which tells the printer to advance the paper to the top of the next page.


_peject Example

This example shows the four possible _peject setting. The last setting is operational in the PRINTJOB:

_peject="before"
_peject="after"
_peject="both"
_peject="none"
* _peject must be set before PRINTJOB
PRINTJOB
 ? "Hello World"
ENDPRINTJOB


Portability

Not supported in dBASE III PLUS.


See Also

_padvance

EJECT

EJECT PAGE

PRINTJOB...ENDPRINTJOB


_pepage

See Also	Example	Portability	Printing

Specifies the page number of the last page of a print job.

Syntax

_pepage = <expN>

<expN>

The page number of the last page to print. The valid range is 1 to 32,767, inclusive. You must specify a positive integer for <expN>.

Default

The default for _pepage is 32,767.

Description

Use _pepage to stop printing a print job at a specific page number. Pages with numbers greater than _pepage do not print. To begin printing at a specific page number, use _pbpage.

If you set _pepage to a value less than _pbpage, dBASE returns an error.


_pepage Example

This example selects two pages from a PRINTJOB. The program prints 500 lines of output and prints the page and line number on each line as in the example for _plineno. Here, the ending page number is set to 2 so that only pages 1 and 2 print:

_pageno=1
_pbpage=1       && reset the default pbpage
_pepage=2       && end on page 2
SET PRINTER ON
PRINTJOB
FOR i=1 TO 500
  ?? "Page",_pageno," Line",_plineno
  ?                    && now force a linefeed
NEXT i
ENDPRINTJOB
SET PRINTER OFF
CLOSE PRINTER          && begin printing

The ? command issues a linefeed before processing consequently in this case, the correct line number is obtained by using ??


Portability

Not supported in dBASE III PLUS.


See Also

_pageno

_pbpage

PRINTJOB...ENDPRINTJOB


_pform

See Also	Example	Portability	Printing

Identifies the current print form file or activates another one.

Syntax

_pform = <filename>

<filename>

The name of a print form file (.PRF).

Default

The default for _pform is an empty string ("").

Description

Use _pform to determine the name of the current print form file or to activate another one. A print form file (.PRF) is a dBASE binary file that contains print settings for printing a print job. The print form file contains the following system memory variables:

Variable	Action
_padvance	Determines whether the printer advances the paper with a formfeed or linefeeds.
_pageno	Determines or sets the current page number.
_pbpage	Specifies the page number at which PRINTJOB begins printing.
_pcopies	Specifies the number of copies to print in a printjob.
_pdriver	Activates a specified printer driver. (If the print form file is from dBASE IV, dBASE for Windows ignores this value.)
_peject	Controls page ejects before and after PRINTJOB.
_pepage	Specifies the number of the last page that PRINTJOB prints.
_plength	Specifies the number of lines per page for streaming output.
_ploffset	Determines the width of the left border on a printed page.
_ppitch	Sets the printer pitch, the number of characters per inch that the printer prints.
_pquality	Specifies if the printer prints in letter-quality or draft mode.
_pspacing	Sets the line spacing for streaming output.
_pwait	Determines if the printer pauses after printing each page.
When you specify a print form file by assigning its name to _pform, the values stored in the file are assigned to their respective variables. Jobs you send to the printer then behave in accordance with these variables.


_pform Example

This example assumes there are two reports, Report1 and Report2. It uses Report1's print form file, Report1.PRF to print Report2:

_pform= "Report1"
REPORT FORM Report2


Portability

Not supported in dBASE III PLUS.


See Also

PRINTJOB...ENDPRINTJOB


_plength

See Also	Example	Portability	Printing

Specifies the number of lines per page for streaming output.

Syntax

_plength = <expN>

<expN>

The number of lines per page. The valid range is 1 to 32,767, inclusive. You can specify a fractional number for <expN> to position output accurately with a proportional font.

Default

The default page length is determined by the default page size of the current printer driver and the current page orientation (portrait or landscape).

Description

Use _plength to specify a page length that is different from the default of the current printer driver. For example, to print short pages, such as checks that are 20 lines long, set _plength to the length of the output (20 in this example) and _padvance to "LINEFEEDS" to advance to the top of the next page.

When you change printer drivers or page orientation, dBASE changes the value of _plength automatically. You can change printer drivers in dBASE by issuing CHOOSEPRINTER( ) or by assigning a value to _pdriver. In Windows, you can change printer drivers with the Printers program of the Control Panel (however, it will not take effect until you quit dBASE and start a new dBASE session). You can change page orientation in any of these ways or, in dBASE, by changing the value of _porientation.


_plength Example

This example sets the form length to 10 lines and prints  25 lines of output. Each line simply prints line number and count (1 thru 25). A three-line heading prints "Top of Page" on each line 1:

_plength=10
_pageno=1
_plineno=0
SET PRINTER ON
FOR i=1 TO 25
  IF _plineno=0  && At first line of page
    ?
    ? "Top of Page ",_pageno
    ?
  ENDIF
  ? "Line",_plineno,"i=",i
NEXT i
SET PRINTER OFF
CLOSE PRINTER
* The first two pages are:
*
* Top of Page           1
*
* Line          3.00 i=          1
* Line          4.00 i=          2
* Line          5.00 i=          3
* Line          6.00 i=          4
* Line          7.00 i=          5
* Line          8.00 i=          6
* Line          9.00 i=          7
*
* Top of Page           2
*
* Line          3.00 i=          8
* Line          4.00 i=          9
* Line          5.00 i=         10
* Line          6.00 i=         11
* Line          7.00 i=         12
* Line          8.00 i=         13
* Line          9.00 i=         14


Portability

Not supported in dBASE III PLUS. In dBASE IV, the default page length is 66 lines.


See Also

_padvance

_pdriver

_porientation

CHOOSEPRINTER( )

EJECT

EJECT PAGE


_plineno

See Also	Example	Portability	Printing

Identifies or sets the current line number of streaming output.

Syntax

_plineno = <expN>

<expN>

The line number at which to begin printing. The valid range is 0 to _plength - 1. You can specify a fractional number for <expN> to position output accurately with a proportional font.

Default

The default for _plineno is 0.

Description

Use _plineno to position printing streaming output from commands such as ?, ??, and LIST. For more information about streaming output, see Chapter 24 in the Programmer's Guide.

The PROW( ) function also returns the current printhead position of the printer, but if SET PRINTER is OFF, the PROW( ) value does not change. _plineno, on the other hand, returns or assigns the current position in the streaming output regardless of the SET PRINTER setting.


_plineno Example

This example prints 32 lines of output on four pages. The page length is set at 10 lines per page, and the report prints the page and line number on each line using _pageno and _plineno:

_pbpage=1       && reset the default pbpage
_pepage=32767   && reset the default pepage
_plength=10     && set the page length to 10 lines
_pageno=1
SET PRINTER ON
PRINTJOB        && PRINTJOB resets _plineno to 0
FOR i=1 TO 32
  IF _plineno=0  && At first line of page
    *?
    ? "Top of Page ",_pageno
    ?
  ENDIF
  ?? "Page",_pageno," Line",_plineno,i
  ?                    && now force a linefeed
NEXT i
ENDPRINTJOB
SET PRINTER OFF
CLOSE PRINTER
* The first two pages of output appear as follows:
*
* Top of Page           1
* Page          1  Line          2.00          1
* Page          1  Line          3.00          2
* Page          1  Line          4.00          3
* Page          1  Line          5.00          4
* Page          1  Line          6.00          5
* Page          1  Line          7.00          6
* Page          1  Line          8.00          7
* Page          1  Line          9.00          8
*
* Top of Page           2
* Page          2  Line          2.00          9
* Page          2  Line          3.00         10
* Page          2  Line          4.00         11
* Page          2  Line          5.00         12
* Page          2  Line          6.00         13
* Page          2  Line          7.00         14
* Page          2  Line          8.00         15
* Page          2  Line          9.00         16


Portability

Not supported in dBASE III PLUS.


See Also

_pcolno

_plength

_ppitch

EJECT PAGE

ON PAGE

PCOL( )

PROW( )


_ploffset

See Also	Example	Portability	Printing

Displays or sets the width of the left border of a printed page.

Syntax

_ploffset = <expN>

<expN>

The column number at which to set the left margin. The valid range is 0 to 254, inclusive. You can specify a fractional number for <expN> to position output accurately with a proportional font.

Default

The default for _ploffset is 0. To change the default, set the MARGIN parameter in DBASEWIN.INI.

Description

Use _ploffset (page left offset) to specify the distance from the left edge of the paper to the left margin of the print area. Use _lmargin to set the left margin from the _ploffset column. For example, if _ploffset is 10 and _lmargin is 5, output prints from the 15th column.

The _ploffset system memory variable is equivalent to the SET MARGIN value. Changing the value of one changes the other. For more information, see SET MARGIN.


_ploffset Example

See the example in SET MARGIN. _ploffset is identical to SET MARGIN.


Portability

Not supported in dBASE III PLUS, but SET MARGIN is.


See Also

_indent

_lmargin

SET MARGIN


_porientation

See Also	Example	Portability	Printing

Determines whether the printer prints in portrait or landscape mode.

Syntax

_porientation = <expC>

<expC>

The character expression "PORTRAIT" or "LANDSCAPE".

Default

The default for _porientation is the orientation you specify with the Printers program of the Windows Control Panel or, in dBASE, with the CHOOSEPRINTER( ) function. By default, this orientation is portrait.

Description

Use _porientation to specify whether you want to print in portrait or landscape mode. When you print in portrait mode, each page is read vertically; a standard American letter-size piece of paper is 8.5 inches wide by 11 inches long. When you print in landscape mode, each page is read horizontally; a standard American letter-size piece of paper is 11 inches wide by 8.5 inches long.

Most printer drivers support landscape printing; however, if you specify landscape while using a printer driver that does not support it, the printer continues to print in portrait mode, possibly truncating text.

Changing page orientation automatically resets _plength.


_porientation Example

_porientation has two settings:

_porientation="PORTRAIT"
_porientation="LANDSCAPE"

It takes effect only on a page boundary.


Portability

Not supported in dBASE III PLUS or dBASE IV.


See Also

_pdriver

_plength

_ppitch

SET PRINTER


_ppitch

See Also	Example	Portability	Printing

Sets the printer pitch, the number of characters per inch that the printer prints.

Syntax

_ppitch = <expC>

<expC>

The character expression "pica", "elite", "condensed", or "default".

Default

The default for _ppitch is "default", the pitch defined by your printer's settings or by setup codes or commands you sent to the printer before you started dBASE. "Default" means that dBASE has not sent any pitch control codes to the printer.

Description

Use _ppitch to set the pitch (characters per inch) on the printer. The _ppitch setting sends a control code appropriate to the current printer driver. Use the Windows Control Panel or CHOOSEPRINTER( ) to select the printer driver.

When you direct output to the printer, dBASE maps each character according to the coordinate plane, a two-dimensional grid. The coordinate plane is divided into character cells whose sizes depend on the value of _ppitch. The height of each character cell is determined by the size of the font. For more information about the coordinate plane, see Chapter 16 in the Programmer's Guide.

The following table lists _ppitch values.

_ppitch value	Character cell width
"pica"	1/10" (10 characters/inch)
"elite"	1/12" (12 characters/inch)
"condensed"	1/17" (17 characters/inch)
If you change the value in other system memory variables such as _lmargin, _rmargin, and _ploffset, dBASE takes the current value of _ppitch into consideration when calculating the cell width of the coordinate plane. This happens regardless of whether you are printing with proportional or monospaced fonts.


_ppitch Example

This example shows the three settings of _ppitch:

s_ppitch=_ppitch  && save current pitch
SET PRINTER ON
_ppitch="pica"
? "John Brown's body: 10 characters per inch"
_ppitch="elite"
? "John Brown's body: 12 characters per inch"
_ppitch="condensed"
? "John Brown's body: 17 characters per inch"
_ppitch=s_ppitch        && restore original setting
CLOSE PRINTER

_ppitch is not valid for all printers.


Portability

Not supported in dBASE III PLUS.


See Also

_pdriver

_pquality

CHOOSEPRINTER( )


_pquality

See Also	Example	Portability	Printing

Specifies whether the printer prints in letter-quality or draft mode. Used primarily with dot-matrix printers; the _pquality value usually has no effect on printers that do not support draft mode, such as laser and Postscript printers.

Syntax

_pquality = <expL>

<expL>

The logical expression .T. for letter quality and .F. for draft quality.

Default

The default for _pquality is false (.F.) for draft mode.

Description

Use _pquality to determine whether the printer prints in letter-quality or draft mode. Letter-quality mode produces printed copy of higher quality (finer resolution) than draft; however, draft mode usually prints more quickly than letter-quality, depending on the printer.


_pquality Example

This example shows the two settings for print quality. Print quality cannot be changed in mid page and might or might not be available on your printer:

CLOSE PRINTER
set printer on
_pquality= .f.     && draft quality
? "John Brown's body"
CLOSE PRINTER
_pquality= .t.     && letter quality
? "John Brown's body"
CLOSE PRINTER


Portability

Not supported in dBASE III PLUS.


See Also

_pdriver

_ppitch


_pspacing

See Also	Example	Portability	Printing

Sets the line spacing for streaming output.

Syntax

_pspacing = <expN>

<expN>

The amount of line spacing. The valid range is 1 to 3, inclusive:

A value of 1 represents single spacing.

A value of 2 represents double spacing. There is one blank line between printed lines.

A value of 3 represents triple spacing. There are two blank lines between printed lines.

Paragraph spacing is in multiples of the height of the line just printed, which depends on the tallest font used in printing the line. You can specify a fractional number for <expN> to space text by partial line heights.

Default

The default for _pspacing is 1, which sets line spacing to single-line.

Description

Use _pspacing to set the line spacing of streaming output from commands such as ?, ??, and LIST. For more information about streaming and non-streaming output, see Chapter 24 in the Programmer's Guide. To insert a single blank line into output, use the ? command.

The _pspacing value also affects the height of boxes displayed with the dBASE IV DEFINE BOX command. For example, if you define a box with a height of 10 and assign 2 to _pspacing, dBASE prints the box with a height of 20 lines.


_pspacing Example

This example uses _pspacing to set the spacing to 1 then 2 lines between lines of text and finally back to 1 line:

_pspacing=1
? "Jack 1"
? "Jill 1"
_pspacing=2
? "Jack 2"
? "Jill 2"
_pspacing=1
? "Jack 1"
? "Jill 1"
* produces:
*         Jack 1
*         Jill 1
*
*         Jack 2
*
*         Jill 2
*         Jack 1
*         Jill 1

Notice that _pspacing takes place immediately so that the double spacing occurs before Jack 2 and before Jill 2.


Portability

Not supported in dBASE III PLUS.


See Also

?

??

_ppitch

DISPLAY

LIST


_rmargin

See Also	Example	Portability	Printing

Defines the right margin for ? and ?? command output when _wrap is true.

Syntax

_rmargin = <expN>

<expN>

The column number of the right margin. The valid range is 0 to 255, inclusive. You can specify a fractional number for <expN> to position output accurately with a proportional font.

Default

The default for _rmargin is 79.

Description

Use _rmargin to set the right margin for output from the ? and ?? commands. The value of _rmargin must be greater than the value of _lmargin or _lmargin + _indent. For example, if _lmargin and _indent are both set to 5, _rmargin must be greater than 10 to display at least one column of output.

When you direct output to the printer, dBASE maps each character according to the coordinate plane, a two-dimensional grid. The coordinate plane is divided into character cells whose widths depend on the value of _ppitch. See the table in the description of _ppitch, which lists _ppitch values. The height of each character cell is determined by the size of the font. For more information about the coordinate plane, see Chapter 16 in the Programmer's Guide.

If you change the value of _rmargin, dBASE takes the current value of _ppitch into consideration when calculating the cell width of the coordinate plane. This happens regardless of whether you are printing with proportional or monospaced fonts. If you issue ? without the STYLE option and use only integer coordinates, dBASE uses a monospaced font, and all output appears exactly the same as in dBASE IV.


_rmargin Example

The following example sets wrap on and then changes the left margin and displays text:

savewrap=_wrap         && save last wrap setting
_wrap=.t.             && must be .t. for alignment
savelmargin=_lmargin   && save last alignment setting
_lmargin=5
savermargin=_rmargin   && save last alignment setting
_rmargin=20
? "New York, Chicago and Boston are cold in wintertime."
* Now the text wraps around between columns 5 and 20
_rmargin=savermargin   && restore the previous margin
_lmargin=savelmargin   && restore the previous margin
_wrap=savewrap         && reset wrap


Portability

Not supported in dBASE III PLUS.


See Also

?

??

_alignment

_indent

_lmargin

_ploffset

_wrap

SET MARGIN


_tabs

See Also	Example	Portability	Printing

Sets one or more tab stops for output from the ? and ?? commands.

Syntax

_tabs = <expC>

<expC>

The list of column numbers for tab stops. If you set more than one tab stop, the numbers must be in ascending order and separated by commas. Enclose the entire list in quotation marks. You can specify fractional numbers for <expC> to position output accurately with a proportional font.

Default

The default for _tabs is an empty string ("").

Description

Use _tabs to define a series of tab stops. If _wrap is true, dBASE ignores tab stops equal to or greater than _rmargin.

When you direct output to the printer, dBASE maps each character according to the coordinate plane, a two-dimensional grid. The coordinate plane is divided into character cells whose widths depend on the value of _ppitch. See the table in the description of _ppitch, which lists _ppitch values. The height of each character cell is determined by the size of the font. For more information about the coordinate plane, see Chapter 16 in the Programmer's Guide.

If you change the value of _tabs, dBASE takes the current value of _ppitch into consideration when calculating the cell width of the coordinate plane. This happens regardless of whether you are printing with proportional or monospaced fonts. If you issue ? without the STYLE option and use only integer coordinates, dBASE uses a monospaced font, and all output appears exactly the same as in dBASE IV.

If you send a tab character, CHR(9), with ? or ??, dBASE expands it to the amount of space required to reach the next tab stop. If the tab character you send is past the last tab stop, dBASE ignores it, displaying output starting in the current column.


_tabs Example

The following program makes two tab stops at columns 5 and 20 The array A is displayed beginning at the first tab stop, and its position in the array (i) is displayed at the second tab stop:

_tabs="5,20"   && tab stops at columns 5 and 20
DECLARE A[2]
A[1]="One"
A[2]="Two"
FOR i=1 to 2
  ? chr(9),A[i],chr(9),ltrim(str(i))
NEXT i
* chr(9) is equivalent to the tab key
* produces:
*     One            1
*     Two            2


Portability

Not supported in dBASE III PLUS. In dBASE IV, the value in_tabs also affects the Text Editor. This is not the case in dBASE for Windows; set tab settings for the Text Editor by setting the Auto Indent value in the Properties Inspector dialog box of the Text Editor window.


See Also

?

??

_indent

_lmargin

_rmargin

_wrap

CHR( )

MODIFY COMMAND


_wrap

See Also	Example	Portability	Printing

Determines if streaming output wraps between margins specified by _lmargin and _rmargin.

Syntax

_wrap = <expL>

<expL>

The logical expression true or false in the form .T. or .F., respectively.

Default

The default for _wrap is false (.F.), which disables wordwrapping.

Description

Set _wrap to .T. to wrap streaming output from commands such as ?, ??, and LIST within the margins you specify with _lmargin and _rmargin. For more information about streaming output, see Chapter 24 in the Programmer's Guide.

When you enable wordwrapping, dBASE wraps text onto the next line, breaking between words or numbers, when the output reaches the right margin. When you disable wordwrap mode, dBASE extends text beyond the right margin, moving to the next line only when a carriage return and linefeed combination (CR/LF) occurs in the text.

The value of _wrap must be .T. for _alignment, _indent, _lmargin, and _rmargin to have an effect.

When _wrap is .T., dBASE stores streaming output in a buffer until it finishes displaying or printing the current line. If you generate output with the ? command, follow it with another ? command to force the last line of text to print.


_wrap Example

This example shows a long string displayed with wrap on and with wrap off:

_lmargin=5
_rmargin=15
string="Now is the time for all men and women to come to."
_wrap=.f.
? string
_wrap=.t.
? string
* wrap false displays as:
* Now is the time for all men and women to come to.
* wrap true displays as:
*      Now is the
*      time for
*      all men and
*      women to
*      come to.


Portability

Not supported in dBASE III PLUS. In dBASE IV, the value in_wrap also affects the Text Editor. This is not the case in dBASE for Windows; set wrap on or off for the Text Editor by selecting or deselecting the Word Wrap checkbox in the Properties Inspector dialog box of the Text Editor window.


See Also

?

??

_alignment

_indent

_lmargin

_ploffset

_rmargin

PRINTJOB...ENDPRINTJOB


!

See Also	Example	Disk and File Utilities

Executes a single DOS command or program from within dBASE.

Syntax

! <DOS command>

<DOS command>

A command recognized by your DOS operating system.

Description

! and RUN are equivalent commands. See the description of RUN.


! Example

The following examples use ! or RUN to issue the DOS COPY command to copy Clients.DBF and Clients.MDX to a floppy diskette in an external drive:

! COPY C:\DBASEWIN\SAMPLES\Clients.DBF B:
RUN COPY C:\DBASEWIN\SAMPLES\Clients.MDX B:


See Also

DOS

RUN


&&

See Also	Example	Programs

Marks the characters to the right as a comment rather than as executable code.

Syntax

&& <comment>

<comment>

Any sequence of characters on the same line as and following &&. If the last character is a semicolon, dBASE recognizes the following line as a comment.

Description

Use the double ampersand (&&) to make a short comment to the right of a command line. You can use && for a single-line comment; however, programmers generally use the asterisk (*) or NOTE command for single-line comments.

Use comment lines in a program to document the function or logic of a series of commands. If you want to modify the program at a later date, comment lines can identify the sections to be changed.

You can use && after a semicolon that continues a statement to the next line, and you can put a semicolon at the end of a comment to make it continue on the next line. If dBASE finds a semicolon before && on a line, it assumes the next line is a continuation of the command statement. If it finds a semicolon after &&, it assumes the next line is a continuation of the comment.


&& Example

The following example uses && for adding notes to program files to enhance portability:

SET TALK OFF                && Suppresses mvar echoes
CLEAR                       && Clears results pane
SELECT 1                    && Selects work area 1
USE Contact ORDER CompCode  && .MDX tag order called
SELECT 2                    && Work area 2 active
USE Company ORDER CompCode
SET RELATION TO CompCode INTO A;
                            && Links work areas;
                            A and B (1 and 2);
                            See Alias in Essentials
SET FIELDS TO Company, State_Prov, A->Contact;
                            && Fields in current;
                            work area do not need;
                            alias names.
LIST TO PRINT OFF           && Off suppresses;
                            record numbers.
RETURN


See Also

*


*

See Also	Example	Programs

Marks an entire program line as a comment rather than an executable line.

Syntax

* <comment>

<comment>

A sequence of up to 1023 characters on the same line. If the last character is a semicolon, dBASE recognizes the following line as a comment.

Description

Use the asterisk (*) to make an entire program line a comment rather than an executable line. The * must be the first nonblank character on the line. When you execute the program, dBASE ignores the line.

Use comment lines in a program to provide useful notes concerning the function or logic of a series of commands. If you want to alter the program at a later date, comment lines can identify the sections to change. You can also use * in front of a command line to make it a comment temporarily when debugging a program.

To put a comment on the same line as a program statement, use &&.

The * and NOTE are identical in function.


* Example

The following example uses an * to add comments in program code:

** CLINTRPT.PRG **
USE Clients ORDER Client_ID
* Table ordered by Client_ID .MDX index Tag
SET FIELDS TO Company, Contact
* Creates a view comprised of just two fields
LIST OFF TO PRINT
* Directs output of the selected fields for the;
entire table to the printer.;
OFF suppresses the printing of Record numbers.
CLOSE DATABASES


See Also

&&


?

See Also	Example	Portability	Input/Output

Evaluates 0 or more expressions and displays or prints the result on a new line.

Syntax

?
[<exp 1>
[PICTURE <format expC>]
[FUNCTION <function expC>]
[AT <column expN>]
[STYLE [<fontstyle expN>] [<fontstyle expC>] ]
[,<exp 2>…]
[,]

<exp 1>[,<exp 2> ...]

An expression or expressions of any data type to evaluate.

PICTURE <format expC>

Formats <exp 1>, or a specified portion of it, with the picture template <format expC>, a character expression consisting of one of the following:

Template characters.

Function symbols preceded by @. (You can also use the FUNCTION option, discussed below.)

Literal characters.

A combination of template characters, function symbols, and literal characters.

A variable containing the character expression.

You can use all the template character and function symbols except A, M, R, and S. For more information about template characters, see Picture.

FUNCTION <function expC>

Formats all characters in <exp 1> with the function template <function expC>, which must contain one or more function symbols. When you specify function symbols with the FUNCTION option, you do not have to precede them with @. For more information about function symbols, see Function.

AT <column expN>

Specifies a character column, <column expN>, at which the ? command starts displaying or printing <exp 1>. The <column expN> argument must be between 0 and 255.

STYLE [<fontstyle expN>] [<fontstyle expC>]

Specifies an optional font or style option. Fonts (<fontstyle expN>) are specified in the [Fonts] section of DBASEWIN.INI, in a format like the following:

[Fonts]
1=Times New Roman,12,ROMAN
2=Courier New,10,MODERN

The first argument is the face name of the font; the second argument is the point size; and the third argument is the font family. You can define up to 32,766 font styles. (When assigning numbers greater than 999, do not use whole-number separators.)

If you want to add a font to DBASEWIN.INI but do not know its exact name or family, use GETFONT( ). Then add the information GETFONT( ) returns into DBASEWIN.INI.

The following table lists the codes you can use for <fontstyle expC>:

<fontstyle expC>	Result

"B"	Bold

"I"	Italic

"U"	Underline

"R"	Superscript

"L"	Subscript

,

The trailing comma is optional and has no effect; it is included for backward compatibility with dBASE IV.

Description

Use ? to display or print (to a file or a printer) the value of valid expressions of any type. Use it like DISPLAY (for example, to display the contents of the current record). In programs, use ? with no expression to skip a line in output.

The ? command differs from ?? only in that ? skips a line before displaying a value, while ?? does not.

If SET PRINTER is ON, output from the ? command prints either to the default printer or to the printer or file you have specified with SET PRINTER TO. If SET ALTERNATE is ON, dBASE stores output from the ? command to the file you have specified with SET ALTERNATE TO.

Use the STYLE option with ? or ?? to change the font styles of individual items.

To overstrike a line of text from a program file in printed output, use the AT option with _wrap set to false (.F.). To overwrite rather than overstrike text in printed output, use the AT option with _wrap set to true (.T.), which causes only the second line to print.

To override both an overall _alignment setting and individual paragraph alignments in a memo field, use the B, I, or J functions.

Issue SET SPACE ON (the default) to control whether dBASE inserts a space between expressions in the list when it displays or prints them.


? Example

This example uses ? and ?? to display a first and last name in various formats:

Firstname="Sally    "
Lastname ="Stephens "
? Firstname,Lastname
* simple display, no formatting or positioning
* Sally     Stephens

? Firstname PICTURE "@T"
?? " "
?? Lastname PICTURE "@!"
* trim Firstname, make lastname uppercase
* Sally STEPHENS

? Lastname STYLE "B"
?? Firstname AT 20
* display in fixed columns.
* Lastname will print in boldface
* Stephens            Sally

This example formats -3273.68 four different ways:

N=-3273.68
? N PICTURE "9,999,999.99" && insert commas
*    -3,273.68
? N PICTURE "9,999,999"    && no decimals
*    -3,274
? N PICTURE "@L 9,999,999" && zero fill
* -0003,274
? N PICTURE "@(BT"         && use () for negative;
                              numbers,;
                              left align;
                              and trim
* (3273.68)


Portability

The AT, PICTURE, FUNCTION, STYLE, and trailing comma options are not supported in dBASE III PLUS.


See Also

??

_alignment

_wrap

DISPLAY

GETFONT( )

LIST

PRINTJOB...ENDPRINTJOB

SET MEMOWIDTH

SET ALTERNATE

SET PRINTER

SET SPACE

TEXT


??

See Also	Example	Input/Output

Evaluates 0 or more expressions and displays or prints the result on the current line.

Syntax

??
[<exp 1>
[PICTURE <format expC>]
[FUNCTION <function expC>]
[AT <column expN>]
[STYLE [<fontstyle expN>] [<fontstyle expC>] ]
[,<exp 2>…]
[,]

Description

The ?? command is identical to the ? command, except it displays or prints on the current line rather than on a new line. See the ? command for a description of the options of both the ? and ?? commands.


?? Example

See the ? command, which also contains an example of ??.


See Also

?


???

See Also	Example	Portability	Printing

Sends output directly to the printer, bypassing the installed printer driver. This command is provided for compatibility with dBASE IV but is not recommended in dBASE for Windows.

Syntax

??? <expC>

<expC>

A character string to send to the printer.

Description

??? is used in the DOS environment to send printer control codes when the current printer driver does not support a particular printing capability. Printer codes instruct a printer to modify its printing style (italic, bold, and underlined) and page orientation (portrait or landscape).

If you do want to send printer codes with ??? in dBASE for Windows, test its behavior with the print driver you intend to use. ??? is supported only for very commonly used printers, such as the HP Laser Jet series, and might not be supported in your environment.

In dBASE for Windows, you can use ? with the STYLE option for font style, and the _porientation system memory variable for page orientation.


??? Example

The following examples present four alternative methods for sending Esc-E to a Hewlett_Packard Laserjet to reset the printer:

??? CHR(27)+"E" && function/ASCII code + letter
??? "{ESC}E"    && control character specifiers
??? "{27}{69}"  && ASCII only
??? "{27}E"     && ASCII and letters


Portability

Not supported in dBASE III PLUS.


See Also

?

_porientation

CLOSE...

SET DEVICE

SET PRINTER


@...CLEAR

See Also	Example	Portability	Input/Output

Clears a portion of the results pane of the Command window or the current dBASE IV window. This command is supported primarily for compatibility with dBASE IV. In dBASE for Windows, use DEFINE to create forms, which are used instead of dBASE IV windows.

Syntax

@ <row 1>,<column 1>
[CLEAR [TO <row 2>,<column 2>]]

<row 1>,<column 1>

The coordinates of the upper left corner of the rectangle or the left starting point of the line to clear. If you specify a number less than 0 for <row 1> or <column 1>, dBASE displays an error message.

CLEAR

Clears a rectangle from the upper left coordinates to the bottom right of the window if you do not specify TO <row 2>,<column 2> coordinates.

TO <row 2>,<column 2>

Clears a rectangle from the upper left coordinates to the lower right coordinates you specify for <row 2> and <column 2>. If you specify a number less than 0 for <row 2> or <column 2>, dBASE displays an error message.

Description

Use @...CLEAR to clear a line or a rectangle in the results pane of the Command window or the current dBASE IV window.

Command	Clears	To
@ <row 1>,<column 1>	Line	End of line <row 1>
@ <row 1>,<column 1> CLEAR	Rectangle	Bottom right corner of the window or form
@ <row 1>,<column 1> CLEAR TO <row 2>,<column 2>	Rectangle	<row 2>,<column 2>
You can use @...CLEAR with @...TO to clear rectangular areas and then display text in the cleared area. You can define a character to fill the rectangle you clear with CLEAR CHARACTER.


@...CLEAR Example

The following example fills a portion of the screen from 0,0 to 4,9 with numbers, then uses @...CLEAR to clear a rectangle from 1,1 to 3,3:

CLEAR
?? "0123456789"
? "0123456789"
? "0123456789"
? "0123456789"
? "0123456789"
* fills 0,0 to 4,9 with column number
*
* This writes to the first 10 columns of the
* first 5 rows i.e., 0,0 to 4,9
@ 1,1 CLEAR TO 3,3
* 0123456789
* 0   456789
* 0   456789
* 0   456789
* 0123456789


Portability

In dBASE III PLUS, @...CLEAR refers to the entire screen.


See Also

CLEAR

DEFINE


@...FILL

See Also	Example	Portability	Input/Output

Specifies the colors for a rectangular portion of the results pane of the Command window or the current dBASE IV window. This command is supported primarily for compatibility with dBASE IV. In dBASE for Windows, use DEFINE to create forms, which are used instead of dBASE IV windows.

Syntax

@ <row 1>,<column 1> FILL TO <row 2>,<column 2>
[COLOR <color>]

<row 1>,<column 1>

The coordinates of the upper left corner of the rectangle to color. If you specify a number less than 0 for<row 1> or <column 1>, dBASE displays an error message.

FILL TO <row 2>,<column 2>

Colors a rectangle from the upper left coordinates to the lower right coordinates you specify for <row 2> and <column 2>. If you specify a number less than 0 for<row 2> or <column 2>, dBASE displays an error message.

COLOR <color>

Specifies the color of the rectangle. For more information on colors, see SET COLOR TO.

Description

@...FILL starts coloring at row <row 1> and column <column 1> and stops coloring at row <row 2> and column <column 2>. If you do not include COLOR <color>, @...FILL works like @...CLEAR and clears the specified rectangle.

@...FILL specifies only one color setting, which applies to all window output in the specified rectangle. This color setting changes only the standard foreground and background colors and affects only the currently displayed window objects and text. Subsequent commands that write to this area use the default colors established with SET COLOR or SET COLOR OF, not the colors set with @...FILL.


@...FILL Example

This example saves the current colors. It resets the screen colors to red on white, writes to the screen, and then uses @ FILL to change the color of the word screen in rows 3, 4 and 5:

Oldcolors=SET("ATTRIBUTE")
SET COLOR TO R/W
CLEAR
? "Testing screen colors"
? "Testing screen colors"
? "Testing screen colors"
? "Testing screen colors"
? "Testing screen colors"
? "Testing screen colors"
@ 3,8 FILL TO 5,13 COLOR G/B
* The word 'screen' occupies cols 8 thru 13.
* It changes to green on blue in rows 3 thru 5
@ 10,0
WAIT "3,8 to 5,13 in green on blue. Press any key"
WAIT ;
  "Press any key to reset original screen colors"
SET COLOR TO &Oldcolors  && reset colors
CLEAR


Portability

In dBASE III PLUS, @...FILL refers to the entire screen.


See Also

DEFINE

DEFINE COLOR

SET COLOR OF

SET COLOR TO


@...SAY...GET

See Also	Example	Portability	Input/Output

Displays or accepts information in a specified format at a specified location in the results pane of the Command window or the current dBASE IV window. This command is supported primarily for compatibility with dBASE IV. In dBASE for Windows, use DEFINE with the Text and EntryField classes for displaying and accepting information on a form.

Syntax

@ <row>,<column>
[SAY <exp>
[PICTURE <picture expC>
[FUNCTION <function expC>]]
[COLOR <color>]]
[GET <field name> | <memvar name>
[PICTURE <picture expC>]
[FUNCTION <function expC>]
[DEFAULT <expC 1>]
[HELP <expC 2>]
[MESSAGE <expC list>]
[RANGE [REQUIRED]
[<low exp>][,[<high exp>]]
[VALID [REQUIRED] <condition expL>
[ERROR <error expC>]]
[WHEN <condition expL>]
[[OPEN] WINDOW <window name>]
[COLOR <color>]]

<row>, <column>

The coordinates of the beginning of the SAY...GET text in the results pane of the Command window or the current dBASE IV window. @ <row>,<column> without options clears line <row> from column <column> to the end of the line. If you specify a number less than 0 for <row> or <column>, dBASE displays an error message.

SAY <exp>

Displays the expression you specify for <exp>, beginning at the @ <row>,<column> coordinates. When displayed, <exp> cannot be edited. SAY <exp> must precede GET<field> or GET <memvar> if you use both the SAY and the GET option.

GET<field> | <memvar>

Displays the contents of the field you specify for <field> or the memory variable you specify for <memvar>. When displayed, GET text can be edited. SAY <exp> must precede GET<field> or GET <memvar> if you use both the SAY and the GET option.

PICTURE <picture expC>

Formats the SAY expression or the GET data (both the initial output display and the input) according to the picture format, or template, you specify for <picture expC>. Use picture template characters, function symbols, and literal characters for <picture expC>.

Each template character determines the format of a single character at its corresponding position in the SAY expression or GET data. Function symbols determine the format of the entire SAY expression or GET data. Precede function symbols with @ when you use them as part of the <picture expC> with PICTURE. If <picture expC> includes both template characters and function symbols, list function symbols first and separate them from template characters with a space. You can also specify function symbols with the FUNCTION clause.

See the Description section for tables of picture template characters and function symbols.

FUNCTION <function expC>

Formats the entire SAY expression or GET data according to the function symbol you specify for <function expC>. You do not need to precede function symbols with @ when you use them as <function expC> with FUNCTION.

See the Description section for tables of picture template characters and function symbols.

COLOR <color>

Sets the SAY expression or the GET data (both the initial display and the input) to the color combination you specify for <color>. If you use the COLOR option, it must be the last specified option for both the SAY expression and for the GET data. The <color> argument includes two settings: a foreground color and a background color. Separate each setting with a forward slash (/). For more information about color settings, see SET COLOR TO or SET COLOR OF.

DEFAULT <expC 1>

Displays <expC 1> as the initial value in the GET field when the @...GET is in an open format file and you issue APPEND or INSERT. If you have used SET CARRY to specify a default value for the field of the table you are editing through @...SAY...GET, the SET CARRY value overrides the value (<expC 1>) you specify with the DEFAULT option.

HELP <expC 2>

Executes a user-defined function (UDF), <expC 2>, when F1 is pressed while the cursor is in the GET field, as long as the UDF returns a character expression. If you specify a character expression for <expC 2> that is not a UDF name, dBASE ignores it.

MESSAGE <expC list>

Displays <expC list> in the Status bar when the results pane of the Command window or the current dBASE IV window is activated.

RANGE

Sets the upper and lower bounds for entries into a GET variable or field. If you also specify a VALID condition for <field> or <memvar>, dBASE evaluates the RANGE condition first.

REQUIRED

After RANGE, prevents dBASE from accepting a GET data entry if it does not fall within the specified RANGE.

<low exp>

After RANGE, the lower bound of the range for entries into a GET variable or field.

<high exp>

After RANGE, the upper bound of the range for entries into a GET variable or field. You can separate <high exp> from <low exp> with a comma or a space. If the decimal character you have set is a comma and <high exp> and <low exp> are numbers, use a space or put spaces on both sides of the comma.

VALID <condition expL>

Specifies a logical expression, <condition expL>, which must evaluate to true when new data is being entered in the GET field; otherwise, the cursor cannot exit the field. If you also specify a RANGE condition for <field> or <memvar>, dBASE evaluates it before evaluating the VALID condition.

REQUIRED

After VALID, causes dBASE to evaluate the current GET data, even if no change was made to it, and prevents dBASE from accepting current or user-entered data if it does not make <condition expL> true.

ERROR <error expC>

Displays <error expC> as an error message when <condition expL> evaluates to false.

WHEN <condition expL>

Specifies a logical expression, <condition expL>, which must evaluate to true before the cursor can move into a GET field.

OPEN

Before WINDOW, displays the memo text in <window name> when you issue READ.

WINDOW <window name>

Specifies an existing window, <window name>, in which to display memo field text when you GET a memo field and issue READ.

Description

@...SAY...GET displays the expression you specify for <exp> and the field or memory variable data you specify for <field> or <memvar>, starting at the coordinates you specify for <row> and <column> in the results pane of the Command window or the current dBASE IV window.

The Command Window

If you have dBASE IV applications that use @...SAY...GET to prompt the user for input and to receive that input, they will run in dBASE for Windows. By default, the @...SAY...GETs in unmodified dBASE IV applications appear in the results pane of the Command window. If you are modifying a dBASE IV application into a dBASE for Windows one or creating a new dBASE for Windows application, you should use DEFINE FORM, DEFINE TEXT, DEFINE ENTRYFIELD, and other DEFINE commands rather than @...SAY...GETs to create a form with text and entryfield objects that prompt for and receive user input. For more information, see DEFINE.

The Current dBASE IV Window

You can direct @...SAY...GETs to a dBASE IV window rather than the results pane of the Command window. You create a dBASE IV window with DEFINE WINDOW, and you open it with ACTIVATE WINDOW. Once you open a dBASE IV window, subsequent @...SAY...GETs appear in that window. To activate GET fields in a dBASE IV window, issue READ. (No dBASE for Windows UI objects appear in dBASE IV windows.)

You can also direct a series of @...SAY...GET lines in an existing format file (.FMT) to a dBASE IV window rather than the Command window. Format files are text files you can create with MODIFY COMMAND or another text editor. For more information about using format files, see the description of SET FORMAT.

Use SET FORMAT TO to open a format file. Once you activate a dBASE IV window, the @...SAY...GETs in the open format file appear in that window. To activate GET fields from a format file that appear in a dBASE IV window, issue APPEND, BROWSE [FORMAT], CHANGE, EDIT, INSERT, or READ.

The Coordinate Plane and Relative Addressing

The row and column (<row>, <column>) coordinates are points on the coordinate plane of the window, the dimensions of which are determined by the window's default font (size and type). The average character width of the font is the coordinate plane's column width, and the character-line height of the font is the coordinate plane's row height.

When positioning @...SAY...GETs, you can specify a row and column relative to a previous display, as in the following procedure. This type of positioning is called relative addressing.

*SHUTDOWN.PRG
PARAMETERS lightsoff, lockson, alarmon
@ 1,3 SAY "Be sure  to do the following"
@ 2,3 SAY "things before leaving for the night:"
IF .NOT. lightsoff
@ 4,5 SAY "Turn off all unnecessary lights"
ENDIF
IF .NOT. lockson
@ ROW() + 1,COL() SAY "Lock all doors"
ENDIF

IF .NOT. alarmon
@ ROW() + 1,COL() SAY "Activate the alarm system"
ENDIF
@ ROW() + 2,10 SAY "Good night"
RETURN

GET data

GET displays a value and records its location in an internal list, so the data can be edited when you activate it, such as with READ. Because GET displays data for editing, it requires a memory variable or field name as its argument. GET does not accept constants as arguments.

If you specify GET data, the user can choose to skip some entry fields. If the user never edits an entry field for which you have specified a VALID condition, dBASE never evaluates the field to determine if it meets the VALID condition unless you also specify REQUIRED for that field.

The PICTURE Option

Use the PICTURE option for the SAY expression or the GET data (or for both) to format their display. The following table describes the action of each picture template character:

Template character	Result
A	Restricts entry to alphabetic characters.
N	Restricts entry to letters, numbers, and the underscore (_).
X	Allows any character.
L	Restricts entry to the single letter T, F, Y, or N, and converts lowercase entries to uppercase.
Y	Restricts entry to the single letter Y or N, and converts lowercase entries to uppercase.
9	Restricts entry of character data to numbers and entry of numeric data to numbers and + and - signs.
#	Restricts entry to numbers, spaces, periods, and + and - signs.
!	Converts letters to uppercase.
$	Inserts the symbol set by SET CURRENCY in place of leading spaces.
*	Inserts asterisks in place of leading spaces.
.	Marks the position of the decimal point.
,	Displays a whole-number separator (comma or period).
A picture template character determines the format of the character at the corresponding position in the SAY expression or GET data. For example, the template character ! makes the character at that position uppercase, while the template character X makes the character unchanged at that position. A function symbol, on the other hand, formats the entire SAY expression or GET data. In the case of GET data, the PICTURE option both formats any initial display and restricts input to the specified format.

When you use a non-template character in a PICTURE clause, dBASE displays that character at the position indicated. Such a character (a placeholder) in a GET PICTURE clause causes the cursor to skip that position when the user enters or edits data, thereby preventing the character from being edited.

If the PICTURE clause you specify does not match the format of the expression, field, or memory variable you specify, dBASE in some cases ignores the clause but in other cases displays what you specified for <picture expC> itself and does not enable editing of the non-matching GET field or memory variable.

The FUNCTION Option

Use the FUNCTION option for the SAY expression or the GET data (or for both) to format their entire displays rather than individual characters. The following table describes the action of each function symbol:

Function Symbol	Result
A	Restricts entry to alphabetic characters
B	Left-aligns display
C	Displays CR (for "credit") after a positive number
D	Displays and accepts entry of a date in the current SET DATE format
E	Displays and accepts entry of a date in European (DD/MM/YY) format
I	Centers display
J	Right-aligns display
L	Displays numbers with leading zeros
M	Displays the multiple choice option you list after M when the Enter key is pressed
R	Causes place holders (described below) not to be stored
S<expN>	Displays the left <expN> columns of a variable in a SAY field; scrolls an entry in a GET field that is <expN> columns wide
T	Removes leading and trailing spaces
X	Displays DB (for "debit") after a negative number
Z	Displays 0 as a blank
(	Encloses negative numbers in parentheses
!	Converts letters to uppercase
^	Displays numbers in exponential form
$	Inserts the symbol set by SET CURRENCY in place of leading blanks
If you use function symbols that are irrelevant to the data type displayed, dBASE ignores them. You can use more than one function symbol in a clause. For example, FUNCTION "A!" restricts entry to alphabetic characters and converts the alphabetic characters to uppercase. The function symbol combination "CX" displays CR after a positive value and DB after a negative value. As in the case of single function symbol clauses, dBASE ignores irrelevant symbols. FUNCTION "A!Z" has the same effect on character data as FUNCTION "A!" does.

You can also combine function symbols with template characters in a PICTURE clause. The function symbols must appear at the beginning of the clause, and one space must separate them from the template characters.

The REQUIRED Option

When you specify REQUIRED for either a RANGE or a VALID condition (or both), dBASE evaluates all GET fields or memory variables for which you have specified REQUIRED. If the required range or valid conditions are not met, dBASE does not let you save any changes, even to other fields for which REQUIRED is not specified, and does not let you leave the window. The only way to exit the window as long as the required conditions are not met is to abandon all changes.

The WINDOW Option

WINDOW <window name> has an effect only when the GET field represents a memo field. When you press F9 to start the Text Editor and edit the memo field, the Text Editor opens in the predefined window <window name>.

OPEN WINDOW <window name> causes the contents of the memo field to display immediately in the predefined window <window name> when the GET field displays, without the user having to press F9 .


@...SAY...GET Example

This example uses @...SAY...GET to create a data entry form for personnel information. It uses the PICTURE, COLOR, VALID ERROR and MESSAGE options to enhance the screen and validate the data. Relative row addressing ROW( ), COL( ) and absolute addressing are used to place the SAYs and GETS on the screen. Finally a READ is issued to inititate the user's data entry:

Firstname=space(10)
Lastname =space(20)
Address  =space(25)
CLEAR  && clear the screen
@ 0,0 SAY "PERSONNEL INFORMATION";
  COLOR W+/G
* displays a heading in intensified white on a
* green background

@ 5,10 SAY "First name "
@ ROW(),COL();
  GET Firstname;
  PICTURE "!XXXXXXXXX";
  MESSAGE "Enter your first name"
* ROW(),COL() means at the current cursor position.
* GETs the first name. Converts the first letter
* to upper case. When the cursor is in this field,
* the message "Enter your first name" is shown in
* the status bar
@ 7,10 SAY "Last name  ";
  GET Lastname;
  VALID REQUIRED (.NOT. empty(Lastname));
  ERROR "You must enter a last name"
* Lastname is a required field.
* If lastname is all spaces then empty(Lastname)
* is true and the VALID clause returns false.
* Then the error window shows the message
* "You must enter a last name"
@ ROW()+2,10 SAY "Address    ";
  GET Address ;
  PICTURE "@!"
* ROW()+2 means two rows below the current row
* i.e. 7+2 = row 9
* PICTURE "@!" converts all characters to
* upper case

The SAYs and GETs are all displayed on the screen. READ initiates the data entry:

READ

See the ? command for other examples of PICTURE statements


Portability

The FUNCTION, DEFAULT, HELP, MESSAGE, VALID, WHEN, OPEN WINDOW, and COLOR options are not supported in dBASE III PLUS.

In dBASE III PLUS, in which windows do not occur, @...SAY...GETs just occur on the screen. In dBASE IV, @...SAY...GETs can appear on the screen outside of windows.

dBASE IV rounds up (or down) fractions used in @...SAY statements. dBASE for Windows does not round these fractions.


See Also

ACTIVATE WINDOW

APPEND

BROWSE

CHANGE

CLEAR

DEFINE

DEFINE WINDOW

EDIT

FUNCTION

INSERT

READ

SET COLOR TO

SET CUAENTER

SET DEVICE

SET FORMAT

UPDATED( )

VARREAD( )


@...SCROLL

See Also	Example	Portability	Input/Output

Shifts the contents of a specified region of the results pane of the Command window or the current dBASE IV-style window left, right, up, or down. This command is supported primarily for compatibility with dBASE IV. In dBASE for Windows, forms have scroll bars the user can use to scroll through a form.

Syntax

@ <row1>,<column1> TO <row2>,<column2> SCROLL
[UP | DOWN | LEFT | RIGHT]
[BY <expN>]
[WRAP]

<row1>,<column1>

The coordinates of the upper left corner of the rectangle to scroll. If you specify a number less than 0 for <row 1> or <column 1>, dBASE displays an error message.

TO <row2>,<column2> SCROLL

Specifies the coordinates of the lower right corner of the rectangle to scroll. If you specify a number less than 0 for <row 2> or <column 2>, dBASE displays an error message.

UP | DOWN | LEFT | RIGHT

Specifies the direction the rectangle of contents scrolls:

Up (the default direction) the specified number of rows

Down the specified number of rows

Left the specified number of columns

Right the specified number of columns

BY <expN>

Specifies the number (<expN>) of rows or columns the text scrolls in the specified direction. The number you specify for <expN> can range from -32,767 to +32,767. Specifying a negative number reverses the direction of scrolling. For example, SCROLL LEFT BY -3 and SCROLL RIGHT BY 3 scroll the region in the same direction. If <expN> is 0, the region does not scroll. The default value is 1.

WRAP

Wraps text within the region to be scrolled to the opposite side of the region. Without WRAP, text in the region scrolls out of view. For example, without WRAP, SCROLL LEFT BY 2 shifts two columns of characters off the left edge of the region and leaves two blank columns on the right edge. With WRAP, SCROLL LEFT BY 2 WRAP scrolls the two columns off the left edge of the region and makes them reappear on (wrap around to) the right edge.

Description

@...SCROLL repositions text in a specified region of the results pane of the Command window or the current dBASE IV-style window. If you issue @...SCROLL without any options, the region scrolls by default up 1 row without wrapping.

If you use some combination of @...CLEAR, @...TO, and @...FILL to define a rectangle in the results pane of the Command window or the current dBASE IV-style window, you can use @...SCROLL to move the contents of the rectangle around.


@...SCROLL Example

The following example fills the screen with numbers and then uses @ SCROLL to move two parts of the screen:

CLEAR
FOR i=0 TO 79
  FOR j=0 to 24
    IF MOD(i+j,10)<>0  && space instead of 0
      @ j,i say right(str(i+j),1)
    ENDIF
  NEXT j
NEXT i
@ 5,5 TO 20,20 SCROLL RIGHT BY 3
* A clear area is shown on the screen
*   3 cols wide where characters were moved

@ 5,40 TO 10,60 SCROLL DOWN BY 4 WRAP
* Wrap moves the data from the bottom
*   back to the top of the scroll area


Portability

In dBASE III PLUS, @...SCROLL refers to the entire screen.


See Also

@...CLEAR

@...FILL

@...TO

DEFINE


@...TO

See Also	Example	Portability	Input/Output

Draws a box in the results pane of the Command window or the current dBASE IV window. This command is supported primarily for compatibility with dBASE IV. In dBASE for Windows, use DEFINE to create forms, which are used instead of dBASE IV windows.

Syntax

@ <row 1>,<column 1> TO <row 2>,<column 2>
[DOUBLE | PANEL | <border definition list>]
[COLOR <color>]

<row 1>,<column 1>

The coordinates of the upper left corner of the box to draw. If you specify a number less than 0 for <row 1> or <column 1>, dBASE displays an error message.

TO <row 2>,<column 2>

The coordinates of the lower right corner of the box to draw. If you specify a number less than 0 for <row 2> or <column 2>, dBASE displays an error message.

DOUBLE

The default border is established with SET BORDER.

PANEL

Makes the border solid, one character high and one character wide, relative to the font.

<border definition list>

A list of characters that make up the border. For more information about setting border definitions, see SET BORDER.

COLOR <color>

Specifies the color of the border. For more information about colors, see SET COLOR TO.

Description

Use @...TO to draw a box in the results pane of the Command window or the current dBASE IV window. Use @...CLEAR to clear the inside of the box. If <row 1> equals <row 2>, dBASE draws a horizontal line from <column 1> to <column 2>. If <column 1> equals <column 2>, dBASE draws a vertical line from <row 1> to <row 2>. The border you define with SET BORDER is the default border when you do not include a border argument with @...TO.


@...TO Example

The following example shows three @...TO commands:

@ 5,5 TO 10,10          && single border
@ 5,20 TO 20,25 DOUBLE  && double border
@ 5,40 TO 15,55 PANEL   && panel border


Portability

The PANEL, COLOR, and <border definition list> options are not supported in dBASE III PLUS. In dBASE III PLUS, @...TO refers to the entire screen.


See Also

@...CLEAR

DEFINE

SET BORDER

SET COLOR TO


ABS( )

See Also	Example	Numeric Data

Returns the absolute value of a specified number.

Syntax

ABS(<expN>)

<expN>

The numeric or float data type number whose absolute value to return.

Description

ABS( ) returns the absolute value of a numeric or float data type number. ABS( ) returns a numeric or float data type according to the data type of the number you supply. The absolute value of a number represents its magnitude. Magnitude is always expressed as a positive value, so the absolute value of a negative number is its positive equivalent.


ABS( ) Example

The following example uses ABS( ) to take the positive value of a number whatever its sign:

? abs(0.2)     && 0.2
? abs( -5)     && 5
? abs(0.2)<1   && true because .2 is less than 1
? abs( -5)<1   && false because 5 is greater than 1


See Also

CEILING( )

FLOOR( )

INT( )

ROUND( )


ACCEPT

See Also	Example	Input/Output

Accepts a user-entered character string and stores it to a memory variable. This command is supported primarily for compatibility with dBASE IV. In dBASE for Windows, use DEFINE with the Text and EntryField classes for displaying and accepting information on a form.

Syntax

ACCEPT [<prompt expC>] TO <memvar>

<prompt expC>

A character expression that prompts the user for input.

TO <memvar>

Assigns the user input to the memory variable you specify for <memvar>. If <memvar> does not exist, dBASE creates it. If <memvar> does exist, ACCEPT overwrites it.

Description

Use ACCEPT primarily in program files to prompt the user for character-type keyboard input. The user terminates data entry by pressing Enter. If the user presses Enter without typing any characters, ACCEPT assigns an empty string (" ") to <memvar>.

Since ACCEPT automatically assigns character type to keyboard entries, the user does not need to enclose input in quotation marks or square brackets. If the user does surround the entry with delimiters, such as quotation marks, the delimiters are stored as part of the string.

If SET ESCAPE is ON, pressing Esc in response to an ACCEPT terminates a program.

Other commands that let programs read data from the keyboard are INPUT and WAIT.


ACCEPT Example

This example uses ACCEPT as part of a program that asks if the user wants to return to the menu. If the answer begins with Y then the user must confirm by answering Yes to a second question:

ACCEPT;
  "Would you like to return to Windows? ";
  to Answer
IF UPPER(Answer)="Y"
* test if first letter of Answer is Y
  ACCEPT;
    "Enter YES to return to Windows? ";
    to Answer1
  IF UPPER(Answer1)="YES"
    QUIT  && Exit dBASE
  ENDIF
ENDIF


See Also

INPUT

SET ESCAPE

WAIT


ACOPY( )

See Also	Example	Portability	Memory Variables

Copies elements from one declared array to another and returns the number of elements copied.

Syntax

ACOPY(<source array name>, <target array name>
[, <starting element expN> [, <elements expN> [, <target element expN>]]])

<source array name>

The name of the declared array from which to copy elements.

<target array name>

The name of the declared array that elements from <source array name> are copied to.

<starting element expN>

The position of the element in <source array name> from which ACOPY( ) starts copying. Without <starting element expN>, ACOPY( ) copies all the elements in <source array name> to <target array name>.

<elements expN>

The number of elements in <source array name> to copy. Without <elements expN>, ACOPY( ) copies all the elements in <source array name> from <starting element expN> to the end of the array. If you want to specify a value for <elements expN>, you must also specify a value for <starting element expN>.

<target element expN>

The position in <target array name> to which ACOPY( ) starts copying. Without <target element expN>, ACOPY( ) copies elements to <target array name> starting at the first position. If you want to specify a value for <target element expN>, you must also specify values for <starting element expN> and <elements expN>.

Description

ACOPY( ) copies elements from a source array to a target array without regard to the current data types of target positions. If the data type of an element in the source array is different from the data type of the associated element in the target array, ACOPY( ) overwrites the target value and data type with the source value and data type.

If the target array is not big enough to contain all the elements being copied from the source array, dBASE displays an error message and does not copy any elements.


ACOPY( ) Example

The following example uses ACOPY( ) to create a second array, Ato from the first array, Afrom. The later portion of the example, consisting of a counting loop and the DISPLAY (?) command, sends the results to the Command window results pane for confirmation:

PUBLIC Afrom, Ato, Copied
SET TALK OFF
DECLARE Afrom[4],Ato[4]
Afrom[1] = 1
Afrom[2] = "Two"
Afrom[3] = .t.
Afrom[4] = 4
Cnt=1
Copied=ACOPY(Afrom,Ato)
DO WHILE Cnt<=4
  ? Ato[Cnt]
Cnt=Cnt+1
ENDDO
? "Elements Copied ",Copied
SET TALK ON


Portability

Not supported in dBASE IV or dBASE III PLUS.


See Also

AFIELDS( )

ALEN( )

APPEND FROM ARRAY

COPY TO ARRAY

DECLARE

REPLACE FROM ARRAY


ACOS( )

See Also	Example	Portability	Numeric Data

Returns the inverse cosine (arccosine) of a number.

Syntax

ACOS(<expN>)

<expN>

The cosine of an angle, from -1 to +1.

Description

ACOS( ) returns the radian value of the angle whose cosine is <expN>. ACOS( ) returns a float from 0 to pi radians. ACOS( ) returns zero when <expN> is 1. For values of x from 0 to pi, ACOS(Y) returns x if COS(X) returns y.

To convert the returned radian value to degrees, use RTOD( ). For example, if the default number of decimal places is 2, ACOS(.5) returns 1.05 radians while RTOD(ACOS(.5)) returns 60.00 degrees.

Use SET DECIMALS to set the number of decimal places ACOS( ) displays.

To find the arcsecant of a value, use 1 divided by the arccosine of the value. For example, the arcsecant of pi is ACOS(1/PI( )), or 1.25 radians.


ACOS( ) Example

The following example uses ACOS( ) to find the arc cosine of a set of cosine values:

? ACOS(-1)       &&        3.14
? ACOS( 0)       &&        1.57
? ACOS( 1)       &&        0.00
? RTOD(ACOS(-1)) &&      180.00
? RTOD(ACOS( 0)) &&       90.00
? RTOD(ACOS( 1)) &&        0.00

RTOD( ) converts radians to degrees.


Portability

Not supported in dBASE III PLUS.


See Also

ASIN( )

ATAN( )

ATN2( )

COS( )

DTOR( )

RTOD( )

SET DECIMALS


ACTIVATE MENU

See Also	Example	Portability	dBASE IV Menus

Displays and enables a defined dBASE IV menu bar. This command is supported primarily for compatibility with dBASE IV. In dBASE for Windows, use DEFINE, OPEN FORM, and READMODAL( ) to create and activate menus associated with forms.

Syntax

ACTIVATE MENU <menu name>
[PAD <pad name>]
[RETRACTED]

PAD <pad name>

Identifies the pad that is highlighted by default when the menu is activated. Without PAD <pad name>, the first pad defined with DEFINE PAD is highlighted.

RETRACTED

Causes a pop-up menu associated with a pad to be displayed only when the user presses Enter or clicks on a highlighted pad. Without RETRACTED, the pop-up menu is displayed as soon as the associated pad is highlighted.

Description

ACTIVATE MENU is the last step in creating a dBASE IV menu bar. Once the menu is active, pressing Right Arrow or Left Arrow moves the highlight from pad to pad. The user can also highlight a pad by clicking on it.


ACTIVATE MENU Example

The following example creates a query utility for a library. The first menu contains Non-Fiction and Fiction prompts. Choosing the Non-Fiction prompt displays another menu with more specific Non-Fiction choices. The program uses the same pop-up with both menus to allow the user to exit or quit. The first menu is activated with ACTIVATE MENU. The second menu is activated with ACTIVATE MENU from within a procedure specified by ON SELECTION PAD.

DEFINE POPUP Science FROM 5,3
DEFINE BAR 1 OF Science PROMPT "Geology"
DEFINE BAR 2 OF Science PROMPT "Biology"
DEFINE BAR 3 OF Science PROMPT "Mathematics"

DEFINE POPUP History FROM  5,30
DEFINE BAR 1 OF History PROMPT "European"
DEFINE BAR 2 OF History PROMPT "Far Eastern"
DEFINE BAR 3 OF History PROMPT "United States"

DEFINE POPUP Exit FROM 5,58
DEFINE BAR 1 OF Exit PROMPT "Quit to Opening Menu"
DEFINE BAR 2 OF Exit PROMPT "Exit to DOS"

DEFINE MENU Nonfmenu
DEFINE PAD Science OF Nonfmenu AT 2,3 ;
   PROMPT "Science"
DEFINE PAD History OF Nonfmenu AT 2,30 ;
   PROMPT "History"
DEFINE PAD Exit OF Nonfmenu AT 2,58 ;
   PROMPT "Exit"
ON PAD Science OF Nonfmenu ACTIVATE POPUP Science
ON PAD History OF Nonfmenu ACTIVATE POPUP History
ON PAD Exit OF Nonfmenu ACTIVATE POPUP Exit

ON SELECTION POPUP Science DO Sciprog
ON SELECTION POPUP History DO Hisprog
ON SELECTION POPUP Exit DO Exprog

DEFINE POPUP Fiction FROM 5,30
DEFINE BAR 1 OF Fiction PROMPT "Adult"
DEFINE BAR 2 OF Fiction PROMPT "Juvenile"

DEFINE MENU Opening
DEFINE PAD Nonfict OF Opening AT 2,3 ;
   PROMPT "Non-fiction"
DEFINE PAD Fiction OF Opening AT 2,30 ;
   PROMPT "Fiction"
DEFINE PAD Exit OF Opening AT 2,58 ;
   PROMPT "Exit"

ON SELECTION PAD Nonfict OF Opening ;
   DO Nonf
ON PAD Fiction OF Opening ACTIVATE POPUP Fiction
ON PAD Exit OF Opening ACTIVATE POPUP Exit

CLEAR
ACTIVATE MENU Opening RETRACTED

PROCEDURE Nonf
CLEAR
ACTIVATE MENU Nonfmenu RETRACTED

PROCEDURE ExProg
DEACTIVATE MENU
CLEAR ALL
RETURN


Portability

Not supported in dBASE III PLUS. The RETRACTED option is not supported in dBASE IV.


See Also

DEACTIVATE MENU

DEFINE

DEFINE MENU

OPEN FORM

READMODAL( )

RELEASE MENUS


ACTIVATE POPUP

See Also	Example	Portability	dBASE IV Menus

Displays and enables a dBASE IV pop-up menu. This command is supported primarily for compatibility with dBASE IV. In dBASE for Windows, use DEFINE, OPEN FORM, and READMODAL( ) to create and activate menus associated with forms.

Syntax

ACTIVATE POPUP <pop-up name>

Description

ACTIVATE POPUP is the last step in creating a dBASE IV pop-up menu. After you create a pop-up menu, you display and enable it with the ACTIVATE POPUP command. ACTIVATE POPUP can be called independently or from a pad in a dBASE IV menu bar.


ACTIVATE POPUP Example

The following example demonstrates that to use ACTIVATE POPUP you must first define a popup menu with DEFINE POPUP plus define what happens when a pop-up bar is selected with ON SELECTION POPUP or ON MOUSE. The example displays Names from the Animals table in a popup, then goes to the selected record in the table:

CLEAR
SET TALK OFF
USE ANIMALS ORDER Name
DEFINE POPUP LocAnim FROM 2,4;
    PROMPT FIELD Name COLOR R+/RB/GB
ON SELECTION POPUP LocAnim DEACTIVATE POPUP
ACTIVATE POPUP LocAnim
STORE PROMPT() to mName
SEEK mName
EDIT
CLOSE ALL
CLEAR ALL
RETURN


Portability

Not supported in dBASE III PLUS.


See Also

DEACTIVATE POPUP

DEFINE

OPEN FORM

READMODAL( )


ACTIVATE SCREEN

See Also	Example	Portability	Input/Output

Sends output to the results pane of the Command window rather than to the current dBASE IV window. This command is supported primarily for compatibility with dBASE IV. In dBASE for Windows, use DEFINE, OPEN FORM, and READMODAL( ) to create and activate forms.

Syntax

ACTIVATE SCREEN

Description

Use ACTIVATE SCREEN to direct output to the results pane of the Command window rather than to the current dBASE IV window. For example, after you issue ACTIVATE SCREEN, any @...SAY...GET coordinates are displayed relative to the results pane of the Command window. Output to the results pane of the Command window appends to the existing results pane of the Command window's contents, causing older contents to scroll up.

To reactivate dBASE IV windows after issuing ACTIVATE SCREEN, issue ACTIVATE WINDOW.


ACTIVATE SCREEN Example

This example uses ACTIVATE SCREEN to switch between the current window, Win1 and the results pane of the Command window. It displays information about COMPANY.DBF in Win1 and lists information in the results pane of the Command window:

DEFINE WINDOW Win1 FROM 3,30 TO 12,70
USE COMPANY
ACTIVATE WINDOW Win1
x=inkey(5)
@ 0,0 SAY "Working on database "+DBF()
@ 2,0 SAY "In work area "+STR(WORKAREA())
ACTIVATE SCREEN SAVE
LIST NEXT 20 FIELDS Company
ACTIVATE WINDOW Win1
x=inkey(5)
@ 4,0 SAY "Back in Win1 Window"
WAIT
DEACTIVATE WINDOW Win1


Portability

Not supported in dBASE III PLUS.


See Also

DEFINE

OPEN FORM

READMODAL( )


ACTIVATE WINDOW

See Also	Example	Portability	dBASE IV Windows

Opens dBASE IV-style windows and directs subsequent screen input and output to the last window opened. This command is supported primarily for compatibility with dBASE IV. In dBASE for Windows, use DEFINE, OPEN FORM, and READMODAL( ) to create and activate forms.

Syntax

ACTIVATE WINDOW <window name 1> [, <window name 2> ...] | ALL

<window name 1> [, <window name 2>]...

Specifies which windows are opened with ACTIVATE WINDOW.

ALL

Causes all windows with definitions resident in memory to be opened.

Description

ACTIVATE WINDOW opens a window and allows input and output through dBASE IV commands such as @...SAY...GET.

Before using ACTIVATE WINDOW, you need to place one or more window definitions in memory with DEFINE WINDOW or RESTORE WINDOW. Once a window is closed with DEACTIVATE WINDOW, its definition still resides in memory, and the window can be presented and enabled again with ACTIVATE WINDOW.

The dBASE IV window displays in the results pane of the Command window. If necessary, use SET DISPLAY to make the results pane of the Command window correspond to the specified DOS display mode.

There are important differences between ACTIVATE WINDOW (which opens dBASE IV windows) and a related command, OPEN FORM (which opens forms). Forms are usually preferred over dBASE IV-style windows, since only forms can display and enable Windows objects such as pushbuttons, check boxes, and entry fields. In contrast, dBASE IV windows can contain only dBASE IV-style menus and dBASE IV input and output commands such as @...SAY or @...GET.


ACTIVATE WINDOW Example

The following example uses ACTIVATE WINDOW A, B, C to bring three tiled windows to the Command window results pane. The most recently called window will be the active window. In this case, C displays on top of windows A and B. To make A the active window, issue ACTIVATE WINDOW A; window A displays on top of windows B and C, and subsequent screen input and output occurs in Window A:

CLEAR
DEFINE WINDOW A FROM 1,1 TO 15,40 DOUBLE
DEFINE WINDOW B FROM 5,5 TO 18,50 DOUBLE
DEFINE WINDOW C FROM 10,10 TO 23,70 DOUBLE
ACTIVATE WINDOW A,B,C
WAIT "Window C is now the active window."
DEACTIVATE WINDOW C
ACTIVATE WINDOW A
WAIT "Window A is now the active window."
DEACTIVATE WINDOW A
ACTIVATE WINDOW B
WAIT "Window B now active"
CLEAR WINDOWS

The following example uses ACTIVATE WINDOW to display a series of inset windows:

SET TALK OFF
CLEAR
STORE 2  TO toprow
STORE 2  TO leftcol
STORE 23 TO botrow
STORE 73 TO rightcol
i=1
DO WHILE i <=5
STORE "WIN" + LTRIM(STR(i)) TO winname
DEFINE WINDOW &Winname FROM toprow,leftcol ;
TO botrow,rightcol PANEL
toprow   = toprow   + 2
leftcol  = leftcol  + 2
botrow   = botrow   - 2
rightcol = rightcol - 2
  i=i+1
ENDDO
ACTIVATE WINDOW WIN1,WIN2,WIN3,WIN4,WIN5
WAIT "         ***** FLASH - Press any key *****"
CLEAR WINDOW
SET TALK ON


Portability

Not supported in dBASE III PLUS.


See Also

DEACTIVATE WINDOW

DEFINE

DEFINE WINDOW

OPEN FORM

READMODAL( )

RESTORE WINDOW

SET DISPLAY


ADEL( )

See Also	Example	Portability	Memory Variables

Deletes an element from a one-dimensional array, or deletes a row or column of elements from a two-dimensional array. Returns 1 if successful, an error if unsuccessful.

Syntax

ADEL(<array name>, <position expN> [, <row/column expN>])

<array name>

The name of the declared one- or two-dimensional array from which to delete data.

<position expN>

When <array name> is a one-dimensional array, <position expN> specifies the number of the element to delete.

When <array name> is a two-dimensional array, <position expN> specifies the number of the row or column whose elements you want to delete. The third argument (discussed in the next paragraph) specifies whether <position expN> is a row or a column.

<row/column expN>

Either 1 or 2. If you omit this argument or specify 1, a row is deleted from a two-dimensional array. If you specify 2, a column is deleted. dBASE returns an error if you use <row/column expN> with a one-dimensional array.

Description

Use ADEL( ) to delete selected elements from an array without changing the size of the array. ADEL( ) does the following:

Deletes an element from a one-dimensional array, or deletes a row or column from a two-dimensional array

Moves all remaining elements toward the beginning of the array (up if a row is deleted, to the left if an element or column is deleted)

Inserts .F. values in the last position(s)

For information about deleting elements by inserting .F. values and moving remaining elements toward the end of the array, see AINS( ). For information about replacing elements without moving remaining elements at all, see AFILL( ). To change the size of an array, use AGROW( ) or ARESIZE( ).

One-dimensional arrays

When you issue ADEL( ) for a one-dimensional array, the element in the specified position is deleted, and the remaining elements move one position toward the beginning of the array. The logical value .F. is stored to the element in the last position.

For example, if you define a one-dimensional array with DECLARE aArray[3] and STORE "A," "B," and "C" to the array, the array has one row and can be illustrated as follows:

A	B	C
Issuing ADEL(aArray, 2) deletes element number 2, whose value is "B," moves the value in aArray[3] to aArray[2], and stores .F. to aArray[3] so that the array now contains these values:

A	C	.F.
Two-dimensional arrays

When you issue ADEL( ) for a two-dimensional array, the elements in the specified row or column are deleted, and the elements in the remaining rows or columns move one position toward the beginning of the array. The logical value .F. is stored to the elements in the last row or column.

For example, suppose you define a two-dimensional array with DECLARE aArray[3,4] and store letters to the array. The following illustration shows how the array is changed by ADEL(aArray, 2, 2).

Figure: Using ADEL( ) with a two-dimensional array

	ADEL(aARRAY,2,2)
1	Original array created as: DECLARE aArray[3,4] STORE "A" TO aArray[1,1] STORE "B" TO aArray[1,2]       STORE "L" TO aArray[3,4]	2	ADEL(aArray,2,2) deletes the elements in the second column...
Initial contents of the array aArray

3	Shifts the elements in the remaining columns towards the beginning of the array...	4	And inserts logical .F. values as elements in the last column, resulting in this array:
		Contents of the array after issuing ADEL(aArray,2,2)


ADEL( ) Example

The following example uses ADEL( ) and AGROW( ) to dynamically add and delete to an array which is being edited with @ GET commands:

DECLARE aTest[3]
AFILL(aTest, space(10))
@0,10 SAY "  ALT-A = Add Element ;
  ALT-D = Delete Element"
ON KEY LABEL ALT-A GrowArray()
ON KEY LABEL ALT-D DelArray()
DO WHILE READKEY() <> 12 .and. aTest.size > 0
   @1,1 CLEAR TO aTest.size, 30
   FOR i = 1 to aTest.size
      @i, 1 SAY i GET aTest[i]
   NEXT
   READ
ENDDO
ON KEY LABEL ALT-A
ON KEY LABEL ALT-D
RETURN

FUNCTION DelArray
   ADEL(aTest, aTest.size)
   KEYBOARD CHR(3)
   RETURN .T.

FUNCTION GrowArray
   AGROW(aTest, 1)
   aTest[aTest.size] = SPACE(10)
   KEYBOARD CHR(3)
   RETURN .T.


Portability

Not supported in dBASE IV or dBASE III PLUS.


See Also

AFILL( )

AGROW( )

AINS( )

ARESIZE( )

DECLARE


ADIR( )

See Also	Example	Portability	Memory Variables

Stores to a declared array five characteristics of specified files: name, size, date stamp, time stamp, and DOS attribute(s). Returns the number of files whose characteristics are stored.

Syntax

ADIR(<array name>
[, <filename skeleton expC> [, <DOS file attribute list expC>]])

<array name>

The name of the declared array of one or more dimensions to which to store the file information. ADIR( ) dynamically sizes <array name> so the number of rows in the array is equal to the number of files that match <DOS file attribute expC>, and the number of columns is five.

<filename skeleton expC>

The file-name pattern (using wildcards) describing the files whose information to store to <array name>.

<DOS file attribute list expC>

The letter or letters D, H, S, and/or V representing one or more DOS file attributes.

If you want to specify a value for <DOS file attribute expC>, you must also specify a value or "*.*" for <filename skeleton expC>.

The meaning of each attribute is as follows:

Character	Meaning
D	Directories
H	Hidden files
S	System files
V	Volume label
If you supply more than one letter for <DOS file attribute expC>, include all the letters between one set of quotation marks, for example, ADIR(aArray, "*.PRG", "HS").

Description

Use ADIR( ) to store information about files to a declared array, which is dynamically resized so all returned information fits in the array.

Without <filename skeleton expC>, ADIR( ) stores information about all files in the current directory that are neither hidden nor system files. For example, if you want to return information only on tables, use "*.DBF" as <filename skeleton expC>.

If you want to include directories, hidden files, or system files in the array, use <DOS file attribute expC>. When D, H, or S is included in <DOS file attribute expC>, all directories, hidden files, and/or system files (respectively) that match <filename skeleton expC> are added to the array.

When V is included in <DOS file attribute expC>, ADIR( ) ignores <filename skeleton expC> as well as other characters in the attribute list, and stores the volume label to a one-element array.

ADIR( ) stores the following information for each file into one row of the array. The data type for each is shown in parentheses:

Column 1	Column 2	Column 3	Column 4	Column 5
File name (character)	Size (numeric)	Date (date)	Time (character)	DOS attribute(s)  (character)

The last column (DOS attribute) can contain one or more of the following DOS attributes:

Attribute	Meaning
R	Read-only file
A	Archive file (modified since it was last backed up)
S	System file
H	Hidden file
D	Directory
For example, a file with none of the attributes would have the following string in column 5:

.....

A read-only, hidden file would have the following string in column 5:

R..H.


ADIR( ) Example

The following example uses ADIR( ) to store the file name, file size, date of update and time of update for all .DBF files on the current directory to the array Dir_Arr. The counting DO WHILE loop displays the results to the Command window results pane:

DECLARE Dir_Arr[1]
Num_Files=ADIR(Dir_Arr,"*.DBF")
Cnt=1
DO WHILE Cnt<=Num_Files
  ? Dir_Arr[Cnt,1], Dir_Arr[Cnt,2] AT 20,;
    Dir_Arr[Cnt,3] AT 35, Dir_Arr[Cnt,4] AT 45,;
    Dir_Arr[Cnt,5] AT 55
    Cnt=Cnt+1
ENDDO
RETURN


Portability

Not supported in dBASE IV or dBASE III PLUS.


See Also

ACOPY( )

AFIELDS( )

ASORT( )

CD

DIR

DECLARE

FDATE( )

FSIZE( )

FTIME( )


AELEMENT( )

See Also	Example	Portability	Memory Variables

Returns the number of a specified element in a one- or two-dimensional array.

Syntax

AELEMENT(<array name>, <subscript1 expN>
[, <subscript2 expN>])

<array name>

A declared one- or two-dimensional array.

<subscript1 expN>

The first subscript of the element. In a one-dimensional array, this is the same as the element number. In a two-dimensional array, this is the row.

<subscript2 expN>

When <array name> is a two-dimensional array, <subscript2 expN> specifies the second subscript, or column, of the element.

If <array name> is a two-dimensional array and you do not specify a value for <subscript2 expN>, dBASE assumes the value 1. dBASE returns an error if you use <subscript2 expN> with a one-dimensional array.

Description

Use AELEMENT( ) when you know the subscripts of an element in a two-dimensional array and need the element number for use with another function, such as ACOPY( ) or ASCAN( ).

In one-dimensional arrays, the number of an element is the same as its subscript, so there is no need to use AELEMENT( ). That is, AELEMENT(aOneArray,3) returns 3, AELEMENT(aOneArray,5) returns 5, and so on.

AELEMENT( ) is the inverse of ASUBSCRIPT( ), which returns an element's row or column subscript number when you specify the element number.


AELEMENT( ) Example

The first section of this example initializes a one-dimensional array and a two-dimensional array:

DECLARE aTeacher[4]
DECLARE aStudent[3,4]
DISPLAY MEMORY

Values held in memory are initialized to logical type and contain the value .F. Note the ordering sequence of the subscripts for the two-dimensional array ASTUDENT:

*ATEACHER
*           [   1]    L .F.
*           [   2]    L .F.
*           [   3]    L .F.
*           [   4]    L .F.
*ASTUDENT
*      [   1,   1]    L .F.
*      [   1,   2]    L .F.
*      [   1,   3]    L .F.
*      [   1,   4]    L .F.
*      [   2,   1]    L .F.
*      [   2,   2]    L .F.
*      [   2,   3]    L .F.
*      [   2,   4]    L .F.
*      [   3,   1]    L .F.
*      [   3,   2]    L .F.
*      [   3,   3]    L .F.
*      [   3,   4]    L .F.

The following statements use AELEMENT( ) to return the number of the element specified by subscripts:

? AELEMENT(aTeacher, 3)            && Returns  3
? AELEMENT(aStudent, 1,  2)        && Returns  2
? AELEMENT(aStudent, 2,  2)        && Returns  6
? AELEMENT(aStudent, 3,  4)        && Returns 12
? AELEMENT(aStudent, 3)            && Returns  9


Portability

Not supported in dBASE IV or dBASE III PLUS.


See Also

ACOPY( )

ADEL( )

AFIELDS( )

AINS( )

ALEN( )

ASCAN( )

ASORT( )

ASUBSCRIPT( )

DECLARE


AFIELDS( )

See Also	Example	Portability	Memory Variables

Stores the current table's structural information to a declared array and returns the number of fields whose characteristics are stored.

Syntax

AFIELDS(<array name>)

<array name>

The name of a declared array of one or more dimensions.

Description

Use AFIELDS( ) to store information about the current table structure in a declared array. You can then reference the elements in the array to return information such as a field name and type for use with other functions or for producing reports. Each row in the array contains information on a single field in the current table.

AFIELDS( ) dynamically sizes <array name> so the number of rows in the array is at least equal to the number of fields in the current table, and the number of columns is at least four. If you declared an array of greater size than required, the rows may not equal the number of fields and the number of columns do not necessarily equal four.

The following table shows which field characteristics AFIELDS( ) stores, and in which column the information is placed:

Column 1	Column 2	Column 3	Column 4
Field name (character data type)	Field type (character data type)	Field length (numeric data type)	Decimal places (numeric data type)
dBASE uses the following codes for field types: BdBASE or Paradox binary field (BLOB), Ccharacter, Ddate, GOLE (general), Llogical, Mmemo, Nnumeric, Ffloat.

AFIELDS( ) stores the same information into an array that COPY TO...STRUCTURE EXTENDED stores into a table, except AFIELDS( ) does not create a row containing FIELD_IDX information.


AFIELDS( ) Example

The following example uses AFIELDS( ) to initialize the array Stru_Arr to the structure of the Company table. The resulting two-dimensional array has four columns containing field name, field type, field length and decimal places and as many rows as the table has fields. The subsequent DO WHILE loop displays the first column only, thus listing the field names of the current table:

USE COMPANY
DECLARE Stru_Arr[1]
Num_Fields=AFIELDS(Stru_Arr)
Cnt1=1
DO WHILE Cnt1<=Num_Fields
    ? Stru_Arr[Cnt1,1]
    Cnt1=Cnt1+1
ENDDO
RETURN


Portability

Not supported in dBASE IV or dBASE III PLUS.


See Also

COPY TO ARRAY

COPY TO...STRUCTURE EXTENDED

DECLARE

FDATE( )

FSIZE( )

FTIME( )


AFILL( )

See Also	Example	Portability	Memory Variables

Inserts a specified value into one or more locations in a declared array, and returns the number of elements inserted.

Syntax

AFILL(<array name>, <exp>
[, <start expN> [, <count expN>]])

<array name>

The name of a declared one- or two-dimensional array to fill with the specified value <exp>.

<exp>

An expression of character, date, logical, numeric, or float data type to insert in the specified array.

<start expN>

The element number at which to begin inserting <exp>. If you do not specify <start expN>, dBASE begins at the first element in the array.

<count expN>

The number of elements in which to insert <exp>, starting at element <start expN>. If you do not specify <count expN>, dBASE inserts <exp> from <start expN> to the last element in the array. If you want to specify a value for <count expN>, you must also specify a value for <start expN>.

If you do not specify <start expN> or <count expN>, dBASE fills all elements in the array with <exp>.

Description

Use AFILL( ) to insert a value into all or some elements of a declared array. For example, if you are going to use elements of an array to calculate totals, you can use AFILL( ) to initialize all values in the array to 0.

AFILL( ) inserts values into the array sequentially. Starting at the first element in the array or at <start expN>, AFILL( ) inserts values in each element in a row, then moves to the first element in the next row, continuing to insert values until the array is filled or until it has inserted <count expN> elements. AFILL( ) overwrites any existing data in the array.

If you know an element's subscripts, you can use AELEMENT( ) to determine its element number for use as <start expN>.


AFILL( ) Example

The following example uses AFILL( ) to replace the current YTD_Sales value held in the 10th column of array Com_Arr. ASCAN( ) returns the element number for the desired Company name which is used by AFILL( ) as a reference point:

SET TALK OFF
CLEAR
USE Company
Lookup="InterSafe"
Sales=143325552.20
Cnt=RECCOUNT()
Flds=FLDCOUNT()
DECLARE Com_Arr[Cnt,Flds]
COPY TO ARRAY Com_Arr
Element=ASCAN(Com_Arr,Lookup)
IF Element>0
  Rplc=AFILL(Com_Arr,Sales,Element+9,1)
ENDIF
Count=1
DO WHILE Count<=Cnt
  ? Com_Arr[Count,1], Com_Arr[Count,10]
  Count=Count+1
ENDDO


Portability

Not supported in dBASE IV or dBASE III PLUS.


See Also

ADEL( )

AELEMENT( )

AINS( )

DECLARE


AGROW( )

See Also	Example	Portability	Memory Variables

Adds an element, row, or column to an array and returns a numeric value representing the number of added elements.

Syntax

AGROW (<array name>, <expN>)

<array name>

The name of a declared one- or two-dimensional array you want to add elements to.

< expN>

Either 1 or 2. When you specify 1, AGROW( ) adds a single element to a one-dimensional array or a row to a two-dimensional array. When you specify 2, AGROW( ) adds a column to the array.

Description

Use AGROW( ) to insert an element, row, or column into an array and change the size of the array to reflect the added elements. AGROW( ) can make a one-dimensional array two-dimensional. All added elements are initialized to .F. values.

To insert .F. values without changing the size of the array, use AINS( ).

One-dimensional arrays

When you specify 1 for <expN>, AGROW( ) adds a single element to the array. When you specify 2, AGROW( ) makes the array two-dimensional, and existing elements are moved into the first column. This is shown in the following figure:

Figure: Using AGROW( ) to make a one-dimensional array two-dimensional

	AGROW(bARRAY,2)
1	Original array created as: DECLARE bArray[4] STORE "A" TO bArray[1] STORE "B" TO bArray[2] STORE "C" TO bArray[3] STORE "D" TO bArray[4]	2	AGROW(bArray,2) adds a new column to the array, makes it a two-dimensional array with dimensions [4,2], and copies the old values into the first column.
	Initial contents of the array bArray		Contents of the array after issuing AGROW(bArray,2)
Two-dimensional arrays

When you specify 1 for <expN>, AGROW( ) adds a row to the array and adds the row at the end of the array. This is shown in the following figure:

Figure: Using AGROW( ) to add a row to a two-dimensional array

	AGROW(aARRAY,1)
1	Original array created as: DECLARE aArray[3,4] STORE "A" TO aArray[1,1] STORE "B" TO aArray[1,2]       STORE "L" TO aArray[3,4]	2	AGROW(aArray,1) adds a new row to the array.
	Initial contents of the array aArray		Contents of the array after issuing AGROW(aArray,1)
When you specify 2 for <expN>, AGROW( ) adds a column to the array and places .F. into each element in the column.


AGROW( ) Example

The following example initially declares an array of three elements, and then uses AGROW( ) to add a fourth element, a second column and finally, to add a row to the two dimensional array. DISPLAY MEMORY is used to show the values in the array after each AGROW( ) operation:

RELEASE ALL
DECLARE A[3]
A[1]="x"
A[2]="y"
A[3]="z"
DISPLAY MEMORY
N=AGROW(A,1)      && adds an element to A
DISPLAY MEMORY
N=AGROW(A,2)      && adds a column to A
DISPLAY MEMORY
N=AGROW(A,1)      && adds a new row to A
DISPLAY MEMORY


Portability

Not supported in dBASE IV or dBASE III PLUS.


See Also

AINS( )

ALEN( )

ARESIZE( )

DECLARE


AINS( )

See Also	Example	Portability	Memory Variables

Inserts an element with the value .F. into a one-dimensional array, or inserts a row or column of elements with the value .F. into a two-dimensional array. Returns 1 if successful, an error if unsuccessful.

Syntax

AINS(<array name>, <position expN> [, <row/column expN>])

<array name>

The name of a declared one- or two-dimensional array in which to insert data.

<position expN>

When <array name> is a one-dimensional array, <position expN> specifies the number of the element in which to insert an .F. value.

When <array name> is a two-dimensional array, <position expN> specifies the number of a row or column in which to insert .F. values. The third argument (discussed in the next paragraph) specifies whether <position expN> is a row or a column.

<row/column expN>

Either 1 or 2. If you omit this argument or specify 1, a row is inserted into a two-dimensional array. If you specify 2, a column is inserted. dBASE returns an error if you use <row/column expN> with a one-dimensional array.

Description

Use AINS( ) to insert .F. values into selected elements in an array without changing the size of the array. AINS( ) does the following:

Inserts an element in a one-dimensional array, or inserts a row or column in a two-dimensional array

Moves all remaining elements toward the end of the array (down if a row is inserted, to the right if an element or column is inserted)

Inserts .F. values in the newly created position(s)

For information about inserting elements by moving remaining elements toward the beginning of the array and inserting .F. values at the end of the array, see ADEL( ). For information about replacing elements without moving remaining elements at all, see AFILL( ). To change a one-dimensional array to two-dimensional, use AGROW( ) or ARESIZE( ).

One-dimensional arrays

When you issue AINS( ) for a one-dimensional array, the logical value .F. is inserted into the position of the specified element. The remaining element(s) are moved one place toward the end of the array. The element that had been in the last position is deleted.

For example, if you define a one-dimensional array with DECLARE aArray[3] and STORE "A," "B," and "C" to the array, the array has one row and can be illustrated as follows:

A	B	C
Issuing AINS(aArray, 2) inserts aArray[2] with the value .F., moves aArray[2], whose value is "B," to aArray[3], and deletes "C" in aArray[3] so that the array now contains these values:

A	.F.	B
Two-dimensional arrays

When you issue AINS( ) for a two-dimensional array, a logical value .F. is inserted into the position of each element in the specified row or column. The elements in the remaining columns or rows are moved one place toward the end of the array. The elements that had been in the last row or column are deleted.

For example, suppose you define a two-dimensional array with DECLARE aArr[3,4] and store letters to the array. The following figure shows how the array is changed by issuing AINS(aArray, 2,2):

Figure: Using AINS( ) with a two-dimensional array

	AINS(aARRAY,2,2)
1	Original array created as: DECLARE aArray[3,4] STORE "A" TO aArray[1,1] STORE "B" TO aArray[1,2]       STORE "L" TO aArray[3,4]	2	AINS(aArray,2,2) inserts logical .F. values as elements in the second column...
Initial contents of the array aArray

3	Shifts the elements in the remaining columns towards the end of the array, and deletes the elements from the last column.	4	Resulting in this array:
		Contents of the array after issuing AINS(aArray,2,2)


AINS( ) Example

The following example uses a two-dimensional array created as follows:

PUBLIC aAlpha
DECLARE aAlpha[2,3]
STORE "one" TO aAlpha[1,1]
STORE "two" TO aAlpha[1,2]
STORE "three" TO aAlpha[1,3]
STORE "four" TO aAlpha[2,1]
STORE "five" TO aAlpha[2,2]
STORE "six" TO aAlpha[2,3]

The array aAlpha now contains the following:

*aAlpha
*  [1,1]    C    "one"
*  [1,2]    C    "two"
*  [1,3]    C    "three"
*  [2,1]    C    "four"
*  [2,2]    C    "five"
*  [2,3]    C    "six"

AINS( ) is now used to change the first column to .F. and move the remaining elements toward the end of the array:

? AINS(aAlpha,1,2)  && Returns 1 if successful

aAlpha now contains the following:

*aAlpha
*  [1,1]    C    .F.
*  [1,2]    C    "one"
*  [1,3]    C    "two"
*  [2,1]    C    .F.
*  [2,2]    C    "four"
*  [2,3]    C    "five"


Portability

Not supported in dBASE IV or dBASE III PLUS.


See Also

ADEL( )

AFILL( )

AGROW( )

ARESIZE( )

DECLARE


ALEN( )

See Also	Example	Portability	Memory Variables

Returns the number of elements, rows, or columns of an array.

Syntax

ALEN(<array name> [, <expN>])

<array name>

The name of a declared one- or two-dimensional array.

<expN>

The number 0, 1, or 2, indicating which array information to return: elements, rows, or columns. dBASE returns an error if you specify <expN> for an array that contains more than two dimensions.

The following table describes what ALEN( ) returns for different <expN> values:

If <expN> is...	ALEN( ) Returns...
not supplied	Number of elements in the array
0	Number of elements in the array
1	For a one-dimensional array, the number of elements; For a two-dimensional array, the number of rows (the first subscript of the array)
2	For a one-dimensional array, 0 (zero); For a two-dimensional array, the number of columns (the second subscript of the array)
any other value	0 (zero)
Description

Use ALEN( ) to determine the dimensions of a declared array--either the number of elements it contains, or the number of rows or columns it contains.

If you need to determine both the number of rows and the number of columns a two-dimensional array contains, issue ALEN( ) twice, once with a value of 1 for < expN> and once with a value of 2 for <expN>. For example, issue the following to determine the number of rows and columns contained in aArray:

? ALEN(aArray,1) && returns number of rows
? ALEN(aArray,2) && returns number of columns


ALEN( ) Example

The following example uses ALEN( ) in a FOR...NEXT loop to print out the contents of an array:

USE Clients
DECLARE acContact[RECCOUNT(),1]
COPY TO ARRAY acContact
USE
ShowArray(acContact)
RETURN

FUNCTION ShowArray
PARAMETER avArray
FOR i = 1 to ALEN(avArray)
  ? avArray[i]
NEXT
RETURN .T.


Portability

Not supported in dBASE IV or dBASE III PLUS.


See Also

ADEL( )

AELEMENT( )

AFIELDS( )

AGROW( )

AINS( )

ARESIZE( )

ASCAN( )

ASUBSCRIPT( )

DECLARE


ALIAS( )

See Also	Example	Portability	Table Basics

Returns the alias name of the current or a specified work area. If no table is open in a work area, ALIAS( ) returns an empty string ("").

Syntax

ALIAS( [<alias>] )

<alias>

The work area you want to return the alias name of. You can enter a work area number (1 through 225), letter (A through J), or work area name. The work area name can be a table name or an alias name specified with the USE command. The work area letter or alias name must be enclosed in quotes.

Description

ALIAS( ) returns the alias name of any work area within the current session (if Sessions is checked in the Desktop Properties dialog box). If you do not specify a work area, the current work area is assumed. If no table is opened in the specified work area, ALIAS( ) returns an empty string ("").


ALIAS( ) Example

The following example uses ALIAS( ) to return the name (or alias) of the table currently in use in work area 20:

USE Clients ALIAS Customers IN 20
? ALIAS(20)            && Returns CUSTOMERS
? ALIAS("Customers")   && Returns CUSTOMERS
SELECT 20
? ALIAS()              && Returns CUSTOMERS
CLOSE DATABASES


Portability

Not supported in dBASE III PLUS.


See Also

DBF( )

SELECT( )

USE

WORKAREA( )


ANSI( )

See Also	Example	Portability	String Data

Returns a character string that is the American National Standards Institute (ANSI) value of a specified Original Equipment Manufacturer (OEM) character expression.

Syntax

ANSI(<expC>)

<expC>

The OEM character expression to convert to ANSI characters.

Description

Use ANSI( ) and OEM( ) to convert characters between an ANSI character set and an OEM character set. ANSI( ) accepts an OEM character expression and converts its characters to ones in the current ANSI character set, while OEM( ) accepts an ANSI character expression and converts its characters to ones in the current OEM character set. For more information on character sets, see Appendix C in the Programmer's Guide.

dBASE uses an OEM character set, while other Windows applications use an ANSI character set. OEM character sets match the ANSI set for most alphabetic and numeric characters but usually differ for high-order characters, those with ASCII values from 128 to 255. You might need to use ANSI( ) before sending a character string from dBASE to another Windows application, for example, if you are using the EXTERN command.

If you need to export a string with different ANSI and OEM values, use ANSI( ). Similarly, if you receive a string from a Windows application, use OEM( ) to convert it into the format used by dBASE.

The following example shows how you can determine if two characters have the same or different ANSI and OEM values.


ANSI( ) Example

The following example displays the 255 characters that are possible with ASCII, ANSI, and OEM formats:

FOR i=1 to 255
  ASCII=CHR(i)
  ? i,ASCII,ANSI(ASCII),OEM(ASCII)
  * The next 3 commands cause a pause
  * every 10 lines
  IF MOD(i,10)=0
    WAIT
  ENDIF
NEXT i


Portability

Not supported in dBASE IV or dBASE III PLUS.


See Also

CHR( )

EXTERN

OEM( )


APPEND

See Also	Example	Fields and Records

Adds new records to a table.

Syntax

APPEND
[BLANK]
[NOWAIT]

BLANK

Adds a blank record to the end of the table and makes the blank record the current record.

NOWAIT

Invokes the form to edit a new record but does not move focus there. If used in a program, execution continues to statement following the APPEND NOWAIT command.

Description

APPEND displays the Table Records window in Form layout. Through this window, you can navigate, view, and edit existing records as well as to add new records. For more information on editing data and navigating in forms, see Using Forms or the User's Guide.

If you use SET FORMAT to select a format file, APPEND displays record entries as directed by the format file. If no format is specified, dBASE for Windows displays a default form. The default form displays a single record at a time, with each field displayed left to right.

The APPEND BLANK command adds a blank record to the current table and positions the record pointer on the new record, but it does not display a window to edit the data. When accessing SQL tables, some database servers do not allow you to enter blank records.Also, constraints on tables created with non-null fields prevent entering records with fields left blank. For more information, refer to the Borland SQL Link documention for your particular database server.

Entering data into an appended record and then moving the record pointer past the end of the record causes APPEND to add another record (but not APPEND BLANK). Each new appended record is displayed with blank fields if SET CARRY is OFF. If SET CARRY is ON, each new appended record contains a copy of the data that is in the previous record.

The APPEND command includes only the fields specified in a SET FIELDS TO command, if one is used. If dBASE tables are linked with the SET RELATION command, the CONSTRAIN and INTEGRITY options control operations that add new records to child and parent tables. For more information, see the SET RELATION command.

APPEND automatically updates any open index files while you append records. APPEND displays records in a table with a master index in indexed order and adds the new record to the end of the table.


APPEND Example

The following example uses APPEND BLANK to add a blank record at the end of the natural order table:

USE Clients
? RECCOUNT()     && Returns number of;
                    records in table
APPEND BLANK
? RECCOUNT()     && Returns previous;
                    number plus 1
EDIT             && Opens new record;
                    for data entry

The next example uses APPEND to add a blank record at the end of the current table and open the editing window without having to use the EDIT command, as in the previous example:

USE Clients
APPEND


See Also

APPEND AUTOMEM

APPEND FROM

BROWSE

CLASS BROWSE

EDIT

SET CARRY

SET FORMAT

SET RELATION

SET WINDOW OF MEMO


APPEND AUTOMEM

See Also	Example	Portability	Fields and Records

Adds a new record to a table using the values stored in automem variables.

Syntax

APPEND AUTOMEM

Description

APPEND AUTOMEM adds a new record to a table and then replaces the value of fields in the table with the contents of corresponding automem variables. Automem variables are variables that have the same names and data types as the fields in the current table.

While the APPEND command presents a display for adding records to a table interactively, APPEND AUTOMEM provides control over data entry in a program. You can customize the editing display and validate data before adding it to a table. APPEND AUTOMEM is also a more efficient way to add new records to a table than using APPEND BLANK and REPLACE.

To use APPEND AUTOMEM to add records to a table, first create a set of automem variables. The USE...AUTOMEM command opens a table and creates the corresponding empty automem variables for that table. CLEAR AUTOMEM creates a set of empty automem variables for the current table or reinitializes existing automem variables to empty values.

When specifying automem variables in commands that allow them (for example, the @...SAY...GET command), you need to prefix the name of an automem variable with m-> to distinguish the variable from fields that may have the same name. For example, @ 0,0 GET Price displays the value in the current record's Price field while @ 0,0 GET
m->Price displays the value of the automem variable named Price.


APPEND AUTOMEM Example

The following example uses APPEND AUTOMEM to add a new record to the Clients table, replacing the the value of fields in the table with values held in automem variables. In this case, the new record will be blank because CLEAR AUTOMEM is issued just prior to APPEND AUTOMEM:

SET TALK OFF
STORE " " TO Answer
USE Clients
? RECCOUNT()
DO WHILE UPPER(Answer) <> "Q"
   CLEAR AUTOMEM
   APPEND AUTOMEM
   ACCEPT "Press Q to Quit, Enter to Continue ";
   to Answer
   ? RECCOUNT()
ENDDO


Portability

Not supported in dBASE IV or dBASE III PLUS.


See Also

APPEND

CLEAR AUTOMEM

INSERT AUTOMEM

REPLACE AUTOMEM

STORE AUTOMEM

USE


APPEND FROM

See Also	Example	Table Basics

Copies records from an existing table to the end of the current table.

Syntax

APPEND FROM <filename> | ? | <filename skeleton>
[FOR <condition>]
[[TYPE] SDF | PARADOX | DBASE |
DELIMITED [WITH
<char> | BLANK] ]
[NOVERIFY]
[POSITION]
[REINDEX]

<filename> | ? | <filename skeleton>

The name of the table whose records you want to append to the current table. APPEND FROM ? and APPEND FROM <filename skeleton> display a dialog box, from which you can select a file. If you specify a file without including its path, dBASE for Windows first looks for the file in the current directory, then in the path you specify with SET PATH. If you specify a file without including its extension, dBASE for Windows assumes the default table type specifed with the SET DBTYPE command.

You can also append records from a table in a database (defined using the IDAPI Configuration Utility) by specifying the database as a prefix (enclosed in colons) to the name of the table, that is, :database name:table name. If the database is not already open, dBASE for Windows displays a dialog box in which you specify the parameters, such as a login name and password, necessary to establish a connection to that database.

FOR <condition>

Restricts APPEND FROM to records in <filename> that meet <condition>. You can specify a FOR <condition> only for fields that exist in the current table.

[TYPE] SDF | PARADOX | DBASE |
DELIMITED [WITH <char> | BLANK]

Specifies the format of data you are appending. The TYPE keyword is included for readability only; it has no effect on the operation of the command. The following table provides a description of the different file formats that are supported:

Type	Description

SDF	A System Data Format file. Records in an SDF file are fixed-length, and the end of a record is marked with a carriage return and a linefeed. In the table receiving SDF data, unused portions of fields are padded with spaces. If you do not specify an extension, dBASE for Windows assumes .TXT.

PARADOX	A Paradox table (with a .DB extension). Paradox rows are copied to dBASE records, and each Paradox column is copied to a dBASE field.

DBASE	A dBASE table. If you do not include an extension for <filename>, dBASE for Windows assumes a .DBF extension.

DELIMITED 	A text format file. Data in the following formats will be translated by dBASE for Windows into the current table as follows:

Data delimited with quotation marks or the character you specify with WITH <char> is appended to character fields.

Data in YYYYMMDD format is appended to date fields.

Data consisting solely of the character T or F is appended to logical fields.

Numbers are appended to numeric fields.
Each carriage return and linefeed indicates a new record.

WITH <char>

Indicates that <filename> character data is delimited with the character <char> instead of with quotation marks.

WITH BLANK

Indicates that <filename> data is separated with spaces instead of commas or any other delimiters. If you specify DELIMITED without including WITH BLANK, dBASE for Windows assumes that data items in <filename> are separated with commas.

NOVERIFY

Disables data validation during APPEND FROM of SDF type files to speed up processing. If you use NOVERIFY, the source data is copied as is into the target fields. Without data validation, dBASE for Windows does not check or convert source data to fit the data type of target fields.

POSITION

Appends fields based on their relative position in the table instead of by matching field names.

REINDEX

Rebuilds all open index files after APPEND FROM finishes executing. Without REINDEX, dBASE updates all open indexes after appending each record from <filename>. When the current table has multiple open indexes or contains many records, APPEND FROM executes faster with the REINDEX option.

Description

Use the APPEND FROM command to add data from another file or table to the end of the current table. You can append data from dBASE tables or files in other formats. Data is appended to the current table in the order in which it is stored in the file you specify.

When you specify a dBASE table as the source of data, only the contents of fields whose names and types are the same as the current table are appended. However, dBASE for Windows does append date data to a character field with the same name, and appends character data in date format to a date field with the same name.

If the fields common to the current and source tables do not have the same widths, dBASE for Windows does one of the following:

If the field of the current table is longer than the matching source data, dBASE for Windows pads the data with spaces.

If the field of the current table is shorter than the matching field of the source table, dBASE for Windows truncates the data.

If SET DELETED is OFF, dBASE adds records from a source dBASE table that are marked for deletion and does not mark them for deletion in the current table. If SET DELETED is ON, dBASE does not add records from a source dBASE table that are marked for deletion.

When importing data from other files, remove column headings and leading blank rows and columns; otherwise, this data is also appended.


APPEND FROM Example

The following example uses APPEND FROM to add records to an empty table from an SDF formatted text (.TXT) file:

USE Contact ORDER CompCode IN SELECT()
USE Company IN SELECT()
SELECT COMPANY
SET RELATION TO CompCode INTO Contact
COPY STRUCTURE TO CntctLst;
  FIELDS Company->Company, ;
  Contact->CompCode, Contact->Contact, ;
  Company->Street1, Company->Street2, ;
  Company->City, Company->State_Prov,;
  Company->Zip_P_Code
COPY TO CntctLst.TXT TYPE SDF;
  FIELDS Company->Company, ;
  Contact->CompCode, Contact->Contact, ;
  Company->Street1, Company->Street2, ;
  Company->City, Company->State_Prov,;
  Company->Zip_P_Code
CLOSE ALL
USE CntctLst
APPEND FROM CntctLst.TXT TYPE SDF
CLOSE ALL

The following example uses APPEND FROM to add records to Clients table from a text file delimited with " (MAILLIST.TXT fields are in the same order as Clients):

USE Clients
COPY TO MailList.TXT TYPE DELIMITED
APPEND FROM MailList.TXT TYPE DELIMITED


See Also

APPEND

APPEND AUTOMEM

COPY

IMPORT

REINDEX

SET DELETED


APPEND FROM ARRAY

See Also	Example	Fields and Records

Adds to the current table one or more records containing data stored in a specified array.

Syntax

APPEND FROM ARRAY <array name>
[FIELDS <field list>]
[FOR <condition>]
[REINDEX]

<array name>

The array containing the data to store in the current table as records.

FIELDS <field list>

Appends <array name> data only to the fields in <field list>. Without FIELDS <field list>, APPEND FROM ARRAY appends to each field an element from the specified row of <array name>, in the order that the data is stored in the array.

FOR <condition>

Restricts APPEND FROM ARRAY to array rows in <array name> that meet <condition>. The FOR <condition> statement can reference a field; dBASE for Windows recognizes which array element corresponds to which field and evaluates whether to append a given array row as if the array element were the named field.

REINDEX

Rebuilds open indexes after all records have been changed.

Description

APPEND FROM ARRAY treats one- and two-dimensional arrays as tables, with columns corresponding to fields and rows corresponding to records. A one-dimensional array works as a table with only one row; therefore, you can append only one record from a one-dimensional array. A two-dimensional array works as a table with multiple rows; therefore, you can append as many records from a two-dimensional array as it has rows. With arrays of more than two dimensions, the last dimension subscript indicates the number of fields to which to add an array row, and the next-to-last dimension subscript indicates the number of records to append. Array subscripts previous to the last two are ignored.

When you append data from an array to the current table, dBASE for Windows appends each array row as a single record. If the table has more fields than the array has columns, the excess fields are left empty. If the array has more columns than the table has fields, the excess columns are disregarded. The data in the first column is added to the first field's contents, the data in the second column to the second field's contents, and so on.

The data types of the array must match those of corresponding fields in the table you are appending. If the data type of an array element and a corresponding field do not match, dBASE for Windows returns an error.

If the current table has a memo field, dBASE for Windows ignores this field. For example, if the second field is a memo field, dBASE for Windows adds the data in the array's first column to the first field's contents, and the data in the array's second column to the third field's contents.

Use APPEND FROM ARRAY as an alternative to automem variables when you need to transfer data between tables where the structures are similar but the field names are different.


APPEND FROM ARRAY Example

The following example copies selected fields from the Company table to an array, and uses APPEND FROM ARRAY to move a subset of records for State_Prov = California to Temp.DBF:

CLOSE ALL
SET SAFETY OFF
USE Company EXCLUSIVE
INDEX ON CompCode TAG CompCode
DECLARE Dup[RECCOUNT(),3]
COPY FIELDS Company, Compcode,State_Prov TO ARRAY Dup
COPY STRUCTURE TO TEMP.DBF WITH PRODUCTION
USE TEMP IN SELECT()
SELECT TEMP
APPEND FROM ARRAY Dup ;
  FIELDS Company, Compcode, State_Prov ;
  FOR State_Prov = "CA" REINDEX
SET FIELDS TO Company, Compcode, State_Prov
GO TOP
BROWSE
RETURN


See Also

APPEND AUTOMEM

COPY TO ARRAY

DECLARE

REPLACE FROM ARRAY

STORE AUTOMEM


APPEND MEMO

See Also	Example	Portability	Fields and Records

Copies a text file to a memo field.

Syntax

APPEND MEMO <memo field>
FROM <filename> | ? | <filename skeleton>
[OVERWRITE]

<memo field>

The memo field of the current table to which the contents of <filename> are appended.

FROM <filename> | ? | <filename skeleton>

Specifies the file to append to the memo field in the current record. APPEND MEMO ? and APPEND MEMO <filename skeleton> display a dialog box from which you can select a file. If you specify a file without including its path, dBASE for Windows looks for the file in the current directory, then in the path you specify with SET PATH. If you specify a file without including its extension, dBASE for Windows assumes a .TXT extension.

OVERWRITE

Erases the contents of the current record memo field before copying the contents of <filename>.

Description

Use APPEND MEMO to copy a text file to the current record memo field. You can copy one text file to each memo field of each record in a table. To overwrite the contents of a memo field in the current record, use OVERWRITE.

While dBASE memo fields can contain types of information other than text, binary fields are recommended for storing images, sound, and other user-defined binary information. For more information, see the REPLACE BINARY command.


APPEND MEMO Example

The following example appends a new, empty record to Clients table, uses APPEND MEMO to place the contents of a text tile in the memo field Notes and takes the user to the record in a Table Editor to edit other fields or review the memo field contents:

USE Clients
APPEND BLANK
APPEND MEMO Notes FROM C:\DBASEWIN\Readme.TXT
BROWSE


Portability

Not supported in dBASE III PLUS.


See Also

COPY MEMO

REPLACE BINARY

REPLACE MEMO

REPLACE MEMO...FROM

REPLACE OLE


ARESIZE( )

See Also	Example	Portability	Memory Variables

Increases or decreases the size of an array according to the specified dimensions and returns a numeric value representing the number of elements in the modified array.

Syntax

ARESIZE(<array name>, <new rows expN>
[,<new cols expN> [, <retain values expN>]])

<array name>

The name of a declared one- or two-dimensional array whose size you want to increase or decrease.

<new rows expN>

The number of rows the resized array should have. <new rows expN> must always be a positive, nonzero value.

<new cols expN>

The number of columns the resized array should have. <new cols expN> must always be 0 or a positive value. If you omit this option, ARESIZE( ) changes the number of rows in the array and leaves the number of columns the same.

<retain values expN>

Determines what happens to the values of the array when rows are added or removed. If you want to specify a value for <retain values expN>, you must also specify a value for <new cols expN>.

Description

Use ARESIZE( ) to change the size of a declared array, making it larger or smaller. To determine the number of rows or columns in an existing array, use ALEN( ).

If you add or remove columns from the array, you can use <retain values expN>to specify how you want existing elements to be placed in the new array. If <retain values expN> is zero or isn't specified, ARESIZE( ) rearranges the elements, filling in the new rows or columns or adjusting for deleted elements, and adding or removing elements at the end of the array, as needed. This is shown in the following two figures. You are most likely to want to do this if you don't need to refer to existing items in the array; that is, you plan to update the array with new values.

Figure: Adding a row and a column to a 3x4 array, rearranging elements

	ARESIZE(aARRAY,4,5)
1	Original array created as: DECLARE aArray[3,4] STORE "A" TO aArray[1,1] STORE "B" TO aArray[1,2]       STORE "L" TO aArray[3,4]	2	ARESIZE(aArray,4,5) adds a new row and column to the array and rearranges the values of the elements.
	Initial contents of the array aArray		Contents of the array after issuing ARESIZE(aArray,4,5)
Figure: Adding a column to a one-dimensional array, rearranging elements

	ARESIZE(bARRAY,4,2)
1	Original array created as: DECLARE bArray[4] STORE "A" TO bArray[1] STORE "B" TO bArray[2] STORE "C" TO bArray[3] STORE "D" TO bArray[4]	2	ARESIZE(bArray,4,2) adds a new column to the array, makes it a two-dimensional array with dimensions [4,2], and reassigns the values of the elements.
	Initial contents of the array bArray		Contents of the array after issuing ARESIZE(bArray,4,2)
When you use ARESIZE( ) on a one-dimensional array, you might want the original row to become the first column of the new array. Similarly, when you use ARESIZE( ) on a two-dimensional array, you might want existing two-dimensional array elements to remain in their original positions. You are most likely to want to do this if you need to refer to existing items in the array; that is, you plan to add new values to the array while continuing to work with existing values.

If <retain values expN> is a nonzero value, ARESIZE( ) ensures that elements retain their original values. The following two figures repeat the statements shown in the previous two figures, with the addition of a value of 1 for <retain values expN >.

Figure: Adding a row and a column to a 3x4 array, "preserving elements"

	ARESIZE(aARRAY,4,5,1)
1	Original array created as: DECLARE aArray[3,4] STORE "A" TO aArray[1,1] STORE "B" TO aArray[1,2]       STORE "L" TO aArray[3,4]	2	ARESIZE(aArray,4,5,1) adds a new row and column to the array and maintains the values of the elements.
	Initial contents of the array aArray		Contents of the array after issuing ARESIZE(aArray,4,5,1)
Figure: Adding a column to a one-dimensional array, "preserving elements"

	ARESIZE(bARRAY,4,2,1)
1	Original array created as: DECLARE bArray[4] STORE "A" TO bArray[1] STORE "B" TO bArray[2] STORE "C" TO bArray[3] STORE "D" TO bArray[4]	2	ARESIZE(bArray,4,2,1) adds a new column to the array, and makes it a two-dimensional array with dimensions [4,2].  Each existing element is now the first element in a row.
	Initial contents of the array bArray		Contents of the array after issuing ARESIZE(bArray,4,2,1)


ARESIZE( ) Example

The following example initially declares an array of three elements, and then uses ARESIZE( ) to resize the array to A[5], A[5,2] and finally back to A[3]. DISPLAY MEMORY is used to show the values in the array after each ARESIZE( ) operation:

RELEASE ALL
DECLARE A[3]
A[1]="x"
A[2]="y"
A[3]="z"
DISPLAY MEMORY
N=ARESIZE(A,5)         && A now has 5 elements
A[4]="new1"
A[5]="new2"
DISPLAY MEMORY
N=ARESIZE(A,5,2,1)
* A now has 5 rows and 2 columns.
* The new cols are all set to .t.
* Old values are retained
DISPLAY MEMORY
N=ARESIZE(A,3,1,1)
* A now is back to the original 3 elements
* use:
DISPLAY MEMORY
* N=ARESIZE(A,3,1,0)
* if you do not need the original values
DISPLAY MEMORY
WAIT


Portability

Not supported in dBASE IV or dBASE III PLUS.


See Also

ADEL( )

AGROW( )

AINS( )

ALEN( )

DECLARE


ASC( )

See Also	Example	Expressions and Type Conversion

Returns the numeric ASCII value of a specified character.

Syntax

ASC(<expC>)

<expC>

The character whose ASCII value to return. You can specify more than one character, but dBASE uses only the first one.

Description

ASC( ) is the inverse function of CHR( ). ASC( ) accepts a character and returns its ASCII value--a number from 0 to 255, inclusive. CHR( ) accepts an ASCII value and returns its character.

You can use ASC( ) to manipulate the returned ASCII values of characters with mathematical operators. See the ASCII table in Appendix E in the Language Reference for a listing of ASCII values and their corresponding characters.


ASC( ) Example

The following example uses ASC( ) to determine the ASCII value of a specified character:

SET TALK OFF
plus_minus = CHR(241)
? "The ASCII value of " + plus_minus + " is "
?? + LTRIM(STR(ASC(plus_minus),3,0))


See Also

ANSI( )

CHR( )

OEM( )


ASCAN( )

See Also	Example	Portability	Memory Variables

Searches an array for an expression. Returns the number of the first element that matches the expression if the search is successful, or 0 if the search is unsuccessful.

Syntax

ASCAN(<array name>, <exp>
[, <starting element expN> [, <elements expN>]])

<array name>

A declared one- or two-dimensional array.

<exp>

The expression to search for in <array name>.

<starting element expN>

The element number in <array name> at which to start searching. Without <starting element expN>, ASCAN( ) starts searching at the first element.

<elements expN>

The number of elements in <array name> that ASCAN( ) searches. Without <elements expN>, ASCAN( ) searches <array name> from <starting element expN> to the end of the array. If you want to specify a value for <elements expN>, you must also specify a value for <starting element expN>.

Description

Use ASCAN( ) to search an array for the value contained in <exp>. For example, if an array contains customer names, you can use ASCAN( ) to find the location in which a particular name appears.

ASCAN( ) returns the element number of the first element in the array that matches <exp>. If you want to determine the subscripts of this element, use ASUBSCRIPT( ).

When <exp> contains string data, ASCAN( ) is case-sensitive; you may want to use UPPER( ), LOWER( ), or PROPER( ) to match the case of <exp> with the case of the data stored in the array.

When <exp> contains string data, ASCAN( ) searches for an expression following the rules established by SET EXACT. If SET EXACT is ON, dBASE returns 0 if the value in <exp> is not identical to the data in an element of the array. If SET EXACT is OFF, dBASE returns 0 if the characters in <expN> do not match the beginning characters in the data in an element of the array. The following code example illustrates this more clearly. For more information, see SET EXACT.

DECLARE aArray[3,4]	   && 3 rows,4 columns
? AFILL(aArray,"abcd",6,1) && place "abcd" in the;
   && 6th element
SET EXACT OFF
? ASCAN(aArray,"abcd")	&& returns 6
? ASCAN(aArray,"abc")	&& returns 6
? ASCAN(aArray,"bcd")	&& returns 0
SET EXACT ON
? ASCAN(aArray,"abcd")	&& returns 6
? ASCAN(aArray,"abc")	&& returns 0
? ASCAN(aArray,"abc")	&& returns 0


ASCAN( ) Example

The following example uses ASCAN( ) to return an element number for a desired string within an array and ASUBSCRIPT( ) to return the row and column coordinates within the array:

CLEAR
DECLARE A_Dir[1]
FileName="CLIENTS.DBF"
Files=ADIR(A_Dir,"*.*")      && Initializes array to;
                                directory contents
Asort=ASORT(A_Dir)           && Orders array
Element=ASCAN(A_Dir,FileName)&& Returns filename;
                                location
IF Element > 0               && ASCAN() returns 1;
                                if successful
  Row=ASUBSCRIPT(A_Dir,Element,1)
  Col=ASUBSCRIPT(A_Dir,Element,2)
  ? "Name" AT 15, "Bytes" AT 30, "Date" AT 39,;
    "Time" AT 48
  ?
  ? "File Info:  " + A_Dir[Row,Col];
    +"  "+STR(A_Dir[Row,Col+1]);
    +"  "+A_Dir[Row,Col+2]+" "+A_Dir[Row,Col+3]
ENDIF


Portability

Not supported in dBASE IV or dBASE III PLUS.


See Also

ACOPY( )

AFIELDS( )

AFILL( )

ASORT( )

ASUBSCRIPT( )

DECLARE

LOWER( )

PROPER( )

SET EXACT

UPPER( )


ASIN( )

See Also	Example	Portability	Numeric Data

Returns the inverse sine (arcsine) of a number.

Syntax

ASIN(<expN>)

<expN>

The sine of an angle, from -1 to +1.

Description

ASIN( ) returns the radian value of the angle whose sine is <expN>. ASIN( ) returns a float from -pi/2 to pi/2 radians. ASIN( ) returns zero when <expN> is 0. For values of x from -pi/2 to pi/2, ASIN(Y) returns x if SIN(X) returns y.

To convert the returned radian value to degrees, use RTOD( ). For example, if the default number of decimal places is 2, ASIN(.5) returns .52 radians while RTOD(ASIN(.5)) returns 30.00 degrees.

Use SET DECIMALS to set the number of decimal places ASIN( ) displays.

To find the arccosecant of a value, use 1 divided by the arcsine of the value. For example, the arccosecant of 1.54 is ASIN(1/1.54), or .71 radians.


ASIN( ) Example

The following example uses ASIN( ) to return the arcsine of a set of sine values:

CLEAR
? "ArcSine" AT 20
?
? "Sine" AT 9, "Radians" AT 20,"Degrees" AT 33
SET DECIMALS TO 2
FOR sine = -1 TO 1 STEP .25
  ? sine AT 0, ASIN(sine) AT 13, RTOD(ASIN(sine)) ;
    AT 26
NEXT


Portability

Not supported in dBASE III PLUS.


See Also

ACOS( )

ATAN( )

ATN2( )

DTOR( )

RTOD( )

SET DECIMALS

SIN( )


ASORT( )

See Also	Example	Portability	Memory Variables

Sorts the elements in a one-dimensional array or the rows in a two-dimensional array, returning 1 if successful or an error if unsuccessful.

Syntax

ASORT(<array name>
[, <starting element expN> [,<elements to sort expN>
[, <sort order expN>]]])

<array name>

A declared one- or two-dimensional array.

<starting element expN>

In a one-dimensional array, the number of the element in <array name> at which to start sorting. In a two-dimensional array, the number (subscript) of the column on which to sort. Without <starting element expN>, ASORT( ) starts sorting at the first element or column in the array.

<elements to sort expN>

In a one-dimensional array, the number of elements to sort. In a two-dimensional array, the number of rows to sort. Without <elements to sort expN>, ASORT( ) sorts the rows starting at the row containing element <starting element expN> to the last row. If you want to specify a value for <elements to sort expN>, you must also specify a value for <starting element expN>.

<sort order expN>

The sort order:

0 specifies ascending order (the default)

1 specifies descending order

If you want to specify a value for <sort order expN>, you must also specify values for <elements to sort expN> and <starting element expN>.

Description

ASORT( ) succeeds in sorting when all elements you specify to be sorted are of the same data type. The elements to sort in a one-dimensional array must be of the same data type, and the elements of the column by which rows are to be sorted in a two-dimensional array must be of the same data type.

ASORT( ) arranges elements in alphabetical, numerical, chronological, or logical order, depending on the data type of <starting element expN>. (For character data, the current language driver determines the sort order.)

One-dimensional arrays

Suppose you issue DECLARE aNums[8] and store numbers to the array so that the array elements are in this order:

5	7	3	9	4	1	2	8

If you issue ASORT(aNums, 1, 5), dBASE sorts the first five elements so that the array elements are in this order:

3	4	5	7	9	1	2	8

If you then issue ASORT(aNums, 5, 2), dBASE sorts two elements starting at the fifth element so that the array elements are now in this order:

3	4	5	7	1	9	2	8

Two-dimensional arrays

Using ASORT( ) with a two-dimensional array is similar to using the SORT command with a table. In this comparison, array rows correspond to records, and array columns correspond to fields.

When you sort a two-dimensional array, whole rows are sorted, not just the elements in the column where <starting element expN>) is located.

For example, suppose you issue DECLARE aInfo[4, 3] and fill the array with the following data:

{09/15/65}	7	A
{12/31/65}	4	D
{01/19/45}	8	C
{05/02/72}	2	B

If you issue ASORT(aInfo, 1), dBASE sorts all rows in the array beginning with element number 1. The rows are sorted by the dates in the first column because element 1 is a date. The following figure shows the results.

Figure: ASORT(aInfo, 1)

	ASORT(aInfo,1)
1	All the rows are to be sorted... starting with the row containing element 1.	2	Element 1 is a date, so the rows are sorted by the dates in the first column.
	Initial contents of the array aInfo		Contents of the array after issuing ASORT(aInfo,1)
If you then issue ASORT(aInfo, 5, 2), dBASE sorts two rows in the array starting with element number 5, whose value is 7. ASORT( ) sorts the second and the third rows based on the numbers in the second column. The following figure shows the results.

Figure: ASORT(aInfo, 5, 2)

	ASORT(aInfo,5,2)
1	Two rows are to be sorted (ASORT(aInfo,5,2)) starting with the row containing element 5 (ASORT(aInfo,5,2)).	2	Element 5 contains a number, so the rows are sorted by the numbers in the second column.
	Initial contents of the array aInfo		Contents of the array after issuing ASORT(aInfo,5,2)


ASORT( ) Example

See ASCAN( ) for an example of ASORT( ).


Portability

Not supported in dBASE IV or dBASE III PLUS.


See Also

AELEMENT( )

ALEN( )

ASCAN( )

ASUBSCRIPT( )

DECLARE


ASUBSCRIPT( )

See Also	Example	Portability	Memory Variables

Returns the row number or the column number of a specified element in an array.

Syntax

ASUBSCRIPT(<array name>, <element expN>, <row/column expN>)

<array name>

A declared one- or two-dimensional array.

<element expN>

The element number.

<row/column expN>

A number, either 1 or 2, that determines whether you want to return the row or column subscript of an array. If <row/column expN> is 1, ASUBSCRIPT( ) returns the number of the row subscript. If <row/column expN> is 2, ASUBSCRIPT( ) returns the number of the column subscript.

If <array name> is a one-dimensional array, dBASE returns an error if <row/column expN> is a value other than 1.

Description

Use ASUBSCRIPT( ) when you know the number of an element in a two-dimensional array and want to reference the element by using its subscripts.

If you need to determine both the row and column number of an element in a two-dimensional array, issue ASUBSCRIPT( ) twice, once with a value of 1 for <row/column expN> and once with a value of 2 for <row/column expN>. For example, if the element number is 13, issue the following to return its subscripts:

? ASUBSCRIPT(aArray,13,1) && returns row subscript
? ASUBSCRIPT(aArray,13,2) && returns column subscript

In one-dimensional arrays, the number of an element is the same as its subscript, so there is no need to use ASUBSCRIPT( ). That is, ASUBSCRIPT(aOneArray,3,1) returns 3, ASUBSCRIPT(aOneArray,5,1) returns 5, and so on.

ASUBSCRIPT( ) is the inverse of AELEMENT( ), which returns an element number when you specify the element subscripts.


ASUBSCRIPT( ) Example

The following example uses ASCAN( ) to return an element number for a desired string within an array and ASUBSCRIPT( ) to return the row and column coordinates within the array:

CLEAR
DECLARE A_Dir[1]
FileName="CLIENTS.DBF"
Files=ADIR(A_Dir,"*.*")      && Initializes array to;
                                directory contents
Asort=ASORT(A_Dir)           && Orders array
Element=ASCAN(A_Dir,FileName)&& Returns filename;
                                location
IF Element > 0               && ASCAN() returns 1;
                                if successful
  Row=ASUBSCRIPT(A_Dir,Element,1)
  Col=ASUBSCRIPT(A_Dir,Element,2)
  ? "Name" AT 15, "Bytes" AT 30, "Date" AT 39,;
    "Time" AT 48
  ?
  ? "File Info:  " + A_Dir[Row,Col];
    +"  "+STR(A_Dir[Row,Col+1]);
    +"  "+A_Dir[Row,Col+2]+" "+A_Dir[Row,Col+3]
ENDIF


Portability

Not supported in dBASE IV or dBASE III PLUS.


See Also

ACOPY( )

ADEL( )

AELEMENT( )

AFIELDS( )

AINS( )

ALEN( )

ASCAN( )

ASORT( )

DECLARE


AT( )

See Also	Example	Portability	String Data

Returns a number that represents the position of a string within another string or memo field.

Syntax

AT(<search expC>, <target expC> | <target memo field>
[, <nth occurrence expN>] )

<search expC>

The string to search for in <target expC> or <target memo field>.

<target expC> | <target memo field>

The string or memo field in which to search for <search expC>.

<nth occurrence expN>

Which occurrence of the string to find. By default, dBASE searches for the first occurrence. You can search for other occurrences by specifying the number, which must be greater than zero.

Description

AT( ) returns the numeric position where a search string begins in a target string or target memo field. AT( ) searches, one character at a time, from the first character of the string or memo field, searching left to right, beginning to end.

The search is case-sensitive. Use UPPER( ) or LOWER( ) to make the search case-insensitive.

You can specify which occurrence of the search string to find by specifying a number for <nth occurrence expN>. If you omit this argument, AT( ) returns the starting position of the first occurrence of the search string.

AT( ) returns 0 when

The search string is not found.

The search string, target string, or target memo field is empty.

The search string is longer than the target string.

The <nth occurrence expN> occurrence does not exist.

If < nth occurrence expN> is less than 1, dBASE returns an error.

When AT( ) counts characters in a memo field, it counts two characters for each carriage-return and linefeed combination (CR/LF) in the memo field.

Use RAT( ) to find the starting position of <search expC>, searching from right to left, end to beginning. Use the substring operator ($) to learn if one string exists within another. See Language Definition for information about operators.


AT( ) Example

The following example uses AT( ) to determine the starting point of a passed text string in a second string:

? AT("B","ABC")                        && Returns 2
? AT("ss","Mississippi")               && Returns 3
? AT("ss","Mississippi",2)             && Returns 6
? AT("Z","ABC")                        && Returns 0
? AT("a","ABC")                        && Returns 0
? AT("ABC","AB")                       && Returns 0
? AT("","ABC")                         && Returns 0
? AT("a","abc",2)                      && Returns 0

The following example uses AT( ) to display or print a listing of all records in the Client table that contain a string in the Notes memo field and the position of the first occurrence.

USE Clients
String="Special Handling"
LIST Company, Notes FOR AT(String, Notes)>0
CLOSE ALL


Portability

dBASE IV limits a memo field search to the first 64K of data, and the <memo field> and <nth occurrence expN> arguments are not supported in dBASE III PLUS.


See Also

RAT( )

STUFF( )

SUBSTR( )


ATAN( )

See Also	Example	Portability	Numeric Data

Returns the inverse tangent (arctangent) of a number.

Syntax

ATAN(<expN>)

<expN>

Any positive or negative number representing the tangent of an angle.

Description

ATAN( ) returns the radian value of the angle whose tangent is <expN>. ATAN( ) returns a float from -pi/2 to pi/2 radians. ATAN( ) returns 0 when <expN> is 0. For values of x from -pi/2 to pi/2, ATAN(Y) returns x if TAN(X) returns y.

To convert the returned radian value to degrees, use RTOD( ). For example, if the default number of decimal places is 2, ATAN(1) returns 0.79 radians, while RTOD(ATAN(1)) returns 45.00 degrees.

Use SET DECIMALS to set the number of decimal places ATAN( ) displays.

ATAN( ) differs from ATN2( ) in that ATAN( ) takes the tangent as the argument while ATN2( ) takes the sine and cosine as the arguments.

To find the arccotangent of a value, subtract pi/2 from the arctangent of the value. For example, the arccotangent of pi/3 is pi/2-ATAN(pi/3), or .76.


ATAN( ) Example

The following example uses ATAN( ) to find the arctangent of a set of tangent values:

CLEAR
SET DECIMALS TO 5
? "Arc Tangent" AT 18
? "Tangent" AT 6, "Radians" AT 20, "Degrees" AT 33
FOR tang = -100 TO 1000 STEP 100
  ? tang AT 0, ATAN(tang) AT 12, ;
  LTRIM(STR(RTOD(ATAN(tang)),8,5)) AT 33
NEXT


Portability

Not supported in dBASE III PLUS.


See Also

ACOS( )

ASIN( )

ATN2( )

RTOD( )

SET DECIMALS

TAN( )


ATN2( )

See Also	Example	Portability	Numeric Data

Returns the inverse tangent (arctangent) of a given point.

Syntax

ATN2(<sine expN>, <cosine expN>)

<sine expN>

The sine of an angle. If <sine expN> is 0, <cosine expN> cannot also be 0.

<cosine expN>

The cosine of an angle. If <cosine expN> is 0, <sine expN> cannot also be 0. When <cosine expN> is 0 and <sine expN> is a positive or negative (nonzero) number, ATN2( ) returns +pi/2 or -pi/2, respectively.

Description

ATN2( ) returns the angle size in radians when you specify the sine and cosine of the angle. ATN2( ) returns a float from --pi to +pi radians. ATN2( ) returns 0 when <sine expN> is 0. When you specify 0 for both arguments, dBASE returns an error.

To convert the returned radian value to degrees, use RTOD( ). For example, if the default number of decimal places is 2, ATN2(1,0) returns 1.57 radians while RTOD(ATN2(1,0)) returns 90.00 degrees.

Use SET DECIMALS to set the number of decimal places ATN2( ) displays.

ATN2( ) differs from ATAN( ) in that ATN2( ) takes the sine and cosine as the arguments while ATAN( ) takes the tangent as the argument. See ATAN( ) for instructions on finding the arccotangent.


ATN2( ) Example

The following example shows some ways to use ATN2( ):

? ATN2(2.79,-3.2)          && Returns 2.42
? ATN2(-3,3)               && Returns -0.79
? RTOD(ATN2(-3,3))         && Returns -45
? RTOD(ATN2(-1,-SQRT(3)))  && Returns -150
x=SIN(DTOR(30))
y=COS(DTOR(30))
? RTOD(ATN2(x,y))          && Returns 30


Portability

Not supported in dBASE III PLUS.


See Also

ACOS( )

ASIN( )

ATAN( )

COS( )

RTOD( )

SET DECIMALS

SIN( )

TAN( )


AVERAGE

See Also	Example	Portability	Table Organization

Computes the arithmetic mean (average) of specified numeric or float type fields in the current table.

Syntax

AVERAGE
[<exp list>]
[<scope>]
[FOR <condition 1>]
[WHILE <condition 2>]
[TO <memvar list> | TO ARRAY <array name>]

<exp list>

The numeric or float fields, or expressions involving numeric or float fields, to average.

<scope>

The range of records to average. RECORD <n> identifies a single record by its record number. NEXT <n> identifies n records, beginning with the current record. ALL specifies all records. REST specifies all records from the current record to the end of the file.

FOR <condition 1>
WHILE <condition 2>

Determines which records are affected by AVERAGE. FOR restricts AVERAGE to records that meet <condition 1>, starting at the first record of the table or view. WHILE starts processing with the current record and continues with each subsequent record as long as <condition 2> is true.

TO <memvar list> | TO ARRAY <array name>

Initializes and stores averages to the memory variables of <memvar list> or stores averages to the existing array <array name>. If you specify an array, each field average is stored to elements in the order in which you specify the fields in <exp list>. If you do not specify <exp list>, each field average is stored in field number order. <array name> can be a single- or multidimensional array. You can store averages to an array without the ARRAY keyword if you explicitly reference the array subscripts.

Description

The AVERAGE command computes the arithmetic means (averages) of numeric expressions and stores the results in specified memory variables or array elements. If you store the values in memory variables, the number of memory variables must be exactly the same as the number of fields or expressions averaged. If you store the values in an array, the array must already exist, and the array must contain at least as many elements as the number of averaged expressions.

If SET TALK is ON, AVERAGE also displays its results in the results pane of the Command window. The SET DECIMALS setting determines the number of decimal places that AVERAGE displays. Numeric fields in blank records are evaluated as zero. To exclude blank records, use the ISBLANK( ) function in defining a FOR condition. EMPTY( ) excludes records in which a specified expression is either 0 or blank.


AVERAGE Example

The following example uses AVERAGE to calculate the average year to date sales for all companies in the Company table:

USE Company
AVERAGE Ytd_sales TO Ytd_Av
? "The average Ytd Sale was $", ;
   Ytd_av PICTURE "99,999,999.99"


Portability

Not supported in dBASE III PLUS.


See Also

CALCULATE

COUNT

SUM

TOTAL


BAR( )

See Also	Example	Portability	dBASE IV Menus

Returns the number of the currently selected (highlighted) or most recently chosen bar in a dBASE IV pop-up menu. This command is supported primarily for compatibility with dBASE IV. In dBASE for Windows, use INSPECT( ) to return information associated with objects in forms.

Syntax

BAR( )

Description

BAR( ) returns the number of the most recently chosen bar from a pop-up menu.


BAR( ) Example

The following example provides a pop-up menu with choices for selecting which program to run. In the procedure Select, BAR( ) is used in a CASE statement to determine which pop-up bar was selected:

CLEAR
SET TALK OFF
DEFINE POPUP Pop1 FROM 5,25
DEFINE BAR 1 OF Pop1 PROMPT "Checking Account"
DEFINE BAR 2 OF Pop1 PROMPT "Investments"
DEFINE BAR 3 OF Pop1 PROMPT "Insurance"
DEFINE BAR 4 OF Pop1 PROMPT "Exit"
ON SELECTION POPUP Pop1 DO Select
ACTIVATE POPUP Pop1
CLEAR ALL
SET TALK ON

PROCEDURE Select
DO CASE
CASE BAR() = 1
DO Checking
CASE BAR() = 2
DO Invest
CASE BAR() = 3
DO Insure
CASE BAR() = 4
DEACTIVATE POPUP
ENDCASE
CLEAR

PROCEDURE Checking
@ 12,0 SAY "Bar 1 was chosen, and this is Checking.prg"
INKEY(0)

PROCEDURE Invest
@ 12,0 SAY "Bar 2 was chosen, and this is Invest.prg"
INKEY(0)

PROCEDURE Insure
@ 12,0 SAY "Bar 3 was chosen, and this is Insure.prg"
INKEY(0)


Portability

Not supported in dBASE III PLUS.


See Also

DEFINE

DEFINE POPUP

INSPECT( )


BARCOUNT( )

See Also	Example	Portability	dBASE IV Menus

Returns the number of bars in a dBASE IV pop-up menu. This command is supported primarily for compatibility with dBASE IV. In dBASE for Windows, use INSPECT( ) to return information associated with objects in forms.

Syntax

BARCOUNT ([<pop-up name>])

<pop-up name>

The pop-up menu evaluated by BARCOUNT( ). If this name is not supplied, BARCOUNT( ) evaluates the current pop-up menu.

Description

BARCOUNT( ) returns the number of bars in a pop-up menu, which is defined with DEFINE POPUP. All bars in a pop-up menu are counted, even if the they cannot be chosen by the user.


BARCOUNT( ) Example

The following example uses BARCOUNT( ) to determine the number of bars in a pop-up menu that displays files in the current directory:

DEFINE WINDOW BarStat FROM 6,20 to 10,78 DOUBLE
ACTIVATE WINDOW BarStat
@ 0,2 SAY "Popup status for: "
@ 1,2 SAY "  On bar:"
@ 2,2 SAY "  Prompt: "
ACTIVATE SCREEN

DEFINE POPUP FilePick FROM 3,5 PROMPT FILES LIKE *.*
ON POPUP FilePick DO BarStat
ACTIVATE POPUP FilePick
RELEASE WINDOW BarStat
RELEASE POPUP FilePick
RETURN

PROCEDURE BarStat
ACTIVATE WINDOW BarStat
@ 0,20 SAY POPUP()           && Displays popup name
@ 1,12 SAY STR(BAR(),3)+STR(BARCOUNT(),3);
                             && Displays current bar;
                             and total number of bars
@ 2,12                       && Clears previous bar;
                             prompt
@ 2,12 SAY LEFT(PROMPT(),35) && Displays current bar;
                             prompt
ACTIVATE SCREEN
RETURN


Portability

Not supported in dBASE III PLUS.


See Also

INSPECT( )


BARPROMPT( )

See Also	Example	Portability	dBASE IV Menus

Returns the prompt of a bar in a dBASE IV pop-up menu. This command is supported primarily for compatibility with dBASE IV. In dBASE for Windows, use INSPECT( ) to return information associated with objects in forms.

Syntax

BARPROMPT(<bar expN> [,<pop-up name>])

<bar expN>

The number of the pop-up menu bar.

<popup name>

The pop-up menu in which the bar's prompt is displayed. If this name is not supplied, BARPROMPT( ) evaluates the current pop-up menu.

Description

BARPROMPT( ) returns the prompt from a pop-up menu bar.


BARPROMPT( ) Example

The following example uses BARPROMPT( ) to return the prompt string of the last selected bar of the specified pop-up menu:

CLEAR
SET TALK OFF
USE ANIMALS ORDER NAME
DEFINE POPUP LocAnim FROM 2,4 PROMPT FIELD NAME
ON SELECTION POPUP LocAnim DEACTIVATE POPUP
ACTIVATE POPUP LocAnim
Picked=BARPROMPT(BAR(),"LocAnim")
SEEK Picked
EDIT
CLOSE ALL
CLEAR ALL
RETURN


Portability

Not supported in dBASE III PLUS.


See Also

DEFINE

INSPECT( )


BEGINTRANS( )

See Also	Example	Portability	Shared Data

Starts a transaction and returns .T. if the transaction started successfully.

Syntax

BEGINTRANS([<database name expC>])

<database name expC>

The name of the SQL database in which to begin the transaction.

If <database name expC> is omitted but a SET DATABASE statement has been issued, BEGINTRANS( ) refers to the database in the SET DATABASE statement.

If <database name expC> is omitted and no SET DATABASE statement has been issued, BEGINTRANS( ) refers to the database opened after issuing BEGINTRANS( ).

Note:	If you include <database name expC> when you issue BEGINTRANS( ), you must also include it in subsequent COMMIT( ) or ROLLBACK( ) statements within that transaction. If you do not, dBASE ignores the COMMIT( ) or ROLLBACK( ) statement.

Description

Use BEGINTRANS( ) to initiate a transaction during which the user might make changes to a table or tables in an SQL database that supports transaction processing. Within a transaction initiated with BEGINTRANS( ), you can work in only one database. Also, you cannot nest transactions.

If you issue BEGINTRANS( ) against an SQL database that does not support transactions, or if a server error occurs, BEGINTRANS( ) returns .F. Otherwise, it returns .T. If BEGINTRANS( ) returns .F., use SQLERROR( ) or SQLMESSAGE( ) to determine the nature of the server error that might have occurred.

To close a transaction, use COMMIT( ) or ROLLBACK( ).COMMIT( ) saves changes made during the transaction, and ROLLBACK( ) discards changes and returns tables to the state they were in before BEGINTRANS( ) was issued.

BEGINTRANS( ) applies to the following commands:

@...SAY...GET	DELETE	REPLACE
APPEND	EDIT	REPLACE MEMO/BINARY/OLE
APPEND BLANK	FLOCK( )	RLOCK( )
APPEND MEMO	INSERT
BROWSE	RECALL
The following commands are not allowed in transactions. dBASE returns an error if you try to issue them from within a transaction.

BEGINTRANS( ) (nested transactions are not allowed)	DELETE TAG
CLEAR ALL	INDEX
CLOSE ALL/DATABASE/INDEX (any command that closes open tables or indexes)	MODIFY STRUCTURE
CONVERT	PACK
CREATE FROM	a USE that would close an open table, or open a table in another database
ZAP


BEGINTRANS( ) Example

The following example begins a transaction with BEGINTRANS( ). It opens a multi-user version of Company.dbf and attempts to make all YTD_SALES 0. ON ERROR detects any error which might occur. In particular, it will detect if another user has locked any record in Company.dbf. If an error occurs, ROLLBACK( ) resets all values. Otherwise COMMIT( ) writes the changes to disk:

CLOSE ALL
SET PROCEDURE TO PROGRAM(1) ADDITIVE
SET EXCLUSIVE OFF

BEGINTRANS()

TransErr=.f.
ON ERROR DO TransErr    && Activates ON ERROR trap

USE L:\MultiUse\Company
REPLACE ALL Ytd_Sales WITH 0
ON ERROR                && Disables ON ERROR

IF TransErr
  ? "Rollback"
  ROLLBACK()            && restore data
ELSE
  ? "Commit"
  COMMIT()              && save changes
ENDIF

PROC TransErr
WAIT "Warning: Transaction Fails"
TransErr=.t.


Portability

Not supported in dBASE IV or dBASE III PLUS. BEGINTRANS( ) replaces the BEGIN TRANSACTION and END TRANSACTION commands in dBASE IV.


See Also

COMMIT( )

FLOCK( )

RLOCK( )

ROLLBACK( )

SET EXCLUSIVE

SQLERROR( )

SQLMESSAGE( )


BINTYPE( )

See Also	Example	Fields and Records

Returns the predefined type number of a specified binary field.

Syntax

BINTYPE([<field name>])

<field name>

The name of a field in the current table.

Description

BINTYPE( ) returns the predefined binary type number of a binary field in the current table. Using this command, you can determine the type of data stored in the field. The values returned by BINTYPE( ) are the following:

Predefined Binary Type Numbers	Description
1 to 32K -1 (1 to 32,767)	User-defined file types
32K (32,768)	.WAV files
32K + 1 (32,769)	.BMP and .PCX files
BINTYPE( ) returns an error if a non-binary field is specified. It returns a value of 0 if the binary field is empty.


BINTYPE( ) Example

The following example uses BINTYPE( ) to return the binary type code for the BMP field of the Animals table:

USE Animals
GO 5
? BINTYPE(BMP)         && Returns 32769


See Also

COPY BINARY

PLAY SOUND

REPLACE BINARY

RESTORE IMAGE


BITAND( )

See Also	Example	Portability	Windows Programming

Performs a bitwise AND operation on two numeric values and returns the result.

Syntax

BITAND(<expN1>, <expN2>)

Description

BITAND( ) is used by advanced programmers to make binary interpretations of numeric values. These values are often returned by functions prototyped with EXTERN to access resources in Windows API or other DLL files. Interpreting such values often requires analysis and manipulation of individual bits.

BITAND( ) compares bits in the numeric value <expN1> with corresponding bits in the numeric value <expN2>. When two bits in the same position are on (set to 1), the corresponding bit in the returned value is on. In any other case, the bit is off (set to 0).

	Bit 1 = 1	Bit 1 = 0
Bit 2 = 1	1	0
Bit 2 = 0	0	0


BITAND( ) Example

The following procedure gets information from the Windows function GetVersion( ), which returns the major and minor DOS and Windows versions as a CLONG. The "High Byte of the High Word" contains the major DOS version, the "Low Byte of the High Word" contains the minor DOS version. The "High Byte of the Low Word" specifies the minor version of Windows and the "Low byte of the Low Word" specifies the major Windows version. The Bit functions BITAND( ) and BITRSHIFT( ) are used to extract the proper values.

FUNCTION GVer
PARAMETER VerType
#define HiWord(x) (BITRSHIFT(BITAND;
  (x,4294901760),16))
#define LoWord(x) (BITAND(x,65535))
#define HiByte(x) (LTRIM(STR(BITRSHIFT(BITAND;
  (x,65280), 8))))
#define LoByte(x) (LTRIM(STR(BITAND(x,255))))
EXTERN CLONG GetVersion()  krnl386.exe
z=GetVersion()
IF UPPER(verType)="DOS"
  RETURN HiByte(HiWord(z))+"."+LoByte(HiWord(z))
ENDIF
IF LEFT(UPPER(verType),3)="WIN"
  RETURN  LoByte(LoWord(z))+"."+HiByte(LoWord(z))
ENDIF


Portability

Not supported in dBASE IV or dBASE III PLUS.


See Also

BITLSHIFT( )

BITOR( )

BITRSHIFT( )

BITSET( )

BITXOR( )

EXTERN

HTOI( )

ITOH( )


BITLSHIFT( )

See Also	Example	Portability	Windows Programming

Returns a number generated by shifting another number's bits to the left.

Syntax

BITLSHIFT(<expN1>, <expN2>)

Description

BITLSHIFT( ) is used by advanced programmers to make binary interpretations of numeric values. These values are often returned by functions prototyped with EXTERN to access resources in Windows API or other DLL files. Interpreting such values often requires analysis and manipulation of individual bits.

BITLSHIFT( ) moves each bit in the numeric value <expN1> to the left the number of times you specify in <expN2>. Each time the bits are shifted, the least significant digit (the bit farthest to the right) is set to 0, and the most significant digit (the bit farthest to the left) is lost.


BITLSHIFT( ) Example

The following example uses BITLSHIFT( ) to move the binary value of the decimal number 15 (00001111 binary) 4 bits left, resulting in the binary number 11110000, which equals 240 decimal:

? BITLSHIFT(15,4)      && Returns 240


Portability

Not supported in dBASE IV or dBASE III PLUS.


See Also

BITAND( )

BITOR( )

BITRSHIFT( )

BITSET( )

BITXOR( )

EXTERN

HTOI( )

ITOH( )


BITOR( )

See Also	Example	Portability	Windows Programming

Performs a bitwise OR operation on two numeric values and returns the result.

Syntax

BITOR(<expN1>, <expN2>)

Description

BITOR( ) is used by advanced programmers to make binary interpretations of numeric values. These values are often returned by functions prototyped with EXTERN to access resources in Windows API or other DLL files. Interpreting such values often requires analysis and manipulation of individual bits.

BITOR( ) compares bits in the numeric value <expN1> with corresponding bits in the numeric value <expN2>. When either or both bits in the same position are on (set to 1), the corresponding bit in the returned value is on. When neither element is on, the bit is off (set to 0).

	Bit 1 = 1	Bit 1 = 0
Bit 2 = 1	1	1
Bit 2 = 0	1	0


BITOR( ) Example

The following example uses BITOR( ) to make bit comparisons of the binary equivalents of the numbers 64 (1000000 binary) and 48 (110000 binary). The result of 112 has a binary value of 1110000:

? BITOR(64,48)               && Returns decimal 112


Portability

Not supported in dBASE IV or dBASE III PLUS.


See Also

BITAND( )

BITLSHIFT( )

BITRSHIFT( )

BITSET( )

BITXOR( )

EXTERN

HTOI( )

ITOH( )


BITRSHIFT( )

See Also	Example	Portability	Windows Programming

Returns a number generated by shifting another number's bits to the right.

Syntax

BITRSHIFT(<expN1>, <expN2>)

Description

BITRSHIFT( ) is used by advanced programmers to make binary interpretations of numeric values. These values are often returned by functions prototyped with EXTERN to access resources in Windows API or other DLL files. Interpreting such values often requires analysis and manipulation of individual bits.

BITRSHIFT( ) moves each bit in the numeric value <expN1> to the right the number of times you specify in <expN2>. Each time the bits are shifted, the most significant digit (the bit farthest to the left) is set to 0, and the least significant digit (the bit farthest to the right) is lost.


BITRSHIFT( ) Example

The following example uses BITRSHIFT( ) to move the binary value of the decimal number 80 (1010000 binary) 4 bits right, resulting in the binary number 00000101, which equals 5 decimal:

? BITRSHIFT(80,4)      && Returns 5

For another example of using BITRSHIFT( ), see BITAND( ).


Portability

Not supported in dBASE IV or dBASE III PLUS.


See Also

BITAND( )

BITLSHIFT( )

BITOR( )

BITSET( )

BITXOR( )

EXTERN

HTOI( )

ITOH( )


BITSET( )

See Also	Example	Portability	Windows Programming

Returns .T. if a specified bit in a numeric value is on.

Syntax

BITSET (<expN1>, <expN2>)

<expN1>

A numeric value to evaluate.

<expN2>

A decimal integer from 0 to 31 representing a position starting from the right end of <expN1>. For example, the binary representation of 3 is 00000011; bit number 0 is on, bit number 2 is off.

Description

BITSET( ) is used by advanced programmers to make binary interpretations of numeric values. These values are often returned by functions prototyped with EXTERN to access resources in Windows API or other DLL files. Interpreting such values often requires analysis and manipulation of individual bits.

BITSET( ) evaluates the number <expN1> and returns .T. if the bit in position <expN2> is on (set to 1), or .F. if it is off (set to 0).


BITSET( ) Example

The following examples use BITSET( ) to return a setting of On (.T.) or Off (.F.) for various binary bits of the number 229 (11100101 binary):

mNum=229
? BITSET(mNum,0)      && Returns .T.
? BITSET(mNum,1)      && Returns .F.
? BITSET(mNum,6)      && Returns .T.


Portability

Not supported in dBASE IV or dBASE III PLUS.


See Also

BITAND( )

BITLSHIFT( )

BITOR( )

BITRSHIFT( )

BITXOR( )

EXTERN


BITXOR( )

See Also	Example	Portability	Windows Programming

Performs a bitwise exclusive OR operation on two numeric values and returns the result.

Syntax

BITXOR(<expN1>, <expN2>)

Description

BITXOR( ) is used by advanced programmers to make binary interpretations of numeric values. These values are often returned by functions prototyped with EXTERN to access resources in Windows API or other DLL files. Interpreting such values often requires analysis and manipulation of individual bits.

BITXOR( ) compares bits in a numeric value <expN1> with corresponding bits in the numeric value <expN2>. When one (and only one) of two bits in the same position are on (set to 1), the corresponding bit in the returned value is on. In any other case, the bit is off (set to 0).

	Bit 1 = 1	Bit 1 = 0
Bit 2 = 1	0	1
Bit 2 = 0	1	0
This operation is known as exclusive OR, since one bit (and only one bit) must be set on for the corresponding bit in the returned value to be set on.


BITXOR( ) Example

The following example uses BITXOR( ) to compare the binary bit makeup of 90 (01011010) to 214 (11010110) and return the number 140 (10001100):

mNum1=90
mNum2=214
? BITXOR(mNum1,mNum2)     && Returns 140


Portability

Not supported in dBASE IV or dBASE III PLUS.


See Also

BITAND( )

BITLSHIFT( )

BITOR( )

BITSET( )

BITRSHIFT( )

HTOI( )

ITOH( )


BLANK

See Also	Example	Portability	Fields and Records

Fills fields in records with blanks.

Syntax

BLANK
[<scope>]
[FOR <condition 1>]
[WHILE <condition 2>]
[FIELDS
<field list> | [LIKE <skeleton 1>] [EXCEPT <skeleton 2>]]
[REINDEX]

<scope>

The number of records to blank. RECORD <n> identifies a single record by its record number. NEXT <n> identifies n records, beginning with the current record. ALL specifies all records. REST specifies all records from the current record to the end of the file.

FOR <condition 1>
WHILE <condition 2>

Determines which records are affected by BLANK. FOR restricts BLANK to records that meet <condition 1>. WHILE starts with the current record and continues with each subsequent record as long as <condition 2> is true.

FIELDS <field list> | LIKE <skeleton 1> | EXCEPT <skeleton 2>

The fields to blank. Without FIELDS, BLANK replaces all field values. If you specify FIELDS LIKE <skeleton 1>, the BLANK command restricts the fields that dBASE makes blank to the fields that match <skeleton 1>. Conversely, if you specify FIELDS EXCEPT <skeleton 2>, the BLANK command makes all fields blank except those whose names match <skeleton 2>.

REINDEX

Rebuilds all open indexes after BLANK finishes executing. Without REINDEX, BLANK updates all open indexes after each record is made blank.

Description

Use BLANK to replace fields in the current table with blanks. EMPTY( ) and ISBLANK( ) return .T. for a field whose value has been replaced using BLANK. BLANK fills an existing record with the same values as APPEND BLANK. Updates to open indexes are performed after each record or a set of records is blanked.

The following table shows the blank values that are displayed for fields of each data type:

Data type	Displayed value

Character	Spaces

Date	"  /  /  "

Float	Empty (nonzero) value

Logical	.F.

Numeric	Empty (nonzero) value

Binary, Memo, and OLE	No text or graphic

Use BLANK to replace logical, float, and numeric fields with true blank values, which REPLACE cannot do. When you use REPLACE to replace a numeric or float field with 0, dBASE treats it as a zero value rather than a blank value. The distinction between empty and zero values in numeric and float fields can be significant when you use commands such as AVERAGE and CALCULATE.


BLANK Example

The following example uses BLANK to reuse records that have been marked for deletion in the natural order file, by blanking the record, removing the deletion mark and entering EDIT:

USE Clients
? Reuse()
EDIT

FUNCTION Reuse
SET DELETED OFF
LOCATE FOR DELETED()
  IF .NOT. FOUND()
    APPEND BLANK
  ELSE
    BLANK            && blanks field values
    RecNum=RECNO()
    RECALL RECNO()
    GOTO RecNum
  ENDIF
RETURN .T.


Portability

Not supported in dBASE III PLUS.


See Also

APPEND

ISBLANK( )

EMPTY( )

REPLACE


BOF( )

See Also	Example	Fields and Records

Indicates if the record pointer in a table is at the beginning of the file.

Syntax

BOF( [<alias>] )

<alias>

A work area number (1 through 225), letter (A through J), or alias name. The work area letter or alias name must be enclosed in quotes.

Description

BOF( ) returns .T. when the record pointer is before the first logical record of the table in the specified work area; otherwise, it returns .F. For example, if you issue SKIP -1 when the record pointer is on the first record, BOF( ) returns .T.

If no table is open in the specified work area, BOF( ) also returns .F.


BOF( ) Example

The following example defines a form and two pushbuttons for moving the record pointer. BOF( ) and EOF( ) are used to avoid a BOF( ) or EOF ( ) error alert at either end of the table:

SET PROCEDURE TO PROGRAM(1) ADDITIVE
USE Clients
DEFINE FORM F1
DEFINE PUSHBUTTON Pb1 OF F1 AT 10,10;
  PROPERTY Text "Previous",;
    Width 8, OnClick Back
DEFINE PUSHBUTTON Pb2 OF F1 AT 10,22;
  PROPERTY Text "Next",;
    Width 8, OnClick Forward
OPEN FORM F1

FUNCTION Back
IF .NOT. BOF()
  SKIP-1
ENDIF
RETURN .T.

FUNCTION Forward
IF .NOT. EOF()
  SKIP
ENDIF
RETURN .T.


See Also

EOF( )

RECNO( )

SKIP


BOOKMARK( )

See Also	Example	Portability	Fields and Records

Returns a bookmark for the current record. Bookmarks are used in place of record number for tables that do not support record pointers (for example, Paradox and SQL tables).

Syntax

BOOKMARK( )

Description

BOOKMARK( ) returns a value for the current record in tables that do not support record pointers. When used with the GO command, bookmarks let you navigate to particular marked records.

The value returned by BOOKMARK( ) is of a special unprintable data type called bookmark. BOOKMARK( ) returns an empty bookmark if no table is open in the current work area.

Bookmark values can be used in all commands and functions that can otherwise use a record number, and with all the relational operators, =, <, <=, >, and >=, for comparisons.


BOOKMARK( ) Example

The following example lets the user press F9 while in a browse to mark a record to edit after continuing to browse and leaving the Table Editor window:

SET DBTYPE TO PARADOX
SET TALK OFF
PUBLIC Srch1
USE Customer
ON KEY LABEL F9 DO GoBack
BROWSE
GOTO Srch1
EDIT
RETURN

PROCEDURE GoBack
Srch1=BOOKMARK()
RETURN


Portability

Not supported in dBASE IV or in dBASE III PLUS.


See Also

GO

RECNO( )


BROWSE

See Also	Example	Fields and Records

Provides display and editing of records in a table format.

Syntax

BROWSE
[<scope>]
[FOR <condition 1>]
[WHILE <condition 2>]
[COLOR [<standard text>]
[, [<enhanced text>]
[, [<perimeter color>]
[, [<background color>]]]]]
[FIELDS <field 1> [<field option list 1>] |
<calculated field 1> = <exp 1> [<calculated field option list 1>]
[, <field 2> [<field option list 2>] |
<calculated field 2> = <exp 2> [<calculated field option list 2>] ...]]
[FORMAT]
[FREEZE <field 3>]
[KEY <exp 3>[, <exp 4>] [EXCLUDE]]
[LOCK <expN 2>]
[NOAPPEND]
[NODELETE]
[NOEDIT | NOMODIFY]
[NOFOLLOW]
[NOINIT]
[NOORGANIZE]
[NORMAL]
[NOTOGGLE]
[NOWAIT]
[TITLE <expC 1>]
[WIDTH <expN 3>]
[WINDOW <window name>]

<scope>

The number of records to browse. ALL specifies all records. REST specifies all records from the current record to the end of the file.

FOR <condition 1>
WHILE <condition 2>

Determines which records are affected by BROWSE. FOR restricts BROWSE to records that meet <condition 1>. WHILE starts processing with the current record and continues with each subsequent record as long as <condition 2> is true.

COLOR [<standard text>] [, [<enhanced text>] [, [<perimeter color>] [, [<background color>]]]]

Specifies the colors of standard text, enhanced text, and the perimeter of the Table Records window. To specify the colors of these elements separately, use the <standard text>, <enhanced text>, and <perimeter> options. You can also use the <background> option if you have a monitor with a uniform background.

<standard text>	Color attributes of command messages and screen output. For example, the output of the ? and @...SAY commands appear in standard text.
<enhanced text>	Color attributes of enhanced text areas, such as @...GET fields and highlighted BROWSE data cells.
<perimeter>	Color attributes of the perimeter that borders the area displaying text onscreen.
<background>	Color attributes of the background for display systems (such as monochrome) with uniform backgrounds. <background> includes two parameters: a background color and an attribute.
The <standard text> and <enhanced text> attributes include three settings: a foreground color, a background color, and an optional color for creating blended (hatched) backgrounds. Separate each setting with a forward slash (/).

For more information about color settings, see SET COLOR TO and SET COLOR OF.

FIELDS <field 1> [<field option list 1>] |
<calculated field 1> = <exp 1> [<calculated field option list 1>]
[, <field 2> [<field option list 2>] |
<calculated field 2> = <exp 2> [<calculated field option list 2>] ... ]]

Displays the specified fields, in the order they are listed, in the Table Records window. Options for <field option list 1>, <field option list 2>, which apply to <field 1>, <field 2>, and so on, affect the way these fields are displayed. These options are as follows:

\<column width>	The width of the column within which <field 1> appears when <field 1> is character type
\B = <exp 1>, <exp 2> [\F]	RANGE option; forces any value entered in <field 1> to fall within <exp 1> and <exp 2>, inclusive. RANGE REQUIRED option; the \F option prevents the cursor from leaving <field 1> and the editing session from ending until the value falls between <exp 1> and <exp 2>, inclusive
\H = <expC>	HEADER option; causes <expC> to appear above the field column in the Table Records window, replacing the field name
\P = <expC>	PICTURE option; displays <field 1> according to the PICTURE or FUNCTION clause <expC>
\R	READ-ONLY option; specifies that <field 1> is read-only and cannot be edited
\V = <condition> [\F] [\E = <expC>]	VALID option; allows a new <field 1> value to be entered only when <condition> evaluates to .T. VALID REQUIRED option; the \F option prevents the cursor from leaving <field 1> and the editing session from ending until <condition> evaluates to .T. ERROR MESSAGE option; \E = <expC> causes <expC> to appear when <condition> evaluates to .F.
\W = <condition>	WHEN option; allows <field 1> to be edited only when <condition> evaluates to .T.
Note:	You may also use the the "/" character when specifying only a single option in a field option list.

Read-only calculated fields are composed of an assigned field name and an expression that results in the calculated field value, as with Commission = Rate * Saleprice. Options for calculated fields affect the way these fields are displayed. These options are as follows:

\<column width>	The width of the column within which <calculated field 1> is displayed
\H = <expC>	Causes <expC> to appear above the calculated field column in the Table Records window, replacing the calculated field name
FORMAT

Causes BROWSE to accept and display input according to the specifications of a format file opened with SET FORMAT. Data entered must conform to any PICTURE, FUNCTION, RANGE, and VALID clauses in the format file.

FREEZE <field 3>

Restricts editing to <field 3>, although other fields are visible.

KEY <exp 3> [,<exp 4>] [EXCLUDE]

When the table has a master index, displays records whose key field value matches or comes after <exp 3>, or falls between <exp 3> and <exp 4>. EXCLUDE specifies that the range of values is non-inclusive.

LOCK <expN 2>

Keeps the first <expN 2> fields in place onscreen as you move the cursor to fields on the right.

NOAPPEND

Prevents you from adding records from the Table Records window.

NODELETE

Prevents the marking of records for deletion from within the Table Records window.

NOEDIT | NOMODIFY

Prevents you from modifying records from the Table Records window.

NOFOLLOW

When the current table has a master index, causes the cursor to remain in place when you change the key field in a record, rather than follow the record to its new location in the indexing order. Otherwise, the record pointer follows the record to its new location.

NOINIT

Causes BROWSE to execute the options specified with the previous BROWSE command. Use NOINIT if a program calls BROWSE several times or if you issue BROWSE several times from the Command window, and you want the same options. Specify the command options the first time you use BROWSE, and issue BROWSE NOINIT for subsequent use in the same session.

NOORGANIZE

Disables options to index, sort, and remove records.

NORMAL

When BROWSE is issued from an active window, displays the Table Records window in normal, full-screen mode with default or defined colors set, ignoring the defined colors of the window. When you leave BROWSE, dBASE for Windows returns you to the active window. Without NORMAL, the table records appears in the active window.

NOTOGGLE

Prevents toggling from browse mode to edit mode.

NOWAIT

Continues execution of a program after a Table Records window is displayed; otherwise, program execution is suspended until after the Table Records window is closed.

TITLE <expC 1>

Causes <expC 1> to appear as the title of the Table Records window.

WIDTH <expN 3>

Specifies the display width for character fields in the Table Records window. If a field is wider than the specified width, you can scroll the field within the specified width. The <expN 3> argument must evaluate to a positive number.

WINDOW <window name>

Activates the window <window name> and displays the table records in the window.

Description

The BROWSE command provides an interactive window-oriented environment for displaying and editing more than one record at a time. Use SET RELATION command to view fields from records in linked tables. While BROWSE is in effect and unless you specify NOTOGGLE, you can press F2 or choose View|Edit to toggle to edit mode, to display a single record.

To move between records in the BROWSE display, you can press the Up and Down arrows to move one record at a time, and PgUp and PgDn to move one window frame at a time. You can also use the window controls and the mouse, and choose from various menu options to control operations performed with BROWSE. See Displaying and Editing Table Records or the User's Guide for more information on editing data and and navigating in the Table Records window.

When you are through editing a table, press Ctrl+W to exit and save changes to the current record or choose the File|Save and Close option. To exit without saving changes to the current record, press Ctrl+Q, choose File|Abandon and Close, or double-click the Control menu. If you are using BROWSE or EDIT in a program, exiting returns program control to the command line immediately following the BROWSE or EDIT command line.


BROWSE Example

The following example uses BROWSE to view selected fields from two related tables, to add custom field headers and to specify read-only fields:

USE Contact ORDER CompCode IN SELECT()
USE Company IN SELECT()
SELECT Company
SET RELATION TO CompCode INTO Contact
BROWSE FIELDS ;
   Contact->CompCode /R /H="Company Code", ;
   Company->Company /R, ;
   Contact->Contact /R /H="Contact Person", ;
   Company->Street1 /R, Company->Street2 /R, ;
   Company->City /R, Company->State_Prov /R
CLOSE ALL


See Also

APPEND

EDIT

SET FIELDS

SET FORMAT

SET MEMOWIDTH

SET RELATION

SET WINDOW OF MEMO


CALCULATE

See Also	Example	Portability	Table Organization

Performs financial and statistical operations for values of records in the current table.

Syntax

CALCULATE <function list>
[<scope>]
[FOR <condition 1>]
[WHILE <condition 2>]
[TO <memvar list> | TO ARRAY <array name>]

<function list>

You can use one or more of the following functions:

Function	Purpose	Return Value
AVG(<expN>)	Calculates the average of the specified numeric or float expression.	CALCULATE AVG( ) returns a float value.
CNT( )	Counts the number of records of the current table.	CALCULATE CNT( ) returns a numeric value.
MAX(<expC> | <expN> | <expD>)	Calculates the maximum value of the specified numeric, float, character, or date expression.	CALCULATE MAX( ) returns the same data type as the expression specified.
MIN(<expC> | <expN> | <expD>)	Calculates the minimum value of the specified numeric, float, character, or date expression.	CALCULATE MIN( ) returns the same data type as the expression specified.
NPV(<expN 1>, <expN 2> [, <expN 3>])	Calculates the net present value of the numeric or float values in <expN 2>; <expN 1> is the periodic interest rate, expressed as a decimal; <expN 3> is the initial investment and is generally a negative number.	CALCULATE NPV( ) returns a float value.
STD(<expN>)	Calculates the standard deviation of the specified numeric or float expression.	CALCULATE STD( ) returns a float value.
SUM(<expN>)	Calculates the sum of the specified numeric or float expression.	CALCULATE SUM( ) returns a float value.
VAR(<expN>)	Calculates the variance of the specified numeric field.	CALCULATE VAR( ) returns a float value.
<scope>

The number of records to calculate. RECORD <n> identifies a single record by its record number. NEXT <n> identifies n records, beginning with the current record. ALL specifies all records. REST specifies all records from the current record to the end of the file.

FOR <condition 1>
WHILE <condition 2>

Determines which records are affected by CALCULATE. FOR restricts CALCULATE to records that meet <condition 1>, starting with the first record of the table or view and continuing until reaching the end of file. WHILE starts processing with the current record and continues with each subsequent record as long as <condition 2> is true.

TO <memvar list> | TO ARRAY <array name>

The TO <memvar list> option initializes the memory variables in <memvar list> and stores the results of CALCULATE in the variables. The TO ARRAY <array name> stores the results of CALCULATE in the existing array <array name>.

Description

CALCULATE uses one or more of the eight associated functions listed in the previous table to calculate and store sums, maximums, minimums, averages, variances, standard deviations, or net present values of specified expressions of the current table. CALCULATE can also return the count or number of records in the current table. These special functions (with the exception of the MAX( ) function) can be used only with CALCULATE.

If SET TALK is ON, CALCULATE displays the results in the result pane.

CALCULATE can use the same function on different expressions or different functions on the same expression. For instance, if your table contains a Salary field and a Bonus field, you can issue the command, CALCULATE SUM(Salary), SUM(Bonus), AVG(Salary), AVG(12*(Salary + Bonus)).

You can calculate values in a work area other than the current work area if you set a relation between the work areas.

CALCULATE stores results to memory variables or to an existing array in the order of the listed functions. If you store the results to memory variables, specify the same number of memory variables as the number of functions in the CALCULATE command line.

When you use CALCULATE TO ARRAY <array name>, dBASE for Windows stores each result to one array element. CALCULATE can store results to a multidimensional array. For example, if you use DECLARE test[3,2], CALCULATE can store values returned by up to six functions in test[1,1], test[1,2], test[2,1], test[2,2], test[3,1], test[3,2], in that order.

You can store to an array without the ARRAY keyword if you explicitly reference the array subscript(s). For example, the command line CALCULATE AVG(Salary), MAX(Salary) TO test[2], test[3] stores the average and maximum of the salary field to two array elements.

If you use CALCULATE...TO ARRAY, declare an array with at least as many elements as there are functions in the command line. Do not include the subscripts of the array in the CALCULATE command line. For instance, if the current table contains a numeric field, Numfield, and you want to store its minimum and maximum to an array minmax, you can issue the command DECLARE minmax[2] and then specify CALCULATE MIN(Numfield), MAX(Numfield) TO ARRAY minmax.

CALCULATE treats a blank numeric or float field as containing 0 and includes the field in its calculations. For example, if you calculate the average of a numeric field in a table containing ten records, five of which are blank, CALCULATE divides the sum by 10 to find the average. Furthermore, if you calculate the minimum of the same table field and five records contain numeric data and the five others are blank in the same fields, CALCULATE returns 0 as the minimum. If you want to exclude blank fields when using CALCULATE, be sure to specify a condition such as FOR .NOT. ISBLANK(numfield).

Although you can use the SUM or AVERAGE commands to find sums and averages, CALCULATE is faster because it runs through the table just once while making all specified calculations.


CALCULATE Example

The following example uses CALCULATE to place results in memory variables:

USE Company
PUBLIC AV,CN,MX,MN,VR,ST
CALCULATE AVG(Ytd_Sales),CNT(),MAX(Ytd_sales),;
  MIN(Ytd_sales),SUM(Ytd_sales),VAR(Ytd_sales),;
  STD(Ytd_sales);
  TO  AV,CN,MX,MN,VR,ST
? AV,CN,MX,MN,VR,ST
WAIT
* Display Average, Record Count, Maximum,
*   Minimum, Sum, Variance and Standard Deviation

The following example uses CALCULATE to place the results in an array:

USE Company
PUBLIC ARRAY Results[10]
CALCULATE AVG(Ytd_Sales),CNT(),MAX(Ytd_sales),;
  MIN(Ytd_sales),SUM(Ytd_sales),VAR(Ytd_sales),;
  STD(Ytd_sales);
  TO ARRAY Results
FOR i=1 TO 7
  ? i,Results[i]
NEXT i
* Display the results


Portability

Not supported in dBASE III PLUS.


See Also

AVERAGE

DECLARE

MAX( )

MIN( )

SET FIELDS

SET RELATION

SUM


CANCEL

See Also	Example	Programs

Halts program execution, closes program files, clears private memory variables, and returns control to the Command window.

Syntax

CANCEL

Description

Use CANCEL to cancel program execution. When dBASE encounters CANCEL in a program file, it ignores any text on lines following CANCEL, halting program execution. You can also issue CANCEL in the Command window when a program is suspended (such as with SUSPEND) to cancel execution of the suspended program. When dBASE halts program execution, it clears all private memory variables for that program and returns control to the Command window.


CANCEL Example

The following example uses CANCEL to halt program execution when the Exit pushbutton within a form is clicked with the mouse:

DEFINE FORM Main FROM 2,2 TO 20,30;
  PROPERTY MDI .F.
DEFINE PUSHBUTTON Exit OF Main AT 13,10;
  PROPERTY;
    TEXT  "Exit",;
    OnClick {;Cancel}
READMODAL(Main.Exit)


See Also

DO

QUIT

RESUME

RETRY

RETURN

SUSPEND


CATALOG( )

See Also	Example	Portability	Table Basics

Returns the name of the current catalog file.

Syntax

CATALOG( )

Description

CATALOG( ) returns the name of the current catalog opened with the SET CATALOG TO command or the Navigator. If no catalog is currently open, CATALOG( ) returns an empty string ("").


CATALOG( ) Example

The following example uses CATALOG( ) to determine the name of the currently open catalog:

SET CATALOG TO Learn
catname = CATALOG()
USE (catname) IN SELECT() NOUPDATE AGAIN


Portability

Not supported in dBASE IV or in dBASE III PLUS.


See Also

CREATE CATALOG

SELECT

SET( )

SET CATALOG

SET TITLE

USE


CD

See Also	Example	Portability	Disk and File Utilities

Changes the current default drive or directory.

Syntax

CD
[<path>]

<path>

A character expression indicating the default path. To specify a root path, start <path> with a backslash (\) or the root directory (as with C:\). If <path> does not begin with \, .. (two periods), or the root directory, dBASE begins the path with the current directory.

Description

CD works like the DOS commands CD and CHDIR. It lets you change the current working drive and directory without exiting to DOS. Use CD to change the current working directory to any valid drive and path. If you are unsure whether a drive is valid, use VALIDDRIVE( ) before issuing CD. The current directory appears in the File Viewer window.

CD .. (two periods) changes the directory to the directory one level above the current directory. CD without the option <path> displays the current drive and directory path.

Another way to access files on different directories is with the command SET PATH. You can specify one or more search paths, and dBASE uses these paths to locate files not on the current directory. Use SET PATH when an application's files are in several directories.

CD works like SET DIRECTORY, except SET DIRECTORY TO (with no argument) returns you to the default working directory, instead of displaying the current directory. See SET DIRECTORY for more information.


CD Example

The following example saves the current directory, then changes directory several times, and finally returns to the original directory:

* This example assumes that
* directories were created by:
MD D:\Project
MD D:\Project\Programs
MD D:\Project\Data
MD D:\Project\Backup
CD D:\Project\Programs
MD C:\Editor

Olddir=SET("DIRECTORY")
? SET("DIRECTORY")      && D:\Project\PROGRAMS
CD ..
? SET("DIRECTORY")      && D:\Project
CD Data
? SET("DIRECTORY")      && D:\Project\Data
CD ..\BACKUP
? SET("DIRECTORY")      && D:\Project\BACKUP
CD C:\Editor
? SET("DIRECTORY")      && C: changes to C:\Editor
CD &Olddir
? SET("DIRECTORY")      && D:\Project\Programs


Portability

Not supported in dBASE IV or dBASE III PLUS, but SET DIRECTORY is supported in dBASE IV.


See Also

MKDIR

SET DEFAULT

SET DIRECTORY

SET PATH

VALIDDRIVE( )


CDOW( )

See Also	Example	Date and Time Data

Returns the day of the week corresponding to a specified date expression as a character string.

Syntax

CDOW(<expD>)

<expD>

The date expression whose corresponding weekday name to return.

Description

CDOW( ) returns a character string containing the name of the day of the week on which a date falls. To return the day of the week as a number from 1 to 7, use DOW( ).

Enter <expD> in the current date format as determined by SET DATE, DBASEWIN.INI, or the International option of the Windows Control Panel (in that order). That is, SET DATE settings override those in DBASEWIN.INI, and settings in DBASEWIN.INI override those in the Windows Control Panel. Be sure <expD> matches the date format in use when your program runs.

If you pass an invalid date to CDOW( ), dBASE converts the date to a valid one and returns the weekday name of that date. If you pass an empty or non-date expression delimited with braces ({ }) to CDOW( ), it returns "Unknown". If you pass a non-date expression or an expression that is not delimited with braces to CDOW( ), it returns an error.


CDOW( ) Example

The following example uses CDOW( ) to return the day of the week for a date type memory variable.

CLEAR
SET TALK OFF
Turncen={12/31/1999}
? CENTER("Welcome in the new century on")
? CENTER(CDOW(Turncen)+ " night,")
? CENTER(CMONTH(Turncen)+ " " +;
  LTRIM(STR(DAY(Turncen)))+ "st " +;
  LTRIM(STR(YEAR(Turncen))))

This code returns:

*           Welcome in the new century on
*                   Friday night,
*                December 31st 1999

CDOW( ) is useful for filtering or manipulating data by the day of the week. For example, if you wanted to determine the number of transactions that occurred on weekends, the following example would apply.

USE Flights
SET EXACT OFF
COUNT FOR CDOW(Date) = "S" TO Weekend
? Weekend 	&& Returns the number of weekend;
flights

To list all Wednesday flights from the Flights table.

SET FILTER TO CDOW(Date)="Wednesday"
LIST OFF	&& "OFF" suppresses record numbers


See Also

CMONTH( )

DATE( )

DAY( )

DOW( )

SET CENTURY

SET DATE

YEAR( )


CEILING( )

See Also	Example	Portability	Numeric Data

Returns the nearest integer that is greater than or equal to a specified number.

Syntax

CEILING(<expN>)

<expN>

A numeric or float number, from which to determine and return the integer that is greater than or equal to it.

Description

CEILING( ) returns the nearest integer that is greater than or equal to <expN>. If you pass a number with any digits other than 0 as decimal digits, CEILING( ) returns the nearest integer that is greater than the number. If you pass an integer to CEILING( ), or a number with only 0s for decimal digits, it returns the integer equal to the number.

For example, if the default number of decimal places is 2,

CEILING(2.10) returns 3.00

CEILING(--2.10) returns --2.00

CEILING(2.00) returns 2.00

CEILING(2) returns 2

CEILING(--2.00) returns --2.00

See the table in the description of INT( ) that compares INT( ), FLOOR( ), CEILING( ), and ROUND( ).

The value returned by CEILING( ) has the same data type as <expN>.


CEILING( ) Example

The following example uses CEILING( ) to return the passed value, rounded up to the next whole number:

SET TALK OFF
msrp = 79.95
cost = 45.50
percent = cost/msrp * 100
? "The cost is " + STR(CEILING(percent),2,0) + ;
  "% of the retail price."
SET TALK ON

See INT( ) for another example of CEILING( ).


Portability

Not supported in dBASE III PLUS. In dBASE IV, CEILING( ) doesn't display any decimal places, regardless of the value of SET DECIMALS.


See Also

FLOOR( )

INT( )

ROUND( )


CENTER( )

See Also	Example	Portability	String Data

Returns a character string that contains a string centered in a line of specified length.

Syntax

CENTER(<expC> | <memo field> [, <length expN> [, <pad expC> ]])

<expC> | <memo field>

The text to center.

<length expN>

The length of the resulting line of text, which must be less than 32766, the maximum length of a string. If <length expN> is not specified, CENTER( ) assumes a line length of 80 characters.

<pad expC>

The single character to pad the string with if <length expN> is greater than the number of characters in <expC> | <memo field>. If <length expN> is equal to or less than the number of characters in <expC> | <memo field>, <pad expC> is ignored.

If <pad expC> is more than one character, CENTER( ) uses only the first character. If <pad expC> is not specified, CENTER( ) pads with spaces.

Description

CENTER( ) returns a character expression or a memo field with the requisite number of leading and trailing spaces to center it in a line that is a specified number of characters wide. If you specify a memo field, CENTER( ) centers the full text of the field, not each line of text.

If you specify a padding character, CENTER( ) pads either side of the character expression or memo field with that character (or with the first character, if you specify more than one) rather than with spaces.

To create the resulting string, CENTER( ) performs the following steps.

Subtracts the length of <expC> or <memo field> from <length expN>

Divides the result in half and rounds up if necessary

Pads <expC> or <memo field> on either side with that number of spaces or the first character in <pad expC>

If the length of <expC> or <memo field> is greater than <length expN>, CENTER( ) does the following:

Subtracts <length expN> from the length of <expC> or <memo field>

Divides the result in half and rounds up if necessary

Truncates both sides of <expC> or <memo field> by that many characters

When the result of subtracting the length of <expC> or <memo field> from <length expN> is an odd number, CENTER( ) pads one less space on the left if the difference is positive, or truncates one less character on the left if the difference is negative.


CENTER( ) Example

The following example uses CENTER( ) to position header text displayed above a listing of the Company table. Nested counting loops display 8 records at a time with header information in the results pane of the Command window:

SET TALK OFF
USE Clients
CLEAR
DO WHILE .NOT. EOF()
  ? CENTER("Clients Database Report",80)
  ?
  ? CENTER("Run on " + CDOW(DATE()) + ;
      " " + DTOC(DATE()),80,"-")
  ? "Company" AT 2,"Phone" AT 40,"Balance Date" AT 60
  ? "*******" AT 2,"*****" AT 40,"************" AT 60
  Cnt=1
  DO WHILE Cnt<9 .AND. .NOT. EOF()
    ? Company AT 2, Phone AT 40, CDOW(Baldate)+",";
      + DTOC(Baldate) AT 60
    SKIP
    Cnt=cnt+1
  ENDDO
  ?
WAIT
CLEAR
ENDDO
CLOSE ALL


Portability

Not supported in dBASE IV or dBASE III PLUS.


See Also

LEN( )

REPLICATE( )

SET MEMOWIDTH

TRANSFORM( )


CERROR( )

See Also	Example	Portability	Error Handling and Debugging

Returns the number of the last compiler error.

Syntax

CERROR( )

Description

Use CERROR( ) before executing a new program to test whether the source code compiles successfully. If no compiler error occurs, CERROR( ) returns 0. CERROR( ) is updated each time you or dBASE compile a program or format file. CERROR( ) is not affected by warning messages generated by compiling.

Use CERROR( ) in a program file. If you issue ? CERROR( ) in the Command window, it returns 0. (This is because dBASE is compiling the "? CERROR( )" command itself, which does not cause a compiler error.)

See the table in the description of ERROR( ) that compares ERROR( ), MESSAGE( ), DBERROR( ), DBMESSAGE( ), SQLERROR( ), SQLMESSAGE( ), and CERROR( ).

See Error Messages for a listing of all error messages.


CERROR( ) Example

The following program segment uses CERROR( ) in a DO WHILE loop to make the user edit the program until it compiles successfully:

DO WHILE .T.
  Clear
    MODIFY COMMAND USER.PRG
    ON ERROR ? ERROR(), MESSAGE(), CERROR()
    COMPILE USER.PRG
    IF CERROR()>0
      ?
      WAIT "Your program did not compile. ;
      press a key to edit your .PRG."
      LOOP
    ELSE
      EXIT
    ENDIF
ENDDO


Portability

Not supported in dBASE III PLUS.


See Also

COMPILE

DBERROR( )

DBMESSAGE( )

ERROR( )

MESSAGE( )

ON ERROR


CHANGE

See Also	Example	Fields and Records

Provides display and editing of data in the current table, one record at a time.

Syntax

CHANGE
[<starting record expN 1> | <bookmark>]
[<scope>]
[FOR <condition 1>]
[WHILE <condition 2>]
[COLOR [<standard text>]
[, [<enhanced text>]
[, [<perimeter color>]
[, <background color>]]]]
[COLUMNAR]
[COMPRESS]
[FIELDS <field 1> [<field option list 1>] |
<calculated field 1> = <exp 1> [<calculated field option list 1>]
[, <field 2> [<field option list 2>] |
<calculated field 2> = <exp 2> [<calculated field option list 2>]  ... ]]
[FORMAT]
[FREEZE <field 3>]
[KEY <exp 3> [, <exp 4>]]
[LOCK <expN 2>]
[NOAPPEND]
[NODELETE]
[NOEDIT | NOMODIFY]
[NOFOLLOW]
[NOINIT]
[NORMAL]
[NOTOGGLE]
[NOWAIT]
[TITLE <expC 1>]
[WIDTH <expN 3>]
[WINDOW <window name>]

Description

CHANGE and EDIT are equivalent commands. See EDIT for a complete discussion of these commands. CHANGE without the FIELDS option displays all fields of the current record.


CHANGE Example

See EDIT for an example of CHANGE, substituting CHANGE for EDIT in the example.


See Also

BROWSE

EDIT


CHANGE( )

See Also	Example	Portability	Shared Data

Returns .T. if another user has changed a record since it was read from a table file.

Syntax

CHANGE([<alias>])

<alias>

A work area number (1 through 225), letter (A through J), or alias name. The work area letter or alias name must be enclosed in quotes. If you don't include <alias>, CHANGE( ) returns information on the current table.

Description

Use CHANGE( ) to determine if another user has made changes to a record since it was read from the table file. If the record has been changed, you might want to display a message to the user before allowing the user to continue.

For CHANGE( ) to return information, the current or specified alias table must have a _dbaselock field. Use CONVERT to add a _dbaselock field to a table. If the table does not contain a _dbaselock field, CHANGE( ) returns .F.

CHANGE( ) compares the counter in the workstation's memory image of _dbaselock to the counter stored on disk. If they are different, the record has changed, and CHANGE( ) returns .T.

You can reset the value of CHANGE( ) to .F. by moving the record pointer. GOTO RECNO( ) rereads the current record's _dbaselock field, and a subsequent CHANGE( ) returns .F., unless another user has changed the record in the interim between moving to it and issuing CHANGE( ).

Note:	CHANGE( ) does not test SQL databases or Paradox tables.


CHANGE( ) Example

The following example opens the Company table, takes the user to a selected record, and opens a form to review the year to date data. Within the form, ReviewYtd, the user can reset that value. (The ReviewYtd form definition is not shown). On leaving the form, the program uses CHANGE( ) to determine if another user has changed the current record. If not, REPLACE updates the value of the YTD_Sales field:

USE COMPANY
SEEK mCompany
OPEN FORM ReviewYtd
IF .NOT. CHANGE()
* Has another user changed this record?
  REPLACE YTD_Sales WITH mYSales
ELSE
  GOTO RECNO()  && Re-read this record
ENDIF


Portability

Not supported in dBASE III PLUS.


See Also

CONVERT

FLOCK( )

LKSYS( )

RLOCK( )

SET EXCLUSIVE

SET REFRESH


CHARSET( )

See Also	Example	Portability	Environment

Returns the name of the character set the current table or a specified table is using. If no table is open and you issue CHARSET( ) without an argument, it returns the global character set in use.

Syntax

CHARSET( [<alias>] )

<alias>

A work area number (1 through 225), letter (A through J), or alias name. The work area letter or alias name must be enclosed in quotes.

Description

Use CHARSET( ) to learn which character set the current table or a specified table is using. If you do not pass CHARSET( ) an argument, it returns the name of the character set of the current table or, if no tables are open, the global character set in use. CHARSET( ) also returns information on Paradox and SQL databases.

The character set a table's data is stored in depends on the language driver setting that was in effect when the table was created. With dBASE for Windows, you can choose the language driver that applies to your dBASE data in the [CommandSettings] section in the DBASEWIN.INI file. For more information on character sets and language drivers, see Appendix C in the Programmer's Guide.

The value CHRSET( ) returns is a subset of the value LDRIVER( ) returns. For more information, see LDRIVER( ).


CHARSET( ) Example

This example shows the CHARSET( ) function and a sample response:

? CHARSET()  && Returns DOS:437


Portability

Not supported in dBASE IV or dBASE III PLUS.


See Also

ANSI( )

LDRIVER( )

OEM( )

SET LDCHECK


CHOOSEPRINTER( )

See Also	Example	Portability	Printing

Opens the Print Setup dialog box for choosing a printer or specifying print options, and resets the appropriate system memory variables for the printer or print options you specify. Returns true (.T.) if you exit the dialog box by choosing OK, and false (.F.) if you choose Cancel.

Syntax

CHOOSEPRINTER(<title expC>)

<title expC>

Specifies a title to display in the Print Setup dialog box.

Description

Use CHOOSEPRINTER( ) to select a new printer or change printer options using the Print Setup dialog box. You can also open the Print Setup dialog box by choosing File|Print Setup. In the Print Setup dialog box, you can select a new installed printer or select options such as paper size, paper source, and orientation (portrait or landscape).

CHOOSEPRINTER( ) modifies the value of the SET PRINTER TO setting, and of the _pdriver, _plength, and _porientation memory variables.

For a printer to appear in the Specific Printer list, you must have installed it previously through the Windows Print Manager. You can also change printer drivers in Windows with the Printers program of the Windows Control Panel.

To activate a specific printer driver, you can also use _pdriver.


CHOOSEPRINTER( ) Example

CHOOSEPRINTER( ) opens the print setup dialog box. Newprinter returns true if the printer was reset:

Newprinter=CHOOSEPRINTER()
Newprinter=CHOOSEPRINTER("Choose a dot matrix"+;
  " printer")


Portability

Not supported in dBASE III PLUS or dBASE IV.


See Also

_pdriver

CLOSE...

SET DEVICE

SET PRINTER


CHR( )

See Also	Example	Expressions and Type Conversion

Returns the character equivalent of a specified ASCII value.

Syntax

CHR(<expN>)

<expN>

The numeric ASCII value, from 0 to 255, inclusive, whose character equivalent to return.

Description

CHR( ) is the inverse function of ASC( ). CHR( ) accepts an ASCII value and returns its character, while ASC( ) accepts a character and returns its ASCII value.

You can use CHR( ) with ASC( ) to convert an ASCII value to its character equivalent. See the ASCII table in Appendix E in the Language Reference for a listing of ASCII values and their corresponding characters.

CHR(7) returns a tone, or beep. Use SET BELL TO [<frequency expN>, <duration expN>] to set the frequency and duration of the tone CHR(7) returns.


CHR( ) Example

The following example uses CHR( ) to display a special character on screen. Special characters are not available on the keyboard but can be printed or displayed with the CHR( ) function (example assumes default OEM character set).

? "The total is 50" + CHR(241) + "2"
* The ASCII value 241 displays a plus/minus symbol

Printer control codes can be sent to a printer with the ?? command and CHR( ) as follows.

SET PRINT ON
?? CHR(27) + "E"
* Resets an HP LaserJet to default mode by
* sending ESCAPE (CHR(27)) plus a control code.
* Could also be sent ?? CHR(27) + CHR(69).


See Also

ANSI( )

ASC( )

OEM( )

SET BELL


CLASS...ENDCLASS

See Also	Example	Portability	Objects

Declares a custom class and specifies the member variables and functions for that class.

Syntax

CLASS <class name> [(<parameters>)] [CUSTOM]
[PARAMETERS <parameters>]
[OF <superclass name> [(<parameters>)]]
[<constructor code>]
[<member functions>]
ENDCLASS

CUSTOM

Specifies that the new object is a custom control. For infomation on custom controls, see Chapter 15 of the Programmer's Guide.

<class name>

The name you give to the new object class.

OF <superclass name>

Specifies that the class you create inherits the properties and methods of <superclass name>. For example, you can give your new object class all the properties and methods of the listbox class or another class you create with CLASS...ENDCLASS.

<constructor code>

Code that is executed when you create an object of class <class name>. Constructor code includes all commands between the CLASS and ENDCLASS keywords except code in <member functions>.

<member functions>

Procedures and functions that you declare between the CLASS and ENDCLASS keywords. These subroutines make up the methods of the new class.

Description

Use CLASS...ENDCLASS to create a new object class.

A class is a specification, or template, for a type of object. dBASE for Windows provides many standard classes, such as Form and Entryfield; for example, when you create a form, you are creating a new form object that has the standard properties and methods from the Form class. However, when you declare a custom class with CLASS...ENDCLASS, you specify the properties and methods that objects derived from the new class will have.

You create properties for the new class with <constructor code>. Constructor code executes when you create an object of the class. Although constructor code can contain any dBASE commands, it usually contains only property and method assignment statements.

When you create a new property in a class declaration, preface the property name with the This keyword. This references the object you create. For example, the following code sample includes a class declaration. The declaration uses This to specify that TagName, a new property, is a member of the new class TableFile.

xFile = NEW TableFile()
? xFile.TagName
? xFile.FileNameId()

CLASS TableFile
This.TagName = "XORDER"
FUNCTION FileNameId	&& Custom method.
RETURN DBF()
ENDCLASS

You create custom methods for the class with <member functions>, which can consist of procedure declarations or user-defined function declarations. FUNCTION FileNameId is an example of a custom class.


CLASS...ENDCLASS Example

The following example uses CLASS...ENDCLASS to define a class of objects within a form that displays pictures from the Pictures table in the SAMPLES directory. This example is an extract from PICTURES.WFM in the SAMPLES directory:

** END HEADER -- do not remove this line*

* Generated on 06/27/94

*

LOCAL f

f = NEW PFORM()

f.Open()

CLASS PFORM OF FORM

   this.HelpFile = ""

   this.Width =         97.00

   this.Maximize = .F.

   this.Minimize = .F.

   this.Height =         24.82

   this.Left =         19.40

   this.Text = "Pictures Form"

   this.Top =          0.53

   this.ColorNormal = "BG/B"

   this.OnOpen = {;create session}

   this.View = "PICTURES.QBE"

   this.HelpId = ""

   DEFINE PUSHBUTTON SOUND OF THIS;

       PROPERTY;

         Width         18.00,;

         Default .T.,;

         OnClick {;play sound binary pictures->sound},;

         Height          3.00,;

         Left          4.00,;

         Text "Sound",;

         Top          8.00,;

         ColorNormal "N/W",;

         FontName "Courier",;

         FontSize         16.00

   DEFINE LISTBOX THINGS OF THIS;

       PROPERTY;

         Width         18.40,;

         DataSource "FIELD NAME",;

         ColorHighLight "W+/B",;

         Height          5.47,;

         Left          3.60,;

         Top         13.41,;

         ColorNormal "bg+/b",;

         FontName "Fixedsys",;

         FontSize         11.25,;

         ID        800

   DEFINE IMAGE PICTURE OF THIS;

       PROPERTY;

         Width         62.00,;

         DataSource "BINARY PICTURES->BITMAPOLE",;

         Height         18.00,;

         Left         25.00,;

         Top          5.00,;

         ID         88

   DEFINE TEXT TITLE OF THIS;

       PROPERTY;

         Width         70.00,;

         Height          4.30,;

         Left         20.00,;

         Text "Sights and Sounds",;

         Top          0.00,;

         ColorNormal "gr+/b",;

         FontName "Serif",;

         Border .F.,;

         FontSize         32.00

ENDCLASS

PROCEDURE Sound_OnClick

PLAY SOUND Binary Pictures->Sound

PROCEDURE ClosePictures

USE IN Pictures

FORM.CLOSE()


Portability

Not supported in dBASE IV or dBASE III PLUS.


See Also

DEFINE

REDEFINE


CLASS ARRAY

See Also	Example	Classes

An object that stores multiple memory variables in locations you can access individually.

Properties

The following table lists the properties of the Array class. For more information on each property, see Properties.

Property	Default	Description

Add( )	N/A	Adds elements to a one-dimensional array object

ClassName	ARRAY	Identifies the array class

Delete( )	N/A	Deletes an element from a one-dimensional array object, or deletes a row or column from a two-dimensional array object

Dimensions	0	Specifies the number of dimensions in the array object

Dir( )	N/A	Stores the name, size, date stamp, time stamp, and DOS attribute(s) of files to an array object

Element( )	N/A	Returns the number of a specified element in the array object

Fields( )	N/A	Stores structure information of the current table to the array object

Fill( )	N/A	Inserts a specified value into one or more locations in an array object

Grow( )	N/A	Adds elements to the array object

Insert( )	N/A	Inserts an element into a one-dimensional array object, or inserts a row or column of elements into a two-dimensional array object

Resize( )	N/A	Increases or decreases the number of elements in the array object

Scan( )	N/A	Searches an array object for a specified value

Size	N/A	Increases or decreases the number of elements in an array object

Sort( )	N/A	Sorts the elements in a one-dimensional array object, or sorts rows in a two-dimensional array object

Subscript( )	N/A	Returns the row number or the column number of a specified element in an array object

Description

Use an array object to store multiple related items in memory. For more information on using array objects, see Chapter 10 in the Programmer's Guide.

When you create an array object with the NEW operator, you can specify two parameters:

<rows expN>--The number of elements if the array object is one-dimensional, or the number of rows if the array object is two-dimensional.

<columns expN>--The number of elements in each row. You specify <columns expN> only if the array object is two-dimensional.

For example, the following command creates a two-dimensional array object with ten rows and twenty elements in each row:

MyArray = NEW ARRAY(10, 20)

Note:	You cannot use DEFINE to create an array object; instead, use the NEW operator. The NEW operator creates an array object in the following example:

Array1 = NEW ARRAY(10, 20)	&& Creates array object.
DEFINE ARRAY Array1	&& Returns an error

You can also create an array object with the DECLARE command:

DECLARE Array1[10]  && Creates an array object Array1


CLASS ARRAY Example

The following example creates a form with one button for each field in a table. Field names are stored in an array object named AButtons:

LOCAL loFields
loFields = NEW FieldForm()
loFields.OPEN()
CLASS FieldForm OF FORM
  USE ?
  * create a button for each field
  AButtons = NEW ARRAY(1)
    FOR i = 1 TO FCOUNT()
      AButtons.ADD(1)
      AButtons[i]         = NEW PUSHBUTTON(THIS)
      AButtons[i].text    = FIELD(i)
      AButtons[i].top     = i * 2
      AButtons[i].left    =  5
      AButtons[i].width   = 20
    NEXT
ENDCLASS


See Also

DECLARE

PUBLIC


CLASS BROWSE

See Also	Example	Classes	Forms

A data-editing tool that displays multiple records in row-and-column format, or single records in columnar or edit format.

Properties

The following table lists the properties of the Browse class. For more information on each property, see Properties.

Property	Default	Description

Alias	Empty string	Determines the table file that is accessed

Append	.T.	Determines if records can be added

Before	N/A	Specifies which object the browse object precedes in the tabbing order of the parent form

ClassName	BROWSE	Identifies the browse object's class

ColorNormal	N/W	Sets the color of the browse object

Delete	.T.	Determines if records can be marked for deletion

Enabled	.T.	Determines if the browse object can be selected

Fields	Empty string	Specifies the fields to display, and the field options to apply to each field

FieldWidth	N/A	Specifies the width of a character field in a browse object

Follow	.T.	Determines if the display follows a record to its new index order when a key field value is changed

FontBold	.T.	Determines if characters are displayed in bold type

FontItalic	.F.	Determines if characters are displayed in italic type

FontName	MS Sans Serif	Specifies the font to apply to displayed characters

FontSize	N/A	Specifies the size of the font in points

Height	N/A	Sets the height

HelpFile	Empty string	Identifies a Windows Help file (.HLP) that contains context-sensitive Help topics

HelpID	Empty string	Specifies the context string or context number of a Help topic in a Windows Help file (.HLP)

hWnd	N/A	Returns the browse object handle

ID	-1	Identifies the browse object with a numeric value

Left	N/A	Sets the position of the left border

Mode	0	Specifies the display format

Modify	.T.	Determines if the user can alter records

MousePointer	0	Specifies the mouse pointer type when the pointer is over the browse object

Move( )	N/A	Moves or sizes the browse object

Name	BROWSE1	Specifies the browse object's name

OnAppend	N/A	Executes a subroutine when a record is added to the table

OnChange	N/A	Executes a subroutine when the user changes a value

OnGotFocus	N/A	Executes a subroutine when the browse object receives focus

OnHelp	N/A	Executes a subroutine when the user presses F1

OnLeftDblClick	N/A	Executes a subroutine when the user double-clicks the browse object

OnLeftMouseDown	N/A	Executes a subroutine when the user clicks the browse object with the left mouse button

OnLeftMouseUp	N/A	Executes a subroutine when the user releases the left mouse button while the pointer is over the browse object

OnLostFocus	N/A	Executes a subroutine when focus is removed

OnMiddleDblClick	N/A	Executes a subroutine when the user double-clicks the browse object with the middle mouse button

OnMiddleMouseDown	N/A	Executes a subroutine when the user clicks the browse object with the middle mouse button

OnMiddleMouseUp	N/A	Executes a subroutine when the user releases the middle mouse button while the pointer is on the browse object

OnMouseMove	N/A	Executes a subroutine when the user moves the mouse over the browse object

OnNavigate	N/A	Executes a subroutine when the user moves to a different record

OnOpen	N/A	Executes a subroutine when the parent form is opened

OnRightDblClick	N/A	Executes a subroutine when the user double-clicks the browse object with the right mouse button

OnRightMouseDown	N/A	Executes a subroutine when the user clicks the browse object with the right mouse button

OnRightMouseUp	N/A	Executes a subroutine when the user releases the right mouse button while the pointer is on the browse object

Parent	N/A	An object reference that points to the parent form

Release( )	N/A	Removes the browse object definition from memory

SetFocus( )	N/A	Gives focus to the browse object

ShowDeleted	.T.	Determines if the browse object's delete box column is displayed

ShowHeading	.T.	Determines if field name headings are displayed at the top of each column in the browse object

ShowRecNo	.T.	Determines if the browse object's record number column is displayed

StatusMessage	Empty string	Specifies a message to display on the status bar

TabStop	.T.	Determines if the user can give object focus to the browse object by pressing Tab or Shift+Tab

Text	BROWSE	Specifies a character string to display on the caption bar

Toggle	.T.	Determines if the user can switch between display modes

Top	N/A	Sets the position of the top border

Visible	.T.	Determines whether the browse object is visible or hidden

When	.T.	Specifies a condition that must evaluate to true before the user can give focus to the browse object

Width	N/A	Sets the width

Description

Use a browse object to allow viewing and editing of records from a table. A browse object offers most the capabilities and options of the BROWSE and EDIT commands.

To display data one record at a time (single-record format), set the Mode property to 1 or 2. Setting Mode to 1 specifies form layout, and setting Mode to 2 specifies columnar layout. To display data in multiple-record format, set Mode to 0. When you set the Toggle property to true, the user can switch between all three formats by pressing F2.

Two properties specify which table is displayed in the browse object.

The View property of the parent form

The Alias property of the browse object

The View property bases the form on a query (QBE), which is automatically invoked when you open the form. The Alias property determines which table opened by the query is displayed. An alias is an alternate name given to an open table file, and can consist of.

A name you specify with the ALIAS option of the USE command.

The table file name (if you did not assign the table an alias).

The letter that corresponds to the work area of the table.

The number, preceded by an underscore character (_), that corresponds to the work area of the table.

A browse object is often used to display child records in a multi-table form. For example, when the parent form is based on a query that opens two or more files in a parent-child relation, you can specify the child table with the Alias property. For more information on aliases and work areas, see Alias, SELECT, and USE.

You can specify individual fields to display with the Fields property. For example, if the browse object's form is based on a query, you use Fields to display fields from any of the query's tables. (You must specify a file with Alias before you can use Fields.)

You determine a browse object's dimensions with the FROM...TO clause of its DEFINE command or with its Height and Width properties.

When you create a browse object with the NEW operator, you can specify two parameters:

<parent form reference>--An object reference pointing to the parent form.

<object name expC>--A character string assigned to the Name property of the new browse object. This value is optional.

For example, the following commands create a form and a browse object to display in it:

MyForm = NEW FORM()
MyBrow = NEW BROWSE(MyForm, "OurBrow")

The Name property of the new browse object contains "OurBrow".

Note:	You can specify a value for the View property with the Choose View dialog box, which lets you choose query or a table. To access the Choose View dialog box, click on the Tool Button next to the View item in the Object Inspector.

You can specify an Alias value with the Choose Alias dialog box, which lists all open tables. To access the Choose Alias dialog box, click on the Tool Button next to the Alias item in the Object Inspector.

You can specify a Fields value with the Choose Field dialog box, which lists fields from all open tables. To access the Choose Field dialog box, click on the Tool Button next to the Fields item in the Object Inspector.

If you use the Object Inspector, do not enclose the View, Alias, or Fields value with quotation marks. If you do, dBASE displays an error message.


CLASS BROWSE Example

The following example defines a form that contains a browse object of the Contact table. The Exit pushbutton gives the user an alternative way to close the form:

LOCAL f
f=NEW EntryForm()
f.OPEN()
CLASS EntryForm OF FORM
  this.Top=2
  this.Left=2
  this.Width=38
  this.Height=20
  this.View = "Contact.DBF"
  this.Text= "Edit as Required"
  DEFINE BROWSE Br1 OF THIS;
    PROPERTY;
      Alias "Contact",;
      Fields "CompCode, Contact",;
      Top 4,;
      Left 3,;
      Width 32,;
      Height 12,;
      Delete .T.,;
      StatusMessage "Contact Table Browse",;
      Toggle .F.  && Disables switching views with F2
  DEFINE TEXT Text1 OF THIS;
    PROPERTY;
      Text "Contact Table Points of Contact",;
      Width 38,;
      Top 1,;
      Left 0,;
      Alignment 1,;
      Height 2.50,;
      FontSize 12.00,;
      FontBold .T.
  DEFINE PUSHBUTTON Exit OF THIS;
    PROPERTY Text "Exit", Height 2,;
      Top 17, Left 14,;
      OnClick {;Form.Close()}
ENDCLASS


See Also

DEFINE

BROWSE

EDIT

OPEN FORM

RELEASE OBJECT


CLASS CHECKBOX

See Also	Example	Classes	Forms

An object that lets users toggle logical values between true (.T.) and false (.F.).

Properties

The following table lists the properties of the Checkbox class. For more information on each property, see Properties.

Property	Default	Description

Before	N/A	Specifies which object the check box precedes in the tabbing order of the parent form

ClassName	CHECKBOX	Identifies the check box class

ColorNormal	N/W	Sets the color of the check box

DataLink	Empty string	Links the check box to a field

Enabled	.T.	Determines if the check box can be selected

FontBold	.F.	Determines if characters in the check box prompt are displayed in bold type

FontItalic	.F.	Determines if characters are displayed in italic type

FontName	MS Sans Serif	Specifies the font to apply to displayed characters

FontSize	N/A	Specifies the size of the font in points

FontStrikeOut	.F.	Determines if characters are displayed in strikeout type

FontUnderline	.F.	Determines if characters are displayed in underlined type

Group	.F.	Starts an object group in the parent form

Height	N/A	Sets the height

HelpFile	Empty string	Identifies a Windows Help file (.HLP) that contains context-sensitive Help topics

HelpID	Empty string	Specifies the context string or context number of a Help topic in a Windows Help file (.HLP)

hWnd	N/A	Specifies the check box handle

ID	-1	Identifies the check box with a numeric value

Left	N/A	Sets the position of the left border

MousePointer	0	Specifies the mouse pointer type when the pointer is over the check box

Move( )	N/A	Moves or sizes the check box

Name	CHECKBOX1	Specifies the check box name

OldStyle	.F.	Determines if the check box is displayed in the default Windows style or in Borland style

OnChange	N/A	Executes a subroutine when the user toggles between values

OnGotFocus	N/A	Executes a subroutine when the check box receives focus

OnHelp	N/A	Executes a subroutine when the user presses F1

OnLeftDblClick	N/A	Executes a subroutine when the user double-clicks the check box

OnLeftMouseDown	N/A	Executes a subroutine when the user clicks the check box with the left mouse button

OnLeftMouseUp	N/A	Executes a subroutine when the user releases the left mouse button while the pointer is over the check box

OnLostFocus	N/A	Executes a subroutine when focus is removed

OnMiddleDblClick	N/A	Executes a subroutine when the user double-clicks the check box with the middle mouse button

OnMiddleMouseDown	N/A	Executes a subroutine when the user clicks the check box with the middle mouse button

OnMiddleMouseUp	N/A	Executes a subroutine when the user releases the middle mouse button while the pointer is on the check box

OnMouseMove	N/A	Executes a subroutine when the user moves the mouse pointer over the check box

OnOpen	N/A	Executes a subroutine when the parent form is opened

OnRightDblClick	N/A	Executes a subroutine when the user double-clicks the check box with the right mouse button

OnRightMouseDown	N/A	Executes a subroutine when the user clicks the check box with the right mouse button

OnRightMouseUp	N/A	Executes a subroutine when the user releases the right mouse button while the pointer is on the check box

Parent	N/A	An object reference that points to the parent form

Release( )	N/A	Removes the check box definition from memory

SetFocus( )	N/A	Gives focus to the check box

StatusMessage	Empty string	Specifies a message to display on the status bar while the check box has focus

TabStop	.T.	Determines if the user can give focus to the check box by pressing Tab or Shift+Tab

Text	CheckBox	Specifies a character string to display next to the check box

Top	N/A	Sets the position of the top border

Value	N/A	Sets the value in the check box

Visible	.T.	Determines whether the check box is visible or hidden

When	N/A	Specifies a condition that must evaluate to true before the user can give focus to the check box

Width	N/A	Sets the width

Description

Use a check box to let users toggle a value between true and false, yes and no, or on and off. This value can be contained in a logical field that you specify with the DataLink property.

The presence of an X in a check box means true, yes, or on, and the absence of an X means false, no, or off.

When you link a check box to a field and the user moves from record to record, the check box setting changes to reflect each value.

When you create a check box with the NEW operator, you can specify two parameters:

<parent form reference>--An object reference pointing to the parent form.

<object name expC>--A character string assigned to the Name property of the new check box. This value is optional.

For example, the following commands create a form and a check box to display in it:

MyForm = NEW FORM()
MyCBox = NEW CHECKBOX(MyForm, "OurCBox")

The Name property of the new check box contains "OurCBox".

Note:	You can specify a field for the DataLink property with the Field Picker. To access the Field Picker, click on the Tool Button next to the DataLink item in the Object Inspector.


CLASS CHECKBOX Example

The following example uses check boxes for selecting options of the LIST command. BigBox is a subclass of Checkbox with a big font:

USE ?
DEFINE FORM ListForm PROPERTY MDI .F.
DEFINE PUSHBUTTON Lister OF ListForm ;
       PROPERTY ;
       Text "List", ;
       Top  10, ;
       Left 15, ;
       OnClick  ListClick
NEW bigBox(ListForm,"Include record numbers")
NEW bigBox(ListForm,"Send to printer")
ListForm.Checkbox1.Top = 2
ListForm.Checkbox2.Top = 6
READMODAL(ListForm)

CLASS bigBox(f,lcText) OF CHECKBOX(f)
      this.FontName = "Arial"
      this.FontSize = 16
      this.Text     = SPACE(2) + lcText
      this.Width    = LEN(lcText) * 2
      this.Left     = 2
      this.Value    = .F.
ENDCLASS

FUNCTION ListClick
   IF Form.Checkbox1.Value    && include record;
                                 numbers
      IF Form.Checkbox2.Value && to printer
         LIST TO PRINTER
      ELSE
         LIST
      ENDIF
   ELSE                       && no record numbers
      IF Form.Checkbox2.Value && to printer
         LIST OFF TO PRINTER
      ELSE
         LIST OFF
      ENDIF
   ENDIF
   FORM.CLOSE()
RETURN 0


See Also

CLASS RADIOBUTTON

DEFINE


CLASS COMBOBOX

See Also	Example	Classes	Forms

An object that lets users select a value from a list by entering characters in a text box or by selecting the value directly from the list.

Properties

The following table lists the properties of the Combobox class. For more information on each property, see Properties.

Property	Default	Description

Before	N/A	Specifies which object the combo box precedes in the tabbing order of the parent form

ClassName	COMBOBOX	Identifies the combo box class

DataLink	Empty string	Links the combo box to a field

DataSource	Empty string	Specifies the prompts to display in the combo box

Enabled	.T.	Determines if the combo box can be selected

FontBold	.T.	Determines if characters are displayed in bold type

FontItalic	.F.	Determines if characters are displayed in italic type

FontName	MS Sans Serif	Specifies the font to apply to displayed characters

FontSize	N/A	Specifies the size of the font in points

FontStrikeOut	.F.	Determines if characters are displayed in strikeout type

FontUnderline	.F.	Determines if characters are displayed in underlined type

Height	N/A	Sets the height

HelpFile	Empty string	Identifies a Windows Help file (.HLP) that contains context-sensitive Help topics

HelpID	Empty string	Specifies the context string or context number of a Help topic in a Windows Help file (.HLP)

hWnd	N/A	Returns the combo box handle

ID	-1	Identifies the combo box with a numeric value

Left	N/A	Sets the position of the left border

MousePointer	0	Specifies the mouse pointer type when the pointer is over the combo box

Move( )	N/A	Moves or sizes the combo box

Name	COMBOBOX1	Specifies the combo box name

OnChange	N/A	Executes a subroutine when the user moves from one prompt to another

OnGotFocus	N/A	Executes a subroutine when the combo box receives focus

OnHelp	N/A	Executes a subroutine when the user presses F1

OnLeftDblClick	N/A	Executes a subroutine when the user double-clicks the combo box

OnLeftMouseDown	N/A	Executes a subroutine when the user clicks the combo box with the left mouse button

OnLeftMouseUp	N/A	Executes a subroutine when the user releases the left mouse button while the pointer is over the combo box

OnLostFocus	N/A	Executes a subroutine when focus is removed

OnMiddleDblClick	N/A	Executes a subroutine when the user double-clicks the combo box with the middle mouse button

OnMiddleMouseDown	N/A	Executes a subroutine when the user clicks the combo box with the middle mouse button

OnMiddleMouseUp	N/A	Executes a subroutine when the user releases the middle mouse button while the pointer is on the combo box

OnMouseMove	N/A	Executes a subroutine when the user moves the mouse in the combo box

OnOpen	N/A	Executes a subroutine when the parent form is opened

OnRightDblClick	N/A	Executes a subroutine when the user double-clicks the combo box with the right mouse button

OnRightMouseDown	N/A	Executes a subroutine when the user clicks the combo box with the right mouse button

OnRightMouseUp	N/A	Executes a subroutine when the user releases the right mouse button while the pointer is on the combo box

Parent	N/A	An object reference that points to the parent form

Release( )	N/A	Removes the combo box definition from memory

SetFocus( )	N/A	Gives focus to the combo box

Sorted	.F.	Determines if the prompts are listed in sorted order

StatusMessage	Empty string	Specifies a message to display on the status bar

Style	0 (Simple)	Determines whether the user can use the text box, the dropdown list, or both

TabStop	.T.	Determines if the user can give focus to the combo box by pressing Tab or Shift+Tab

Top	N/A	Sets the position of the top border

Value	Empty string	Sets the value in the combo box

Visible	.T.	Determines whether the combo box is visible or hidden

When	N/A	Specifies a condition that must evaluate to true before the user can give the combo box focus

Width	N/A	Sets the width

Description

Use a combo box to display a list of options and allow users to search through the options rapidly.

For example, combo box prompts might consist of last names from a field in an indexed table. The user could locate the first record containing a particular last name by entering the name's initial characters in the text box. As the user enters the characters, the prompt scrolls to the top of the display. Alternatively, the user could use the scroll bars to visually locate the last name, then select it directly with the mouse.

A combo box can display five different types of prompt:

File names

Values in a table field.

Field names from the structure of a table

Elements in an array object

The names of all tables in the currently open database (See OPEN DATABASE for information on databases.)

Specify the prompts with the DataSource property.

Determine the dimensions of a combo box with the FROM...TO clause of the DEFINE command or with the Height and Width properties. If the height you specify is not enough for all the prompts, the user can scroll through the prompts. If the height you specify is greater than needed, dBASE reduces the height automatically.

When you create a combo box with the NEW operator, you can specify two parameters:

<parent form reference>--An object reference pointing to the parent form.

<object name expC>--A character string assigned to the Name property of the new combo box. This value is optional.

For example, the following commands create a form and a combo box to display in it:

MyForm = NEW FORM()
MyComb = NEW COMBOBOX(MyForm, "OurComb")

The Name property of the new combo box contains "OurComb".

Note:	You can specify a DataSource value with the Choose Data Source dialog box in the Form Designer. To access the Choose Data Source dialog box, click the Tool Button next to the DataSource item in the Object Inspector.

You can specify a field for the DataLink property with the Choose Field dialog box. To access the Choose Field dialog box, click the Tool Button next to the DataLink item in the Object Inspector.


CLASS COMBOBOX Example

The following example defines a form that contains a combobox that displays names from the Animals.DBF table. Double clicking on one of the choices closes the form:

LOCAL f
f=NEW Showbox()
f.OPEN()
CLASS Showbox OF FORM
  this.View = "ANIMALS.DBF"
  DEFINE COMBOBOX CB1 OF THIS;
    PROPERTY;
      DataSource "FIELD Animals->Name",;
      FontBold .T.,;
      Top 4,;
      Left 6,;
      Width 20, ;
      OnLeftDblClick {; ? 'You picked...',;
        THIS.value, ; FORM.CLOSE()}
  DEFINE TEXT Text1 OF THIS;
    PROPERTY;
      Text "Pick Your Favorite Animal",;
      FontBold .T., Width 40,;
      Top 1, Left 3
ENDCLASS


See Also

CLASS LISTBOX

DEFINE


CLASS DDELINK

See Also	Example	Classes

Initiates and controls a DDE link between dBASE and a server application, allowing dBASE to send instructions and data-exchange requests to the server.

Properties

The following table lists the properties of the DDELink class. For more information on each property, see Properties.

Property	Default	Description

Advise( )	N/A	Requests that the server notify the client when an item in the server document changes

ClassName	DDELINK	Identifies the DDELink class

Execute( )	N/A	Sends instructions to the server in its own language

Initiate( )	N/A	Starts a conversation with a DDE server application

OnNewValue	N/A	Executes a subroutine when an item in the server application changes

Peek( )	N/A	Retrieves a data item stored in a server document

Poke( )	N/A	Inserts a data item into a server document

Reconnect( )	N/A	Restores a DDE link that was terminated with Terminate( )

Release( )	N/A	Removes the DDELink object definition from memory

Server	N/A	Contains the name of the server you specified with the Initiate( ) method

Terminate( )	N/A	Terminates the link with the server application

Timeout	10.00	Determines the amount of time dBASE waits for a transaction before returning an error

Topic	Empty string	Contains the name of the topic you specified with the Initiate( ) method

Unadvise( )	N/A	Asks the server to stop notifying the DDELink object when an item in the server document changes

Description

Use a DDELink object to open a channel of communication (known as a DDE link) between dBASE and an external Windows application (known as a server). You can exchange data and instructions through this link, making the two applications work together. For example, a DDElink object might establish a link to Quattro Pro for Windows, open one of its notebook files, and copy its data into a dBASE table.

Establish a DDE link with the Initiate( ) property. If a session in the server application is not already running, Initiate( ) tries to start a session before establishing the link. If the attempt is unsuccessful, Initiate( ) returns a value of false.

For more information on DDE, see Chapter 26 in the Programmer's Guide. For information on using dBASE as a server application, see CLASS DDETOPIC.


CLASS DDELINK Example

The following example creates a DDELINK object with the NEW operator, attempts to initiate a server session with Quattro Pro for Windows with the Initiate method, uses the Peek method to extract a value from element GasCosts:B5 to a dBASE memory variable and Poke to place a new value in cell GasCosts:B6 of the QPW spreadsheet:

LOCAL LinkObj
LinkObj = NEW DDELINK()
IF LinkObj.Initiate("QPW","Tutor.WB1")
  ? "Connection to QPW initiated"
ELSE
  ? "Connection to QPW failed"
ENDIF
mValue1=LinkObj.Peek("GasCosts:B5")
? mValue1
LinkObj.Poke("GasCosts:B6","198")
mValue2=LinkObj.Peek("GasCosts:B6")
? mValue2
LinkObj.RELEASE()


See Also

CLASS DDETOPIC

CLASS OLE

DEFINE


CLASS DDETOPIC

See Also	Example	Classes

Determines the actions taken when dBASE for Windows receives requests from a DDE client.

Properties

The following table lists the properties of the DDETopic class. For more information on each property, see Properties.

Property	Default	Description

ClassName	DDETOPIC	Identifies the DDETopic class

Notify( )	N/A	Notifies all client applications that a dBASE item was changed

OnAdvise	N/A	Executes a subroutine when an external application creates a hot link

OnExecute	N/A	Executes a subroutine when a client application sends a directive to dBASE

OnPeek	N/A	Executes a subroutine when the client requests a value from dBASE

OnPoke	N/A	Executes a subroutine when the client inserts a new value into a dBASE item

OnUnadvise	N/A	Executes a subroutine when a client removes a hot link from a particular item

Release( )	N/A	Removes the DDETopic object definition from memory

Topic	N/A	The DDETopic object's topic

Description

Use a DDETopic object to determine what dBASE does for a client application when dBASE is the server in a DDE link.

As a server application, dBASE for Windows accepts directives from a client application, accepts and sends data items to the server application, and performs whatever actions you specify with DDETopic object properties. For example, an OnPoke subroutine might receive a field name and a field value from a client application, insert the value into the designated field, and notify the client application with the Notify( ) method.

You usually create a DDETopic object in an initiation-handler routine, which you assign to the OnInitiate property of _app. An initiation handler executes when a client application requests a DDE link with dBASE. For more information on initiation handlers, see Chapter 26 in the Programmer's Guide.

For information on using dBASE as a client application, see CLASS DDELINK.

When you create a DDETopic object with the NEW operator, specify the <topic> parameter. This value is automatically placed in the Topic property of the new DDETopic object. External applications use this property to identify the object and establish a DDE link. For example, the following command creates a DDETopic object, and puts "MyTopic" in the Topic property:

OurTopic = NEW DDETopic("MyTopic")

A Quattro Pro spreadsheet might execute the following command to invoke the new object:

{INITIATE "DBASEWIN", "MyTopic"}


CLASS DDETOPIC Example

The following example creates a DDE server for handling stock information. For simplicity, only one hot link is supported at a time, and all stocks have the same value. When a client buys a stock (Execute feature), the stock price goes up; when a client sells a stock, the stock price goes down.

SET PROCEDURE TO PROGRAM(1) ADDITIVE
PUBLIC Stock, Adviser, Value
Value = 100.0
_app.DDEServiceName = "Stock"
_app.OnInitiate = INITHANDLER

FUNCTION InitHandler
PARAMETER Topic
IF ".STK" $ Topic
  x = NEW StockTopic()
  ELSE
  x = .F.
ENDIF
RETURN x

CLASS StockTopic OF DDETOPIC
Stock.OnAdvise = AdvHandler
Stock.OnExecute = ExeHandler
Stock.OnPeek = PeekHandler
Stock.OnPoke = PokeHandler
Stock.OnUnadvise = UnAdvHandler

FUNCTION AdvHandler
PARAMETER Item
Adviser = Item
RETURN .T.

FUNCTION ExeHandler
PARAMETER Cmd
IF Cmd = "SELL"
  Value = Value - 10.0
ELSE
  IF Cmd = "BUY"
    Value = Value + 10.0
  ENDIF
ENDIF
THIS.Notify(Adviser)
RETURN .T.

FUNCTION PeekHandler
PARAMETER Item
RETURN Value

FUNCTION PokeHandler
PARAM Item, Val
? "POKE: ", Item, Val
RETURN .T.

FUNCTION UnAdvHandler
PARAMETER Item
IF(Adviser = item)
  Adviser = .F.
ENDIF
RETURN .T.

ENDCLASS


See Also

CLASS DDELINK


CLASS EDITOR

See Also	Example	Classes	Forms

A tool that lets the user view and edit a text file or memo field.

Properties

The following table lists the properties of the Editor class. For more information on each property, see Properties.

Property	Default	Description

Before	N/A	Specifies which object the editor object precedes in the tabbing order of the parent form

ClassName	EDITOR	Identifies the editor class

ColorNormal	N/W	Sets the color of the editor object when it does not have focus

DataLink	Empty string	Links the editor object to a text file, a memo field, or a character field.

Enabled	.T.	Determines if the editor object can be selected

FontBold	.T.	Determines if characters are displayed in bold type

FontItalic	.F.	Determines if characters are displayed in italic type

FontName	MS Sans Serif	Specifies the font to apply to characters in the display

FontSize	N/A	Specifies the size of the font in point size

FontStrikeOut	.F.	Determines if characters are displayed in strikeout type

FontUnderline	.F.	Determines if characters are displayed in underlined type

Height	N/A	Sets the height

HelpFile	Empty string	Identifies a Windows Help file (.HLP) that contains context-sensitive help topics

HelpID	Empty string	Specifies the context string or context number of a help topic in a Windows Help file (.HLP)

hWnd	N/A	Returns the editor object handle

ID	-1	Identifies the editor object with a numeric value

Left	N/A	Sets the position of the left border

Modify	.T.	Determines if the user can alter data in the editor object

MousePointer	0	Specifies the mouse pointer type when the pointer is over the editor object

Move( )	N/A	Moves or sizes the editor object

Name	EDITOR1	Specifies the name of the editor object

OnChange	N/A	Executes a subroutine when the user changes text in the editor object

OnGotFocus	N/A	Executes a subroutine when the editor object receives focus

OnHelp	N/A	Executes a subroutine when the user presses F1

OnLeftDblClick	N/A	Executes a subroutine when the user double-clicks on the editor object

OnLeftMouseDown	N/A	Executes a subroutine when the user clicks on the editor object with the left mouse button

OnLeftMouseUp	N/A	Executes a subroutine when the user releases the left mouse button while the pointer is over the editor object

OnLostFocus	N/A	Executes a subroutine when focus is removed

OnMiddleDblClick	N/A	Executes a subroutine when the user double-clicks on the editor object with the middle mouse button

OnMiddleMouseDown	N/A	Executes a subroutine when the user clicks on the editor object with the middle mouse button

OnMiddleMouseUp	N/A	Executes a subroutine when the user releases the middle mouse button while the pointer is on the editor object

OnMouseMove	N/A	Executes a subroutine when the user moves the mouse in the editor object

OnOpen	N/A	Executes a subroutine when the parent form is opened

OnRightDblClick	N/A	Executes a subroutine when the user double-clicks on the editor object with the right mouse button

OnRightMouseDown	N/A	Executes a subroutine when the user clicks on the editor object with the right mouse button

OnRightMouseUp	N/A	Executes a subroutine when the user releases the right mouse button while the pointer is on the editor object

Parent	N/A	An object reference that points to the parent form

Release( )	N/A	Removes the editor object definition from memory

Scrollbar	1 (On)	Determines if the editor object has a scroll bar

SetFocus( )	N/A	Gives focus to the editor object

StatusMessage	Empty string	Specifies a message to display on the status bar when the editor object receives focus

TabStop	.T.	Determines if the user can give focus to the editor object by pressing Tab or Shift+Tab

Top	N/A	Sets the position of the top border

Valid	N/A	Specifies a condition that must evaluate to true (.T.) before the user can remove focus from the editor object

Value	Empty string	Determines the contents of the editor object

Visible	.T.	Determines whether the editor object is visible or hidden

When	N/A	Specifies a condition that must evaluate to true before the user can give focus to the editor object

Width	N/A	Sets the width

Wrap	.T.	Determines if the editor object wraps input text automatically

Description

Use an editor object to give a form text-editing capability, letting users view and change the contents of text files, memo fields, and character fields.

Use the DataLink property to specify the text file or memo field to access. To access a text file, use the keyword FILE, as with:

"FILE MYTEXT.TXT"

To access a memo field or a character field, use the field name and the alias of the table that contains the field.

To set the dimensions of the editor object, use the FROM...TO clause of its DEFINE command or with its Height and Width properties. The scroll bars let the user move horizontally or vertically within the display when input exceeds the dimensions of the editor object.

To position the editor object on the form, use the Top and Left properties.

When you create an editor object with the NEW operator, you can specify two parameters:

<parent form reference>--An object reference pointing to the parent form.

<object name expC>--A character string assigned to the Name property of the new editor object. This value is optional.

For example, the following commands create a form and an editor object to display in it:

MyForm = NEW FORM()
MyEdit = NEW EDITOR(MyForm, "OurEdit")

The Name property of the new editor object contains "OurEdit".


CLASS EDITOR Example

The following example defines a form that contains a browse object containing CompCode and Contact information from the Contact table plus the associated memo field contents displayed in an editor object to the right. Back and Next pushbuttons advance or retard the record pointer while Exit gives the user an alternative way to close the form:

LOCAL f
f=NEW EntryForm()
f.OPEN()
CLASS EntryForm OF FORM
  this.Top=2
  this.Left=2
  this.Width=72
  this.Height=20
  this.View = "Contact.DBF"
  this.Text= "Edit as Required"
  DEFINE BROWSE Br1 OF THIS;
    PROPERTY;
      Top 4,;
      Left 3,;
      Width 32,;
      Height 12
  DEFINE TEXT Text1 OF THIS;
    PROPERTY;
      Text "Contact Table Points of Contact",;
      Width 72,;
      Top 1,;
      Left 0,;
      Alignment 1,;
      Height 2.50,;
      FontBold .T.,;
      FontSize 14.00,;
      ColorNormal "R/W"
  DEFINE EDITOR ED1 OF THIS;
    PROPERTY;
      Top 4,;
      Left 37,;
      Width 32,;
      Height 12,;
      DataSource "MEMO Contact->Notes"
  DEFINE PUSHBUTTON Back OF THIS;
    PROPERTY Text "Back", Height 2,;
      Top 17, Left 22,;
      OnClick {;SKIP-1}, FontBold .T.
  DEFINE PUSHBUTTON Next OF THIS;
    PROPERTY TEXT "Next", Height 2,;
      Top 17, Left 32,;
      OnClick {;SKIP}, FontBold .T.
  DEFINE PUSHBUTTON Exit OF THIS;
    PROPERTY Text "Exit", Height 2,;
      Top 17, Left 42,;
      OnClick {;Form.Close()}, FontBold .T.
ENDCLASS


See Also

MODIFY COMMAND


CLASS ENTRYFIELD

See Also	Example	Classes	Forms

An area in which the user can input or modify a single value.

Properties

The following table lists the properties of the Entryfield class. For more information on each property, see Properties.

Property	Default	Description

Before	N/A	Specifies which object the entry field precedes in the tabbing order of the parent form

Border	.T.	Determines if the entry field is surrounded with a border

ClassName	ENTRYFIELD	Identifies the Entryfield class

ColorHighlight	N/W	Sets the color of the entry field when it is highlighted

ColorNormal	N/W	Sets the color of the entry field when it is not highlighted

DataLink	Empty string	Links the entry field to a table field

Enabled	.T.	Determines if the entry field can be selected

FontBold	.T.	Determines if characters in the entry field are displayed in bold type

FontItalic	.F.	Determines if characters are displayed in italic type

FontName	MS Sans Serif	Specifies the font to apply to displayed characters

FontSize	N/A	Specifies the size of the font in points

FontStrikeOut	.F.	Determines if characters are displayed in strikeout type

FontUnderline	.F.	Determines if characters are displayed in underlined type

Function	Empty string	Formats displayed text

Height	N/A	Sets the height

HelpFile	Empty string	Identifies a Windows Help file (.HLP) that contains context-sensitive Help topics

HelpID	Empty string	Specifies the context string or context number of a Help topic in a Windows Help file (.HLP)

hWnd	N/A	Returns the entry field handle

ID	-1	Identifies the entry field with a numeric value

Key	N/A	Executes a subroutine when the user presses a key

Left	N/A	Sets the position of the left border

MaxLength	N/A	Specifies the scrolling width

MousePointer	0	Specifies the mouse pointer type when the pointer is over the entry field

Move( )	N/A	Moves or sizes the entry field

Name	ENTRYFIELD1	Specifies the name of the entry field

OldStyle	N/A	Determines if the entry field is displayed in the default Windows style or in Borland style

OnChange	N/A	Executes a subroutine when the user changes a value

OnGotFocus	N/A	Executes a subroutine when the entry field receives focus

OnHelp	N/A	Executes a subroutine when the user presses F1

OnLeftDblClick	N/A	Executes a subroutine when the user double-clicks the entry field

OnLeftMouseDown	N/A	Executes a subroutine when the user clicks the entry field with the left mouse button

OnLeftMouseUp	N/A	Executes a subroutine when the user releases the left mouse button while the pointer is over the entry field

OnLostFocus	N/A	Executes a subroutine when focus is removed

OnMiddleDblClick	N/A	Executes a subroutine when the user double-clicks the entry field with the middle mouse button

OnMiddleMouseDown	N/A	Executes a subroutine when the user clicks the entry field with the middle mouse button

OnMiddleMouseUp	N/A	Executes a subroutine when the user releases the middle mouse button while the pointer is on the listbox

OnMouseMove	N/A	Executes a subroutine when the user moves the mouse over the entry field

OnOpen	N/A	Executes a subroutine when the parent form is opened

OnRightDblClick	N/A	Executes a subroutine when the user double-clicks the entry field with the right mouse button

OnRightMouseDown	N/A	Executes a subroutine when the user clicks the entry field with the right mouse button

OnRightMouseUp	N/A	Executes a subroutine when the user releases the right mouse button while the pointer is on the entry field

Parent	N/A	An object reference that points to the parent form

Picture	Empty string	Formats text

Release( )	N/A	Removes the entry field definition from memory

SelectAll	.F.	Determines if the initial value in the entry field appears selected (highlighted)

SetFocus( )	N/A	Gives focus to the entry field

StatusMessage	Empty string	Specifies a message to display on the status bar while the entry field has focus

TabStop	.T.	Determines if the user can give focus to the entry field by pressing Tab or Shift+Tab

Top	N/A	Sets the position of the top border

Valid	N/A	Specifies a condition that must evaluate to true (.T.) before the user can remove focus from the entry field

ValidErrorMsg	Empty string	Specifies a character string to display on the status bar when the Valid property returns false (N/A)

ValidRequired	.F.	Determines if the Valid property applies to all data or to new data only

Value	Empty string	Sets the value in the entry field

Visible	.T.	Determines whether the entry field is visible or hidden

When	N/A	Specifies a condition that must evaluate to true before the user can give focus to the entry field

Width	N/A	Sets the width

Description

Use an entry field to let users enter and edit data in a single field. For example, a form that allows access to only one table field might use an entry field instead of a browse object.

An entry field physically resembles an entry area created by the dBASE IV command @...GET. However, entering data in an entry field does not require a READ command.

Use the DataLink property to specify the field to edit. If you wish, you can specify a field for the DataLink property with the Field Picker in the Form Designer. To access the Field Picker, click on the Tool Button next to the DataLink item in the Object Inspector.

Create entry field prompts with text objects. For example, a text object saying "Enter password" might appear above an entry field that accepts passwords. For information on text objects, see CLASS TEXT.

When you create an entry field with the NEW operator, you can specify two parameters:

<parent form reference>--An object reference pointing to the parent form.

<object name expC>--A character string assigned to the Name property of the new entry field. This value is optional.

For example, the following commands create a form and an entry field to display in it:

MyForm = NEW FORM()
MyField = NEW ENTRYFIELD(MyForm, "OurField")

The Name property of the new entry field contains "OurField".


CLASS ENTRYFIELD Example

The following example defines a form that contains three entry fields. Each ENTRYFIELD uses a different object-oriented definition syntax, all of which work in dBASE for Windows. The Back and Next pushbuttons let the user move the record pointer:

LOCAL F1
F1=NEW EntryForm()
F1.OPEN()
CLASS EntryForm OF FORM
  this.View="Company.DBF"
  this.Top=2
  this.Left=2
  this.Width=38
  this.Height=13
  this.Text= "Edit as Required"
* NEW operator syntax:
    CompCode=NEW ENTRYFIELD(this)
    CompCode.DataLink="Company->CompCode"
    CompCode.Top=5
    CompCode.Left=2
    CompCode.Width=5
    CompCode.Height=1.5
* Combination syntax:
    DEFINE ENTRYFIELD Type OF THIS
      this.Type.Width=5
      this.Type.Top=5
      this.Type.Left=9
      this.Type.Height=1.5
      this.Type.DataLink="Company->Type"
* DEFINE object syntax
      DEFINE ENTRYFIELD Company OF THIS;
        PROPERTY;
          Width 20,;
          Top 5,;
          Left 16,;
          Height 1.5,;
          DataLink "Company->Company"
  DEFINE TEXT Text1 OF THIS;
    PROPERTY;
      Text "Company Information",;
      Width 34,;
      Top 1,;
      Left 2,;
      Alignment 7,;
      Height 2.50,;
      FontSize 12.00,;
      Border .T.
  DEFINE PUSHBUTTON Back OF THIS;
    PROPERTY Text "Back", Height 2,;
      Top 10, Left 10,;
      OnClick {;SKIP-1}
  DEFINE PUSHBUTTON Next OF THIS;
    PROPERTY TEXT "Next", Height 2,;
      Top 10, Left 20,;
      OnClick {;SKIP}
ENDCLASS


See Also

@...SAY...GET

DEFINE


CLASS FORM

See Also	Example	Classes	Forms

A customized window containing objects for input and output.

Properties

The following table lists the properties of the Form class. For more information on each property, see Properties.

Property	Default	Description

ActiveControl	N/A	Contains a reference to the object that currently has focus

AutoSize	.T.	Determines if the form adjusts itself automatically to contain its objects when the form is opened

ClassName	FORM	Identifies the Form class

Close( )	N/A	Closes the form

ColorNormal	N/W	Sets the color of the form

Enabled	.T.	Determines if the form can receive focus

EscExit	.T.	Determines if the user can close the form by pressing Esc

First	N/A	Contains an object reference that points to the first object in the form

Height	N/A	Sets the height

HelpFile	Empty string	Identifies a Windows Help file (.HLP) that contains context-sensitive Help topics

HelpID	Empty string	Specifies the context string or context number of a Help topic in a Windows Help file (.HLP)

hWnd	N/A	Returns the object handle of the form

Left	N/A	Sets the position of the left border

Maximize	.F.	Determines if the form can be maximized

MDI	.T.	Determines if the form conforms to Windows Multiple Document Interface (MDI) standards

MenuFile	Empty string	Assigns a predefined menu system to the form

Minimize	.F.	Determines if the form can be minimized

MousePointer	0	Specifies the mouse pointer type when the pointer is over the form

Moveable	.T.	Determines if the form can be moved with the mouse

NextCol( )	N/A	The next highest column position

NextObj	N/A	Returns a reference to the next object in the form's tabbing order

NextRow( )	N/A	The next highest row position

OnChange	N/A	Executes a subroutine when the user changes a value in an object

OnClose	N/A	Executes a subroutine when the form is closed

OnGotFocus	N/A	Executes a subroutine when the form receives focus

OnHelp	N/A	Executes a subroutine when the user presses F1

OnLeftDblClick	N/A	Executes a subroutine when the user double-clicks the form

OnLeftMouseDown	N/A	Executes a subroutine when the user clicks the form with the left mouse button

OnLeftMouseUp	N/A	Executes a subroutine when the user releases the left mouse button while the pointer is over the form

OnLostFocus	N/A	Executes a subroutine when focus is removed

OnMiddleDblClick	N/A	Executes a subroutine when the user double-clicks the form with the middle mouse button

OnMiddleMouseDown	N/A	Executes a subroutine when the user clicks the form with the middle mouse button

OnMiddleMouseUp	N/A	Executes a subroutine when the user releases the middle mouse button while the pointer is on the form

OnMouseMove	N/A	Executes a subroutine when the user moves the mouse in the form

OnMove	N/A	Executes a subroutine after the user moves the form

OnNavigate	N/A	Executes a subroutine when the user moves to a different record

OnOpen	N/A	Executes a subroutine when the form is opened

OnRightDblClick	N/A	Executes a subroutine when the user double-clicks the form with the right mouse button

OnRightMouseDown	N/A	Executes a subroutine when the user clicks the form with the right mouse button

OnRightMouseUp	N/A	Executes a subroutine when the user releases the right mouse button while the pointer is on the form

OnSelection	N/A	Executes a subroutine when the user submits the form

OnSize	N/A	Executes a subroutine after the user resizes the form

Open( )	N/A	Opens the form as a modeless window

Print( )	N/A	Prints the form and the objects it contains

Readmodal( )	N/A	Opens the form as a modal window

Release( )	N/A	Removes the form definition from memory

ScaleFontName	MS Sans Serif	Determines which font the coordinate plane of the form is based on

ScaleFontSize	N/A	Determines the height of each row and the width of each column in the coordinate plane of the form.

Scrollbar	0 (Off)	Determines if the form has a scroll bar

SetFocus( )	N/A	Gives focus to the form

Sizeable	.F.	Determines if the user can resize the form

StatusMessage	Empty string	Specifies a message to display on the status bar while the form has focus

SysMenu	.F.	Determines if the form has a Control menu

Text	Form	Specifies a character string to display in the caption bar

Top	N/A	Sets the position of the top border

View	Empty string	Specifies the query or table on which the form is based

Visible	.T.	Determines whether the form is visible or hidden

Width	N/A	Sets the width

WindowState	0 (Normal)	Determines whether the form is minimized, maximized, or normal

Description

A form is a window you design. It can contain standard Windows interface objects (also called controls) that let users enter, access, and modify data. For example, a form might display a browse object (for editing records), entry fields (for entering single values) and check boxes (for setting a logical field to true or false). A form is a container for the objects it displays. Consequently, releasing a form definition from memory automatically releases the definitions of the objects it contains.

Most forms are based on a query (QBE), which you specify with the View property. For example, to base a form on a QBE named CONTACT.QBE, set the View property to "CONTACT.QBE". Then use the DataLink and DataSource properties to link the objects contained by the form to fields in the QBE tables.

You can create two types of forms: modal and modeless. In the Windows environment, a modal form window is like a dBASE IV window. A modal form halts execution of the routine that opened it until the form is closed. When active, it takes control of the user interface; users cannot switch to another window without exiting the form. A dialog box is an example of a modal form; when it is opened, program execution stops and focus cannot be given to another window until the user closes the dialog box.

In contrast, a modeless form window allows users to freely switch to other windows in an application. Most forms that you create for a Windows application will typically be modeless. A modeless form window conforms to the Multiple Document Interface (MDI) protocol, which lets you open multiple document windows within an application window.

To create and use a modeless form, set the MDI property to true (.T.) and open the form with the Open( ) method or the OPEN FORM command. To create and use a modal form, set MDI to false (.F.) and open the form with the ReadModal( ) method or the READMODAL( ) function.

You can also create form windows that appear like application windows. To do so, set the MDI property to false and use SHELL(.F.). SHELL(.F.) hides the standard dBASE for Windows environment and lets your form take over the user interface. The dBASE application window disappears, and the form name appears in the Windows Task List in place of "dBASE for Windows".

When you create an form with the NEW operator, you can specify a value for the Text property with the <text> parameter. For example, the following commands create a form and an editor object:

MyForm = NEW FORM("This is my form.")

When this form is opened, "This is my form" is displayed in the caption bar.


CLASS FORM Example

The following example uses DEFINE FORM, NEW FORM( ) and a subclass of form to create similar forms:

DEFINE FORM Doggy;
  PROPERTY;
  Text "Oly",;
  Top 5,;
  Left 5
OPEN FORM Doggy

Kitty = NEW FORM()
Kitty.Text = "Lacey"
Kitty.Top  = 10
Kitty.Left = 10
Kitty.OPEN()

Buddy = NEW Toni()
Buddy.OPEN()
CLASS Toni OF FORM
      this.Text = "Toni"
      this.Top  = 15
      this.Left = 15
ENDCLASS


See Also

DEFINE

MDI

Open( )

OPEN FORM

Readmodal( )

READMODAL( )

SHELL( )


CLASS IMAGE

See Also	Example	Classes	Forms

An area that displays bitmap images.

Properties

The following table lists the properties of the Image class. For more information on each property, see Properties.

Property	Default	Description

Alignment	0 (Top Left)	Positions a graphic image in the image object

ClassName	IMAGE	Identifies the image class

DataSource	Empty string	Specifies which DLL resource, file, or binary field that contains the graphic image

Height	N/A	Sets the height

hWnd	N/A	Returns the image object handle

ID	-1	Identifies the image object with a numeric value

Left	N/A	Sets the position of the left border

MousePointer	0	Specifies the mouse pointer's type when the pointer is over the image object.

Move( )	N/A	Moves or sizes the image object

Name	IMAGE1	Specifies the name of the image object

OnLeftDblClick	N/A	Executes a subroutine when the user double-clicks the image object

OnLeftMouseDown	N/A	Executes a subroutine when the user clicks the image object with the left mouse button

OnLeftMouseUp	N/A	Executes a subroutine when the user releases the left mouse button while the pointer is over the image object

OnMiddleDblClick	N/A	Executes a subroutine when the user double-clicks the image object with the middle mouse button

OnMiddleMouseDown	N/A	Executes a subroutine when the user clicks the image object with the middle mouse button

OnMiddleMouseUp	N/A	Executes a subroutine when the user releases the middle mouse button while the pointer is on the image object

OnMouseMove	N/A	Executes a subroutine when the user moves the mouse in the image object

OnOpen	N/A	Executes a subroutine when the parent form is opened

OnRightDblClick	N/A	Executes a subroutine when the user double-clicks the image object with the right mouse button

OnRightMouseDown	N/A	Executes a subroutine when the user clicks the image object with the right mouse button

OnRightMouseUp	N/A	Executes a subroutine when the user releases the right mouse button while the pointer is on the image object

Parent	N/A	An object reference that points to the parent form

Release( )	N/A	Removes the image object definition from memory

Top	N/A	Sets the position of the top border

Visible	.T.	Determines whether the image object is visible or hidden

Width	N/A	Sets the width

Description

Use an image object to display images in a form. For example, an image object might display bitmap pictures stored in a binary field.

You can link an image object to any of three sources with the DataSource property:

A file containing a bitmap image (.BMP or .PCX).

A binary field containing bitmap images.

A bitmap resource in a DLL file.

When you link an image object with a binary field and the user moves from record to record, the image stored in each record is displayed.

The image you display in an image object is read-only.

When you create an image object with the NEW operator, you can specify two parameters:

<parent form reference>--An object reference pointing to the parent form.

<object name expC>--A character string assigned to the Name property of the new image object. This value is optional.

For example, the following commands create a form and an image object to display in it:

MyForm = NEW FORM()
MyImage = NEW IMAGE(MyForm, "OurImage")

The Name property of the new image object contains "OurImage".

Note:	You can select a bitmap image with the Choose Bitmap dialog box. To access the Choose Bitmap dialog box, click on the Tool Button next to the DataSource item in the Object Inspector.


CLASS IMAGE Example

The following example creates a subclass of Form containing a subclass of Image. The subclass of Image places a bitmap in the form:

LOCAL ShowPlane
ShowPlane = NEW PlaneForm()
ShowPlane.OPEN()

CLASS PlaneForm OF FORM
      NEW PlaneBMP(this)
ENDCLASS

CLASS PlaneBmp(form) OF IMAGE(form)
      this.DataSource = "FILE Airbrlnd.BMP"
ENDCLASS

See CLASS LISTBOX for an additional example of using CLASS IMAGE.


See Also

DEFINE

RESTORE IMAGE


CLASS LINE

See Also	Example	Classes	Forms

A line you display at a specified location in a form.

Properties

The following table lists the properties of the Line class. For more information on each property, see Properties.

Property	Default	Description

Bottom	N/A	Sets the row position of the lower end of the line object

ClassName	LINE	Identifies the line class

ColorNormal	N	Sets the color of the line object

Left	N/A	Sets the horizontal position of the left end of the line object

Name	LINE1	Specifies the name of the line object

OnOpen	.F.	Executes a subroutine when the parent form is opened

Parent	N/A	An object reference that points to the parent form

Pen	0 (Solid)	Specifies the line object's style

Release( )	N/A	Removes the line object definition from memory

Right	N/A	Sets the column position right end of the line object

Top	N/A	Sets the row position of the higher end of the line object

Visible	.T.	Determines whether the line object is visible or hidden

Width	N/A	Sets the thickness of the line object

Description

Use a line object to draw a line on a form. A line object can underline another object or mark a boundary between two areas in a form.

The user cannot give focus to a line object.

When you create a line object with the NEW operator, you can specify two parameters:

<parent form reference>--An object reference pointing to the parent form.

<object name expC>--A character string assigned to the Name property of the new line object. This value is optional.

For example, the following commands create a form and a line object to display in it:

MyForm = NEW FORM()
MyLine = NEW LINE(MyForm, "OurLine")

The Name property of the new line object contains "OurLine".


CLASS LINE Example

The following example uses DEFINE LINE, within a Class definition, to create two magenta lines (one vertical and one horizontal) on the form:

LOCAL f
f=NEW EntryForm()
f.OPEN()
CLASS EntryForm OF FORM
  this.Top=2
  this.Left=2
  this.Width=36
  this.Height=13
  this.Text= "Class Line Demo"
*
* other object definitions
*
  DEFINE LINE Ln1 OF THIS;
    PROPERTY;
      Left 10,;
      Top 3,;
      Width 4,;
      Bottom 8,;
      ColorNormal "RB"
  DEFINE LINE Ln2 OF THIS;
    PROPERTY;
      Left 3,;
      Top 8,;
      Width 4,;
      Bottom 8,;
      Right 33,;
      ColorNormal "RB"
ENDCLASS


See Also

CLASS RECTANGLE

DEFINE


CLASS LISTBOX

See Also	Example	Classes	Forms

An object that lets users select one or many values from a list.

Properties

The following table lists the properties of the Listbox class. For more information on each property, see Properties.

Property	Default	Description

Before	N/A	Specifies which object the list box precedes in the tabbing order of the parent form

ClassName	LISTBOX	Identifies the list box class

ColorHighlight	W+/B	Sets the color of the list box when it is highlighted

ColorNormal	N/W*	Sets the color of the list box when it is not highlighted

Count( )	N/A	Returns the number of prompts in the list box

CurSel	0	Specifies the currently-selected prompt in the list box

DataSource	Empty string	Determines which data is displayed in the list box

Enabled	.T.	Determines if the list box can be selected

FontBold	.T.	Determines if characters are displayed in bold type

FontItalic	.F.	Determines if characters are displayed in italic type

FontName	MS Sans Serif	Specifies the font to apply to displayed characters

FontSize	N/A	Specifies the size of the font in point size

FontStrikeOut	.F.	Determines if characters are displayed in strikeout type

FontUnderline	.F.	Determines if characters are displayed in underlined type

Height	N/A	Sets the height

HelpFile	Empty string	Identifies a Windows Help file (.HLP) that contains context-sensitive Help topics

HelpID	Empty string	Specifies the context string or context number of a Help topic in a Windows Help file (.HLP)

hWnd	N/A	Returns the list box handle

ID	-1	Identifies the list box with a numeric value

Left	N/A	Sets the position of the left border

MousePointer	0	Specifies the mouse pointer type when the pointer is over the list box

Move( )	N/A	Moves or sizes the list box

Multiple	.F.	Determines if more than one item in the list box can be selected

Name	LISTBOX1	Specifies the name of the list box

OldStyle	N/A	Determines if the list box is displayed in the default Windows style or in Borland style

OnGotFocus	N/A	Executes a subroutine when the list box receives focus

OnHelp	N/A	Executes a subroutine when the user presses F1

OnLeftDblClick	N/A	Executes a subroutine when the user double-clicks the list box

OnLeftMouseDown	N/A	Executes a subroutine when the user clicks the list box with the left mouse button

OnLeftMouseUp	N/A	Executes a subroutine when the user releases the left mouse button while the pointer is over the list box

OnLostFocus	N/A	Executes a subroutine when focus is removed

OnMiddleDblClick	N/A	Executes a subroutine when the user double-clicks the list box with the middle mouse button

OnMiddleMouseDown	N/A	Executes a subroutine when the user clicks the list box with the middle mouse button

OnMiddleMouseUp	N/A	Executes a subroutine when the user releases the middle mouse button while the pointer is on the list box

OnMouseMove	N/A	Executes a subroutine when the user moves the mouse in the list box

OnOpen	N/A	Executes a subroutine when the parent form is opened

OnRightDblClick	N/A	Executes a subroutine when the user double-clicks the list box with the right mouse button

OnRightMouseDown	N/A	Executes a subroutine when the user clicks the list box with the right mouse button

OnRightMouseUp	N/A	Executes a subroutine when the user releases the right mouse button while the pointer is on the list box

OnSelChange	N/A	Executes a subroutine when the highlight is moved from one prompt to another

Parent	N/A	An object reference that points to the parent form

Release( )	N/A	Removes the list box definition from memory

Selected( )	N/A	Returns the currently-selected prompt

SetFocus( )	N/A	Gives focus to the list box

Sorted	.F.	Determines whether the list box prompts are in sorted order or in natural order

StatusMessage	Empty string	Specifies a message to display on the status bar

TabStop	.T.	Determines if the user can give focus to the list box by pressing Tab or Shift+Tab

Top	N/A	Sets the position of the top border

Value	Empty string	The currently selected prompt in the list box

Visible	.T.	Determines whether the list box is visible or hidden

When	N/A	Specifies a condition that must evaluate to true before the user can give focus to the list box

Width	N/A	Sets the width

Description

Use a list box to let the user select from a series of prompts. For example, an application might display file names in a list box, letting the user select one or more for deletion.

Specify list box prompts with the DataSource property. You can create five different types of prompts:

File names and subdirectories.

The contents of a table field.

Field names from a table.

Elements in an array object.

The names of all tables in the currently open database. (See OPEN DATABASE for information on databases.)

Determine the dimensions of a list box with the FROM...TO clause of the DEFINE command or with its Height and Width properties. If the height you specify is not enough for all the prompts, the user can scroll through the prompts. If the height you specify is greater than needed, dBASE reduces the height automatically.

Pressing the first character of a prompt selects that prompt. If more than one prompt begins with the same character, pressing the character again selects the next prompt that begins with the character.

To let the user choose any number of prompts (or none at all), set the Multiple property to true. Each chosen prompt is tagged with a checkmark, and the list box is said to be multiple-choice.

There are two ways to determine which prompt or prompts were chosen by the user:

Check the contents of the Value property. Value contains the current selection in a single-choice list box or the most recent selection in a multiple-choice list box.

Use the LISTSELECTED( ) and LISTCOUNT( ) functions in a DO...WHILE loop to evaluate the prompts. For more information, see the descriptions of LISTSELECTED( ) and LISTCOUNT( ).

When you create a list box with the NEW operator, you can specify two parameters:

<parent form reference>--An object reference pointing to the parent form.

<object name expC>--A character string assigned to the Name property of the new list box. This value is optional.

For example, the following commands create a form and a list box to display in it:

MyForm = NEW FORM()
MyList = NEW LISTBOX(MyForm, "OurList")

The Name property of the new list box contains "OurList".


CLASS LISTBOX Example

The following example defines a form that contains a list box that displays names from the Animals.DBF table and an image object that displays the associated animal's .BMP image:

LOCAL ShowPics
ShowPics=NEW PickForm()
ShowPics.OPEN()
CLASS PickForm OF FORM
  this.View="Animals.DBF"
  this.Top=2
  this.Left=2
  this.Width=60
  this.Height=20
  this.Text= "Animals of the World"
  DEFINE LISTBOX LB1 OF THIS;
    PROPERTY;
      DataSource "FIELD Animals->Name",;
      Top 4,;
      Left 6,;
      Width 20,;
      Height 12
  DEFINE TEXT Text1 OF THIS;
    PROPERTY;
      Text "Pick Your Favorite Animal",;
      FontBold .T.,;
      Width 40,;
      Top 1,;
      Left 3,;
      Height 2.50,;
      FontSize 12.00,;
      ColorNormal "RB/W"
  DEFINE IMAGE Img1 OF THIS;
    PROPERTY;
      DataSource "BINARY Animals->BMP",;
      Top 2,;
      Left 32,;
      Width 25,;
      Height 15
ENDCLASS


See Also

DO WHILE

DEFINE

LISTCOUNT( )

LISTSELECTED( )

ON SELECTION FORM

OPEN FORM


CLASS MENU

See Also	Example	Classes	Forms

A Windows-style menu system assigned to a form.

Properties

The following table lists the properties of the Menu class. For more information on each property, see Properties.

Property	Default	Description

Before	N/A	Specifies which other menu object the menu object precedes

Checked	.F.	Determines if a checkmark appears beside a menu prompt

ClassName	MENU	Identifies the menu class

Enabled	.T.	Determines if the menu can be selected

ID	-1	Identifies the menu with a numeric value

Name	MENU1	Specifies the name of the menu item

OnClick	.F.	Executes a subroutine when the user chooses the menu

Parent	Empty string	An object reference that points to the parent form

Release( )	N/A	Removes the menu object definition from memory

Separator	.F.	Determines if the menu prompt is a menu item that the user cannot select

ShortCut	Empty string	Specifies a key combination that executes the OnClick subroutine

StatusMessage	Empty string	Specifies a message to display on the status bar

Text	Empty string	Specifies a character string to display in the menu prompt

Description

Use menu objects to create a menu system for a form.

A menu system consists of two elements:

The object reference variable that identifies the entire menu system. You must create this variable before you can create the menu system. (The variable name is not displayed anywhere.)

Menu items, the prompts offered by the menu system. You can display menu items in four places:

The dBASE application menu bar, a row near the top of the application frame window. (This happens only when the MDI property is set to true.)

The Menu Bar, an unmarked row at the top of the form. (This happens only when the MDI property is set to false.) The first menu item you create is automatically displayed at the left end of the menu bar.

A pulldown menu, which the user opens by selecting a menu item from the menu bar.

A cascading menu, which the user opens by selecting a menu item from a pulldown menu or another cascading menu.

You create the object reference variable and menu items with the DEFINE MENU command. For example, the following commands create a form and declare a name for its menu system:

MyForm = NEW FORM()
DEFINE MENU Main OF MyForm

The following command creates a menu item (File) on the application menu bar:

DEFINE MENU File OF MyForm.Main PROPERTY Text "File"

The following command moves the menu item (File) to the menu bar of the form:

MyForm.MDI = .F.

The following commands create two menu items (Open and Close) in a pulldown menu:

DEFINE MENU xOpen OF;
MyForm.Main.File PROPERTY Text "Open"

DEFINE MENU xClose OF;
MyForm.Main.File PROPERTY Text "Close"

The user opens this pulldown menu by selecting File, the menu item on the menu bar.

The following commands create a cascading menu with two menu items (Close Without Saving, and Close and Save):

DEFINE MENU NoSave OF MyForm.Main.File.xClose;
PROPERTY Text "Close Without Saving"

DEFINE MENU YesSave OF MyForm.Main.File.xClose;
PROPERTY Text "Close and Save"

The user opens this cascading menu by selecting the Close menu item.

Creating pick characters

To let the user select a menu item with a key press, specify a pick character by placing an ampersand to the left of the character in the menu item prompt. For example, the previous command could have specified "S" as the pick character for the Close and Save menu item:

DEFINE MENU YesSave OF MyForm.Main.File.xClose;
PROPERTY Text "Close and &Save"

The method for entering a pick character depends on the level of the menu item. When the pick character selects a menu item from the menu bar, the user presses the <Alt> key before entering the character. To select any other menu item, the user inputs the character only.

Assigning actions to menu items

You assign an action to a menu item with the OnClick subroutine. For example, the following command assigns a subroutine named ClsSave to the Close and Save menu item:

MyForm.Main.File.xClose.YesSave.OnClick = ClsSave

Note:	You can move a menu object from one form to another by changing the Parent property of the menu object. The Parent property is read-only for all other classes.

You can design a menu with the Menu Designer, a tool that creates a menu file (.MNU). The menu file contains dBASE code that generates the menu you design. To access the Menu Designer, click the Tool button next to the MenuFile property in the Object Inspector.


CLASS MENU Example

The following example defines a main menu with two pull-down options, File and Equipment. File has an Exit option and Equipment has a Select Flights option. This menu definition is Equipmnt.MNU, a menu file called by Equipmnt.WFM on the DBASEWIN\SAMPLES directory:

PARAMETER FormObj

NEW EQUIPMNTMENU(FormObj,"Root")

CLASS EQUIPMNTMENU(FormObj,Name) OF MENU(FormObj,Name)

   this.Text = ""

   DEFINE MENU FILE OF THIS;

       PROPERTY;

         Text "&File"

         DEFINE MENU EXIT OF THIS.FILE;

             PROPERTY;

               OnClick {;form.close()},;

               Text "E&xit",;

               Shortcut "CTRL-Q"

   DEFINE MENU EQUIPMENT OF THIS;

       PROPERTY;

         Text "&Equipment"

         DEFINE MENU SELECT_FLIGHTS OF THIS.EQUIPMENT;

             PROPERTY;

               OnClick CLASS::GETFLIGHTS,;

               Text "&Select Flights",;

               Shortcut "CTRL-S"

   PROCEDURE GETFLIGHTS

     LOCAL getFltsF, Selected

     SET PROCEDURE TO GetFlts.wfm ADDITIVE

     getFltsF = NEW GetFltsForm()

     getFltsF.MDI = .f.

     getFltsF.ReadModal()

     SHOW OBJECT form.FlightsBrowse

   RETURN

ENDCLASS


See Also

_app

DEFINE

MDI


CLASS OBJECT

See Also	Example	Classes	Forms

Creates a custom object with no properties.

Properties

The Object class does not have built-in properties.

Description

Use the Object class to create your own object. An object of the Object class is empty - it contains no properties or methods. You customize this object by creating the properties you want.


CLASS OBJECT Example

The following example creates a user-defined object that contains the name and address of a client:

oClient=NEW OBJECT()
oClient.Firstname = "Harvey"
oClient.Lastname = "West"
oClient.Address = "111 Last St."
oClient.City = "Portland"
oClient.State= "OR"


See Also

CLASS...ENDCLASS


CLASS OLE

See Also	Example	Classes	Forms

Displays an OLE document that is stored in an OLE field, and lets the user initate an action in the server application that created the document.

Properties

The following table lists the properties of the OLE class. For more information on each property, see Properties.

Property	Default	Description

Before	N/A	Specifies which object the OLE object precedes in the tabbing order of the parent form

Border	.T.	Determines if the OLE object is surrounded with a border

ClassName	OLEITEM	Identifies the combo box class

DataLink	Empty string	Links the OLE object to a field

DoVerb( )	0	Starts an OLE server session and determines its type

Enabled	.T.	Determines if the OLE object can be selected

Height	N/A	Sets the height

hWnd	N/A	Returns the OLE object handle

ID	-1	Identifies the OLE object with a numeric value

Left	N/A	Sets the position of the left border

LinkFileName	Empty string	Identifies which OLE document file (if any) is linked with the current OLE field.

MousePointer	0	Specifies the mouse pointer type when the pointer is over the OLE object

Name	OLE1	Specifies the name of the OLE object

OleType	0	Returns a number that reveals whether an OLE field is empty, contains an embedded document, or contains a link to a document file.

OnChange	N/A	Executes a subroutine when the user modifies a document

OnClose	N/A	Executes a subroutine when the OLE server session is ended

OnGotFocus	N/A	Executes a subroutine when the OLE object receives focus

OnLostFocus	N/A	Executes a subroutine when focus is removed

OnOpen	N/A	Executes a subroutine when the parent form is opened

Parent	N/A	An object reference that points to the parent form

Release( )	N/A	Removes the OLE object definition from memory

ServerName	Empty string	Identifies the server application that is invoked when the user double-clicks on an OLE viewer object.

SetFocus( )	N/A	Gives focus to the OLE object

StatusMessage	Empty string	Specifies a message to display on the status bar

TabStop	.T.	Determines if the user can give object focus to the OLE object by pressing Tab or Shift+Tab

Top	N/A	Sets the position of the top border

Valid	N/A	Specifies a condition that must evaluate to true (.T.) before the user can remove focus from the OLE object

Visible	.T.	Determines whether the OLE object is visible or hidden

Width	N/A	Sets the width

Description

Place an OLE object in a form to view and edit a document stored in an OLE field. For example, if an OLE field contains a bitmap image created in Paintbrush, double-clicking the OLE object linked to the field starts a session in Paintbrush and places the image in the Paintbrush work area.

OLE stands for Object Linking and Embedding. When you link a document to an OLE object, the OLE field does not contain the document itself; instead, it holds a link to a file containing the document. When you embed a document in an OLE field, a copy of the document is inserted into the OLE field, and no connection is made to a document file.

By double-clicking the OLE object, the user can invoke the application that created the OLE document. Therefore, if an image was created in Paintbrush and linked or embedded in the OLE field, double-clicking on the field starts a session in Paintbrush; the image is displayed in the Paintbrush drawing area, ready for editing. If the object was linked, any changes made in the Paintbrush session are stored in the document file; if the object was embedded, the changes are stored in the OLE field only.

An OLE viewer window object displays the contents of an OLE field. (Use the DataLink property to identify this field by name.) Each time the record pointer is moved, the contents of the viewer window are refreshed to display the OLE field in the current record.

When you create an OLE object with the NEW operator, you can specify two parameters:

<parent form reference>--An object reference pointing to the parent form.

<object name expC>--A character string assigned to the Name property of the new OLE object. This value is optional.

For example, the following commands create a form and an OLE object to display in it:

MyForm = NEW FORM()
MyOLE = NEW OLE(MyForm, "OurOLE")

The Name property of the new OLE object contains "OurOLE".


CLASS OLE Example

The following example is an extract from PICTURES.WFM on the SAMPLES directory and demonstates displaying an OLE field from the Pictures table on a form with an OLE object:

LOCAL f
f = NEW PICTURES ()
f.Open()

CLASS PICTURES OF FORM
   this.EscExit = .T.
   this.View = "PICTURES.QBE"
   this.ColorNormal = "BG/B"
   this.Text = "Pictures Form"
   this.Width =         76.00
   this.Top =          0.00
   this.Left =          0.00
   this.Height =         30.00
   this.Minimize = .F.
   this.Maximize = .F.
   this.OnOpen = {;create session}

  DEFINE PUSHBUTTON SOUND OF THIS;
    PROPERTY;
      OnClick {;play sound binary pictures->sound},;
      Text "Sound",;
      Width         18.00,;
      Top          5.00,;
      Left          1.00,;
      Height          3.00,;
      FontSize         16.00,;
      FontName "Courier"

  DEFINE LISTBOX THINGS OF THIS;
    PROPERTY;
      ColorNormal "bg+/b",;
      Width         18.50,;
      Top         11.42,;
      Left          0.75,;
      Height          5.50,;
      DataSource "FIELD NAME",;
      ColorHighLight "W+/B",;
      FontSize         11.25,;
      FontName "Fixedsys",;
      ID        800

  DEFINE OLE PICTURE OF THIS;
    PROPERTY;
      Width         55.00,;
      Top          5.00,;
      Left         20.00,;
      Height         24.00,;
      DataLink "PICTURES->BITMAPOLE",;
      ID         88

  DEFINE TEXT TITLE OF THIS;
    PROPERTY;
      ColorNormal "gr+/b",;
      Text "Sights and Sounds",;
      Width         59.50,;
      Top          0.00,;
      Left         20.00,;
      Height          4.30,;
      FontSize         32.00,;
      FontName "Serif"
ENDCLASS

PROCEDURE Sound_OnClick
PLAY SOUND BINARY Pictures->Sound

PROCEDURE ClosePictures
USE IN PICTURES
FORM.CLOSE()


See Also

CLASS DDELINK

CLASS DDETOPIC

CLASS IMAGE

DEFINE

DoVerb( )


CLASS PUSHBUTTON

See Also	Example	Classes	Forms

A button that executes a command or action when a user chooses it.

Properties

The following table lists the properties of the Pushbutton class. For more information on each property, see Properties.

Property	Default	Description

Before	N/A	Specifies which object the pushbutton precedes in the tabbing order of the parent form

ClassName	PUSHBUTTON	Identifies the Pushbutton class

ColorNormal	N/W	Sets the color of the pushbutton

Default	.F.	Determines if the pushbutton is the default pushbutton

DisabledBitmap	Empty string	Specifies the graphic image to display in the pushbutton when the pushbutton is disabled

DownBitMap	Empty string	Specifies the graphic image to display in the pushbutton when the user presses the mouse button over the pushbutton, or when the user presses the Spacebar while the pushbutton has focus

Enabled	.T.	Determines if the pushbutton can be selected

FocusBitMap	Empty string	Specifies the graphic image to display in the pushbutton when the pushbutton has focus

FontBold	.T.	Determines if characters are displayed in bold type

FontItalic	.F.	Determines if characters are displayed in italic type

FontName	MS Sans Serif	Specifies the font to apply to displayed characters

FontSize	N/A	Specifies the size of the font in points

FontStrikeOut	.F.	Determines if characters are displayed in strikeout type

FontUnderline	.F.	Determines if characters are displayed in underlined type

Group	.F.	Starts an object group in the parent form

Height	N/A	Sets the height

HelpFile	Empty string	Identifies a Windows Help file (.HLP) that contains context-sensitive Help topics

HelpID	Empty string	Specifies the context string or context number of a Help topic in a Windows Help file (.HLP)

hWnd	N/A	Returns the object handle of the pushbutton

ID	-1	Identifies the pushbutton with a numeric value

Left	N/A	Sets the position of the left border

MousePointer	0	Specifies the mouse pointer type when the pointer is over the pushbutton

Move( )	N/A	Moves or sizes the pushbutton

Name	BUTTON1	Specifies the the name of the pushbutton

OnClick	N/A	Executes a subroutine when the user chooses a pushbutton

OnGotFocus	N/A	Executes a subroutine when the pushbutton receives focus

OnHelp	N/A	Executes a subroutine when the user presses F1

OnLeftDblClick	N/A	Executes a subroutine when the user double-clicks the pushbutton

OnLeftMouseDown	N/A	Executes a subroutine when the user clicks the pushbutton with the left mouse button

OnLeftMouseUp	N/A	Executes a subroutine when the user releases the left mouse button while the pointer is over the pushbutton

OnLostFocus	N/A	Executes a subroutine when focus is removed

OnMiddleDblClick	N/A	Executes a subroutine when the user double-clicks the pushbutton with the middle mouse button

OnMiddleMouseDown	N/A	Executes a subroutine when the user clicks the pushbutton with the middle mouse button

OnMiddleMouseUp	N/A	Executes a subroutine when the user releases the middle mouse button while the pointer is on the pushbutton

OnMouseMove	N/A	Executes a subroutine when the user moves the mouse in the pushbutton

OnOpen	N/A	Executes a subroutine when the parent form is opened

OnRightDblClick	N/A	Executes a subroutine when the user double-clicks the pushbutton with the right mouse button

OnRightMouseDown	N/A	Executes a subroutine when the user clicks the pushbutton with the right mouse button

OnRightMouseUp	N/A	Executes a subroutine when the user releases the right mouse button while the pointer is on the pushbutton

Parent	N/A	An object reference that points to the parent form

Release( )	N/A	Removes the pushbutton definition from memory

SetFocus( )	N/A	Gives focus to the pushbutton

SpeedBar	.F.	Determines whether the pushbutton behaves like a SpeedBar button or a standard pushbutton

StatusMessage	Empty string	Specifies a message to display on the status bar

TabStop	.T.	Determines if the user can give object focus to the pushbutton by pressing Tab or Shift+Tab

Text	BUTTON1	Specifies a character string to display on the pushbutton

Top	N/A	Sets the position of the top border

UpBitmap	Empty string	Specifies the graphic image to display in the pushbutton when it is not selected

Visible	.T.	Determines whether the pushbutton is visible or hidden

When	N/A	Specifies a condition that must evaluate to true before the user can give focus to the pushbutton

Width	N/A	Sets the width

Description

Use a pushbutton to execute a specific action when the user chooses it.

When the user chooses a pushbutton, two things happen:

dBASE executes any procedure or codeblock you assign to the OnGotFocus property.

dBASE executes any procedure or codeblock you assign to the OnClick property.

dBASE submits the parent form, which executes any procedure or codeblock you assign to the OnSelection property of the parent form.

The OnSelection procedure or codeblock identifies the pushbutton through the ID property. When the user chooses the pushbutton, dBASE passes this value to the procedure or codeblock you assigned to the OnSelection property. The procedure or codeblock can use Id to identify which object was last selected.

When you create a pushbutton with the NEW operator, you can specify two parameters:

<parent form reference>--An object reference pointing to the parent form.

<object name expC>--A character string assigned to the Name property of the new pushbutton. This value is optional.

For example, the following commands create a form and a pushbutton to display in it:

MyForm = NEW FORM()
MyButton = NEW PUSHBUTTON(MyForm, "OurButton")

The Name property of the new pushbutton contains "OurButton".

Note:	You can write an OnClick or OnSelection procedure with the Procedure Editor, a window that lets you enter dBASE program code. To access the Procedure Editor, click the Tool Button next to the OnClick or OnSelection item in the Object Inspector.


CLASS PUSHBUTTON Example

The following example defines a form with two fields from the Contact table displayed and three alternative methods of defining pushbuttons to advance or retard the record pointer and exit the form:

SET PROCEDURE TO BUTTONS.CC ADDITIVE
* Makes available custom objects PREVBUTTON,
* NEXTBUTTON and CANCELBUTTON
LOCAL f
f=NEW EntryForm()
f.OPEN()
CLASS EntryForm OF FORM
  this.Top=2
  this.Left=2
  this.Width=36
  this.Height=27
  this.View = "Contact.DBF"
  this.Text= "Class Pushbutton Demo"
  DEFINE ENTRYFIELD CompCode OF THIS;
    PROPERTY;
      Width 5,;
      Top 1,;
      Left 2,;
      Height 1.5,;
      FontBold .T.,;
      DataLink "COMPCODE"
  DEFINE ENTRYFIELD Contact OF THIS;
    PROPERTY;
      Width 22,;
      Top 1,;
      Left 12,;
      Height 1.5,;
      FontBold .T.,;
      DataLink "CONTACT"
  DEFINE PUSHBUTTON Reverse OF THIS;
    PROPERTY;
      OnClick {;SKIP-1},;
      Text "&Previous",;
      Top  4,;
      Left 5,;
      Width 12,;
      Height 2.5,;
      Group .T.,;
      FontSize 8,;
      FocusBitmap "Resource #104 DBAS0009.DLL",;
      DownBitmap "Resource #104 DBAS0009.DLL",;
      UpBitmap "Resource #104 DBAS0009.DLL"
  DEFINE PUSHBUTTON NxtRcd OF THIS;
    PROPERTY;
      OnClick {;SKIP},;
      Text "&Next",;
      Top  4,;
      Left 19,;
      Width 12,;
      Height 2.5,;
      Group .T.,;
      FontSize 8,;
      FocusBitmap "Resource #100 DBAS0009.DLL",;
      DownBitmap "Resource #100 DBAS0009.DLL",;
      UpBitmap "Resource #100 DBAS0009.DLL"
  DEFINE PUSHBUTTON Cx OF THIS;
    PROPERTY;
      OnClick {;Form.Close()},;
      Text "&Cancel",;
      Top  7,;
      Left 12,;
      Height 2.5,;
      Width 12,;
      Group .T.,;
      FontSize 8,;
      FocusBitmap "Resource #28 DBAS0009.DLL",;
      DownBitmap "Resource #29 DBAS0009.DLL",;
      UpBitmap "Resource #28 DBAS0009.DLL"
  DEFINE LINE Ln1 OF THIS;
    PROPERTY Left 7, Top 11, Width 4,;
      Bottom 11, Right 29, ColorNormal "RB/W"
  DEFINE PUSHBUTTON Back OF THIS AT 13,7;
    PROPERTY Text "&Back", Height 2,;
      OnClick {;SKIP-1}, FontBold .T.
  DEFINE PUSHBUTTON Next OF THIS AT 13,21;
    PROPERTY TEXT "&Next", Height 2,;
      OnClick {;SKIP}, FontBold .T.
  DEFINE PUSHBUTTON Exit OF THIS AT 16,14;
    PROPERTY Text "&Exit", Height 2,;
      OnClick {;Form.Close()}, FontBold .T.
  DEFINE LINE Ln2 OF THIS;
    PROPERTY Left 7, Top 19, Width 4,;
      Bottom 19, Right 29, ColorNormal "RB/W"
  DEFINE PREVBUTTON PriorRecord OF THIS;
    PROPERTY;
      Top 21 ,;
      Left 6
  DEFINE NEXTBUTTON NextRecord OF THIS;
    PROPERTY;
      Top 21,;
      Left 20
  DEFINE CANCELBUTTON Cy OF THIS;
    PROPERTY;
      Top  24,;
      Left 13
ENDCLASS


See Also

CLASS FORM

DEFINE

ON SELECTION FORM


CLASS RADIOBUTTON

See Also	Example	Classes	Forms

An object that represents a single choice in a set of mutually exclusive choices.

Properties

The following table lists the properties of the Radiobutton class. For more information on each property, see Properties.

Property	Default	Description

Before	N/A	Specifies which object the radio button precedes in the tabbing order of the parent form

ClassName	RADIOBUTTON	Identifies the radio button class

ColorNormal	N/W	Sets the color of the radio button

DataLink	Empty string	Links the radio button to a field

Enabled	.T.	Determines if the radio button can be selected

FontBold	.T.	Determines if characters in the radio button prompt are displayed in bold type

FontItalic	.F.	Determines if characters are displayed in italic type

FontName	MS Sans Serif	Specifies the font to apply to displayed characters

FontSize	N/A	Specifies the size of the font in point size

FontStrikeOut	.F.	Determines if characters are displayed in strikeout type

FontUnderline	.F.	Determines if characters are displayed in underlined type

Group	.F.	Starts an object group in the parent form

Height	N/A	Sets the height

HelpFile	Empty string	Identifies a Windows Help file (.HLP) that contains context-sensitive help topics

HelpID	Empty string	Specifies the context string or context number of a help topic in a Windows Help file (.HLP)

hWnd	N/A	Returns the radio button handle

ID	-1	Identifies the radio button with a numeric value

Left	N/A	Sets the position of the left border

MousePointer	0	Specifies the mouse pointer type when the pointer is over the radio button

Move( )	N/A	Moves or sizes the radio button

Name	RADIOBUTTON1	Specifies the name of the radio button

OldStyle	.F.	Determines if the radio button is displayed in the default Windows style or in Borland style

OnChange	N/A	Executes a subroutine when the user selects a different radio button

OnGotFocus	N/A	Executes a subroutine when the radio button receives focus

OnHelp	N/A	Executes a subroutine when the user presses F1

OnLeftDblClick	N/A	Executes a subroutine when the user double-clicks the radio button

OnLeftMouseDown	N/A	Executes a subroutine when the user clicks the radio button with the left mouse button

OnLeftMouseUp	N/A	Executes a subroutine when the user releases the left mouse button while the pointer is over the radio button

OnLostFocus	N/A	Executes a subroutine when focus is removed

OnMiddleDblClick	N/A	Executes a subroutine when the user double-clicks the radio button with the middle mouse button

OnMiddleMouseDown	N/A	Executes a subroutine when the user clicks the radio button with the middle mouse button

OnMiddleMouseUp	N/A	Executes a subroutine when the user releases the middle mouse button while the pointer is on the radio button

OnMouseMove	N/A	Executes a subroutine when the user moves the mouse in the radio button

OnOpen	N/A	Executes a subroutine when the parent form is opened

OnRightDblClick	N/A	Executes a subroutine when the user double-clicks the radio button with the right mouse button

OnRightMouseDown	N/A	Executes a subroutine when the user clicks the radio button with the right mouse button

OnRightMouseUp	N/A	Executes a subroutine when the user releases the right mouse button while the pointer is on the radio button

Parent	N/A	An object reference that points to the parent form

Release( )	N/A	Removes the radio button definition from memory

SetFocus( )	N/A	Gives focus to the radio button

StatusMessage	Empty string	Specifies a message to display on the status bar

TabStop	.T.	Determines if the user can give focus to the radio button by pressing Tab or Shift+Tab

Text	RADIOBUTTON1	Specifies a character string to display next to the radio button

Top	N/A	Sets the position of the top border

Value	Empty string	Sets the value in the radio button

Visible	.T.	Determines whether the radio button is visible or hidden

When	N/A	Specifies a condition that must evaluate to true before the user can give focus to the radio button

Width	N/A	Sets the width

Description

Use a radio button group to make users choose between options you provide, like the buttons on older car radios. The user can select only one option from a group; for example, a report-printing application might use a three-button group that gives a choice between "Printer", "Screen", or "File".

Use the Group property to make two or more radio buttons work together. For example, if you create seven radio buttons and set the Group properties of the first and fourth radio button to true (.T.), the first three buttons form one group, and the last four form another. The two groups are independent; the user can select one button in the first group and one button in the other.

Use the DataLink property to link the radio button with a field. Use the Text property to specify the value each radio button inserts into the field when chosen. The Text value is automatically displayed as a prompt next to the radio button.

When you create a radio button with the NEW operator, you can specify two parameters:

<parent form reference>--An object reference pointing to the parent form.

<object name expC>--A character string assigned to the Name property of the new radio button. This value is optional.

For example, the following commands create a form and a radio button to display in it:

MyForm = NEW FORM()
MyRadio = NEW RADIOBUTTON(MyForm, "OurRadio")

The Name property of the new radio button contains "OurRadio".

Note:	You can specify a field for the DataLink property with the Choose Field dialog box. To access this dialog box, click on the Tool Button next to the DataLink item in the Object Inspector.


CLASS RADIOBUTTON Example

The following example creates an entry form with three radiobuttons to select a desired conversion factor. Numeric values entered in the entry field are converted to the checked unit of measure after clicking the Compute pushbutton:

** Metric Conversion Program **
SET PROCEDURE TO PROGRAM(1) ADDITIVE
LOCAL f
f=NEW Convert()
f.OPEN()
CLASS Convert OF FORM
  this.Top=2
  this.Left=2
  this.Width=38
  this.Height=18
  this.Text= "Conversion Utility"
  DEFINE ENTRYFIELD Amt OF THIS;
    PROPERTY Value 0, Width 8,;
    Top 4, Left 15
  DEFINE TEXT Ln1 OF THIS;
    PROPERTY;
    Text "Enter Amount; Select a RadioButton",;
    Width 40, Top 2, Left 6
  DEFINE RadioButton Inches OF THIS;
    PROPERTY Text "Inches to Centimeters",;
    Width 22, Value .F., Top 6, Left 8
  DEFINE RadioButton Pounds OF THIS;
    PROPERTY Text "Pounds to Kilograms",;
    Width 21, Value .F., Top 8, Left 8
  DEFINE RadioButton Degrees OF THIS;
    PROPERTY Text "Degrees F to C",;
    Width 21, Value .F., Top 10, Left 8
  DEFINE TEXT Ln2 OF THIS;
    PROPERTY Text "Results:",;
    Width 30, Top 12, Left 8,;
    ColorNormal "R/W"
  DEFINE PUSHBUTTON Results OF THIS;
    PROPERTY TEXT "&Compute",;
    Top 15, Left 15,;
    OnClick {;myResult=Metric(form);
    ;Form.Ln2.Text="Results: " + myResult}
ENDCLASS

FUNCTION Metric(pForm)
DO CASE
   CASE pForm.Inches.Value
      myResult = LTRIM(STR(pForm.Amt.Value;
      * 2.54,10,2))+" Centimeters"
   CASE pForm.Pounds.Value
      myResult = LTRIM(STR(pForm.Amt.Value;
      * .454,10,2))+" Kilograms"
   CASE pForm.Degrees.Value
      myResult = LTRIM(STR((pForm.Amt.Value;
      -32)* (5/9),10,2))+" Degrees C"
ENDCASE
RETURN myResult


See Also

DEFINE


CLASS RECTANGLE

See Also	Example	Classes	Forms

A rectangle you display at a specified location in a form.

Properties

The following table lists the properties of the Rectangle class. For more information on each property, see Properties.

Property	Default	Description

Border	.T.	Determines if the rectangle object is surrounded with a border

BorderStyle	Normal	Determines whether the border is Normal, Raised, or Lowered

ClassName	RECTANGLE	Identifies the rectangle class

ColorNormal	N/W	Sets the color of the rectangle object

FontBold	.F.	Determines if characters in the label of the rectangle object are displayed in bold type

FontItalic	.F.	Determines if characters in the label of the rectangle object are displayed in italic type

FontName	MS Sans Serif	Specifies the font to apply to displayed characters

FontSize	N/A	Specifies the size of the font in points

FontStrikeOut	.F.	Determines if characters in the label of the rectangle object are displayed in strikeout type

FontUnderline	.F.	Determines if characters in the label of the rectangle object are displayed in underlined type

Height	N/A	Sets the height

hWnd	N/A	Returns the object handle of the rectangle object

Left	N/A	Sets the position of the left border

MousePointer	0	Specifies the mouse pointer type when the pointer is over the rectangle object

Move( )	N/A	Moves or sizes the rectangle object

Name	RECTANGLE1	Specifies the name of the rectangle object

OldStyle	.F.	Determines if the rectangle object is displayed in the default Windows style or in Borland style

OnLeftDblClick	N/A	Executes a subroutine when the user double-clicks the rectangle object

OnLeftMouseDown	N/A	Executes a subroutine when the user clicks the rectangle object with the left mouse button

OnLeftMouseUp	N/A	Executes a subroutine when the user releases the left mouse button while the pointer is over the rectangle object

OnMiddleDblClick	N/A	Executes a subroutine when the user double-clicks the rectangle object with the middle mouse button

OnMiddleMouseDown	N/A	Executes a subroutine when the user clicks the rectangle object with the middle mouse button

OnMiddleMouseUp	N/A	Executes a subroutine when the user releases the middle mouse button while the pointer is on the rectangle object

OnMouseMove	N/A	Executes a subroutine when the user moves the mouse in the rectangle object

OnOpen	N/A	Executes a subroutine when the parent form is opened

OnRightDblClick	N/A	Executes a subroutine when the user double-clicks the rectangle object with the right mouse button

OnRightMouseDown	N/A	Executes a subroutine when the user clicks the rectangle object with the right mouse button

OnRightMouseUp	N/A	Executes a subroutine when the user releases the right mouse button while the pointer is on the rectangle object

Parent	Empty string	An object reference that points to the parent form

PatternStyle	Solid	Specifies a pre-defined Windows background hatching pattern

Release( )	N/A	Removes the rectangle object definition from memory

Text	RECTANGLE1	Specifies a character string to display in the label of the rectangle object

Top	N/A	Sets the position of the top border

Visible	.T.	Determines whether the rectangle object is visible or hidden

Width	N/A	Sets the width

Description

Use a rectangle object to enclose an area of a form. For example, you can use a rectangle object to draw a border around a group of related objects, such as a group of radio buttons.

To assign a label that describes the group of objects, use the Text property. The label appears in the top left corner of the rectangle.

A rectangle object does not affect other objects. The user cannot give focus to the rectangle object, and it does not display or modify data.

When you create a rectangle object with the NEW operator, you can specify two parameters:

<parent form reference>--An object reference pointing to the parent form.

<object name expC>--A character string assigned to the Name property of the new rectangle object. This value is optional.

For example, the following commands create a form and a rectangle object to display in it:

MyForm = NEW FORM()
MySquare = NEW RECTANGLE(MyForm, "OurSquare")

The Name property of the new rectangle object contains "OurSquare".


CLASS RECTANGLE Example

The following example uses DEFINE RECTANGLE, within a Class definition, to create a lowered-border rectangle in the center of the form, which creates the visual effect of a raised border around the edge of the form:

LOCAL f
f=NEW DISPLAY()
f.OPEN()
CLASS DISPLAY OF FORM
  this.Top=2
  this.Left=2
  this.Width=36
  this.Height=13
  this.Text= "Class Rectangle Demo"
  DEFINE RECTANGLE Rec1 OF THIS;
    PROPERTY;
      Left 3,;
      Top 2,;
      Width 30,;
      Height 9,;
      ColorNormal "RB/W",;
      BorderStyle 2        && Lowered border style
  DEFINE TEXT Txt1 OF THIS;
    PROPERTY;
      Text "dBASE for Windows",;
      Top 4, Left 5,;
      FontItalic .T., FontSize 14,;
      Width 24, Height 3, FontBold .T.,;
      ColorNormal "RB/W"
  DEFINE TEXT Txt2 OF THIS;
    PROPERTY;
      Text "has arrived",;
      Top 7, Left 10,;
      FontItalic .T., FontSize 14,;
      Width 18, Height 3, FontBold .T.
ENDCLASS


See Also

CLASS LINE


CLASS SCROLLBAR

See Also	Example	Classes	Forms

An object that lets the user increase or decrease a value by moving a slider button.

Properties

The following table lists the properties of the Scrollbar class. For more information on each property, see Properties.

Property	Default	Description

Before	N/A	Specifies which object the scroll bar precedes in the tabbing order of the parent form

ClassName	SCROLLBAR	Identifies the scrollbar class

DataLink	Empty string	Links the scroll bar to a field

Enabled	.T.	Determines if the scroll bar can be selected

Height	N/A	Sets the height

HelpFile	Empty string	Identifies a Windows Help file (.HLP) that contains context-sensitive help topics

HelpID	Empty string	Specifies the context string or context number of a help topic in a Windows Help file (.HLP)

hWnd	N/A	Returns the scroll bar object handle

ID	-1	Identifies the scroll bar with a numeric value

Left	N/A	Sets the position of the left border

MousePointer	0	Specifies the mouse pointer type when the pointer is over the scroll bar

Move( )	N/A	Moves or sizes the scroll bar

Name	SCROLLBAR1	Specifies the name of the scrollbar

OnChange	N/A	Executes a subroutine when the user moves the slider button

OnGotFocus	N/A	Executes a subroutine when the scroll bar receives focus

OnHelp	N/A	Executes a subroutine when the user presses F1

OnLeftDblClick	N/A	Executes a subroutine when the user double-clicks the scroll bar

OnLeftMouseDown	N/A	Executes a subroutine when the user clicks the scroll bar with the left mouse button

OnLeftMouseUp	N/A	Executes a subroutine when the user releases the left mouse button while the pointer is over the scroll bar

OnLostFocus	N/A	Executes a subroutine when focus is removed

OnMiddleDblClick	N/A	Executes a subroutine when the user double-clicks the scroll bar with the middle mouse button

OnMiddleMouseDown	N/A	Executes a subroutine when the user clicks the scroll bar with the middle mouse button

OnMiddleMouseUp	N/A	Executes a subroutine when the user releases the middle mouse button while the pointer is on the scroll bar

OnMouseMove	N/A	Executes a subroutine when the user moves the mouse in the scroll bar

OnOpen	N/A	Executes a subroutine when the parent form is opened

OnRightDblClick	N/A	Executes a subroutine when the user double-clicks the scroll bar with the right mouse button

OnRightMouseDown	N/A	Executes a subroutine when the user clicks the scroll bar with the right mouse button

OnRightMouseUp	N/A	Executes a subroutine when the user releases the right mouse button while the pointer is on the scroll bar

Parent	N/A	An object reference that points to the parent form

RangeMax	100.00	Determines the upper limit for the value linked to the scroll bar

RangeMin	1.00	Determines the lower limit for the value linked to the scroll bar

Release( )	N/A	Removes the scroll bar definition from memory

SetFocus( )	N/A	Gives focus to the scrollbar

StatusMessage	Empty string	Specifies a message to display on the status bar

TabStop	.T.	Determines if the user can give focus to the scroll bar by pressing Tab or Shift+Tab

Top	N/A	Sets the position of the top border

Value	1	Sets the value in the scroll bar

Vertical	.T.	Determines whether the scroll bar is aligned vertically or horizontally

Visible	.T.	Determines whether the scroll bar is visible or hidden

When	N/A	Specifies a condition that must evaluate to true before the user can give focus to the scroll bar

Width	N/A	Sets the width

Description

Use a scroll bar to let users vary numeric values rapidly. Unlike spin boxes, scroll bars do not accept keyboard input or use a Step value. Instead, the user drags the slider button to increase or decrease the value.

As the user moves the slider button, the value is continually updated to reflect the position of the button. For example, a scroll bar that varies a numeric value between 1 and 100 sets the value to 50 when the slider button is at the center of the scroll bar.

Link a scroll bar to a numeric field with the DataLink property.

To set a range for the scrollbar, set RangeMin to the minimum value and RangeMax to the maximum value.

You can combine a scroll bar with an entry field so that values set through the scroll bar are reflected in the entry field. To do so, give the entry field the same DataLink specification as the scroll bar.

When you create a scroll bar with the NEW operator, you can specify two parameters:

<parent form reference>--An object reference pointing to the parent form.

<object name expC>--A character string assigned to the Name property of the new scroll bar. This value is optional.

For example, the following commands create a form and a scroll bar to display in it:

MyForm = NEW FORM()
MyScroll = NEW SCROLLBAR(MyForm, "OurScroll")

The Name property of the new scroll bar contains "OurScroll".


CLASS SCROLLBAR Example

The following example creates a form with an entry field object that displays the value in the GNP field of Country.DBF. A horizontal scroll bar can be used to change the field value within a specified range:

LOCAL f
f=NEW DISPLAY()
f.OPEN()
CLASS DISPLAY OF FORM
  this.Top=2
  this.Left=2
  this.Width=36
  this.Height=13
  this.View = "Country.DBF"
  this.Text= "Class Scrollbar Demo"
  DEFINE ENTRYFIELD Etf1 OF THIS;
    PROPERTY Datalink "Country->GNP",;
    Width 9, Top 4, Left 13
  DEFINE SCROLLBAR Sb1 OF THIS;
    PROPERTY Vertical .F., Height 2,;
    Top 6, Left 5,;
    Width 25, DataLink "Country->GNP",;
    RangeMin 1000, RangeMax 999999999
  DEFINE TEXT Txt1 OF THIS;
    PROPERTY Text "***Range: 1000 to 999999999***",;
      Top 9, Left 0, Width 36, Alignment 7
ENDCLASS


See Also

CLASS SPINBOX


CLASS SPINBOX

See Also	Example	Classes	Forms

An object that lets the user enter values in a text box or change a value by clicking arrow buttons.

Properties

The following table lists the properties of the Spinbox class. For more information on each property, see Properties.

Property	Default	Description

Before	N/A	Specifies which object the spin box precedes in the tabbing order of the parent form

Border	.T.	Determines if the spin box is surrounded with a border

ClassName	SPINBOX	Identifies the spin boxbutton class

ColorHighlight	N/W	Sets the color of the spin box when it is highlighted

ColorNormal	N/W	Sets the color of the spin box when it is not highlighted

DataLink	Empty string	Links the spin box to a field

Enabled	.T.	Determines if the spin box can be selected

FontBold	.T.	Determines if characters are displayed in bold type

FontItalic	.F.	Determines if characters are displayed in italic type

FontName	MS Sans Serif	Specifies the font to apply to displayed characters

FontSize	N/A	Specifies the size of the font in points

FontStrikeOut	.F.	Determines if characters are displayed in strikeout type

FontUnderline	.F.	Determines if characters are displayed in underlined type

Function	Empty string	Formats displayed text

Height	N/A	Sets the height

HelpFile	Empty string	Identifies a Windows Help file (.HLP) that contains context-sensitive Help topics

HelpID	Empty string	Specifies the context string or context number of a Help topic in a Windows Help file (.HLP)

hWnd	N/A	Returns the object handle of the spin box

ID	-1	Identifies the spin box with a numeric value

Left	N/A	Sets the position of the left border

MousePointer	0	Specifies the mouse pointer type when the pointer is over the spin box

Move( )	.F.	Moves or sizes the spin box

Name	SPINBOX1	Specifies the name of the spin box

OldStyle	.F.	Determines if the spin box is displayed in the default Windows style or in Borland style

OnChange	N/A	Executes a subroutine when the user changes a value

OnGotFocus	N/A	Executes a subroutine when the spin box receives focus

OnHelp	N/A	Executes a subroutine when the user presses F1

OnLeftDblClick	N/A	Executes a subroutine when the user double-clicks the spin box

OnLeftMouseDown	N/A	Executes a subroutine when the user clicks the spin box with the left mouse button

OnLeftMouseUp	N/A	Executes a subroutine when the user releases the left mouse button while the pointer is over the spin box

OnLostFocus	N/A	Executes a subroutine when focus is removed

OnMiddleDblClick	N/A	Executes a subroutine when the user double-clicks the spin box with the middle mouse button

OnMiddleMouseDown	N/A	Executes a subroutine when the user clicks the spin box with the middle mouse button

OnMiddleMouseUp	N/A	Executes a subroutine when the user releases the middle mouse button while the pointer is on the spin box

OnMouseMove	N/A	Executes a subroutine when the user moves the mouse in the spin box

OnOpen	N/A	Executes a subroutine when the parent form is opened

OnRightDblClick	N/A	Executes a subroutine when the user double-clicks the spin box with the right mouse button

OnRightMouseDown	N/A	Executes a subroutine when the user clicks the spin box with the right mouse button

OnRightMouseUp	N/A	Executes a subroutine when the user releases the right mouse button while the pointer is on the spin box

Parent	Empty string	An object reference that points to the parent form

Picture	Empty string	Formats text

RangeMax	100.00	Determines the upper limit for the value linked to the spin box

RangeMin	1.00	Determines the lower limit for the value linked to the spin box

RangeRequired	.F.	Determines whether the range you specify with RangeMax and RangeMin applies to all data or to new data only

Release( )	N/A	Removes the spin boxbutton definition from memory

SelectAll	.F.	Determines if the initial value is selected (highlighted)

SetFocus( )	N/A	Gives focus to the spin box

SpinOnly	.F.	Enables or disables editing in the text box portion of the spin box.

StatusMessage	Empty string	Specifies a message to display on the status bar

Step	1	Determines how much a user can add to and subtract from a value by clicking on the spin boxbutton arrows

TabStop	.T.	Determines if the user can give focus to the spin box by pressing Tab or Shift+Tab

Top	N/A	Sets the position of the top border

Valid	N/A	Specifies a condition that must evaluate to true (.T.) before the user can remove focus from the spin box

ValidErrorMsg	Empty string	Specifies a character string to display on the status bar when the Valid property returns false (.F.)

ValidRequired	.F.	Determines if the Valid property applies to all data or to new data only

Value	1	Sets the value in the spin box

Visible	.T.	Determines whether the spin box is visible or hidden

When	N/A	Specifies a condition that must evaluate to true before the user can give focus to the spin box

Width	N/A	Sets the width

Description

Use a spin box to let users enter values by typing them in the text box or by increasing or decreasing the current value using the up and down arrow buttons.

Spin boxes control the rate at which users change numeric or date values. For example, one spin box might change an interest rate in increments of hundredths, while another might change a date value in year increments. Set the size of each increment with the Step property; for example, if you set Step to 5, each click on an arrow changes a numeric value by 5 or a date value by 5 days.

Link a spin box to a numeric, float, or date field with the DataLink property. The Value property contains the current value of the field.

To restrict entries to those within a particular range of values, set the RangeMin property to the minimum value and RangeMax to the maximum value. If you want users to only select values with the arrow buttons, set SpinOnly to true (.T.).

When you create a spin box with the NEW operator, you can specify two parameters:

<parent form reference>--An object reference pointing to the parent form.

<object name expC>--A character string assigned to the Name property of the new spin box. This value is optional.

For example, the following commands create a form and a spin box to display in it:

MyForm = NEW FORM()
MySpin = NEW SPINBOX(MyForm, "OurSpin")

The Name property of the new spin box contains "OurSpin".


CLASS SPINBOX Example

The following example creates a form with a browse object displaying country population data and a spin box object for incrementing population by intervals of 1000:

LOCAL f
f=NEW DISPLAY()
f.OPEN()
CLASS DISPLAY OF FORM
  this.Top=2
  this.Left=2
  this.Width=36
  this.Height=13
  this.View = "Country.DBF"
  this.Text= "Class SpinBox Demo"
  DEFINE BROWSE BR1 OF THIS;
    PROPERTY Fields "Name, Population, GNP",;
    Top 1, Left 1.5, Width 32, Height 6
  DEFINE SPINBOX Sp1 OF THIS;
    PROPERTY;
      Datalink "Country->Population",;
      Top 10,;
      Left 19,;
      Height 2.0,;
      Width 15,;
      TabStop .F.,;
      Step 1000
  DEFINE TEXT Txt1 OF THIS;
    PROPERTY Top 10.5, Left 2, Width 16,;
      Text "Change Population:", ColorNormal "R/W"
ENDCLASS


See Also

CLASS SCROLLBAR


CLASS TEXT

See Also	Example	Classes	Forms

A string of text characters.

Properties

The following table lists the properties of the Text class. For more information on each property, see Properties.

Property	Default	Description

Alignment	Top Left	Positions text in the text object

Before	N/A	Specifies which object the text object precedes in the tabbing order of the parent form.

Border	.T.	Determines if the text object is surrounded with a border

ClassName	TEXT	Identifies the text class

ColorNormal	N/W	Sets the color of the text

FontBold	.T.	Determines if characters are displayed in bold type

FontItalic	.F.	Determines if characters are displayed in italic type

FontName	MS Sans Serif	Specifies the font to apply to displayed characters

FontSize	N/A	Specifies the size of the font in points

FontStrikeOut	.F.	Determines if characters are displayed in strikeout type

FontUnderline	.F.	Determines if characters are displayed in underlined type

Function	Empty string	Formats displayed text

GetTextExtent( )	N/A	Returns the length of the text object based on a comparison between the font of the text object and the font of the form

Height	N/A	Sets the height

hWnd	N/A	Returns the object handle of the text object

ID	-1	Identifies the text object with a numeric value

Left	N/A	Sets the position of the left border

MousePointer	0	Specifies the mouse pointer type when the pointer is over the text object

Move( )	.F.	Moves or sizes the text object

Name	TEXT1	Specifies the name of the text object

OldStyle	.F.	Determines if the text object is displayed in the default Windows style or in Borland style

OnLeftDblClick	N/A	Executes a subroutine when the user double-clicks the text object

OnLeftMouseDown	N/A	Executes a subroutine when the user clicks the text object with the left mouse button

OnLeftMouseUp	N/A	Executes a subroutine when the user releases the left mouse button while the pointer is over the text object

OnMiddleDblClick	N/A	Executes a subroutine when the user double-clicks the text object with the middle mouse button

OnMiddleMouseDown	N/A	Executes a subroutine when the user clicks the text object with the middle mouse button

OnMiddleMouseUp	N/A	Executes a subroutine when the user releases the middle mouse button while the pointer is on the text object

OnMouseMove	N/A	Executes a subroutine when the user moves the mouse in the text object

OnOpen	N/A	Executes a subroutine when the parent form is opened

OnRightDblClick	N/A	Executes a subroutine when the user double-clicks the text object with the right mouse button

OnRightMouseDown	N/A	Executes a subroutine when the user clicks the text object with the right mouse button

OnRightMouseUp	N/A	Executes a subroutine when the user releases the right mouse button while the pointer is on the text object

Parent	N/A	An object reference that points to the parent form

Picture	Empty string	Formats text

Release( )	N/A	Removes the text object definition from memory

Text	Text	Specifies the displayed character string

Top	N/A	Sets the position of the top border

Visible	.T.	Determines whether the text object is visible or hidden

Width	N/A	Sets the width

Description

Use a text object as a prompt, heading, label, or reminder. For example, a text object can prompt the user to enter values in an entry field, or give brief instructions on using a scroll bar.

Use the Text property to specify the character string to display. The displayed text is read-only; the user cannot give it focus or modify it directly.

When you create a text object with the NEW operator, you can specify two parameters:

<parent form reference>--An object reference pointing to the parent form.

<object name expC>--A character string assigned to the Name property of the new text object. This value is optional.

For example, the following commands create a form and a text object to display in it:

MyForm = NEW FORM()
MyText = NEW TEXT(MyForm, "OurText")

The Name property of the new text object contains "OurText".


CLASS TEXT Example

The following example places three text line samples on the form. The first uses a font predefined by #define; the second and third demonstrate alternative parameter options:

#define BIGFONT    FontName "Arial", FontSize 26
LOCAL f
f=NEW Demo()
f.OPEN()
CLASS Demo OF FORM
  this.Top=2
  this.Left=2
  this.Width=50
  this.Height=13
  this.Text= "Class TEXT Demo"
  DEFINE TEXT Txt1 OF THIS;
    PROPERTY;
      Top 1,;
      Left 0,;
      Alignment 4,;
      Text "dBASE for Windows",;
      Height 3,;
      Width 50,;
      BIGFONT,;
      ColorNormal "R/W"
  DEFINE TEXT Txt2 OF THIS;
    PROPERTY;
      Top 5,;
      Left 0,;
      Alignment 4,;
      Text "is here in '94",;
      Height 2,;
      Width 50,;
      FontBold .T.,;
      FontItalic .T.,;
      FontSize 16
  DEFINE TEXT Txt3 OF THIS;
    PROPERTY;
      Top 8,;
      Left 10,;
      Alignment 4,;
      Text "from BORLAND",;
      Height 3,;
      Width 30,;
      FontBold .T.,;
      FontSize 22,;
      Border .T.,;
      ColorNormal "GB/W"
ENDCLASS


See Also

DEFINE


CLEAR

See Also	Portability	Environment

Erases the contents of the results pane of the Command window or the current dBASE IV window, and clears pending @...GETs.

Syntax

CLEAR
[CHARACTER <expC>]

CHARACTER <expC>

Fills the results pane of the Command window or the current dBASE IV window with the first character of the expression <expC>. If you do not specify a character, CLEAR fills the window with the last character specified by <expC>, if any, or else with space characters.

Description

Use CLEAR to remove the contents of the results pane of the Command window or the current dBASE IV window. Use the option CHARACTER <expC> with CLEAR to specify a character for dBASE to repeat when clearing the window. To clear only parts of the window, use @...CLEAR.

If you use CLEAR without an option after issuing CLEAR CHARACTER <expC>, CLEAR uses <expC> again. To reset CLEAR, issue CLEAR CHARACTER " " (with a space character or empty string as <expC>).

If you do not want to close and remove open GETs from the display, issue READ SAVE before CLEAR.

CLEAR does not close the window. CLEAR also does not affect dBASE for Windows forms, which you create with DEFINE FORM.


Portability

The CHARACTER <expC> option is not supported in dBASE IV or dBASE III PLUS.


See Also

@...CLEAR

@...SAY...GET

DEFINE FORM

READ


CLEAR ALL

See Also	Portability	Environment

Releases all memory variables (except system memory variables), closes a catalog if one is open, closes all open tables, and selects work area 1.

Syntax

CLEAR ALL

Description

Use CLEAR ALL to close open tables and databases in the current session and clear the working environment without affecting any open PROCEDURE or LIBRARY files. CLEAR ALL does all of the following:

Releases all memory variables (except system memory variables) in all currently active sessions

Closes all open dBASE IV windows

Removes from memory all dBASE IV window definitions, including window elements, menu bars, pull-down menus, and pop-up menus

Closes an open catalog (.CAT) file

Closes all open tables and databases in the current session, and their associated index, memo, and format files

Selects work area 1

Note:	CLEAR ALL does not normally release objects. However, if the only reference to an object is in a memory variable, CLEAR ALL releases the object.


Portability

Not supported in dBASE III PLUS.


See Also

CLEAR PROGRAM

CLOSE...

RELEASE

SET PROCEDURE

SET LIBRARY


CLEAR AUTOMEM

See Also	Example	Fields and Records

Initializes automem variables with empty values for the current table.

Syntax

CLEAR AUTOMEM

Description

Use CLEAR AUTOMEM to initialize a set of automem variables containing empty values for the current table. CLEAR AUTOMEM creates any automem variables that do not exist already. If the variables exist, CLEAR AUTOMEM reinitializes them. If no table is in use, CLEAR AUTOMEM does not create any variables.

Automem variables have the same names and data types as the fields in an active table. You can create empty automem variables automatically for the current table by using CLEAR AUTOMEM or USE...AUTOMEM, or manually by using STORE.

Use CLEAR AUTOMEM if automem variables are used more than once within a program, so that automem variables are reset with empty values and do not carry over into a subsequent form display or record. For example, use CLEAR AUTOMEM within a loop that adds data by means of a form, automem variables, and APPEND AUTOMEM, so that the values entered on one pass of the loop do not appear in the entry form on the next pass.

You can also use CLEAR AUTOMEM to create automem variables if you did not create them with USE...AUTOMEM. For example, you can create automem variables from the Command window for a table already in use.


CLEAR AUTOMEM Example

The following example uses CLEAR AUTOMEM to enable the user to edit AUTOMEM variables for a new record. A new record will be added only if the user confirms that the data held in automem variables is correct:

SET TALK OFF
CLEAR
USE Clients
AddMoreData()
RETURN

FUNCTION AddMoreData
@0,0 to 8, 70
@10,20 to 12,45
CLEAR AUTOMEM
DO WHILE .T.
  lConfirm = .f.
  @11,22 CLEAR TO 11,39
  @1,1 SAY 'ID' GET m->CLIENT_ID
  @1,10 SAY 'COMPANY' GET m->COMPANY
  @3,1 SAY 'Contact' GET m->CONTACT
  @4,1 SAY 'Address' GET m->ADDRESS
  @6,1 SAY 'City' GET m->CITY
  @6,23 SAY 'State/Province' GET STATE_PROV
  @6,54 SAY 'Zip' GET ZIP_P_CODE
  READ
    IF READKEY() = 12
      EXIT
    ELSE
      @ 11,22 SAY "Data Correct, Y-N?";
      GET lConfirm picture 'Y'
      READ
        IF lConfirm
          APPEND AUTOMEM
          CLEAR AUTOMEM
        ENDIF
      ENDIF
   ENDDO
   RETURN .T.


See Also

APPEND

STORE

USE


CLEAR FIELDS

See Also	Example	Fields and Records

Removes the fields list defined with the SET FIELDS TO command.

Syntax

CLEAR FIELDS

Description

Use CLEAR FIELDS to remove the SET FIELDS TO <field list> setting in all work areas and automatically turn SET FIELDS to OFF, thus making all fields in all open tables accessible. You can use CLEAR FIELDS prior to specifying a new fields list with SET FIELDS TO. You might also want to use CLEAR FIELDS at the end of a program. CLEAR FIELDS has the same effect as SET FIELDS TO with no options.


CLEAR FIELDS Example

See SET FIELDS for examples of CLEAR FIELDS.


See Also

SET FIELDS


CLEAR GETS

See Also	Example	Portability	Input/Output

Clears all current @...GET fields. This command is supported primarily for compatibility with dBASE IV. In dBASE for Windows, use DEFINE with the Text and EntryField classes for displaying and accepting information on a form.

Syntax

CLEAR GETS

Description

Use CLEAR GETS to make all currently activated @...GET fields in the Command window or current dBASE IV-style window inactive. You cannot edit an inactive @...GET field. (CLEAR GETS does not release memory variables or array elements.)


CLEAR GETS Example

See READ for an example of CLEAR GETS.


Portability

In dBASE III PLUS, in which no windows occur, @...GET fields occur on the screen. In dBASE IV, @...GET fields can appear on the screen outside of windows.


See Also

@...SAY...GET

DEFINE


CLEAR MEMORY

See Also	Example	Memory Variables

Clears all user-defined memory variables.

Syntax

CLEAR MEMORY

Description

Use CLEAR MEMORY to release all memory variables (except system memory variables) in all currently active sessions, including those declared PUBLIC and STATIC and those initialized in higher-level subroutines. CLEAR MEMORY has no effect on system memory variables.

Note:	CLEAR MEMORY does not normally release objects. However, if the only reference to an object is in a memory variable, CLEAR MEMORY releases the object.

CLEAR MEMORY, whether issued in a program or in the Command window, has the same effect as issuing RELEASE ALL in the Command window. However, CLEAR MEMORY in a program is different from RELEASE ALL in a program. RELEASE ALL in a program clears only memory variables created at the same program level as the RELEASE ALL statement. Unlike CLEAR MEMORY, it has no effect on higher-level, public, or static variables.

CLEAR MEMORY is also different from RELEASE AUTOMEM. In a program or in the Command window, RELEASE AUTOMEM erases only automem variables associated with the current table. (For information about AUTOMEM variables, see USE, CLEAR AUTOMEM, and RELEASE AUTOMEM.)

To clear only selected memory variables, use RELEASE.


CLEAR MEMORY Example

The following example uses CLEAR MEMORY to release variables held in an array after they have been saved to a .DBF file used for backup purposes:

SET SAFETY OFF
USE Clients EXCLUSIVE
INDEX ON Client_ID TAG Client_ID
DECLARE StbyInfo[RECCOUNT(),FLDCOUNT()]
COPY TO ARRAY StbyInfo
*
* Perform various file operations...
*
COPY STRUCTURE TO Backup.DBF WITH PRODUCTION
USE Backup
APPEND FROM ARRAY StbyInfo
CLEAR MEMORY      && Releases values held;
                     in StbyInfo array
* Subsequent operations that require
* additional memory...
CLOSE ALL


See Also

CLEAR AUTOMEM

PRIVATE

PUBLIC

RELEASE

RELEASE AUTOMEM

STATIC

USE


CLEAR MENUS

See Also	Example	Portability	dBASE IV Menus

Clears all dBASE IV bar menus from the screen and their definitions from memory. This command is supported primarily for compatibility with dBASE IV. In dBASE for Windows, use RELEASE OBJECT to clear an object from a form.

Syntax

CLEAR MENUS

Description

Use CLEAR MENUS to clear and disable all dBASE IV menu bars and remove their definitions from memory. CLEAR MENUS removes from memory all menu bar names established with DEFINE MENU and all associated menu pad definitions established with DEFINE PAD

CLEAR MENUS works like RELEASE MENUS, except that RELEASE MENUS lets you designate specific menu bar definitions, while CLEAR MENUS releases the definitions of all currently defined menu bars.


CLEAR MENUS Example

See DEFINE MENU for an example of CLEAR MENUS.


Portability

Not supported in dBASE III PLUS.


See Also

DEACTIVATE MENU

DEFINE

RELEASE MENUS

RELEASE OBJECT


CLEAR POPUPS

See Also	Portability	dBASE IV Menus

Clears all dBASE IV pop-up menus from the screen and their definitions from memory. This command is supported primarily for compatibility with dBASE IV. In dBASE for Windows, use RELEASE OBJECT to clear an object from a form.

Syntax

CLEAR POPUPS

Description

Use CLEAR POPUPS to remove from memory all dBASE IV pop-up menus and release their definitions from memory. CLEAR POPUPS removes from memory all pop-up menu definitions established with DEFINE POPUP, and all associated bar definitions established with DEFINE BAR.

CLEAR POPUPS works like RELEASE POPUPS, except that RELEASE POPUPS lets you designate specific pop-up menu definitions, while CLEAR POPUPS releases the definitions of all currently defined pop-up menus.


Portability

Not supported in dBASE III PLUS.


See Also

DEFINE

DEFINE BAR

DEFINE POPUP

RELEASE OBJECT

RELEASE POPUPS


CLEAR PROGRAM

See Also	Example	Portability	Programs

Clears from memory all compiled program files that are not currently executing and are not currently open with SET FORMAT, SET PROCEDURE, or SET LIBRARY.

Syntax

CLEAR PROGRAM

Description

When you run a program with DO, dBASE loads into memory the compiled program and all compiled programs, procedures, user-defined functions (UDFs), and format files the program calls with DO, SET FORMAT, SET PROCEDURE, and SET LIBRARY. These files remain in memory until you issue CLEAR PROGRAM or until dBASE needs more memory--for example, when you open a large table. dBASE's internal dynamic memory management can also make more memory available by clearing from memory any programs that haven't been active for a while.

CLEAR PROGRAM clears all inactive compiled programs from memory. The command does not clear programs that are currently executing or files the current program opens with SET FORMAT, SET PROCEDURE or SET LIBRARY. However, if you close a called file (for example, with CLOSE PROCEDURE or CLOSE FORMAT), a subsequent CLEAR PROGRAM clears the closed file from memory.

Use CLEAR PROGRAM to clear memory before executing tasks that require a lot of memory. For example, use CLEAR PROGRAM before you run a memory-intensive DOS command, before using an external text editor, or before you open a large number of tables.

Do not use CLEAR PROGRAM frequently, because dBASE keeps programs in memory to speed execution. Repeatedly loading called files into memory slows program execution.


CLEAR PROGRAM Example

The following example uses CLEAR PROGRAM to release memory occupied by unused programs, procedures, or format files:

** Main.PRG **
CLEAR
DO Set_Main                        && External PRG
DO Get_Mov                         && Internal Proc
CLEAR PROGRAM                      && Release memory;
                                   by clearing;
                                   programs
DO Mov_Rpt

PROCEDURE Get_Mov
USE Movies
INDEX ON Director TAG Mov_Dir
GOTO rec_no
DO WHILE Director = Mov_Dir
   ? Title
   SKIP
ENDDO WHILE Director = Mov_Dir
GOTO rec_no
CLOSE DATABASES
RETURN


Portability

Not supported in dBASE IV or dBASE III PLUS.


See Also

DO

CLEAR ALL

CLOSE...

SET FORMAT

SET LIBRARY

SET PROCEDURE


CLEAR SCREENS

See Also	Example	Portability	Input/Output

Removes from memory all variables created by SAVE SCREEN, and clears the Command window buffer. This command is supported primarily for compatibility with dBASE IV.

Syntax

CLEAR SCREENS

Description

Use CLEAR SCREENS to release all memory variables created with SAVE SCREEN TO <memvar>. CLEAR SCREENS has no effect on screens saved with the SAVE SCREEN TO FILE option.

To clear only some of the variables created with SAVE SCREEN, use RELEASE or RELEASE SCREENS.


CLEAR SCREENS Example

CLEAR SCREENS has no arguments:

SAVE SCREEN TO SaveScreen
CLEAR SCREENS

The memory variable SaveScreen is released by CLEAR SCREENS.


Portability

Not supported in dBASE III PLUS.


See Also

RELEASE

RELEASE SCREENS

SAVE SCREEN


CLEAR TYPEAHEAD

See Also	Example	Keyboard and Mouse Events

Clears the typeahead buffer, where keystrokes are stored while dBASE is busy processing other data. This command is supported primarily for compatibility with dBASE IV. In dBASE for Windows, forms do not use the typeahead buffer.

Syntax

CLEAR TYPEAHEAD

Description

If you have not issued a SET TYPEAHEAD TO 0 command, the keyboard typeahead buffer stores keystrokes the user enters while dBASE is busy processing other data. When the processing is complete and keyboard input is enabled again, dBASE processes and deletes the values in the buffer in the order they were entered until the buffer is empty. Use CLEAR TYPEAHEAD to discard any keystrokes that may have been entered during processing, to ensure that the keyboard data currently being processed comes directly from the keyboard.

For example, if you want to be able to fill in multiple screens quickly, one after the other, you would not issue CLEAR TYPEAHEAD during processing. This would let you continue typing data while data from one screen was being saved and the next (blank) one being displayed. The data you entered during processing would be entered onto the new screen when it appeared. On the other hand, if you want to make sure that no data is entered until the next screen is displayed, issue CLEAR TYPEAHEAD after displaying the blank screen and before beginning data entry.


CLEAR TYPEAHEAD Example

The following example uses CLEAR TYPEAHEAD to ensure that the user does not inadvertently quit the program when asked the question that follows:

CLEAR
CLEAR TYPEAHEAD
* CLEAR KEY is identical to CLEAR TYPEAHEAD
WAIT "Do you want to quit now? " TO Ans
IF UPPER(Ans)="Y"
  QUIT
ENDIF
RETURN


See Also

SET CONFIRM

SET TYPEAHEAD


CLEAR WINDOWS

See Also	Example	Portability	dBASE IV Windows

Clears all dBASE IV-style windows from the screen and removes their definitions from memory. This command is supported primarily for compatibility with dBASE IV. In dBASE for Windows, use CLOSE FORMS or RELEASE OBJECT to close or release a form.

Syntax

CLEAR WINDOWS

Description

Use CLEAR WINDOWS to clear all windows from the screen and remove their definitions from memory. To clear specific windows from the screen and remove their definitions from memory, use RELEASE WINDOWS. To clear specific windows from the screen while keeping their definitions in memory, use DEACTIVATE WINDOW.


CLEAR WINDOWS Example

See ACTIVATE WINDOW for an example of CLEAR WINDOWS.


Portability

Not supported in dBASE III PLUS.


See Also

CLOSE FORMS

DEACTIVATE WINDOW

DEFINE

RELEASE OBJECT

RELEASE WINDOWS


CLOSE...

See Also	Example	Table Basics

Closes various file types.

Syntax

CLOSE ALL

CLOSE ALTERNATE

CLOSE DATABASES [<database name list>]

CLOSE FORMAT

CLOSE FORMS [<form name list>]

CLOSE INDEXES

CLOSE PRINTER

CLOSE PROCEDURE <filename>

CLOSE TABLES

CLOSE ALL

Closes tables, databases, and files of all types, including low-level files, and reselects work area 1. However, files opened by SET DEVICE TO <filename> or SET PRINTER TO <filename> and SQL databases remain open. To close SQL databases, use CLOSE DATABASES.

CLOSE ALTERNATE

Closes text (.TXT) files opened with the SET ALTERNATE command.

CLOSE DATABASES [<database name list>]

Closes a specified list of databases (separated by commas) or all open databases, including all tables, and associated index (.MDX and .NDX) files, memo (.DBT) files, and format (.FMT) files for each database.

CLOSE FORMAT

Closes format (.FMT) files open in the current work area.

CLOSE FORMS [<form name list>]

Closes the specified forms and executes the standard close routines for the forms and the objects that are contained in them.

CLOSE INDEXES

Closes index (.MDX and .NDX) files open in the current work area. This option does not close the production .MDX file.

CLOSE PRINTER

Closes a file opened with the SET PRINTER command.

CLOSE PROCEDURE <filename>

Closes an open procedure file.

CLOSE TABLES

Closes all tables in all work areas or all tables in the current database, if one is selected.

Description

If you use the CREATE SESSION command, the CLOSE commands affect only the files in the current session. A session is similar to a user session in a multi-usr envronment - each session manages its own set of work areas, and a file opened as exclusive cannot be accessed by other sessions.

By default, the dBASE for Windows interactive environment operates with CREATE SESSION. For example, if you open tables through the user interface (for example, by double-clicking the file icon), dBASE opens each table in its own session (observe the Command window and you will notice that a CREATE SESSION command is executed each time you open a table). If you then type CLOSE TABLES in the Command window, the tables remain open because they are protected by their sessions. As in a multi-user environment, a user cannot close the files in use by another user.

The Command window itself runs in an independent session; that is another reason why the CLOSE commands issued there have no effect on files opened through the user interface. If, however, you open tables by using the USE and BROWSE commands in the Command window, those tables are in the Command window session. Therefore, when you type CLOSE TABLES in the Command window, those tables are closed.

For more information about sessions, see CREATE SESSION.


CLOSE... Example

The following example uses CLOSE ALL to close all open tables upon completion of a report:

SET SAFETY OFF
SET TALK OFF
USE Contact EXCLUSIVE IN SELECT()
INDEX ON COMPCODE TAG COMPCODE
USE Company IN SELECT()
SELECT Company
SET RELATION TO CompCode INTO Contact
GO TOP
DO ListComp
CLOSE ALL

PROCEDURE ListComp
SET ALTERNATE TO CompList
SET ALTERNATE ON
CLEAR
? "Company" AT 5, "Contact Person" AT 45
?
DO WHILE .NOT. EOF()
  ? Company->Company AT 5, Contact->Contact AT 45
  ? "In " + REPLICATE("- ",7) + "->" AT 5,;
    TRIM(Company->City) +", " +;
    TRIM(Company->State_Prov) AT 25
   SKIP
ENDDO
RETURN


See Also

CLEAR ALL

CREATE SESSION


CMONTH( )

See Also	Example	Date and Time Data

Returns the name of the month in which a specified date expression falls.

Syntax

CMONTH(<expD>)

<expD>

The date expression, in the current date format, whose corresponding month name to return.

Description

CMONTH( ) returns a character string containing the name of the month in which a date falls.

Enter <expD> in the current date format as determined by SET DATE, DBASEWIN.INI, or the International option of the Windows Control Panel (in that order). That is, SET DATE settings override those in DBASEWIN.INI, and settings in DBASEWIN.INI override those in the Windows Control Panel. Be sure <expD> matches the date format in use when your program runs.

If you pass an invalid date to CMONTH( ), dBASE converts the date to a valid one and returns the month name of that date. If you pass an empty or non-date expression delimited with braces ({ }) to CMONTH( ), it returns "Unknown". If you pass a non-date expression or an expression that is not delimited with braces to CMONTH( ), it returns an error.


CMONTH( ) Example

The following example uses CMONTH( ), DAY( ), and YEAR( ) to return the literal day of week, month, date and year in a character string.

SET TALK OFF
SET CENTURY ON
date = {04/01/94}
? FullDate(date)	&& Function is called;
                     returns "Friday, April 1, 1994"

FUNCTION FullDate
PARAMETERS date
full_date = CDOW(date) +  ", " + CMONTH(date) + ;
   " "  + LTRIM(STR(DAY(date))) + ;
   ", " + LTRIM(STR(YEAR(date)))
RETURN full_date


See Also

CDOW( )

DAY( )

MONTH( )

SET DATE

YEAR( )


COL( )

See Also	Example	Input/Output

Returns the number of the current column position in the results pane of the Command window or the current dBASE IV window. This command is supported primarily for compatibility with dBASE IV. In dBASE for Windows, use the Left property of a class to determine its horizontal position on a form.

Syntax

COL( )

Description

COL( ) returns the number of the current row position in the results pane of the Command window or the current dBASE IV window opened with ACTIVATE WINDOW. COL( ) returns the column position of the cursor as a numeric type number.


COL( ) Example

See ROW( ) for an example of COL( ).


See Also

ACTIVATE WINDOW

DEFINE

ROW( )


COMMIT( )

See Also	Example	Portability	Shared Data

Ends a transaction initiated by BEGINTRANS( ) and writes to the open files any changes made during the transaction. Returns .T. if the data was committed successfully.

Syntax

COMMIT( [<database name expC>] )

<database name expC>

The name of the database in which to complete the transaction.

If you began the transaction with BEGINTRANS( <database name expC>), you must issue COMMIT(<database name expC>). If instead you issue COMMIT( ), dBASE ignores the COMMIT( ) statement.

If you began the transaction with BEGINTRANS( ), <database name expC> is an optional COMMIT( ) argument. If you include it, it must refer to the same database as the SET DATABASE TO statement that preceded BEGINTRANS( ).

Description

Use COMMIT( ) to end the open transaction and write changes to any open files. To end a transaction without writing changes to the file, use ROLLBACK( ). For more information on transactions, see BEGINTRANS( ).


COMMIT( ) Example

The following example begins a transaction with BEGINTRANS( ). It opens a multi-user version of Company.dbf and attempts to set all values in the Ytd_Sales field to 0. ON ERROR detects any error which might occur. In particular, it will detect if another user has locked any record in Company.dbf. If an error occurs, ROLLBACK( ) resets all values. Otherwise COMMIT( ) writes the changes to disk:

CLOSE ALL
SET PROCEDURE TO PROGRAM(1) ADDITIVE
SET EXCLUSIVE OFF

BEGINTRANS()

TransErr=.f.
ON ERROR DO TransErr    && Activates ON ERROR trap

USE L:\MultiUse\Company
REPLACE ALL Ytd_Sales WITH 0
ON ERROR                && Disables ON ERROR

IF TransErr
  ? "Rollback"
  ROLLBACK()            && restore data
ELSE
  ? "Commit"
  COMMIT()              && save changes
ENDIF

PROC TransErr
WAIT "Warning: Transaction Fails"
TransErr=.t.


Portability

Not supported in dBASE IV or dBASE III PLUS. COMMIT( ) replaces the COMMIT command in dBASE IV.


See Also

BEGINTRANS( )

ROLLBACK( )

SET EXCLUSIVE


COMPILE

See Also	Portability	Programs

Compiles program files (.PRG, .WFM), creating object code files (.PRO, .WFO).

Syntax

COMPILE <filename> | <filename skeleton>

<filename> | <filename skeleton>

The file to compile. The <filename skeleton> option displays a dialog box from which you can select a file. If you specify a file without including its path, dBASE looks for the file in the current directory. If you specify a file without including its extension, dBASE assumes .PRG.

Description

Use COMPILE to create compiled program files without executing or opening the files, or to compile only certain files. You cannot run a program until it is been compiled. Because a compiled file cannot be read or modified, compiling a program protects your source code from modification by users of the program. By default, dBASE creates compiled object files in the same directory as the source code files.

COMPILE has several advantages over compiling files with DO, SET PROCEDURE, or SET FORMAT:

COMPILE does not execute or open the specified files.

If you write an application that contains many program files, you can use COMPILE to compile only those program files you change rather than all the program files of the application. To specify a date and time range for the programs to be compiled, use FDATE( ) and FTIME( ).

COMPILE <filename skeleton> lets you compile groups of unrelated or related files.

When you compile a program, dBASE detects any syntax errors in the source file and displays an error message corresponding to the error in a dialog box that contains three buttons:

Cancel cancels compilation (equivalent to pressing Esc).

Ignore cancels compilation of the program containing the syntax error but continues compilation of the rest of the files that match <filename skeleton> if you specified a skeleton.

Fix lets you fix the error by opening the source code in an editing window, positioning the insertion point at the point where the error occurred.


Portability

By default, both dBASE IV and dBASE III PLUS create compiled object files in the current directory rather than in the same directory as the source code files.


See Also

CLEAR PROGRAM

DO

FDATE( )

FTIME( )

SET COVERAGE

SET DEVELOPMENT

SET FORMAT

SET PROCEDURE


CONTINUE

See Also	Example	Table Organization

Continues a search for the next record that meets the conditions specified in a previously issued LOCATE command.

Syntax

CONTINUE

Description

CONTINUE continues the search of the last LOCATE issued in the selected work area. After you issue the LOCATE command, the current table is searched sequentially for the first record that matches the search criteria. Unless a WHILE <condition> is included, or <scope> is NEXT or REST, the search begins with the first record.

If a record is found, dBASE moves the record pointer to the matching record and displays the message Record = <n> (if SET TALK is ON). To continue the search, issue the CONTINUE command. If another match is found, CONTINUE displays the message Record = <n>, and FOUND( ) returns .T. If another match is not found, it displays the message End of LOCATE scope and positions the record pointer at the last record of the LOCATE scope or at end-of -file. Also, FOUND( ) returns .F.

If you issue CONTINUE without first issuing a LOCATE command for the current table, dBASE for Windows returns an error message.


CONTINUE Example

The following example uses CONTINUE to find the next Company that is not in California. It relies on the LOCATE command:

USE Company
LOCATE FOR Company <> "CA"
* After LOCATE, CONTINUE can be used
IF EOF()
* IF .NOT. FOUND() can also be used to
* test LOCATE/CONTINUE
  ? "No companies found"
ENDIF
DO WHILE .NOT. EOF()
   ? Company, State_Prov
   CONTINUE
ENDDO


See Also

EOF( )

FIND

FOUND( )

LOCATE

SEEK

SEEK( )


CONVERT

See Also	Example	Portability	Shared Data

Adds a _dbaselock field to a table for storing multiuser lock information.

Syntax

CONVERT
[TO <expN>]

TO <expN>

Specifies the length of the multiuser information field to add to the current table. The <expN> argument can be a number from 8 to 24, inclusive. The default is 16.

Description

Use CONVERT to add a character field, _dbaselock, to the structure of the current table. Use the option TO <expN> to specify the length of the field. If you issue CONVERT without the TO <expN> option, the width of the field is 16. If you want to change the length of the _dbaselock field after using CONVERT, you can issue CONVERT again on the same table. To view the contents of the _dbaselock field, use LKSYS( ).

Note:	You must use the table exclusively (USE...EXCLUSIVE) before issuing CONVERT. You must also turn SET DELETED OFF before issuing CONVERT or reindex the table (REINDEX) after issuing CONVERT.

When you issue CONVERT, dBASE copies the current table to a new file with extension .CVT, then creates a new .DBF file containing the _dbaselock field. The .CVT table contains the original file structure before CONVERT.

The _dbaselock field contains the following values:

Count	A 2-byte hexadecimal number used by CHANGE( )
Time	A 3-byte hexadecimal number that records the time a lock was placed
Date	A 3-byte hexadecimal number that records the date a lock was placed
Name	A 0- to 16-character representation of the login name of the user who placed a lock, if a lock is active
The count, time, and date portions of the _dbaselock field always make up its first 8 characters. If you accept the default 16-character width of the _dbaselock field, the login name is truncated to 8 characters. If you set the field width to fewer than 16 characters, the login name is truncated the necessary amount. If you set the width of <expN> to 8 characters, the login name does not appear at all.

Every time a record is updated, dBASE rewrites the count portion of _dbaselock. If you issue CHANGE( ), dBASE reads the count portion from disk and compares it to the previous value it stored in memory when the record was initially read. If the values are different, another user has changed the record, and CHANGE( ) returns .T. For more information, see CHANGE( ).

LKSYS( ) returns the login name, date, and time portions of the _dbaselock field. If you place a file lock on the table containing the _dbaselock field, the value in the _dbaselock field of the first record contains the information used by CHANGE( ) and LKSYS( ). For more information, see LKSYS( ).

Note:	CONVERT does not affect SQL databases or Paradox tables.


CONVERT Example

The following series of commands issued at the Command window add a field to the active table to track multiuser change information:

SET DELETED OFF
USE Company EXCLUSIVE
DISPLAY STRUCTURE       && Note structure
CONVERT TO 24
DISPLAY STRUCTURE       && Note added _dbaselock;
                           field with 24 byte size


Portability

Not supported in dBASE III PLUS.


See Also

CHANGE( )

FLOCK( )

LKSYS( )

LOCK( )

NETWORK( )

REINDEX

RLOCK( )

SET DELETED

SET EXCLUSIVE

SET LOCK

SET REPROCESS

UNLOCK

USE


COPY

See Also	Example	Table Basics

Creates a new table and copies records to it from the current table. COPY also allows you to export data to non-dBASE files.

Syntax

COPY TO <filename> | ?
[<scope>]
[FOR <condition 1>]
[WHILE <condition 2>]
[FIELDS <field list>]
[[TYPE] SDF | DBMEMO3 | PARADOX | DBASE |
DELIMITED [WITH
<char> | BLANK] ] |
[[WITH] PRODUCTION]

TO <filename> | ?

Specifies the name of the table or file you want to create. COPY TO ? displays a dialog box, in which you can specify a new destination file. If you specify a file without including its path, dBASE for Windows saves the file to the current drive and directory. If you specify a file without including an extension, defining a default table type with SET DBTYPE, or using one of the TYPE options, dBASE for Windows assigns a .DBF extension.

You can also copy records to a table in a database (defined using the IDAPI Configuration Utility) by specifying the database as a prefix (enclosed in colons) to the name of the table, that is, :database name:table name. If the database is not already open, dBASE for Windows displays a dialog box in which you specify the parameters, such as a login name and password, necessary to establish a connection to that database.

<scope>

The number of records to copy to <filename>. RECORD <n> identifies a single record by its record number. NEXT <n> identifies n records, beginning with the current record. ALL specifies all records. REST specifies all records from the current record to the end of the file.

FOR <condition 1>
WHILE <condition 2>

Determines which records are affected by COPY. FOR restricts COPY to records that meet <condition 1>. WHILE starts processing with the current record and continues with each subsequent record as long as <condition 2> is true.

FIELDS <field list>

Specifies which fields to copy to the new table.

[TYPE] SDF | DBMEMO3 | PARADOX | DBASE |
DELIMITED [WITH <char> | BLANK]

Specifies the format of the file to which you want to copy data. The TYPE keyword is included for readability only; it has no effect on the operation of the command. The following table provides a description of the different file formats that are supported:

Type 	Description

SDF	A System Data Format file. Records are fixed-length in the SDF file, and the end of a record is marked with a carriage return and a linefeed. If you do not include an extension for<filename>, dBASE for Windows assigns a .TXT extension.

DBMEMO3	A table (.DBF) and memo (.DBT) files in dBASE III PLUS format.

PARADOX	A Paradox table. Records are Paradox rows, and fields are Paradox columns. dBASE for Windows assigns a .DB extension.

DBASE	A dBASE table (the default). If you do not include an extension for <filename>, dBASE for Windows assigns a .DBF extension.

DELIMITED	A text file in which

Character fields are delimited with quotation marks or with <char> if you use WITH <char>.

Logical fields are the characters T or F.

Numeric fields are numbers.

Each carriage return and linefeed indicates a new record.

If you do not include an extension for<filename>, dBASE for Windows assigns a .TXT extension.

WITH <char>

Delimits character fields in a delimited text file with the character <char> instead of with quotation marks.

WITH BLANK

Separates delimited text file data with spaces instead of commas. Character fields are not delimited with quotes or other delimiters.

[WITH] PRODUCTION

Specifies copying the production .MDX file along with the associated table. This option can be used only when copying to another dBASE table.

Description

Use COPY to copy all or part of a table to a file of the same or a different type. If an index is active, COPY arranges the records of the new table or file according to the indexed order. The COPY command does not copy a _dbaselock field in a table that you have created with CONVERT.

If you COPY a table containing a memo field to another dBASE table, dBASE for Windows creates another file with the same name as the table but having a .DBT extension, and copies the contents of the memo field to it. If, however, you use the SDF or DELIMITED options and COPY to an ASCII text file, dBASE for Windows does not copy the memo field .DBT file.

Deleted records are copied to the target file (if it is a dBASE table) unless a FOR or WHILE condition excludes them or unless SET DELETED is ON. Deleted records remain marked for deletion in the target dBASE table.

You can use COPY to create a file containing fields from more than one table. To do that, open the source tables in different work areas and define a relation between the tables. Use SET FIELDS TO to select the fields from each table that you want to copy to a new file. Before you issue the COPY command, SET FIELDS must be ON and you must be in the work area in which the parent table resides.

The COPY command does not verify that the files you build are compatible with other software programs. You may specify field lengths, record lengths, number of fields, or number of records that are incompatible with other software. Check the file limitations of your other software program before exporting tables using COPY.


COPY Example

The following example uses COPY to copy selected fields from two related tables to a new Paradox table:

SET SAFETY OFF
USE Contact Exclusive
INDEX ON CompCode TAG CompCode
USE Company IN SELECT()
SELECT Company
SET RELATION TO CompCode INTO Contact
COPY TO CntctLst FOR Company->State_Prov = "CA";
  FIELDS Company->Company,;
  Contact->CompCode, Contact->Contact, ;
  Company->Street1, Company->Street2, ;
  Company->City, Company->State_Prov,;
  Company->Zip_P_Code TYPE PARADOX
CLOSE DATABASES
SET DBTYPE TO PARADOX
USE CntctLst
BROWSE
CLOSE DATABASES
SET DBTYPE TO


See Also

APPEND FROM

CONVERT

COPY FILE

COPY STRUCTURE

COPY TABLE

COPY TO...STRUCTURE EXTENDED

IMPORT

SET DELETED

SET FIELDS


COPY BINARY

See Also	Example	Portability	Fields and Records

Copies the contents of the specified binary field to a file.

Syntax

COPY BINARY <field name> TO <filename>
[ADDITIVE]

<field name>

Specifies the binary field to copy.

TO <filename> | ?

Specifies the name of the file where the contents of the binary field are copied. For predefined binary file types, dBASE for Windows assigns the appropriate extension, for example, .BMP, .WAV, and so on. For user-defined binary type fields, dBASE assigns a .TXT extension by default.

ADDITIVE

Appends the contents of the binary field to the end of an existing file. Without the ADDITIVE option, dBASE for Windows overwrites the previous contents of the file.

Description

Use COPY BINARY to export data from a binary field in the current record to a file. You can use binary fields to store text, images, sound, video, and other user-defined binary data.

If you specify the ADDITIVE option, dBASE for Windows appends the contents of the binary field to the end of the named file, which lets you combine the contents of binary fields from more than one record. When you do not use ADDITIVE, dBASE for Windows displays a warning message before overwriting an existing file if SET SAFETY is ON. Note that you cannot combine the data from more than one field for many of the predefined binary data types. For example, you can store only a single image in a binary field or file, so do not use the ADDITIVE option of COPY BINARY when copying an image to a file.


COPY BINARY Example

The following example uses COPY BINARY to copy bitmapped pictures and sound data stored in binary fields to external files. The newly created files are given a name comprised of the Name field contents, the digit 2 to distinguish the new file from old files and a .BMP or .WAV file extension:

USE Pictures
DO WHILE .NOT. EOF()
   bmp_file = TRIM(Name) + "2.BMP"
   wav_file = TRIM(Name) + "2.WAV"
   COPY BINARY Bitmap TO &bmp_file
   COPY BINARY Sound TO &wav_file
   SKIP
ENDDO
CLOSE ALL


Portability

Not supported in dBASE IV or dBASE III PLUS.


See Also

APPEND MEMO

BINTYPE( )

CLASS IMAGE

COPY

COPY FILE

COPY MEMO

PLAY SOUND

REPLACE BINARY

RESTORE IMAGE


COPY FILE

See Also	Example	Portability	Disk and File Utilities

Duplicates a file.

Syntax

COPY FILE <filename 1> | ? | <filename skeleton 1>
TO <filename 2> | ? | <filename skeleton 2>

<filename 1> | ? | <filename skeleton 1>

Identifies the file to duplicate (also known as the source file). ? and <filename skeleton> display a dialog box from which you can select a file to duplicate.

If you specify a source file without including its path, dBASE looks for the file in the current directory, then in the path(s) you specified with SET PATH. If you specify a source file without including its extension, dBASE assumes no extension.

TO <filename 2> | ? | <filename skeleton 2>

Identifies the target file that will be created or overwritten by COPY FILE. The ? and <filename skeleton> options display a dialog box in which you specify the name of the target file and its directory.

Description

COPY FILE is a dBASE utility command that lets you duplicate an existing file at the operating system level. COPY FILE duplicates a single file of any type.

COPY FILE differs from the COPY command in DOS in that wildcards do not let you copy more than one file at a time. To copy more than one file at a time using wildcards, use !, RUN, or DOS, and execute the DOS COPY command.

If SET SAFETY is ON and a file exists with the same name as the target file, dBASE displays a dialog box asking if you want to overwrite the file. If SET SAFETY is OFF, any existing file with the same name is overwritten without warning.

COPY FILE does not automatically copy a .DBT or .MDX file associated with a .DBF file. If, for example, you copy a table file that has memo fields and you do not copy the associated .DBT file, an error message displays when you try to use the file. In such cases, it is best to use COPY instead of COPY FILE. Also, you must close a dBASE file before you can use COPY FILE on it.


COPY FILE Example

The following examples use COPY FILE:

COPY FILE Temp.prg TO B:Temp.prg
* Copies Temp.prg
COPY FILE *.DBF TO B:*.DBF
* Displays the open source dialog box


Portability

The ? and <filename skeleton> options are not supported in dBASE IV or dBASE III PLUS.


See Also

COPY

COPY INDEXES

COPY MEMO

COPY STRUCTURE

COPY TO ARRAY

COPY TO...STRUCTURE EXTENDED

RENAME

SET FULLPATH

SET PATH


COPY INDEXES

See Also	Example	Portability	Table Organization

Copies a list of .NDX files to index tags within a single .MDX file. (Applicable only to .NDX indexes created on dBASE tables.)

Syntax

COPY INDEXES <.ndx filename list>
[TO <.mdx filename> | ? ]

<.ndx filename list>

Specifies a list of .NDX files (up to ten) that you want to create index tags for.

TO <.mdx filename> | ?

Specifies the name of the .MDX file to add index tags to. By default, dBASE for Windows assigns the index file the same name as the current table with an .MDX extension and saves the file in the current directory. The ? option displays a dialog box, in which you specify the name and location of the .MDX file.

Description

The COPY INDEXES command converts a list of .NDX files into index tags in a single .MDX file. If you do not specify an .MDX file with the TO <.mdx filename> option, index tags are created in the production .MDX file, which has the same name as the table (and which is opened automatically when you open the associated table). If a production .MDX file does not exist, it is created with the same name as the table, and, for dBASE tables, the table header is updated to indicate the presence of the production index. If you use the TO <.mdx filename> option, the index tags are written to the specified .MDX file. You can create up to 47 individual index tags in a single .MDX file.

The .NDX files you want to copy and the associated table must already be open before you issue the COPY INDEXES command. In a multiuser environment, the table associated with the indexes you want to copy must be opened in exclusive mode.


COPY INDEXES Example

The following example first creates two .NDX indexes for the Company table. It then uses COPY INDEXES to create tags for the current table using these two existing .NDX files as the source:

USE Company EXCLUSIVE
INDEX ON Company TO Company    && create .ndx
INDEX ON Compcode TO Compcode  && create .ndx
* There are now two .NDX indexes
SET INDEX TO Company, Compcode
COPY INDEXES Company, Compcode
SET ORDER TO TAG Company
BROWSE FIELDS Company, Compcode


Portability

Not supported in dBASE III PLUS.


See Also

COPY TAG

DELETE TAG

INDEX

MDX( )

NDX( )

SET INDEX

SET ORDER

TAG( )

TAGNO( )

TAGCOUNT( )

USE


COPY MEMO

See Also	Example	Portability	Fields and Records

Copies the contents of the specified memo field to a file.

Syntax

COPY MEMO <memo field> TO <filename> | ?
[ADDITIVE]

<memo field>

Specifies the memo field to copy.

TO <filename> | ?

Specifies the name of the text file where text will be copied. By default, dBASE for Windows assigns a .TXT extension and saves the file in the current directory. The ? option displays a dialog box, in which you specify the name of the target file and the directory to save it in.

ADDITIVE

Appends the contents of the memo field to the end of an existing text file. Without the ADDITIVE option, dBASE for Windows overwrites any previous text in the text file.

Description

Use COPY MEMO to export memo file text in the current record to a text file. You can also use COPY MEMO to copy images or other binary-type data to a file; however, binary fields are recommended for storing images, sound, and other user-defined binary information.

If you specify the ADDITIVE option, dBASE for Windows appends the contents of the memo field to the end of the named file, which lets you combine the contents of memo fields from more than one record. When you do not use ADDITIVE, dBASE displays a warning message before overwriting an existing file if SET SAFETY is ON. You can store only a single image in either a memo field or in a file, so do not use the ADDITIVE option of COPY MEMO when copying an image to a file. (RESTORE IMAGE can display an image stored in either a memo field or a text file.)


COPY MEMO Example

The following example uses COPY MEMO to create a text file that holds the unformated contents of all Notes memo fields in the Company table:

USE Company
IF .NOT. FILE("Test.Txt")
  COPY MEMO Notes TO Test.Txt
  SKIP
ENDIF
DO WHILE .NOT. EOF()
  COPY MEMO Notes TO Test.TXT ADDITIVE
  SKIP
ENDDO
MODI COMM Test.TXT     && Note all memos in .TXT file
RETURN


Portability

Not supported in dBASE III PLUS.


See Also

APPEND MEMO

COPY

COPY BINARY

COPY FILE

REPLACE BINARY

REPLACE OLE


COPY STRUCTURE

See Also	Example	Table Basics

Creates an empty table with the same structure as the current table.

Syntax

COPY STRUCTURE TO <filename> | ? | <filename skeleton>
[[TYPE] PARADOX | DBASE]
[FIELDS <field list>]
[[WITH] PRODUCTION]

<filename> | ? | <filename skeleton>

The name of the table you want to create. COPY STRUCTURE TO ? and COPY STRUCTURE TO <filename skeleton> display a dialog box, in which you can specify the name of the destination table. If you specify a table name without including its path, dBASE for Windows saves the table to the current drive and directory. If you specify a table name without including an extension, defining a default table type with SET DBTYPE, or using one of the TYPE options, dBASE for Windows assigns a .DBF extension.

You can also copy a structure to a table in a database (defined using the IDAPI Configuration Utility) by specifying the database as a prefix (enclosed in colons) to the name of the table, that is, :database name:table name. If the database is not already open, dBASE for Windows displays a dialog box in which you specify the parameters, such as a login name and password, necessary to establish a connection to that database.

[TYPE] PARADOX | DBASE

Specifies the type of table to create, overriding the current setting of DBTYPE. The TYPE keyword is included for readability only; it has no affect on the operation of the command.

Specifying PARADOX creates a Paradox table. with a .DB extension.

Specifying DBASE creates a dBASE table (the default). If you do not include an extension for <filename>, dBASE for Windows assigns a .DBF extension.

FIELDS <field list>

Determines which fields dBASE for Windows includes in the structure of the new table. The fields appear in the order specified by <field list>.

[WITH] PRODUCTION

Creates a production .MDX file for the new table. The new index file has the same index tags as the production index file associated with the original table.

Description

The COPY STRUCTURE command copies the structure of the current table but does not copy any records. If SET SAFETY is OFF, dBASE for Windows overwrites any existing tables of the same name without issuing a warning message.

The COPY STRUCTURE command copies the entire table structure unless limited by the FIELDS option or the SET FIELDS command. When you issue COPY STRUCTURE without the FIELDS <field list> option, dBASE for Windows copies the fields in the SET FIELDS TO list to the new table. The _dbaselock field created with the CONVERT command is not copied to new tables.

You can use COPY STRUCTURE to create an empty table structure with fields from more than one table. To do so,

1.	Open the source tables in different work areas.

2.	Use the FIELDS <field list> option, including the table alias for each field name not in the current table.

You can also set a relationship between the tables using the SET RELATION command, and then use COPY STRUCTURE to copy fields from the related tables.


COPY STRUCTURE Example

The following example uses COPY STRUCTURE to copy selected fields from two open tables to a new table:

USE Contact
USE Company IN SELECT()
COPY STRUCTURE TO CntctLst ;
  FIELDS Company->Company,;
  Contact->CompCode, Contact->Contact, ;
  Company->Street1, Company->Street2, ;
  Company->City, Company->State_Prov, ;
  Company->Zip_P_Code
USE CntctLst
APPEND
CLOSE ALL


See Also

APPEND

APPEND FROM

COPY

COPY TO...STRUCTURE EXTENDED

DISPLAY STRUCTURE

MODIFY STRUCTURE

SET FIELDS

SET SAFETY


COPY TABLE

See Also	Example	Portability	Table Basics

Copies a specified table.

Syntax

COPY TABLE <source tablename> TO <target tablename>
[ [TYPE] DBASE | PARADOX]

<source table name>

The name of the table that you want to copy. You can also copy a table in a database (defined using the IDAPI Configuration Utility) by specifying the database as a prefix (enclosed in colons) to the name of the table, that is, :database name:table name. If the database is not already open, dBASE for Windows displays a dialog box in which you specify the parameters, such as a login name and password, necessary to establish a connection to that database.

<target table name>

The name of the table you want to create. The table type is the same as the source table. If you copy a table in a database, you must specify the same database as the destination of the target table.

[TYPE] PARADOX | DBASE

Specifies the type of table to copy, which can include either Paradox or dBASE tables. Overrides the current setting of DBTYPE.

Description

Use the COPY TABLE command to copy tables and their associated .NDX and .MDX index files. For Paradox tables, COPY TABLE copies associated indexes, BLOB and .VAL files. Make sure the table is not in use before you attempt to copy it.


COPY TABLE Example

The following example uses COPY TABLE to create a duplicate table without first opening Clients.DBF:

COPY TABLE Clients TO Region1


Portability

Not supported in dBASE IV or dBASE III PLUS.


See Also

COPY

COPY FILE

DELETE FILE

DELETE TABLE

ERASE


COPY TAG

See Also	Example	Portability	Table Organization

Copies .MDX index tags to .NDX files. (This command is only applicable for dBASE tables.)

Syntax

COPY TAG <tag name>
[OF .mdx filename]
TO <.ndx filename>

<tag name>

Specifies a .MDX index tag you want to copy.

OF <.mdx filename>

The .MDX file that contains the specified index tag. If you specify a file without including its path, dBASE for Windows looks for the file in the current directory, then in the path you specify with SET PATH. If you specify a file without including its extension, dBASE for Windows assumes an .MDX extension.

TO <.ndx filename>

The name of an .NDX file that you want to copy the index tag to. If you specify a file without including its path, dBASE for Windows creates the file in the current directory. If you specify a file without including its extension, dBASE for Windows assigns an .NDX extension.

Description

COPY TAG creates individual .NDX files from the index tags in the production index or a specified .MDX file. You might use this command if tables and indexes you create might be accessed by previous versions of dBASE.

Before issuing the COPY TAG command, the .MDX file and its associated table must already be open. Only one tag can be copied at a time. A FOR clause of an .MDX file tag is ignored, since .NDX files do not support them.


COPY TAG Example

The following example uses COPY TAG to create an .NDX index file from an open tag index:

DELETE FILE Company.ndx && remove any existing index
USE Company EXCLUSIVE
INDEX ON Company TAG Company
* now there is a TAG index
COPY TAG Company TO Company
* COPY TAG creates a .NDX index
SET INDEX TO Company
BROWSE FIELDS Company, Compcode


Portability

Not supported in dBASE III PLUS.


See Also

COPY INDEXES

FOR( )

INDEX

MDX( )

NDX( )

SET INDEX

SET ORDER

TAG( )

TAGCOUNT( )

TAGNO( )


COPY TO ARRAY

See Also	Example	Fields and Records

Copies data from non-memo fields of the current table, overwrites elements of an existing array, and moves the record pointer to the last record copied.

Syntax

COPY TO ARRAY <array name>
[<scope>]
[FOR <condition 1>]
[WHILE <condition 2>]
[FIELDS <field list>]

<scope>

The number of records to copy to the specified array. RECORD <n> identifies a single record by its record number. (You can also specify a bookmark for tables that do not provide record numbers.) NEXT <n> identifies n records, beginning with the current record. ALL specifies all records. REST specifies all records from the current record to the end of the file.

FOR <condition 1>
WHILE <condition 2>

Determines which records are affected by COPY TO ARRAY. FOR restricts COPY TO ARRAY to records that meet <condition 1>. WHILE starts processing with the current record and continues with each subsequent record as long as <condition 2> is true.

FIELDS <field list>

Copies data from the fields in <field list> in the order of <field list>. Without FIELDS, dBASE copies all the fields the array can hold in the order they occur in the current table.

Description

Use COPY TO ARRAY to copy records from the current table to an existing array. To copy specified records and fields, use DECLARE Sample[<memvar 1>,<memvar 2>], where <memvar 1> is the maximum number of records to copy and <memvar 2> is the maximum number of fields to copy. If you use DECLARE Sample[2,3], you can copy a maximum of three fields from a maximum of two records. To copy data from all fields in all records in a table without memo fields, use DECLARE sample[RECCOUNT( ), FCOUNT( )].

Using a two-dimensional array, the first subscript is the number of records to copy, and the second subscript is the number of fields to copy. For example, if you DECLARE Test[2,3], COPY TO ARRAY Test can copy three fields from two records.

COPY TO ARRAY can copy to arrays that have more than two dimensions (multi-dimensional), but it uses only the last two subscripts. The next-to-last subscript in <array name> determines how many records the array can hold, and the last subscript determines how many fields from each record the array can hold. For example, DECLARE Test[4,5,2,3] and DECLARE Test[2,3] both create an array to which COPY TO ARRAY copies three fields from two records.

If the array is one-dimensional, COPY TO ARRAY can copy only one record; in this case, the number of elements determines the number of fields to copy. For example, if you use DECLARE Test[5], COPY TO ARRAY copies the first five fields from the current record.

COPY TO ARRAY copies in record number or index order and, within each record, in field number order unless you use the FIELDS option to specify the order of the fields to copy.

If the number specified by the last subscript in the array is larger than the number of fields copied from the table, the additional array elements remain initialized to .F. or to a previously stored value. Similarly, if the number specified by the next-to-last subscript of the array is larger than the number of records copied from the table, the additional array elements remain initialized to .F. or to a previously stored value.


COPY TO ARRAY Example

The following example uses COPY TO ARRAY to copy 5 records of a view created with SET RELATION to an array of 5 rows and 3 columns for further manipulation:

CLEAR
SET TALK OFF
USE Contact ORDER Compcode IN SELECT()
USE Company IN SELECT()
SELECT Company
SET RELATION TO CompCode INTO Contact;
                                && Set a relation;
                                on CompCode
get_rec = 5
DECLARE CompCtc[get_rec,3]      && Create an array;
                                5 records long with;
                                3 fields
COPY TO ARRAY CompCtc ;
   NEXT get_rec FIELDS Company->Company, ;
   Contact->Contact, Company->YTD_Sales
Record = 1
? "Company" AT 10, "Contact" AT 40, ;
  "Sales" AT 60
?
DO WHILE Record <= get_rec
 ? CompCtc[Record,1] AT 10, CompCtc[Record,2] AT 40,;
   LTRIM(STR(CompCtc[Record,3])) AT 60
   Record = Record + 1
ENDDO
CLOSE ALL


See Also

APPEND FROM ARRAY

DECLARE

REPLACE FROM ARRAY

SET FIELDS

STORE MEMO


COPY TO...STRUCTURE EXTENDED

See Also	Example	Table Basics

Creates a new table whose records contain the structure of the current table.

Syntax

COPY TO <filename> | ?
STRUCTURE EXTENDED
[[TYPE] PARADOX | DBASE]

or

COPY STRUCTURE EXTENDED TO <filename> | ?
[[TYPE] PARADOX | DBASE ]

<filename> | ?

The name of the table that you want to create to contain the structure of the current table. COPY TO ? and COPY STRUCTURE EXTENDED TO ? display a dialog box in which you can specify the name of the destination table. If you specify a table name without including its path, dBASE for Windows saves the table to the current drive and directory. If you specify a table name without including an extension, defining a default table type with SET DBTYPE, or using one of the TYPE options, dBASE for Windows assigns a .DBF extension.

You can also create a table in a database (defined using the IDAPI Configuration Utility) by specifying the database as a prefix (enclosed in colons) to the name of the table, that is, :database name:table name. If the database is not already open, dBASE for Windows displays a dialog box in which you specify the parameters, such as a login name and password, necessary to establish a connection to that database.

[TYPE] PARADOX | DBASE

Specifies the type of table to create. The TYPE keyword is included for readability only; it has no effect on the operation of the command.

Specifying PARADOX creates a Paradox tablewith a .DB file extension.

Specifying DBASE creates a dBASE table (the default). If you do not include an extension for <filename>, dBASE for Windows assigns a .DBF extension.

Description

COPY TO...STRUCTURE EXTENDED copies the structure of the current table to records in a new table.

COPY TO...STRUCTURE EXTENDED first defines a table, called a structure-extended table, containing five fields of fixed names, types, and lengths. Once the structure-extended table is defined, COPY TO...STRUCTURE EXTENDED appends records that provide information about each field in the current table. The fields in the structure-extended table store the following information about fields in the current table:

Field	Contents
FIELD_NAME	Character field that contains the name of the field.
FIELD_TYPE	Character field that contains the field's data type.
FIELD_LEN	Numeric field that contains the field length.
FIELD_DEC	Numeric field that contains the number of decimal places for numeric and float data.
FIELD_IDX	Character field (not created in dBASE III PLUS) that indicates if index tags were created on particular fields when the current table was created.
When the process is complete, the structure-extended table contains as many records as there are fields in the current table. You can then use CREATE...FROM to create a new table from the information provided by the structure-extended table.

The _dbaselock field created with the CONVERT command is not copied to structure-extended tables.


COPY TO...STRUCTURE EXTENDED Example

The following example uses COPY TO...STRUCTURE EXTENDED to create the table Names that contains the structure of Clients as its records. The structure is then altered by deleting those records beyond the Zip field. CREATE is then used to create a new table with the abbreviated structure, and records from Clients are appended. Creating a new table via COPY TO .. STRUCTURE EXTENDED is also a useful tool for correcting .DBF file corruption:

SET TALK OFF
SET SAFETY OFF
USE Clients
COPY TO Names STRUCTURE EXTENDED
USE Names EXCLUSIVE
DELETE FOR RECNO()>7   && Excludes fields beyond Zip
PACK
CREATE Names2 FROM Names
DISPLAY STRUCTURE      && Names2 currently in use
? ALIAS()+" has " + LTRIM(STR(RECCOUNT())) +;
  " records at this point."
WAIT
APPEND FROM Clients
?
? ALIAS()+" has " + LTRIM(STR(RECCOUNT())) +;
  " records now."
WAIT
GO TOP
BROWSE


See Also

COPY

COPY STRUCTURE

CREATE

CREATE...FROM

CREATE...STRUCTURE EXTENDED

DISPLAY STRUCTURE

LIST STRUCTURE

MODIFY STRUCTURE

SET SAFETY


COS( )

See Also	Example	Portability	Numeric Data

Returns the trigonometric cosine of an angle.

Syntax

COS(<expN>)

<expN>

The size of the angle in radians. To convert an angle's degree value to radians, use DTOR( ). For example, to find the cosine of a 30-degree angle, use COS(DTOR(30)).

Description

COS( ) calculates the ratio between the side adjacent to an angle and the hypotenuse in a right triangle. COS( ) returns a float from -1 to +1. COS( ) returns 0 when <expN> is pi/2 or 3*pi/2 radians.

Use SET DECIMALS to set the number of decimal places COS( ) displays.

The secant of an angle is the reciprocal of the cosine of the angle. To return the secant of an angle, use 1/COS( ).


COS( ) Example

The following example uses COS( ) to compute the length of a rafter after room width and roof angle have been entered by the user:

SET PROCEDURE TO PROGRAM(1) ADDITIVE
LOCAL f
f = NEW PFORM()
f.Open()

CLASS PFORM OF FORM
   this.HelpFile = ""
   this.Width =         43.00
   this.Height =         10.47
   this.Left =         46.60
   this.Text = "Rafter Computer"
   this.Top =          6.94
   this.HelpId = ""

   DEFINE ENTRYFIELD ROOM OF THIS;
       PROPERTY;
         Width          4.00,;
         Picture "999",;
         Height          1.00,;
         Left         32.00,;
         Top          2.00,;
         Border .T.,;
         Value          0

   DEFINE ENTRYFIELD ANGLE OF THIS;
       PROPERTY;
         Width          4.00,;
         Picture "99",;
         Height          1.00,;
         Left         32.00,;
         Top          4.00,;
         Border .T.,;
         Value          0

   DEFINE ENTRYFIELD RAFTLENGTH OF THIS;
       PROPERTY;
         Width          6.00,;
         Height          1.00,;
         Left         33.00,;
         Top          6.00,;
         Border .T.,;
         Value          0.00,;
         OnGotFocus RESULTS

   DEFINE TEXT LN1 OF THIS;
       PROPERTY;
         Width         26.00,;
         Height          1.00,;
         Left          3.00,;
         Text "Enter Width of Room:",;
         Top          2.00,;
         ColorNormal "N/W",;
         Border .F.

   DEFINE TEXT LN2 OF THIS;
       PROPERTY;
         Width         27.00,;
         Height          1.00,;
         Left          3.00,;
         Text "Enter Angle of Rise:",;
         Top          4.00,;
         ColorNormal "N/W",;
         Border .F.

   DEFINE TEXT LN3 OF THIS;
       PROPERTY;
         Width         29.00,;
         Height          1.00,;
         Left          3.00,;
         Text "Cut Rafter to this length:",;
         Top          6.00,;
         ColorNormal "R/W",;
         Border .F.

   DEFINE PUSHBUTTON EXIT OF THIS;
       PROPERTY;
         Width         15.60,;
         Default .T.,;
         OnClick {;Form.Close()},;
         Height          1.12,;
         Left         14.00,;
         Text "Exit",;
         Top          8.00,;
         ColorNormal "N/W"

ENDCLASS

FUNCTION Results
Form.RaftLength.Value=LTRIM(STR((Form.Room.Value/2);
  /COS(DTOR(Form.Angle.Value)),6,2))
RETURN .T.


Portability

Not supported in dBASE III PLUS.


See Also

ACOS( )

DTOR( )

PI( )

RTOD( )

SET DECIMALS

SIN( )

TAN( )


COUNT

See Also	Example	Fields and Records

Counts the number of table records that match specified conditions.

Syntax

COUNT
[<scope>]
[FOR <condition 1>]
[WHILE <condition 2>]
[TO <memvar>]

<scope>

The number of records to count. RECORD <n> identifies a single record by its record number. NEXT <n> identifies n records, beginning with the current record. ALL specifies all records. REST specifies all records from the current record to the end of the file.

FOR <condition 1>
WHILE <condition 2>

Determines which records are affected by COUNT. FOR restricts COUNT to records that meet <condition 1>, starting at the first record of the table or scope and continuing to the end of the table or scope. WHILE starts processing with the current record and continues with each subsequent record as long as <condition 2> is true.

TO <memvar>

Stores the result of COUNT, a number, to the specified memory variable.

Description

Use COUNT to total the number of records that meet a specified criterion. If SET TALK is ON, the COUNT command also displays the total. If SET DELETED is ON, records marked for deletion are not included in the count.

In a multi-user environment, COUNT automatically locks the table during its operation if SET LOCK is ON (the default), and unlocks it after the count is finished. If SET LOCK is OFF, you can still perform a count; however the result may change if another user changes the table.

You can also count the total number of records in a table using the RECCOUNT( ) function. However, unlike COUNT, RECCOUNT( ) does not let you specify conditions to qualify the records it counts.


COUNT Example

The following example uses COUNT to determine the number of records for companies from California with a value entered for YTD_Sales in the Company table. This number is then used to calculate an average sales figure for all California companies with a current YTD_Sales entry:

SET TALK OFF
CLEAR
USE Company
Condition = "State_Prov = 'CA'"
CALCULATE SUM(YTD_Sales) TO Sales FOR &Condition
COUNT TO Num FOR &condition .AND. YTD_SALES<>0
? "Average California Sales: $"+LTRIM(STR(Sales/Num))
CLOSE ALL


See Also

AVERAGE

CALCULATE

RECCOUNT( )

SUM

TOTAL


CREATE

See Also	Example	Table Basics

Opens the Table Designer to create or modify a table interactively.

Syntax

CREATE
[<filename> | ? | <filename skeleton>]
[[TYPE] PARADOX | DBASE]

<filename> | ? | <filename skeleton>

The name of the table you want to create. CREATE ? and CREATE <filename skeleton> display a dialog box, in which you can specify the name of a new table. If you specify a table name without including its path, dBASE for Windows saves the table to the current drive and directory. If you specify a table name without including an extension, dBASE for Windows assigns a .DBF extension or the file extension of the table type you specified with SET DBTYPE. If you do not specify a name, the table remains untitled until you save the file. If you specify an existing table name, dBASE for Windows asks whether you want to modify the existing table or overwrite it.

You can also create a table in a database (defined using the IDAPI Configuration Utility) by specifying the database as a prefix (enclosed in colons) to the name of the table, that is, :database name:table name. If the database is not already open, dBASE for Windows displays a dialog box in which you specify the parameters, such as a login name and password, necessary to establish a connection to that database.

[TYPE] PARADOX | DBASE

Specifies the type of table to create. The TYPE keyword is included for readability only; it has no effect on the operation of the command.

Specifying PARADOX creates a Paradox table with a .DB extension.

Specifying DBASE creates a dBASE table (the default). If you do not include an extension for <filename>, dBASE assigns a .DBF extension.

Description

CREATE opens the Table Designer, an interactive environment in which you can create or modify the structure of a table. The type of table you create or modify depends on your selection of the table type specified with the CREATE command, or with SET DBTYPE.

Create a table by defining the name, type, and size of each field. For more information on using the Table Designer, see Designing Table Structures or the User's Guide.


CREATE Example

The following examples show several ways to use CREATE to design a table from the Command window:

CREATE MailList   && Opens table designer -.DBF table
CREATE MailList TYPE PARADOX
                  && Opens table designer - .DB table
CREATE ?          && Opens dialog box for naming file


See Also

APPEND

APPEND MEMO

COPY STRUCTURE

DISPLAY STRUCTURE

LIST STRUCTURE

MODIFY STRUCTURE

REPLACE


CREATE...FROM

See Also	Example	Table Basics

Creates a table with the structure defined by using the COPY TO...STRUCTURE EXTENDED or CREATE...STRUCTURE EXTENDED commands.

Syntax

CREATE <filename 1> | ? | <filename skeleton 1>
[[TYPE] PARADOX | DBASE]
FROM <filename 2> | ? | <filename skeleton 2>
[[TYPE] PARADOX | DBASE]

<filename 1> | ? | <filename skeleton 1>

The name of the table you want to create. CREATE ? and CREATE <filename skeleton> display a dialog box, in which you can specify the name of the destination table. If you specify a table without including its path, dBASE for Windows saves the table to the current drive and directory. If you specify a table namewithout including an extension, defining a default table type with SET DBTYPE, or using one of the TYPE options, dBASE for Windows assigns a .DBF extension.If you do not specify a table name, the table remains untitled until you save it. If you specify an existing table name, dBASE for Windows displays a dialog box, in which you can indicate whether you want to modify the existing table.

You can also create a table in a database (defined using the IDAPI Configuration Utility) by specifying the database as a prefix (enclosed in colons) to the name of the table, that is, :database name:table name. If the database is not already open, dBASE for Windows displays a dialog box in which you specify the parameters, such as a login name and password, necessary to establish a connection to that database.

[TYPE] PARADOX | DBASE

Specifies the type of table to create. The TYPE keyword is included for readability only; it has no effect on the operation of the command.

Specifying PARADOX creates a Paradox table with the .DB extension.

Specifying DBASE creates a dBASE table (the default). If you do not include an extension for <filename>, dBASE for Windows assigns a .DBF extension.

FROM <filename 2> | ? | <filename skeleton 2>
[TYPE] PARADOX | DBASE

Identifies the table whose structure you want to store in a new table. FROM ? and FROM <filename skeleton> display a dialog box, from which you can select the name of an existing table. If you specify a table without including its path, dBASE for Windows looks for the table in the current directory, then in the path you specify with SET PATH. The Type and Database options are the same as those described in the previous paragraph.

You can also copy the structure of a table in a database (defined using the IDAPI Configuration Utility) by specifying the database as a prefix (enclosed in colons) to the name of the table, that is, :database name:table name. If the database is not already open, dBASE for Windows displays a dialog box, in which you specify the parameters, such as a login name and password, necessary to establish a connection to that database.

Description

The CREATE...FROM command is most often used with the COPY TO...STRUCTURE EXTENDED command in a program to create a new table from another table that defines its structure, instead of using the interactive CREATE or MODIFY STRUCTURE commands. To do this, you can

1.	Use COPY TO...STRUCTURE EXTENDED to create a table whose records provide information on each field of the original table.

2.	Optionally, modify the structural data in the new table with any dBASE command used to manipulate data, such as REPLACE.

3.	Use CREATE...FROM to create a new table from the structural information in the structure extended file. The new table is active when you exit CREATE...FROM.

The table created with CREATE...FROM becomes the current table in the currently selected work area. If the CREATE...FROM operation fails for any reason, no table remains open in the current work area.

If any fields in the table created with COPY TO...STRUCTURE EXTENDED have index flag fields set, CREATE...FROM also creates a production .MDX file with the specified index tags.


CREATE...FROM Example

The following example uses COPY TO...STRUCTURE EXTENDED to create a temporary table containing the structure of Clients table that can be modified. CREATE...FROM is then used to create a new table with an altered structure:

SET SAFETY OFF
USE Clients
COPY TO Clients2 STRUCTURE EXTENDED
* Clients2.DBF now contains records that
* define Clients' structure.
USE Clients2 EXCLUSIVE
REPLACE Field_Name WITH "TELEPHONE" FOR RECNO()=9
CREATE NewClnt FROM Clients2
APPEND
CLOSE ALL

See COPY TO...STRUCTURE EXTENDED for an additional example of using CREATE...FROM.


See Also

COPY STRUCTURE

COPY TO...STRUCTURE EXTENDED

CREATE

DISPLAY STRUCTURE

LIST STRUCTURE

MODIFY STRUCTURE


CREATE...STRUCTURE EXTENDED

See Also	Example	Portability	Table Basics

Creates and opens a table that you can use to design the structure of a new table.

Syntax

CREATE <tablename> | ?
STRUCTURE EXTENDED
[[TYPE] PARADOX | DBASE]

<tablename> | ?

The name of the table you want to create. CREATE ? STRUCTURE EXTENDED displays a dialog box, in which you can specify the name of the destination table. If you specify a table without including its path, dBASE for Windows saves the table to the current drive and directory. If you specify a table name without including an extension, defining a default table type with SET DBTYPE, or using one of the TYPE options, dBASE for Windows assigns a .DBF extension.

You can also create a table in a database (defined using the IDAPI Configuration Utility) by specifying the database as a prefix (enclosed in colons) to the name of the table, that is, :database name:table name. If the database is not already open, dBASE for Windows displays a dialog box in which you specify the parameters, such as a login name and password, necessary to establish a connection to that database.

[[TYPE] PARADOX | DBASE]

Specifies the type of table to create. The TYPE keyword is included for readability only; it has no effect on the operation of the command.

Specifying PARADOX creates a Paradox table with a .DB extension.

Specifying DBASE creates a dBASE table (the default). If you do not include an extension for <filename>, dBASE for Windows assigns a .DBF extension.

Description

CREATE...STRUCTURE EXTENDED creates an empty table, called a structure-extended table, containing five fields of fixed names, types, and lengths. The fields correspond to attributes that describe fields in the table you want to create:

Field	Contents
FIELD_NAME	Character field that contains the name of the field.
FIELD_TYPE	Character field that contains the field's data type.
FIELD_LEN	Numeric field that contains the field length.
FIELD_DEC	Numeric field that contains the number of decimal places for numeric and float data.
FIELD_IDX	Character field (not created in dBASE III PLUS) that indicates if index tags were created on particular fields when the current table was created.
The CREATE...STRUCTURE EXTENDED command is similar to the COPY TO...STRUCTURE EXTENDED command. However, unlike COPY TO...STRUCTURE EXTENDED, which creates a table with records providing information on fields in the current table, CREATE...STRUCTURE creates an empty table. After using CREATE...STRUCTURE EXTENDED to create a new table, add records to define the structure of a new table. Then use the CREATE...FROM command to create a new table from the field definitions stored in the structure-extended table.


CREATE...STRUCTURE EXTENDED Example

The following example shows how CREATE...STRUCTURE EXTENDED is used to create a table with fields representing table design values. After creating an empty file, the example appends blank records and places structure values within the fields. DBFrame is then used to create a new dBASE table called Names:

SET SAFETY OFF
CLOSE ALL
CLEAR ALL
CREATE DBFrame STRUCTURE EXTENDED
APPEND BLANK
REPLACE Field_Name WITH "FNAME"
REPLACE Field_Type WITH "C"
REPLACE Field_Len  WITH 15
REPLACE Field_IDX  WITH "N"
APPEND BLANK
REPLACE Field_Name WITH "LNAME"
REPLACE Field_Type WITH "C"
REPLACE Field_Len  WITH 15
REPLACE Field_IDX  WITH "N"
APPEND BLANK
REPLACE Field_Name WITH "ADDRESS"
REPLACE Field_Type WITH "C"
REPLACE Field_Len  WITH 20
REPLACE Field_IDX  WITH "N"
CREATE Names FROM DBFRAME TYPE DBASE
APPEND


Portability

Not supported in dBASE IV or dBASE III PLUS.


See Also

COPY TO...STRUCTURE EXTENDED

CREATE

CREATE...FROM


CREATE APPLICATION

See Also	Example	Portability	Forms

Opens the Form Designer to create or modify a form interactively.

Syntax

CREATE APPLICATION
[<filename> | ? | <filename skeleton>]

<filename> | ? | <filename skeleton>

The form to create or modify. CREATE APPLICATION ? and CREATE APPLICATION <filename skeleton> display a dialog box, from which you can select a file. If you specify a file without including its path, dBASE looks for the file in the current directory, then in the path you specify with SET PATH. If you specify a file without including its extension, dBASE assumes .WFM.

Description

CREATE SCREEN, CREATE APPLICATION, and CREATE FORM are identical; all launch the Form Designer. See the description of CREATE FORM for more information.


CREATE APPLICATION Example

See the example of CREATE FORM. In this example, CREATE APPLICATION works the same as CREATE FORM.


Portability

Not supported in dBASE III PLUS. In dBASE IV, CREATE APPLICATION launches the dBASE IV Applications Generator.


See Also

CREATE FORM

CREATE SCREEN

MODIFY APPLICATION

MODIFY FORM

MODIFY SCREEN

OPEN FORM


CREATE CATALOG

See Also	Example	Portability	Table Basics

Creates a catalog file.

Syntax

CREATE CATALOG
[<filename> | ? | <filename skeleton>

<filename> | ? | <filename skeleton>

The catalog file you want to create. CREATE CATALOG ? and CREATE CATALOG <filename skeleton> display a dialog box, in which you can specify the name of a catalog file.

Description

Use CREATE CATALOG to create a new catalog. Catalog file names are limited to eight characters, following rules for naming DOS files. dBASE for Windows always assigns the extension (.CAT) to catalog file names.

If you set TITLE ON when you create a new catalog, dBASE for Windows prompts you to enter a one-line description of the catalog file. A master catalog, CATALOG.CAT, stores catalog file names along with catalog title descriptions. The description you enter for each catalog entry is displayed later in the catalog window when you use the SET CATALOG TO ? command to select a catalog name.

Catalogs are dBASE tables which have a predefined table structure. When you create or select a catalog file, it is automatically opened in its own work area buffer and SET CATALOG is set ON. From then on, all tables and associated files such as index, query, format, report, and label files you use or new files you create are added to the catalog.

Catalog structure

All catalogs have the same structure. The following table describes the fields contained in a catalog.

Field	Field name	Type	Width	Description
1	Path	Character	70	Contains the full path name of the table or file if it is not in the current directory.
2	File_name	Character	12	This is the name of the file, including its extension.
3	Alias	Character	8	Assigned table alias. If you do not assign an alias name, dBASE for Windows uses the table name as the alias name. This field is left blank for all other file types.
4	Type	Character	3	This field contains the default file-name extension that identifies the type of file. Even if you specified a different extension when creating the file, the default extension is entered in the Type field. However, the extension that you specified is included in the File_name field.
5	Title	Character	80	This is an optional field. If SET TITLE is ON, dBASE for Windows prompts you to add a description of up to 80 characters when you create the catalog.
6	Code	Numeric	3	When you have a catalog open, Code is the number assigned to each table in use. Program files are assigned a value of 0. A table is assigned a number when it is created. Each new table is assigned the next available number higher than the previous table. Files associated with a table, such as an index, format, label, query, report form, screen, and view files, are assigned the same code number as the table they reference.
7	Tag	Character	4	Field not currently used.

With the exception of the Title and Tag fields, dBASE for Windows automatically fills in the field contents whenever a new file is entered in the catalog.

If you want to modify the contents of the catalog table, first open it in a user-accessible work area, and then use EDIT or BROWSE. For more information, see SET CATALOG.


CREATE CATALOG Example

The following example uses CREATE CATALOG to make a CATALOG for your files.

CREATE CATALOG Mail  && Creates a Catalog called;
                        Mail. Prompts you to;
                        enter a Description of;
                        this Catalog
CREATE CATALOG ?     && Displays Open Catalog dialog;
                        box


Portability

Not supported in dBASE IV or dBASE III PLUS.


See Also

CATALOG( )

SELECT( )

SET( )

SET CATALOG

SET TITLE

USE


CREATE COMMAND

See Also	Portability	Programs

Displays a specified program file for editing, or displays an empty editing window.

Syntax

CREATE COMMAND
[<filename> | ? | <filename skeleton>]
[WINDOW <window name>]

<filename> | ? | <filename skeleton>

The file to display and edit. The ? and <filename skeleton> options display a dialog box from which you can select a file. If you specify a file without including its path, dBASE looks for the file in the current directory, then in the path you specify with SET PATH. If you specify a file without including its extension, dBASE assumes .PRG. If you issue CREATE COMMAND without an option, dBASE displays an empty editing window.

[WINDOW <window name>]

Included for compatibility with dBASE IV. Displays the file in <window name>, previously opened with ACTIVATE WINDOW.

Default

By default, CREATE COMMAND launches the dBASE internal Text Editor. You can specify an alternate editor by changing the EDITOR setting in DBASEWIN.INI. To do so, either use the SET command to specify the setting interactively, or enter the EDITOR parameter directly in DBASEWIN.INI.

Description

Use CREATE COMMAND to create new or edit existing program files. Use DO to execute program files.

Note:	dBASE compiles programs before running them, and assigns the compiled files the same name as the original, but with the letter "O" as the last letter. For example, the compiled version of SALESRPT.PRG would be SALESRPT.PRO. If SALESPRT.PRO already exists, it is overwritten. For this reason, avoid using file names ending in "O" in directories containing compiled programs.

If you are creating a new program file, CREATE COMMAND displays an editing window with no file. If you specify an existing file, CREATE COMMAND displays the program in an editing window, with the cursor at the beginning of line 1.

The dBASE menu changes when an editing window is active. See Editing Text or the User's Guide for information on the internal Text Editor, including its menu and shortcut keys.


Portability

Not supported in dBASE IV, but MODIFY COMMAND is supported in dBASE IV.


See Also

DO

CREATE FILE

SET DEVELOPMENT

SET EDITOR


CREATE FILE

See Also	Portability	Disk and File Utilities

Displays a specified text file for editing, or displays an empty editing window.

Syntax

CREATE FILE
[<filename> | ? | <filename skeleton>]
[WINDOW <window name>]

<filename> | ? | <filename skeleton>

The text file to display and edit. The ? and <filename skeleton> options display a dialog box from which you can select a file. If you specify a file without including its path, dBASE looks for the file in the current directory, then in the path you specify with SET PATH. If you specify a file without including its extension, dBASE assumes .PRG. If you issue CREATE FILE without an option, dBASE displays an empty editing window.

[WINDOW <window name>]

Included for compatibility with dBASE IV. Displays the file in <window name>, previously opened with ACTIVATE WINDOW.

Description

Use CREATE FILE to create and edit text files using the dBASE for Windows internal text editor, or the editor specified in SET EDITOR.

CREATE FILE is identical to CREATE COMMAND, MODIFY COMMAND and MODIFY FILE. See CREATE COMMAND for more information.


Portability

Not supported in dBASE IV, but MODIFY FILE is supported in dBASE IV.


See Also

CREATE COMMAND

SET EDITOR


CREATE FORM

See Also	Example	Portability	Forms

Opens the Form Designer to create or modify a form.

Syntax

CREATE FORM
[<filename> | ? | <filename skeleton>]

<filename> | ? | <filename skeleton>

The form to create or modify. CREATE FORM ? and CREATE FORM <filename skeleton> display a dialog box, from which you can select a file. If you specify a file without including its path, dBASE looks for the file in the current directory, then in the path you specify with SET PATH. If you specify a file without including its extension, dBASE assumes .WFM.

Description

Use CREATE FORM to open the Form Designer and create or modify a form interactively. The Form Designer automatically generates dBASE program code that defines the contents and format of a form, and stores this code in an editable text file (.WFM).

CREATE SCREEN, CREATE APPLICATION and CREATE FORM are identical. For all these commands, the presence of a form file determines whether a create or modify operation occurs. If the .WFM file exists, the commands let you modify it in the Form Designer. If the file does not exist, the commands create a new file.

Since a .WFM file is a program file, you can edit it with MODIFY COMMAND.

See Designing Forms or the Forms chapters in the User's Guide for instructions on using the Form Designer.

Note:	The Forms Designer is a two-way tool. You can open a form in the Form Designer even if you have edited the code in the .WFM file.


CREATE FORM Example

The following examples open the Save File dialog box with the cursor positioned at the File Name block to name a new form. The picklist of .WFM files on the current directory is available if you desire to use an existing form name to create a new form. By contrast, MODIFY FORM ? would edit an existing form:

CREATE FORM ?
CREATE FORM *.WFM

CREATE FORM issued alone in the Command window will open an unnamed form design surface:

CREATE FORM


Portability

Not supported in dBASE IV or dBASE III PLUS.


See Also

CREATE APPLICATION

CREATE SCREEN

MODIFY APPLICATION

MODIFY FORM

MODIFY SCREEN

OPEN FORM


CREATE LABEL

See Also	Example	Portability	Input/Output

Opens the Report Designer to create or modify a label file.

Syntax

CREATE LABEL
[<filename> | ? | <filename skeleton>]

<filename> | ? | <filename skeleton>

The label file to create or modify. The ? and <filename skeleton> options display a dialog box from which you can select a file. If you specify a file without including its path, dBASE looks for the file in the current directory, then in the path you specify with SET PATH. If you specify a file without including its extension, dBASE assumes .RPL.

If dBASE cannot find <filename>, it creates the file. By default, dBASE assigns an .RPL extension to <filename> and saves the file in the current directory.

CREATE LABEL without an option opens the empty Report Designer to create a new label file.

Description

Use CREATE LABEL to open the Report Designer and create or modify a label file. A label file contains the information that formats labels. For information about using the Report Designer, see Designing Reports and Labels or the Crystal Reports documentation. CREATE LABEL and MODIFY LABEL are identical commands.

Before issuing CREATE LABEL, you must have a default printer selected. After you create or modify the label file, use LABEL FORM to print the labels.


CREATE LABEL Example

This example opens a database table and then issues CREATE LABEL to construct a label form:

CLOSE DATABASE
USE Company
CREATE LABEL COMPLBL1
* If COMPLBL1.LBL already exists then it will be
* modified. Otherwise a new label form will be
* created.


Portability

The <filename skeleton> option is not supported in dBASE IV or dBASE III PLUS. In dBASE IV and dBASE III PLUS, the default label file extension is .LBL.


See Also

CREATE REPORT

LABEL FORM


CREATE MENU

See Also	Forms

Opens the Menu Designer to create or modify a menu file.

Syntax

CREATE MENU
[<filename> | ? | <filename skeleton>]

<filename> | ? | <filename skeleton>

The menu file to create or modify. CREATE MENU ? and CREATE MENU <filename skeleton> display a dialog box, from which you can select a file. If you specify a file without including its path, dBASE looks for the file in the current directory, then in the path you specify with SET PATH. If you specify a file without including its extension, dBASE assumes .MNU.

Description

Use CREATE MENU to design a menu for a form.

The menu you design is stored in a menu definition file (.MNU), which contains dBASE program code. You attach this program to a form via the form's Menu property.

For information on using the Menu Designer, see Designing Menus or Chapter 10 in the User's Guide.


See Also

CLASS MENU


CREATE QUERY

See Also	Example	Table Organization

Opens the Query Designer to create or modify a query file.

Syntax

CREATE QUERY
[<filename> | ? | <filename skeleton>]

<filename> | ? | <filename skeleton>

Specifies the name of the file you want to create or modify. CREATE QUERY ? and CREATE QUERY <filename skeleton> display a dialog box, in which you can specify the name of a query file. If you specify a file without including its path, dBASE for Windows saves the file to the current drive and directory. If you specify a file without including an extension, dBASE for Windows assumes a .QBE extension.

Description

CREATE QUERY performs the same operation as CREATE VIEW. Use either command to invoke the Query Designer, an interactive environment in which you can create or modify a query. The Query Designer creates a .QBE file that displays only the fields and records that meet specified conditions. To activate a query (.QBE) file, you can use the SET VIEW command. For more information on using the Query Designer, see Designing Queries or the User's Guide.


CREATE QUERY Example

CREATE QUERY or CREATE VIEW with no arguments opens the Query Designer and generates an untitled query, which the user will name later:

CREATE QUERY

CREATE QUERY followed by a file name creates a file of that name when the file is saved:

CREATE QUERY Myquery

If MYQUERY.QBE already exists, you are asked if you want to overwrite it.


See Also

CREATE

SET VIEW


CREATE REPORT

See Also	Example	Portability	Input/Output

Opens the Report Designer to create or modify a report file.

Syntax

CREATE REPORT
[CROSSTAB]
[<filename> | ? | <filename skeleton>]

CROSSTAB

Opens the Report Designer with the Cross-Tab dialog box displayed.

<filename> | ? | <filename skeleton>

The report file to create or modify. The ? and <filename skeleton> options display a dialog box from which you can select a file. If you specify a file without including its path, dBASE looks for the file in the current directory, then in the path you specify with SET PATH.

If you specify a file without including its extension, dBASE assumes .RPT if you haven't specified CROSSTAB, and .RPC if you have. If dBASE cannot find <filename>, it creates a file with the appropriate extension and saves it in the current directory.

CREATE REPORT without any options opens the empty Report Designer to create a new report.

Description

Use CREATE REPORT to open the Report Designer and create or modify a report file. A report file contains the information that formats a report. For information about using the Report Designer, see Designing Reports and Labels or the Crystal Reports documentation. CREATE REPORT and MODIFY REPORT are identical commands.

Before issuing CREATE REPORT, you must have a default printer selected. After you create or modify the report file, use REPORT FORM to print the report.


CREATE REPORT Example

This example opens a database table and then issues CREATE REPORT to construct a report form:

CLOSE DATABASE
USE COMPANY
CREATE REPORT Comprep1
* If Comprep1 already exists then it will be
* modified. Otherwise a new report form will be
* created


Portability

The <filename skeleton> option is not supported in dBASE IV or dBASE III PLUS. In dBASE IV and dBASE III PLUS, the default report file extension is .FRM.


See Also

REPORT FORM


CREATE SCREEN

See Also	Example	Portability	Forms

Opens the Form Designer to create or modify a form.

Syntax

CREATE SCREEN
[<filename> | ? | <filename skeleton>]

<filename> | ? | <filename skeleton>

The form to create or modify. CREATE SCREEN ? and CREATE SCREEN <filename skeleton> display the Save File dialog box, from which you can select a file. If you specify a file without including its path, dBASE looks for the file in the current directory, then in the path you specify with SET PATH. If you specify a file without including its extension, dBASE assumes .WFM.

Description

CREATE SCREEN, CREATE APPLICATION, and CREATE FORM are identical; all launch the Form Designer. See the description of CREATE FORM for more information.


CREATE SCREEN Example

See the example of CREATE FORM. In this example, CREATE SCREEN works the same as CREATE FORM.


Portability

In dBASE III PLUS and dBASE IV, CREATE SCREEN opens the dBASE III PLUS or dBASE IV Form Designer. These Form Designers create two files, .SCR and .FMT. You can use .FMT files in dBASE for Windows; however, you cannot modify them with the dBASE for Windows Form Designer.


See Also

CREATE APPLICATION

CREATE FORM

MODIFY APPLICATION

MODIFY FORM

MODIFY SCREEN

OPEN FORM


CREATE SESSION

See Also	Example	Portability	Environment

Creates a new session and immediately selects it. Subsequent commands that are session-based apply to the new session.

Syntax

CREATE SESSION

Description

Use CREATE SESSION to initiate a clean work session within dBASE. A session can be compared to a multi-user environment; each session manages its own set of work areas. Associating a form or application with a session ensures that no other form or application can interfere with the environment in the session. For example, if an application running in another session issues CLOSE ALL, the files in the current session are not affected.

In particular, CREATE SESSION does the following:

Makes all work areas available, even if other running programs have tables open. As in a multi-user environment, the same table can be opened in different sessions, but the record pointer actions are independent in each session. When updates to a table are performed in one session, however, the changes are reflected in the same table opened in another session.

Resets the value of most SET commands to their default value (a complete list is included later in this section)

Note:	CREATE SESSION does not release or remove access to memory variables. Access to variables is controlled only by their scope (public, private, local, or static), not by the session in which they are declared.

You might want to issue CREATE SESSION at the following times in an application:

At the beginning of any program or procedure that needs to start in the default environment, or that needs to be protected from commands issued in another session..

At the beginning of the first program in a sequence of related programs; this ensures that your program starts in a known environment and is protected from actions in other sessions.

At the beginning of the code (.PRG or .WFM) defining a form that is linked to a table; this ensures that the form has access to the table, even if the table is in use in another session.

Before opening a table you want to open and display in a BROWSE or EDIT window; this makes it possible for you to set filters, indexes, and other conditions relevant to the current view, even if the table is in use in another session.

Before beginning a series of transactions with BEGINTRANS( ); this ensures the transaction can be started, even if another BEGINTRANS( ) is active in another session.

You can't issue a command to select or end a particular session. A session is selected in one of the following ways:

When you issue CREATE SESSION, that session is selected.

When a form is activated, the session in effect when the form was created is selected.

When you open a Browse or Query window, the session in effect when the Browse or Query was created is selected.

A session ends automatically when all windows or forms associated with the session cease to exist.

The following SET commands affect only the current session:

SET AUTOSAVE	SET BLOCKSIZE	SET CARRY
SET CENTURY	SET CONFIRM	SET CUAENTER
SET CURRENCY	SET DATABASE	SET DATE
SET DBTYPE	SET DECIMALS	SET DEFAULT
SET DELETED	SET DELIMITERS	SET DIRECTORY
SET EXACT	SET EXCLUSIVE	SET FIELDS
SET FILTER	SET IBLOCK	SET INDEX
SET KEY TO	SET LOCK	SET MARK
SET MBLOCK	SET MEMOWIDTH	SET NEAR
SET ORDER	SET PATH	SET POINT
SET PRECISION	SET REFRESH	SET RELATION
SET REPROCESS	SET SAFETY	SET SEPARATOR
SET SKIP	SET TALK	SET UNIQUE
For more information on sessions, see Chapter 21 in the Programmer's Guide.


CREATE SESSION Example

The following example sets up two BROWSEs with different indexes in different sessions:

SET EXCLUSIVE OFF
CLOSE ALL
USE Company ORDER Company
BROWSE
CREATE SESSION
USE COMPANY ORDER CompCode
BROWSE


Portability

Not supported in dBASE IV or dBASE III PLUS.


See Also

DO

DEFINE

LOCAL

PRIVATE

PUBLIC

STATIC


CREATE VIEW

See Also	Example	Table Organization

Opens the Query Designer to create or modify a query file.

Syntax

CREATE VIEW <filename> | ? | <filename skeleton>

<filename> | ? | <filename skeleton>

Specifies the name of the file you want to create. CREATE VIEW ? and CREATE VIEW <filename skeleton> display a dialog box, in which you can specify the name of a new query file. If you specify a file without including its path, dBASE for Windows saves the file to the current drive and directory. If you specify a file without including an extension, dBASE for Windows assumes a .QBE extension.

Description

CREATE VIEW performs the same operation as CREATE QUERY. Use either command to invoke the Query Designer, an interactive environment in which you can create or modify a query. The Query Designer creates a .QBE file that displays only the fields and records that meet specified conditions. To activate a query (.QBE) file, you can use the SET VIEW command. For more information on using the Query Designer, see Designing Queries or the User's Guide.


CREATE VIEW Example

CREATE VIEW or CREATE QUERY with no arguments opens the query designer and generates an untitled query which the user will name later:

CREATE VIEW

CREATE VIEW followed by a file name will create a file of that name when the file is saved.

CREATE FILE Myquery

If MYQUERY.QBE already exists, you will be asked if you wish to overwrite it.

dBASE issues a CLOSE DATABASES command after CREATE VIEW


See Also

SET VIEW


CREATE VIEW...FROM ENVIRONMENT

See Also	Example	Table Organization

Creates a dBASE III PLUS-compatible view file based on the current working environment.

Syntax

CREATE VIEW <filename> FROM ENVIRONMENT

<filename>

The view file to contain the current working environment specifications. By default, dBASE for Windows assigns a .VUE extension to <filename> and saves the file in the current directory.

Description

This command saves the current working environment to a view (.VUE) file; you can open the file later with the SET VIEW TO <filename> command to restore the captured environment settings. The current working environment includes all open tables and index files, as well as their work area numbers, all relations, the active fields list, filter conditions, and any open format file. It does not, however, include SET RELATION...INTEGRITY or SET KEY options.


CREATE VIEW...FROM ENVIRONMENT Example

The following example opens two tables, sets a relationship, filters, and field statements. It then issues CREATE VIEW which creates the .VUE file. CRT_VFE.VUE contains all these statements. SET VIEW TO reproduces them:

CLOSE DATABASE
USE Company EXCLUSIVE
SELECT 2
USE CONTACT EXCLUSIVE
INDEX ON Compcode TAG Compcode
SET FIELDS TO Contact
SELECT Company
SET RELATION TO Compcode INTO Contact
SET FIELDS TO Company, State_Prov
SET FILTER TO State_Prov="CA"
CREATE VIEW Crt_vfe FROM ENVIRONMENT

All these commands are reproduced when the user issues:

SET VIEW TO Crt_vfe


See Also

CREATE QUERY

CREATE VIEW

SET FIELDS

SET FILTER

SET FORMAT

SET INDEX

SET RELATION

SET VIEW

USE


CTOD( )

See Also	Example	Expressions and Type Conversion

Returns a specified character expression as a date expression.

Syntax

CTOD(<expC>)

<expC>

The character expression, in the current date format, to return as a date expression.

Description

Use CTOD( ) to convert a character expression to a date expression. Once you convert character data to date data, you can manipulate it with date functions and date arithmetic.

You must enter <expC> in the current date format as determined by SET DATE, DBASEWIN.INI, or the Windows Control Panel (in that order). That is, SET DATE settings override those in DBASEWIN.INI, and settings in DBASEWIN.INI override those in the Windows Control Panel. Be sure <expC> matches the date format in use when your program runs.

CTOD( ) returns a date in the current date format.

If you pass an invalid date to CTOD( ), it converts the date to a valid one and returns that date as a date expression. If you pass an empty or non-date string to CTOD( ), it returns an empty date expression in the current format. For example, if the SET DATE format is AMERICAN, CTOD("") returns /  /.

You can substitute the separator in <expC>with any character except a number. For example, <expC> can be "MM*DD*YY" or "MM!DD!YY". CTOD( ) returns the date with the current default separator.

You can specify a B.C. date by typing "bc" in uppercase or lowercase after the date and a space--for example, CTOD("4/4/92 BC").


CTOD( ) Example

The following examples uses CTOD( ) to change character data to a date format:

SET DATE AMERICAN
? CTOD("4/1/94")              && Returns 04/01/94
? CTOD("14/1/94")             && Returns 01/01/94
? CTOD("4/32/94")             && Returns 05/02/94
? CTOD("00/00/00")            && Returns   /  /
? CTOD("")                    && Returns   /  /
? CTOD("X/X/X")               && Returns   /  /
? CTOD(4/1/94)                && Returns an error
x = "4/1/94"
? CTOD(x)                     && Returns 04/01/94
? CTOD("1/1/91 BC")           && Returns 01/01/91 BC


See Also

DTOC( )

DTOS( )

SET DATE

SET CENTURY

SET MARK


DATABASE( )

See Also	Example	Portability	Table Basics

Returns the name of the current database from which tables are accessed.

Syntax

DATABASE( )

Description

DATABASE( ) returns the name of the current default database selected with the SET DATABASE command. (Databases are defined with the IDAPI Configuration Utility; see Getting Started for more information.) If no database is open, the DATABASE( ) function returns an empty string ("").


DATABASE( ) Example

The following example uses OPEN DATABASE and SET DATABASE TO to connect to databases on a database server and DATABASE( ) to confirm which database is open:

CLEAR
SET DBTYPE TO             && default is DBASE
OPEN DATABASE CAClients LOGIN guest/guest;
       && Establish connection with database server;
          and enter user name / password
OPEN DATABASE FLClients LOGIN guest/guest;
       && Establish connection with database server;
          and enter user name / password
SET DATABASE TO CAClients && Makes it current database
USE admin.Oakland
? DATABASE()             && Returns CACLIENTS
? ALIAS()                && Returns 1
? DBF()                  && Returns ADMIN.OAKLAND
? WORKAREA()             && Returns 1
SET DATABASE TO FLClients && Makes it Current;
                             database
? DATABASE()             && Returns FLCLIENTS
CLOSE DATABASES CAClients, FLClients ;
                          && Disconnect from database;
                             server


Portability

Not supported in dBASE IV or in dBASE III PLUS.


See Also

CLOSE...

OPEN DATABASE

SET DATABASE

SET DBTYPE


DATE( )

See Also	Example	Date and Time Data

Returns the system date.

Syntax

DATE( )

Description

DATE( ) returns a date expression that is your computer system's current date.

dBASE uses the value set by SET DATE, DBASEWIN.INI, or the International option of the Windows Control Panel (in that order) to determine the current date format. That is, SET DATE settings override those in DBASEWIN.INI, and settings in DBASEWIN.INI override those in the Windows Control Panel. DATE( ) returns a date in the current date format.

If SET CENTURY is ON, DATE( ) returns the date with a 4-digit year.

To change the system date, use SET DATE TO. To express the date as a character string, use DTOC( ) or DTOS( ).


DATE( ) Example

The following example uses DATE( ) to compute the number of days between a date field's contents and the current system date, and to derive a due date 30 days in the future.

USE Clients
? DTOC(Baldate) + ", " + ;
  LTRIM(STR(DATE() - Baldate)) + ;
  " days have passed since this account was" + ;
  " balanced."
CLOSE DATABASE
?
?  "Your account is due in thirty (30) days - "
?? DATE() + 30


See Also

DTOC( )

DTOS( )

SET CENTURY

SET DATE

SET DATE TO

SET MARK


DAY( )

See Also	Example	Date and Time Data

Returns the numeric value of the day of the month for a specified date expression.

Syntax

DAY(<expD>)

<expD>

The date expression whose corresponding day-of-the-month number to return.

Description

DAY( ) returns a date's day of the month number--a value from 1 to 31.

Enter <expD> in the current date format as determined by SET DATE, DBASEWIN.INI, or the International option of the Windows Control Panel (in that order). That is, SET DATE settings override those in DBASEWIN.INI, and settings in DBASEWIN.INI override those in the Windows Control Panel. Be sure <expD> matches the date format in use when your program runs.

If you pass an invalid date to DAY( ), dBASE converts the date to a valid one and returns the month-day number of that date. If you pass an empty or non-date expression delimited with braces ({ }) to DAY( ), it returns 0. If you pass a non-date expression or an expression that is not delimited with braces to DAY( ), it returns an error.


DAY( ) Example

The following examples use DAY( ) to return the numeric day of the month from date type data.

SET DATE AMERICAN
? DAY({4/1/94})              && Returns 1
? DAY({4/32/93})             && Returns 2 because;
                                April has 30 days
? DAY({00/00/00})            && Returns 0
? DAY({})                    && Returns 0
? DAY(X)                     && Returns error message
? DAY(4/1/94)                && Returns error message
X = {4/1/94}
? DAY(X)                     && Returns 1

For additional examples of DAY( ) see CMONTH( ) and CDOW( ).


See Also

DOW( )

MONTH( )

SET CENTURY

SET DATE


DBERROR( )

See Also	Example	Portability	Error Handling and Debugging

Returns the number of the last IDAPI error.

Syntax

DBERROR( )

Description

DBERROR( ) returns the IDAPI error number of the last IDAPI error generated by the current table. To learn the IDAPI error message itself, use DBMESSAGE( ).

See the table in the description of ERROR( ) that compares ERROR( ), MESSAGE( ), DBERROR( ), DBMESSAGE( ), SQLERROR( ), SQLMESSAGE( ), and CERROR( ).

See Error Messages for a listing of all error messages.


DBERROR( ) Example

The following example uses ON ERROR to branch to an error procedure that uses DBERROR( ) to return what IDAPI error has occurred during the BROWSE and DBMESSAGE( ) to return what it means:

USE Clients
ON ERROR DO Recovery
COPY TO TEMP
USE TEMP
BROWSE

PROCEDURE Recovery
CLOSE DATABASES
CLEAR
IF ERROR()=239
  ? "The IDAPI error was error number: " + ;
  STR(DBERROR())
  ? "Which means: " + DBMESSAGE()
ELSE
  ? "No IDAPI error encountered"
ENDIF
RETURN


Portability

Not supported in dBASE IV or dBASE III PLUS.


See Also

CERROR( )

DBMESSAGE( )

ERROR( )

MESSAGE( )

SQLERROR( )

SQLMESSAGE( )


DBF( )

See Also	Example	Table Basics

Returns the name of a table open in the current or a specified work area.

Syntax

DBF( [<alias>] )

<alias>

A work area number (1 through 225), letter (A through J), or alias name. The work area letter or alias name must be enclosed in quotes.

Description

DBF( ) returns the name of the table open in a specified work area. If SET FULLPATH is ON, the DBF( ) function also returns the drive and directory location of the table in addition to the table name. If you do not specify a work area, the current work area is assumed.

If no table is in use in the current or specified work area, DBF( ) returns an empty string ("").


DBF( ) Example

The following example demonstrates the relationship between DBF( ), SELECT( ) and WORKAREA( ) when multiple tables are open in more than one workarea:

CLOSE ALL
USE Flights IN 1
USE Aircrdb IN 2
USE Company IN 3
SELECT 3
? DBF()              && Returns C:COMPANY.DBF
? SELECT()           && Returns 4
? WORKAREA()         && Returns 3


See Also

ALIAS( )

MDX( )

NDX( )

SET FULLPATH

TAG( )

WORKAREA( )

USE


DBMESSAGE( )

See Also	Example	Portability	Error Handling and Debugging

Returns the error message of the last IDAPI error.

Syntax

DBMESSAGE( )

Description

DBMESSAGE( ) returns the error message of the most recent IDAPI error.

See the table in the description of ERROR( ) that compares ERROR( ), MESSAGE( ), DBERROR( ), DBMESSAGE( ), CERROR( ), SQLERROR( ), and SQLMESSAGE( ).

See Error Messages for a listing of all error messages.


DBMESSAGE( ) Example

See DBERROR( ) for an example of using DBMESSAGE( ).


Portability

Not supported in dBASE IV or dBASE III PLUS.


See Also

CERROR( )

DBERROR( )

ERROR( )

MESSAGE( )

SQLERROR( )

SQLMESSAGE( )


DEACTIVATE MENU

See Also	Example	Portability	dBASE IV Menus

Erases and disables an active dBASE IV menu bar without removing its definition from memory. This command is supported primarily for compatibility with dBASE IV. In dBASE for Windows, use RELEASE OBJECT to clear an object from a form.

Syntax

DEACTIVATE MENU

Description

Use DEACTIVATE MENU to erase and disable the current dBASE IV menu bar. Since its definition remains in memory, you can display and enable the menu again with ACTIVATE MENU. To remove a menu definition from memory, use RELEASE MENU.

When dBASE erases the menu bar from the screen, it restores the screen display the menu covered.

When you use DEACTIVATE MENU in a program, program control goes to the command following the command that activated the menu. If one menu is activated from another menu, program control returns to the parent menu when the child menu is deactivated.


DEACTIVATE MENU Example

The following program displays a menu with three options: List Memory, List Status or Quit. The Quit option calls procedure QuitProc, which uses DEACTIVATE MENU to remove the menu from memory and close the program:

CLEAR
DEFINE MENU Menu_mem MESSAGE "List memory or status"
DEFINE PAD Pad_mem OF Menu_mem PROMPT "List Memory" ;
AT 0,1
DEFINE PAD Pad_stat OF Menu_mem PROMPT "List Status";
AT 0,20
DEFINE PAD Pad_quit OF Menu_mem PROMPT "Quit" AT 0,40
ON SELECTION PAD Pad_mem OF Menu_mem DO Memproc
ON SELECTION PAD Pad_stat OF Menu_mem DO Statproc
ON SELECTION PAD Pad_quit OF Menu_mem DO Quitproc
ACTIVATE MENU Menu_mem

PROCEDURE Memproc
CLEAR
LIST MEMORY

PROCEDURE Statproc
CLEAR
LIST STATUS

PROCEDURE Quitproc
CLEAR
DEACTIVATE MENU


Portability

Not supported in dBASE III PLUS.


See Also

ACTIVATE MENU

CLEAR MENUS

DEFINE

RELEASE MENUS

RELEASE OBJECT


DEACTIVATE POPUP

See Also	Example	Portability	dBASE IV Menus

Erases and disables an active dBASE IV pop-up menu without removing its definition from memory. This command is supported primarily for compatibility with dBASE IV. In dBASE for Windows, use RELEASE OBJECT to clear an object from a form.

Syntax

DEACTIVATE POPUP

Description

DEACTIVATE POPUP disables the current pop-up menu and removes it from the screen without removing the menu definition from memory.

When you use DEACTIVATE POPUP in a program, program control goes to the command following the command that activated the pop-up menu. If a child pop-up menu is activated from a parent menu, program control returns to the parent menu when the child menu is deactivated. All commands following DEACTIVATE POPUP in the routine that executes it are ignored.

When dBASE erases the pop-up menu from the screen, it restores the screen display it covered.


DEACTIVATE POPUP Example

The following example shows how to retain the pop-up menu Sort_pop on the screen for multiple selections until the Exit menu option issues the DEACTIVATE POPUP command, which clears the pop-up menu from the screen:

* Sort Program
DEFINE POPUP Sort_pop FROM 2,2
DEFINE BAR 1 OF Sort_pop PROMPT "Select Sort Order";
    SKIP                     && Line not selectable
DEFINE BAR 2 OF Sort_pop PROMPT "*****************";
    SKIP                     && Line not selectable
DEFINE BAR 3 OF Sort_pop PROMPT "Ascending";
    MESSAGE "Sort the Country table in ascending;
        order"
DEFINE BAR 4 OF Sort_pop PROMPT "Descending";
    MESSAGE "Sort the Country table in descending;
        order"
DEFINE BAR 5 OF Sort_pop PROMPT "Exit program"
ON SELECTION POPUP Sort_pop DO Sort_proc

USE COUNTRY EXCLUSIVE
SET SAFETY OFF
SET TALK OFF
CLEAR
ACTIVATE POPUP Sort_pop
CLOSE ALL
SET TALK ON
SET SAFETY ON

PROCEDURE Sort_proc
IF BAR()=3
    INDEX ON Name TAG Acountry
ELSEIF BAR()=4
    INDEX ON Name TAG Dcountry DESCENDING
ELSEIF BAR()=5
    DEACTIVATE POPUP    && Returns to line following;
                        ACTIVATE POPUP Sort_pop in;
                        the main program
ENDIF
BROWSE


Portability

Not supported in dBASE III PLUS.


See Also

CLEAR POPUPS

DEFINE

RELEASE OBJECT


DEACTIVATE WINDOW

See Also	Example	Portability	dBASE IV Windows

Clears from the screen windows that were displayed and enabled with the dBASE IV command ACTIVATE WINDOW, without releasing their definitions from memory. This command is supported primarily for compatibility with dBASE IV. In dBASE for Windows, use CLOSE FORMS or RELEASE OBJECT to close or release a form.

Syntax

DEACTIVATE WINDOW <window name 1> [, <window name 2> ...] | ALL

<window name 1> [, <window name 2>]...

Specifies which windows are closed with DEACTIVATE WINDOW.

ALL

Causes all windows with definitions resident in memory to be closed.

Description

DEACTIVATE WINDOW closes windows while retaining their definitions in memory. After you close a window, you can open it again with ACTIVATE WINDOW.

When you close one or more windows with DEACTIVATE WINDOW, the window that was most recently opened becomes the active window (that is, the window with input focus). If no windows remain active, all screen input and output go to the results pane of the Command window.

To clear windows from the screen and release their definitions from memory, use RELEASE WINDOWS, CLEAR WINDOWS, or CLEAR ALL.


DEACTIVATE WINDOW Example

The following example opens three tiled windows, browses two fields of the Contact table in Window C, uses DEACTIVATE WINDOW to revert to Window B and Window A:

SELECT A
USE COMPANY
SELECT B
USE CONTACT
CLEAR
DEFINE WINDOW A FROM 1,1 TO 15,40 DOUBLE
DEFINE WINDOW B FROM 5,5 TO 18,60 DOUBLE
DEFINE WINDOW C FROM 10,10 TO 23,50 DOUBLE
ACTIVATE WINDOW A, B, C
BROWSE FIELDS COMPCODE, CONTACT
DEACTIVATE WINDOW C        && Cleared from screen
SELECT A
BROWSE FIELDS COMPANY, YTD_SALES
DEACTIVATE WINDOW B        && Cleared from screen
WAIT "Window A remains open"
DEACTIVATE WINDOW ALL      && Windows still in memory
WAIT "No windows are open"
CLEAR WINDOWS              && Cleared from memory
CLEAR                      && Clear screen
RETURN


Portability

Not supported in dBASE III PLUS.


See Also

CLEAR ALL

CLEAR WINDOWS

CLOSE FORMS

DEFINE

RELEASE OBJECT

RELEASE WINDOWS


DEBUG

See Also	Example	Error Handling and Debugging

Opens the dBASE Debugger.

Syntax

DEBUG
[<filename> | ? | <filename skeleton> |
<procedure name> | <UDF name>
[WITH <parameter list>]]

<filename> | ? | <filename skeleton>

The file to debug. DEBUG ? and DEBUG <filename skeleton> display the Open Source File dialog box, from which you can select a file. If you specify a file without including its path, dBASE looks for the file in the current directory, then in the path you specify with SET PATH. If you specify a file without including its extension, dBASE assumes .PRG.

<procedure name> | <UDF name>

The procedure or user-defined function (UDF) in an open program file to debug. The procedure or UDF must be in the program file containing the DEBUG command that calls it, or in a separate open procedure file on the search path. (You can open a procedure file with SET PROCEDURE TO.) See the description of DOfor an explanation of the search path and order dBASE follows when it encounters a call to a program, procedure, or UDF.

WITH <parameter list>

Specifies expressions to pass as parameters to a program, procedure, or UDF that contains PARAMETERS <parameter list> as its first executable command line. For information about parameter passing, see the description of PARAMETERS.

You can debug a UDF without DEBUG...WITH by calling the UDF directly in an expression; in which case, you enclose parameters to pass to it in parentheses after the UDF name.

If you want to specify a parameter list, you must also specify one of the preceding options. That is, issuing DEBUG WITH <parameter list> returns an error.

Description

Use DEBUG to turn on the Debugger and view or control program execution interactively. The Debugger displays information about the state of a program, procedure, or UDF--and any procedure files that the program or subroutine opens--during execution. For more information, see the Programmer's Guide, which describes the Debugger in detail.

You can issue DEBUG without any options from the Command window or from within a program file. If you issue DEBUG without any options in the Command window, dBASE opens the Debugger without loading a program or subroutine. (You can load a file to debug from the Debugger.) If you issue DEBUG without any options in a program file, dBASE loads the current program file in the Debugger. If you issue DEBUG <filename> from a program file, <filename> should be a program file other than the one containing the command; otherwise, you get an error.

You can issue DEBUG <procedure name> and DEBUG <UDF name> from within the program file that calls the procedure or UDF. You can also issue both of these commands from the Command window or from within a program file other than the one containing the procedure or UDF, but the file must be on the search path.

You can run a program line by line in the Debugger and control which lines to stop at. If you do not want to stop execution within a subroutine, you can step over the command line that calls the subroutine. The call to the subroutine is still made, and the subroutine still executes; you just do not see the line-by-line execution of the subroutine. The Debugger stops at the first command line following the subroutine.

When you debug a UDF with DEBUG <UDF name> WITH <parameter list>, dBASE ignores the return value of the UDF. If you want to call a UDF in the context of an expression so that you can see if the UDF returns the right value and the right data type, you can, in a program file, issue DEBUG with no parameters and then the command-line expression containing the call to the UDF. DEBUG will open the program file in the Debugger, in which you can then step to the next line containing the UDF call.

In the Debugger, step over a command line that calls a subroutine by doing one of the following:

Click the Step Over icon on the Debugger SpeedBar

Choose Run|Step Over from the Debugger menu

Press F8


DEBUG Example

The following examples demonstrate three options for calling the Debugger. Type in the Command window:

DEBUG ?       && Opens "Open Source File" dialog box
DEBUG *.WFM   && Opens "Open Source File" dialog box;
                 with .WFM files selectable
DEBUG ANIMALS && Enters Debugger with Animals.PRG ;
                 source code in the upper-left window

Including the following code line in your program automatically takes you to the Debugger. SET ECHO ON is another way to accomplish the same thing:

ON ERROR DEBUG PROGRAM()


See Also

DISPLAY COVERAGE

GENERATE

ON ERROR

RESUME

SET COVERAGE

SET PATH

SUSPEND


DECLARE

See Also	Example	Portability	Memory Variables

Defines one or more fixed arrays.

Syntax

DECLARE <array name 1>"["<expN list 1>"]"
[,<array name 2>"["<expN list 2>"]" ...]

Brackets ([ ]) in quotation marks are required syntax components.

<array name 1>[,<array name 2> ...]

The memory variable(s) that are the name(s) of the array(s).

"["<expN list 1>"]"[,..."["<expN list 2>"]"][,...]

Numeric or float expressions (from 1 to 254 inclusive). The number of expressions you specify determines the number of dimensions of the array. Each one of the expressions specifies how many values (data elements) that dimension has. For example, if [<expN list 1>] is [3,4], dBASE defines a two-dimensional array with three rows and four columns.

Description

Use DECLARE to define an array of a specified size as a memory variable. Array elements can be of any data type. (An array element can also specify the name of another array.) A single array can contain multiple data types. When you use DECLARE, all array elements are initialized to a logical data type with a value of .F.

The array can hold as many elements as memory allows. You can create arrays that contain more than two dimensions, but most dBASE array functions work only on one- or two-dimensional arrays.

There are two ways to refer to individual elements in an array; you can use either the element subscripts or the element number. Element subscripts indicate the row and column in which an element is located. Element numbers indicate the sequential position of the element in the array, starting at the first row and first column of the array. To determine the number of elements, rows, or columns in an array, use ALEN( ).

Certain dBASE functions require the element number, and others require the subscripts. If you are using one- or two-dimensional arrays, you can use AELEMENT( ) to determine the element number if you know the subscripts, and ASUBSCRIPT( ) to determine the subscripts if you know the element number.

After you create an array, you can place values in cells of the array using STORE, or you can use =. You can also use AFILL( ) to place the same value in a range of cells in the array. To add or delete elements from an array, use ADEL( ) and AINS( ). To resize an array, or make a one-dimensional array two-dimensional, use AGROW( ) or ARESIZE( ). For more information on using arrays, see Chapter 5 in the Programmer's Guide.

You can pass array elements as parameters, and you can pass a complete array as a parameter to a program or procedure by specifying the array name without a subscript. For more information on passing arrays as parameters, see Chapter 4 in the Programmer's Guide.


DECLARE Example

The following example relates two tables to create a view consisting of two fields from each table, then uses DECLARE to create an array Compsumm and copies the selected data to the array. The counting DO WHILE loop displays the contents of the array to the results pane of the Command window:

CLOSE ALL
CLEAR
USE Contact IN SELECT()  ORDER CompCode
USE Company IN SELECT()
SELECT Company
SET RELATION TO CompCode INTO Contact

DECLARE Compsumm[5,4]         && Create an array of;
                                 5 rows and 4 columns
COPY TO ARRAY Compsumm NEXT 5;
   FIELDS Company->Company, ;
   Company->City, Contact->CompCode, ;
   Contact->Contact
Cnt=1
DO WHILE Cnt<=5
  ? Compsumm[Cnt,1], Compsumm[Cnt,2]
  ?? Compsumm[Cnt,3], Compsumm[Cnt,4]
  Cnt=Cnt+1
ENDDO
CLOSE ALL


Portability

Not supported in dBASE III PLUS.


See Also

ADEL( )

AELEMENT( )

AFILL( )

AGROW( )

AINS( )

ALEN( )

APPEND FROM ARRAY

ARESIZE( )

ASUBSCRIPT( )

COPY TO ARRAY

REPLACE FROM ARRAY

STORE


DEFINE

See Also	Example	Portability	Objects

Creates an object from a class.

Syntax

DEFINE <class name><object name>
[OF <container object>]
[FROM <row, col> TO <row, col> > | <AT <row, col>]
[PROPERTY <stock property list>]
[CUSTOM <custom property list>]
[WITH <parameter list>]

<class name>

The class of the object you create. DEFINE can create objects from twenty standard classes:

Browse	Checkbox	Combobox

DDElink	DDETopic	Editor

Entryfield	Form	Image

Line	Listbox	Menu

Object	OLE	Pushbutton

Radiobutton	Rectangle	Scrollbar

Spinbox	Text

You can also specify a custom class, which you define with the CLASS...ENDCLASS command.

<object name>

The identifier for the object you create. <object name> is the object reference variable, through which you can access and change the object properties. For information on using object reference variables, see Chapter 10 in the Programmer's Guide.

OF <container object>

Identifies the object that contains the object you define. (For most UI objects the container object is a form.) OF <container object> is required if you identify the object using <index operator expN>.

FROM <row>, <col> TO <row>, <col> | AT <row>, <col>

Specifies the initial location and size of the object within its parent form. FROM and TO specify the upper left and lower right coordinates of the object, respectively. AT specifies the position of the upper left corner.

PROPERTY <stock property list>

Specifies values you assign to the built-in properties of the object.

CUSTOM <custom property list>

Specifies new properties you create for the object and the values you assign to them. For information on custom properties, see Chapter 10 in the Programmer's Guide.

WITH <parameter list>

Specifies the parameters you pass to the object. Declare these parameters with the PARAMETERS clause of the CLASS...ENDCLASS command.

Description

Use DEFINE to create an object definition in memory.

An object contains memory variables called properties. Some properties hold data values that modify the object itself, while others reference subroutines that are executed in response to events. For example, a pushbutton responds to a mouse click by triggering its OnClick subroutine and the OnSelection subroutine of its parent form.

Every object belongs to a class. A class is a specification, or template, for a type of object. dBASE for Windows provides many built-in classes that you can use to create common Windows objects (also called controls), such as radio buttons, pushbuttons, and entry fields. For example, each time you create a form with DEFINE FORM, you make a new form object that has the built-in specifications from the Form class.

You can design your own custom class with the CLASS...ENDCLASS command. CLASS...ENDCLASS lets you use regular dBASE code to declare the properties and methods that objects of the class will have. For information on classes, see Chapter 11 in the Programmer's Guide.


DEFINE Example

The following example uses DEFINE to create a custom DIALOG BOX class, with several useful functions:

rDialog = NEW Dialog()
rDialog.alert("This is an alert box")
? rDialog.YesNo("Do you like it?")
? rDialog.GetString("What is your name?",;
  SPACE(20),"@!", "Last Name first")
RETURN

CLASS Dialog
   this.Top = 20
   this.Left = 12
   this.Height = 7
   this.Width = 12
   this.Value = .f.
   this.Color = 'n/w'
   SET CUAENTER OFF

FUNCTION Alert
PARAMETER cString, cTitle
PRIVATE nButtonCol
  this.Height = 8
  this.Value = ""
  this.Left = 39 - (this.Width/2)
    IF TYPE( 'cTitle') <> 'C'
      this.Text = ""
      this.Height = 7
    ELSE
      this.Text = cTitle
      this.Height = 9
    ENDIF
      this.Width = MAX(LEN(cString),LEN(this.Text))+7
DEFINE FORM F1;
  PROPERTY Top this.Top,;
    Left this.Left, ;
    Height this.Height, ;
    Width this.Width, ;
    MDI .F., ;
    Text this.Text
  DEFINE TEXT T1 of F1;
    PROPERTY Top 1, Left 3, ;
      Width LEN(cString), ;
      Text cString
      nButtonCol = (this.width/2)-5
  DEFINE PUSHBUTTON B1 of F1;
    PROPERTY Top 4, Left nButtonCol, ;
      Text "OK", OnClick {; Form.CLOSE()}
F1.READMODAL()
F1.RELEASE()
RETURN .T.

FUNCTION GetString
PARAMETER cPrompt, cString, cPicture, cTitle
RETURN this.GetValue(cPrompt,cString,LEN(cString),;
  cPicture, cTitle)

FUNCTION GetNumber
PARAMETER cPrompt, nNumber, cPicture, cTitle
RETURN this.GetValue(cPrompt,nNumber,;
  LEN(STR(nNumber)), cPicture, cTitle )

FUNCTION GetDate
PARAMETER cPrompt, dDate, cPicture, cTitle
RETURN CTOD(this.GetValue(cPrompt,DTOC(dDate),8,;
  cPicture, cTitle))

FUNCTION YesNo
PARAMETER cString, cTitle, lInitValue
PRIVATE nButtonCol1, lRetval
   this.Height = 8
   lRetval = lInitValue
   this.Value = .t.
   this.Left = 39 - (this.width/2)
     IF TYPE( 'cTitle') <> 'C'
        this.Text = ""
        this.Height = 7
     ELSE
        this.Text = cTitle
        this.Height = 9
     ENDIF
   this.Width=MAX(18,MAX(LEN(cString),;
     LEN(this.Text))+ 7 )
DEFINE FORM F1;
  PROPERTY Top this.Top, ;
    Left this.Left, ;
    Height this.Height, ;
    Width this.Width, ;
    MDI .F., ;
    Text this.Text
  DEFINE TEXT T1 OF F1;
    PROPERTY Top 1, left 3, ;
      Width LEN(cString), ;
      Text cString
      nButtonCol1 = (this.width/2) - 9
  DEFINE PUSHBUTTON Yes OF F1;
    PROPERTY Top 4, Left nButtonCol1, ;
      Width 5, Text "Yes", OnClick this.SetYes
  DEFINE PUSHBUTTON No OF F1;
    PROPERTY Top 4, Left nButtonCol1 + 12,;
      Width 5, Text "No", OnClick this.SetNo
F1.READMODAL()
F1.RELEASE()
RETURN lRetval

FUNCTION GetValue
PARAMETER cPrompt, cString, nLen, cPicture, cTitle
PRIVATE nButtonCol
  this.Width = nLen + 8 + LEN(cPrompt)
  this.Value = ""
  this.Left = 39 - (this.width/2)
    IF TYPE( 'cTitle') <> 'C'
      this.Text = ""
      this.Height = 8
    ELSE
      this.Text = cTitle
      this.Height = 10
    ENDIF
      this.Width=MAX(LEN(cString)+nLen,;
        LEN(this.Text)) + 8
DEFINE FORM F1;
  PROPERTY Top this.Top, ;
    Left this.Left, ;
    Height this.Height, ;
    Width this.Width, ;
    MDI .F., ;
    Text this.Text, ;
    ColorNormal this.Color

  DEFINE TEXT T1 OF F1;
    PROPERTY Top 1, Left 3, ;
      WIDTH LEN(cPrompt), ;
      Text cPrompt
        IF TYPE('cPicture') = 'C'
          DEFINE ENTRYFIELD E1 OF F1;
            PROPERTY Top 1, Left 4+LEN(cPrompt),;
              Width nLen, ;
              Value cString, ;
              Datalink "cString", ;
              Picture cPicture
        ELSE
          DEFINE ENTRYFIELD E1 OF F1;
            PROPERTY Top 1, Left 4 + LEN(cPrompt), ;
              Width nLen, ;
              Value cString, ;
              Datalink "cString"
        ENDIF
        nButtonCol = (this.width/2) - 5
  DEFINE PUSHBUTTON B1 OF F1;
    PROPERTY Top 4, Left nButtonCol, ;
      Text "OK", OnClick {; Form.Close()}
F1.READMODAL()
F1.RELEASE()
RETURN cString

FUNCTION SetYes
lRetval = .T.
Form.CLOSE()
RETURN .T.

FUNCTION SetNo
lRetval = .F.
Form.CLOSE()
RETURN .T.
ENDCLASS


Portability

Not supported in dBASE IV or dBASE III PLUS.


See Also

CLASS...ENDCLASS

REDEFINE

NEW Operator


DEFINE BAR

See Also	Example	Portability	dBASE IV Menus

Creates a bar and its prompt in a dBASE IV pop-up menu. This command is supported primarily for compatibility with dBASE IV. In dBASE for Windows, use DEFINE, OPEN FORM, and READMODAL( ) to create and activate menus associated with forms.

Syntax

DEFINE BAR <expN>
OF <popup name>
PROMPT <prompt expC>
[MESSAGE <message expC>]
[SKIP [FOR <condition expL>]]

PROMPT <prompt expC>

Defines a prompt for the menu bar.

MESSAGE <message expC>

Defines a message that appears on the Status Bar at the bottom of the screen.

SKIP [FOR <condition expL>]

Makes the pop-up menu item unavailable for selection. FOR <condition expL> makes it unavailable only when <condition expL> evaluates to true.

Description

DEFINE BAR creates a pop-up menu bar and defines a prompt for it. You can specify the bar prompts displayed in a pop-up menu in one of two ways:

Use DEFINE POPUP with one of the PROMPT options, FILES, STRUCTURE, FIELD, or ARRAY.

Designate each choice with a DEFINE BAR command.


DEFINE BAR Example

The following program displays a pop-up menu with five bars. The third menu bar with the prompt "Delete an Order" can only be chosen when the No_delete flag is false (.F.). The fourth menu bar is a line of dashes that separates the Exit option from the other choices:

SET TALK OFF
* Set the flag to choose "Delete an order"
No_delete = .T.
DEFINE POPUP Ord_pop FROM 2,2 MESSAGE ;
  "Order entry menu"
* Define Bars of Popup
DEFINE BAR 1 OF Ord_pop PROMPT "Add an order"
DEFINE BAR 2 OF Ord_pop PROMPT "Change an order"
DEFINE BAR 3 OF Ord_pop PROMPT "Delete an order" ;
   SKIP FOR No_delete
DEFINE BAR 4 OF Ord_pop PROMPT REPLICATE("-",17) SKIP
DEFINE BAR 5 OF Ord_pop PROMPT "Exit"
ON SELECTION POPUP Ord_pop DO Branch

* Activate the popup
ACTIVATE POPUP Ord_pop

PROCEDURE Branch
CLEAR
? " You picked " + Prompt()
DEACTIVATE Popup
RETURN


Portability

Not supported in dBASE III PLUS. The SKIP option is not supported in dBASE IV.


See Also

BAR( )

BARPROMPT( )

DEFINE

DEFINE POPUP

ON SELECTION POPUP

OPEN FORM

POPUP( )

PROMPT( )

READMODAL( )


DEFINE BOX

See Also	Example	Portability	Printing

Defines a character-mode box to draw around ? command output. This command is supported primarily for compatibility with dBASE IV. In dBASE for Windows, use DEFINE to create and place rectangles on forms,

Syntax

DEFINE BOX FROM <left col> TO <right col> HEIGHT <expN 1>
[AT LINE <expN 2>]
[SINGLE | DOUBLE | <border definition list>]

<left col>

The left column of the box to draw. If you specify a number less than 0 for <left col>, dBASE displays an error message. The upper limit for <left col> is 255.

TO <right col>

Specifies the right column of the box to draw. If you specify a number less than 0 for <right col>, dBASE displays an error message. The upper limit for <right col> is 255.

HEIGHT <expN 1>

Specifies the height of the box in number of lines, <expN 1>.

AT LINE <expN 2>

Specifies the top line of the box, <expN 2>. If you do not specify a line with AT LINE, dBASE draws the top of the box on the current line.

SINGLE

Makes the border single line. The default border is established with SET BORDER.

DOUBLE

Makes the border double line. The default border is established with SET BORDER.

<border definition list>

A list of characters that make up the border. For information about defining borders, see SET BORDER.

Description

Use DEFINE BOX to draw a dBASE IV character-mode box around streaming output from the ? command. To enable DEFINE BOX, assign .T. to the _box system memory variable. For more information about streaming and non-streaming output, see Chapter 24 in the Programmer's Guide.


DEFINE BOX Example

The following example draws a box to emphasise a heading at the top of a page. It draws the box across 5 rows using DEFINE BOX and prints "This is a heading" on the third row:

SET PRINTER ON
SET TALK OFF
EJECT
_box=.t.                 && _box must be set .t.
DEFINE BOX FROM 10 TO 70 HEIGHT 5
?
?
?
?? "This is a heading" at 30
?
?
SET PRINTER OFF
CLOSE PRINTER


Portability

Not supported in dBASE III PLUS.


See Also

@...TO

DEFINE


DEFINE COLOR

See Also	Example	Portability	Colors and Fonts

Creates and names a customized color.

Syntax

DEFINE COLOR <color name>
<red expN> , <green expN> , <blue expN>

<red expN>, <green expN>, <blue expN>

Specifies the proportions of red, green, and blue that make up the defined color. Each number determines the intensity of the color it represents, and can range from 0 (least intensity) to 255 (greatest intensity).

Description

Use DEFINE COLOR to create a customized color combination. Once you have defined <color name>, you can use it instead of one of the standard colors such as R, W, BG, and so on.

The color you create with DEFINE COLOR is based on three numbers, <red expN>, <green expN>, and<blue expN>. Adjusting these numbers alters the color you create. For example, increasing or decreasing <green expN> increases or decreases the amount of green contained in the customized color.

Use the GETCOLOR( ) function to open a dialog box in which you create a custom color or choose from a palette of available colors. After exiting GETCOLOR( ), issue DEFINE COLOR with the values it returns to define the desired color.

You cannot use standard color names (such as blue, red, white or black) as <color name>. If you do, dBASE returns an error when you later issue SET COLOR TO <color name>. Also, you cannot redefine a dBASE color with a command such as DEFINE COLOR R <red expN> , <green expN> , <blue expN>. If you later use R in a SET COLOR TO statement, dBASE uses its internal value for R, which is red, rather than the color you defined.


DEFINE COLOR Example

The following example defines white, black, red, green, blue, and yellow using DEFINE COLOR and then uses them with SET COLOR TO:

Oldcolors=SET("ATTRIBUTE")
DEFINE COLOR Col_white   255, 255,  255
* Equivalent to W
DEFINE COLOR Col_black     0,   0,    0
* Equivalent to N
DEFINE COLOR Col_red     255,   0,    0
* Equivalent to R
DEFINE COLOR Col_green     0, 255,    0
* Equivalent to G
DEFINE COLOR Col_blue     0    ,0,  255
* Equivalent to B
DEFINE COLOR Col_yellow  255, 255,    0
*
SET COLOR TO Col_white/Col_green
? "Now is the time"
?? "Col_white/Col_green" AT 40
SET COLOR TO Col_red/Col_blue
? " for all good"
?? "Col_red/Col_blue" AT 40
SET COLOR TO Col_blue/Col_red
? "  men and women"
?? "Col_blue/Col_red" AT 40
SET COLOR TO Col_blue/Col_green
? "   to come to "
?? "Col_blue/Col_green" AT 40
SET COLOR TO Col_red/Col_blue
? "    as soon as"
?? "Col_red/Col_blue" AT 40
SET COLOR TO Col_yellow/Col_green
? "     they possibly can"
?? "Col_yellow/Col_green" AT 40
WAIT
SET COLOR TO &Oldcolors  && Reset colors
CLEAR


Portability

Not supported in dBASE IV or dBASE III PLUS.


See Also

ColorHighlight

ColorNormal

GETCOLOR( )

SET COLOR TO

SET COLOR OF


DEFINE MENU

See Also	Example	Portability	dBASE IV Menus

Names a dBASE IV menu bar and begins its definition in memory. This command is supported primarily for compatibility with dBASE IV. In dBASE for Windows, use DEFINE, OPEN FORM, and READMODAL( ) to create and activate menus associated with forms.

Syntax

DEFINE MENU <menu name>
[MESSAGE <expC>]

MESSAGE <expC>

Defines a message that appears on the status line at the bottom of the screen.

Description

Use DEFINE MENU as the first step in creating a dBASE IV menu bar. After starting the menu bar with DEFINE MENU, you can define individual menu prompts, called pads, with DEFINE PAD. The menu and its associated pads are invoked with ACTIVATE MENU.

Use CLEAR MENUS or RELEASE MENUS to release a menu and its associated definitions from memory.


DEFINE MENU Example

The following example uses DEFINE MENU with the MESSAGE option to create a menu within a window. The window is centered in the lower half of the screen:

DEFINE WINDOW A FROM 5,10 TO 20,65;
    COLOR W+/B,RG+/RB+,R+/GB
DEFINE MENU Main;
    MESSAGE "Table Maintenance"
DEFINE PAD Add OF Main PROMPT "Add Records";
    AT 4,3 MESSAGE "Add new records"
DEFINE PAD Search OF Main PROMPT "Search File";
    AT 4,16 MESSAGE "Search for record"
DEFINE PAD Print OF Main PROMPT "Print";
    AT 4,29 MESSAGE "Print a report"
DEFINE PAD Exit OF Main PROMPT "Quit";
    AT 4,49 MESSAGE "Leave the program"

ON SELECTION PAD Add OF Main DO AddRec
ON SELECTION PAD Search OF Main DO SeekRec
ON SELECTION PAD Print OF Main DO Prt_Rpt
ON SELECTION PAD Exit OF Main DO ExitMain
CLEAR
ACTIVATE WINDOW A
ACTIVATE MENU Main

PROCEDURE ExitMain
DEACTIVATE WINDOW A      && Clears window from screen
DEACTIVATE MENU          && Clears menu from screen
CLEAR WINDOWS            && Clears window from memory
CLEAR MENUS              && Clears menu from memory
RETURN

PROCEDURE AddRec
KEYBOARD " "             && Demo purposes only
RETURN

PROCEDURE SeekRec
KEYBOARD " "             && Demo purposes only
RETURN

PROCEDURE Prt_Rpt
KEYBOARD " "             && Demo purposes only
RETURN


Portability

Not supported in dBASE III PLUS.


See Also

ACTIVATE MENU

CLEAR MENUS

DEFINE

DEFINE PAD

OPEN FORM

READMODAL( )

RELEASE MENUS


DEFINE PAD

See Also	Example	Portability	dBASE IV Menus

Creates and names a pad in an existing dBASE IV menu bar. This command is supported primarily for compatibility with dBASE IV. In dBASE for Windows, use DEFINE, OPEN FORM, and READMODAL( ) to create and activate menus associated with forms.

Syntax

DEFINE PAD <pad name>
OF <menu name>
PROMPT <prompt expC>
[AT <row>,<col>]
[MESSAGE <message expC>]
[SKIP [FOR <condition expL>]]

OF <menu name>

Identifies the menu in which the pad prompt is displayed.

PROMPT <prompt expC>

Defines a prompt for the menu pad.

AT <row>,<col>

Specifies the position of the pad prompt's upper left corner.

MESSAGE <message expC>

Defines a message that appears in the status bar.

SKIP [FOR <condition expL>]

Makes the menu pad unavailable for selection. FOR <condition exp L> makes it unavailable only when <condition expL> evaluates to true.

Description

DEFINE PAD adds a pad prompt to a dBASE IV menu bar.

When you display and enable the menu, dBASE IV highlights an individual prompt. You can move the cursor from one prompt to another by clicking with the mouse or by pressing an arrow key.


DEFINE PAD Example

The following example uses DEFINE PAD to create selection options for the Main bar menu. On selection of each pad the program branches to a procedure that carries out a more specific task:

SET TALK OFF
CLEAR
DEFINE MENU Main
DEFINE PAD Add OF MAIN PROMPT "Add Records";
    AT 0,3 MESSAGE "Add new records"
DEFINE PAD Search OF MAIN PROMPT "Search File";
    AT 0,16 MESSAGE "Search for record"
DEFINE PAD Print OF MAIN PROMPT "Print";
    AT 0,29 MESSAGE "Print a report"
DEFINE PAD Exit OF MAIN PROMPT "Quit";
    AT 0,49 MESSAGE "Leave the program"

ON SELECTION PAD Add OF Main DO AddRec
ON SELECTION PAD Search OF Main DO SeekRec
ON SELECTION PAD Print OF Main DO Prt_Rpt
ON SELECTION PAD Exit OF Main DO ExitMain
ACTIVATE MENU MAIN

PROCEDURE ExitMain
DEACTIVATE MENU          && Clears menu from screen
CLEAR MENUS              && Clears menu from memory
RETURN

PROCEDURE AddRec         && Demo purposes only
WAIT "Add new records..."
CLEAR
RETURN

PROCEDURE SeekRec        && Demo purposes only
WAIT "Search for record..."
CLEAR
RETURN

PROCEDURE Prt_Rpt        && Demo purposes only
WAIT "Print a report..."
CLEAR
RETURN


Portability

Not supported in dBASE III PLUS. The SKIP option is not supported in dBASE IV.


See Also

ACTIVATE MENU

CLEAR MENUS

DEACTIVATE MENU

DEFINE

OPEN FORM

READMODAL( )

RELEASE MENUS


DEFINE POPUP

See Also	Example	Portability	dBASE IV Menus

Creates a dBASE IV popup menu and stores the definition in memory. This command is supported primarily for compatibility with dBASE IV. In dBASE for Windows, use DEFINE, OPEN FORM, and READMODAL( ) to create and activate menus associated with forms.

Syntax

DEFINE POPUP <pop-up name>
FROM <row>,<col> [TO <row>,<col>]
[PROMPT
ARRAY <array name> |
FIELD <field> |
FILES [LIKE <filename skeleton>] |
STRUCTURE]

[MESSAGE <expC>]

FROM <row>, <col> TO <row>, <col>

Specifies the initial location and size of the pop-up menu within its parent window. FROM and TO specify the upper left and lower right coordinates of the pop-up menu, respectively.

PROMPT ARRAY <array name> | FIELD <field> | FILES [LIKE <filename skeleton>] |
STRUCTURE

Determines which items appear as prompts in the pop-up menu.

PROMPT ARRAY <array name> causes the pop-up menu to display the value of each element in the specified array.

PROMPT FIELD <field> causes the pop-up menu to display the contents of the specified field in each record of a .DBF file that is open in the current work area. <field> cannot be a memo field.

PROMPT FILES causes the pop-up menu to display the parent directory, subdirectories of the current directory, drive specifiers, and every file name in the current directory. PROMPT FILES LIKE <filename skeleton> causes the pop-up menu to display the parent directory, subdirectories, drive specifiers, and every file name that fits the skeleton. The skeleton may include a path.

PROMPT STRUCTURE causes the pop-up menu to display the name of each field in the .DBF file that is open in the current work area.

MESSAGE <expC>

Defines a message that appears in the Status Bar.

Description

DEFINE POPUP creates a dBASE IV pop-up menu, a vertically-arranged list of options called bars which are represented by prompts.


DEFINE POPUP Example

The following example creates a pop-up menu with the seven days of the week as bar prompts. Back and Start variables cause the pop-up menu to list days starting with Sunday:

SET TALK OFF
CLEAR
Back=DOW(DATE())-1
Start=DATE()-Back
DEFINE POPUP Pop1 FROM 2,2;
    MESSAGE "Press Esc to Exit"
FOR i = 0 TO 6
    DEFINE BAR i + 1 OF Pop1 PROMPT CDOW(Start + i)
NEXT
ON SELECTION POPUP Pop1 DEACTIVATE POPUP
ACTIVATE POPUP Pop1
CLEAR
? "You picked " + PROMPT()
SET TALK ON


Portability

Not supported in dBASE III PLUS. The PROMPT ARRAY is not supported in dBASE IV.


See Also

ACTIVATE POPUP

DEFINE

OPEN FORM

READMODAL( )


DEFINE WINDOW

See Also	Example	Portability	dBASE IV Windows

Creates a dBASE IV-style window, a rectangular area in which menus and input areas can be displayed and enabled. This command is supported primarily for compatibility with dBASE IV. In dBASE for Windows, use DEFINE to create forms, which are used instead of dBASE IV windows.

Syntax

DEFINE WINDOW <window name>
FROM <row1>, <col1> TO <row2>, <col2>
[COLOR 	<standard text> | <enhanced text> | <frame> ]
[DOUBLE | NONE | PANEL | <border definition list>]

<window name>

The name of the window you want to create.

FROM <row1>, <col1> TO <row2>, <col2>

Specifies the initial location and size of the window within its parent window. FROM and TO specify the upper left and lower right coordinates of the window, respectively.

COLOR <standard text> | <enhanced text> | <frame>

Defines the window color attributes.

<standard text>	Color attributes of command messages and screen output. For example, the output of the ? and @...SAY commands appear in standard text.
<enhanced text>	Color attributes of enhanced text areas like @...GET fields.
<frame>	Color attributes of the window frame.
For more information about color settings, see SET COLOR TO and SET COLOR OF.

DOUBLE | NONE | PANEL | <t>,<b>,<l>,<r>,<tl>,<tr>,<bl>,<br>

Defines the window border.

DOUBLE	Double-line border
NONE	No border
PANEL	Solid border: sides are one column wide, top and bottom are one row thick
<border definition list>	Custom border definition attributes
For more information about borders, see SET BORDER.

Description

Use DEFINE WINDOW to create a dBASE IV-style window. To open the window, use ACTIVATE WINDOW. To store a window opened with ACTIVATE WINDOW and restore the definitions later, use SAVE WINDOW and RESTORE WINDOW.

The dBASE IV window displays in the results pane of the Command window. If necessary, use SET DISPLAY to make the results pane of the Command window correspond to the specified DOS display mode.

dBASE for Windows also lets you create forms. Forms are usually preferred over dBASE IV-style windows, since only forms can display and enable Windows objects like pushbuttons, check boxes, and entry fields. In contrast, dBASE IV windows can contain only dBASE IV-style menus and dBASE IV input and output commands like @...SAY or @...GET.

Create forms with DEFINE FORM and open them with OPEN FORM or READMODAL( ), just as you create dBASE IV-style windows with DEFINE WINDOW and open them with ACTIVATE WINDOW.


DEFINE WINDOW Example

The following example uses DEFINE WINDOW to create a window in the lower center of the screen with a double-line border of the specified colors:

CLEAR
DEFINE WINDOW A FROM 5,15 TO 20,60;
COLOR W+/B,R+/RB,G+/R DOUBLE
ACTIVATE WINDOW A
?
?
?
?
? SPACE(15)+"This is a test"
? SPACE(2)+"which includes color and border options"
?
WAIT
DEACTIVATE WINDOW A
CLEAR WINDOWS
RETURN


Portability

Not supported in dBASE III PLUS.


See Also

ACTIVATE WINDOW

DEFINE

OPEN FORM

READMODAL( )

RESTORE WINDOW

SAVE WINDOW

WINDOW( )


DELETE

See Also	Example	Fields and Records

For dBASE tables, marks records for deletion. When accessing Paradox or SQL tables, DELETE removes records from the table.

Syntax

DELETE
[<scope>]
[FOR <condition 1>]
[WHILE <condition 2>]

<scope>

The number of records to delete. RECORD <n> identifies a single record by its record number. NEXT <n> identifies n records, beginning with the current record. ALL specifies all records. REST specifies all records from the current record to the end of the file.

FOR <condition 1>
WHILE <condition 2>

Determines which records are affected by DELETE. FOR restricts DELETE to records that meet <condition 1>. WHILE starts processing with the current record and continues with each subsequent record as long as <condition 2> is true.

Description

When you use DELETE to mark records for deletion in a dBASE table, dBASE for Windows does not actually remove them from the table. It removes records marked for deletion when you issue PACK. DELETE with no options marks only the current record. When using a Paradox or SQL table, the DELETE command removes records from the table immediately (similar to issuing a PACK command with a dBASE table).

The mark that appears next to deleted records in a list or display is an asterisk.

To work with a table as if you have issued PACK, but without deleting marked records irrevocably, turn SET DELETED ON (the default). To undelete records, issue the RECALL command. However, use ZAP to remove all records.


DELETE Example

The following example uses DELETE to mark all records with StartBal less than $750 and SET DELETED ON to exclude those marked records from the subsequent BROWSE:

USE Clients
DELETE FOR StartBal < 750
SET DELETED ON
GO TOP
BROWSE FIELDS Company, City, State_Prov, Zip_P_Code,;
   StartBal NOMODIFY NOAPPEND NODELETE
RECALL ALL                 && Removes deletion marks
CLOSE ALL

The following example uses DELETE to mark five randomly selected contest winners and list them to the screen. You can also use LABEL FORM in a similar way to print labels:

SET TALK OFF
SET DELETED OFF
USE Company
RECALL ALL
SET DECIMALS TO 0
Cnt=1
DO WHILE Cnt<=5
   STORE (INT(RAND()*RECCOUNT())+1) TO Mark
   GOTO Mark
   IF .NOT. DELETED()
       DELETE
       Cnt=Cnt+1
   ENDIF
ENDDO
SCAN FOR DELETED()
  ? Company
ENDSCAN

The same concept applies if you want to create a new table from these randomly selected records:

SET SAFETY OFF
COPY TO Winners FOR DELETED()
RECALL ALL
USE Winners
BROWSE


See Also

PACK

RECALL

SET DELETED

ZAP


DELETE FILE

See Also	Example	Portability	Disk and File Utilities

Removes a file from a disk.

Syntax

DELETE FILE <filename> | ? | <filename skeleton>

<filename> | ? | <filename skeleton>

Identifies the file to remove. ? and <filename skeleton> display a dialog box from which you can select a file.

If you specify a file without including its path, dBASE looks for the file in the current directory, then in the path you specify with SET PATH. If you specify a file without including its extension, dBASE does not assume an extension.

Description

DELETE FILE and ERASE are equivalent commands. See ERASE for more information.


DELETE FILE Example

The following examples use DELETE FILE:

DELETE FILE Temp.prg
DELETE FILE ?
* Displays the open source dialog box


Portability

Not supported in dBASE III PLUS, but ERASE is. The <filename skeleton> argument is not supported in dBASE IV.


See Also

ERASE

RENAME

SET PATH


DELETE TABLE

See Also	Example	Portability	Table Basics

Deletes a specified table.

Syntax

DELETE TABLE <table name> | ? | <filename skeleton>
[[TYPE] PARADOX | DBASE]

<table name> | ? | <filename skeleton>

The name of the table that you want to delete. DELETE TABLE ? and DELETE <filename skeleton> display a dialog box, in which you can select the table you want to delete.

You can also delete a table in a database (defined using the IDAPI Configuration Utility) by specifying the database as a prefix (enclosed in colons) to the name of the table, that is, :database name:table name. If the database is not already open, dBASE for Windows displays a dialog box in which you specify the parameters, such as a login name and password, necessary to establish a connection to that database.

[TYPE] PARADOX | DBASE

Specifies the type of table to delete, which can include either Paradox or dBASE tables.

Description

Use the DELETE TABLE command to delete tables and associated .NDX and .MDX index files. Make sure the table is not in use before you attempt to delete it.


DELETE TABLE Example

The following example uses DELETE TABLE to delete two temporary tables after creating an adhoc view of Clients table:

SET SAFETY OFF
USE Clients
COPY TO NewNames STRUCTURE EXTENDED
USE NewNames EXCLUSIVE
BROWSE           && Delete unwanted fields;
                 or edit design from table
PACK             && Saves new structure
CREATE NewClnt FROM NewNames
APPEND FROM Clients FOR State_Prov = "CA"
GO TOP
BROWSE
CLOSE DATABASES
DELETE TABLE NewNames TYPE DBASE
DELETE TABLE NewClnt TYPE DBASE


Portability

Not supported in dBASE IV or dBASE III PLUS.


See Also

DELETE FILE

DELETE TAG

ERASE


DELETE TAG

See Also	Example	Portability	Table Organization

Deletes specified index tags from .MDX files. You can also use this command to delete individual index tags defined for Paradox and SQL tables.

Syntax

DELETE TAG <tag name 1>
[OF <filename 1> | ? | <filename skeleton 1>]
[, <tag name 2>
[OF <filename 2> | ? | <filename skeleton 2>] ...]

<tag name 1>, <tag name 2>, ... <tag name n>

The index tag names to delete from .MDX files.

OF <filename 1> | ? | <filename skeleton 1>

Specifies the .MDX file containing the tag name to delete. OF ? and OF <filename skeleton 1> display a dialog box, in which you select a multiple index file. If you specify a file without including its path, dBASE for Windows looks for the file in the current directory, then in the path you specify with SET PATH. If you specify a file without including an extension, dBASE for Windows assumes an .MDX extension. If you do not specify an index file, dBASE for Windows assumes the index tag you want to delete is in the index file with the same name as the current table.

Description

Use DELETE TAG to delete index tags from .MDX files for dBASE tables or secondary indexes on a Paradox table. dBASE for Windows allows a maximum of 47 index tags in a single .MDX file, so deleting unneeded tags frees slots for new tags as well as reducing the amount of disk space and memory that an .MDX file requires.

For dBASE tables, the .MDX file must be open when you delete the tags. If you delete all tags in an .MDX file, the .MDX file is also deleted. If you delete the production .MDX file by deleting all index tags, the table file header is updated to indicate there is no longer a production index associated with the table.

In a multiuser environment, the table associated with the indexes you want to delete must be opened in exclusive mode. When accessing a Paradox table, specifying DELETE TAG without an argument deletes the primary index.


DELETE TAG Example

The following example creates a temporary index, uses it in a BROWSE command then removes it with DELETE TAG:

USE Company EXCLUSIVE
INDEX ON Sic_code TAG Sic_code
BROWSE FIELDS Sic_code, Company
* now the Sic_code index is not needed, delete it
DELETE TAG Sic_code


Portability

Not supported in dBASE III PLUS. Also, the <filename skeleton> option is not available in dBASE IV.


See Also

CLOSE INDEXES

COPY INDEXES

SET INDEX

TAG( )


DELETED( )

See Also	Example	Fields and Records

Indicates if records in the current or a specified table have been marked for deletion.

Syntax

DELETED( [<alias>] )

<alias>

A work area number (1 through 225), letter (A through J), or alias name. The work area letter or alias name must be enclosed in quotes.

Description

DELETED( ) returns .T. if the current record in the specified work area is marked for deletion; otherwise, DELETED( ) returns .F.. If you do not specify a work area, the current work area is assumed.

If no table is open in the current or specified work area, DELETED( ) also returns .F..


DELETED( ) Example

The following example uses DELETE to mark a subset of the total table. DELETED( ) is then used to perform a BROWSE that displays only that subset of records and to create another table (Cal) that contains only California records:

SET TALK OFF
SET SAFETY OFF
USE Clients
SET DELETED OFF
DELETE FOR State_Prov = "CA"
GO TOP
BROWSE FIELDS Company, City, State_Prov FOR DELETED()
COPY TO Cal FOR DELETED()
USE Cal
BROWSE
CLOSE ALL

The next example uses DELETED( ) in an INDEX statement to place all records marked as deleted at the beginning of the ordered table:

USE Clients EXCLUSIVE
DELETE FOR State_Prov = "CA"
INDEX ON IIF(DELETED(),"AA"+State_Prov,"Z" ;
  +State_Prov)TAG DelState
BROWSE FIELDS Company, City, State_Prov
* California records would appear at the top; other
* states alphabetically below.
RECALL ALL
CLOSE ALL


See Also

DELETE

PACK

RECALL

SET DELETED


DESCENDING( )

See Also	Example	Portability	Table Organization

Indicates if a specified index was created with the DESCENDING keyword.

Syntax

DESCENDING( [<.mdx filename expC>,] <index position expN> [, <alias>] )

<.mdx filename expC>

Specifies a multiple index file that contains the index tag you want to check.

<index position expN>

Selects an index tag by its position in an .MDX file or the position of an index tag in the list of open indexes in the current or specified work area.

<alias>

A work area number (1 through 225), letter (A through J), or alias name. The work area letter or alias name must be enclosed in quotes.

Description

The DESCENDING( ) function returns .T. if the index tag specified by the <index position expN> parameter was created with the DESCENDING keyword; otherwise, it returns .F.. The optional alias parameter specifies the work area in which you want to check an index tag. If you do not specify a work area, the current work area is assumed.

If you do not specify an .MDX file name, the DESCENDING( ) function checks for the index tag in all open .MDX files. If a production .MDX file and other .MDX files are open, the DESCENDING( ) function checks for the DESCENDING keyword in the production .MDX file only.

If you do not specify an index tag, DESCENDING( ) determines if the master index tag was created with the DESCENDING keyword. DESCENDING( ) returns .F. if the index is an .NDX file or there is no master index.

If the specified .MDX file or index tag does not exist, the DESCENDING( ) function returns an error message.


DESCENDING( ) Example

The following example uses DESCENDING( ) to determine if the key for a specified index was created using a descending index:

USE Company EXCLUSIVE
INDEX ON Company TAG Company
SET ORDER TO TAG Company
? TAG(), "Descending = ", DESCENDING()

INDEX ON Company TAG DescCo DESCENDING
? TAG(), "Descending = ", DESCENDING()


Portability

Not supported in dBASE III PLUS.


See Also

FOR( )

INDEX

KEY( )

MDX( )

ORDER( )

TAGCOUNT( )

TAGNO( )

UNIQUE( )


DIFFERENCE( )

See Also	Example	Portability	String Data

Returns a number that represents the phonetic difference between two strings.

Syntax

DIFFERENCE(<expC1> | <memo field 1>, <expC2> | <memo field 2>)

<expC1> | <memo field 1>

The first character expression or memo field to evaluate the SOUNDEX( ) of and compare to the second value.

<expC2> | <memo field 2>

The second character expression or memo field to evaluate the SOUNDEX( ) of and compare to the first value.

Description

SOUNDEX( ) returns a four-character code that represents the phonetic value of a character expression or memo field. DIFFERENCE( ) compares the SOUNDEX( ) codes of two character expressions or memo fields, and returns an integer from 0 to 4 that expresses the difference between the codes.

A returned value of 0 indicates the greatest difference in SOUNDEX( ) codes--the two expressions have no SOUNDEX( ) characters in common. A returned value of 4 indicates the least difference--the two expressions have all four SOUNDEX( ) characters in common. However, using DIFFERENCE( ) on short strings can produce unexpected results, as shown in the following example.

? SOUNDEX("Mom")	   && returns M500
? SOUNDEX("Dad")   && returns D300
? DIFFERENCE("Mom","Dad") && returns 2

To compare the character-by-character similarity between two strings rather than the phonetic similarity, use LIKE( ).


DIFFERENCE( ) Example

The following example uses DIFFERENCE( ) to determine how closely two text strings might match phonetically:

? SOUNDEX("Apples")                 && Returns A142
? SOUNDEX("Lapels")                 && Returns L142
? DIFFERENCE("Apples","Lapels")     && Returns 3
? DIFFERENCE("Katherine","Kathryn") && Returns 4
? DIFFERENCE("Daniel","Damien")     && Returns 3
? DIFFERENCE("Money","Monet")       && Returns 3
? DIFFERENCE("dBASE","C")           && Returns 1
? DIFFERENCE("Motor Oil","Cookies") && Returns 1


Portability

Not supported in dBASE III PLUS. The memo field arguments are not supported in dBASE IV.


See Also

LIKE( )

SOUNDEX( )


DIR/DIRECTORY

See Also	Example	Portability	Disk and File Utilities

Performs a directory listing.

Syntax

DIR (or DIRECTORY)
[[ON]<drive>:]
[[LIKE] [<path>\] [<filename> | <filename skeleton>]]

[ON] <drive>:

Specifies the drive from which DIR performs its directory listing. A colon (:) is optional after ON <drive>; however, if you use <drive> without ON, you must follow it with a colon.

ON is optional and has no effect; it is included for backward compatibility with dBASE IV.

[LIKE] [<path>\] <filename> | <filename skeleton>

Specifies a path and/or file specification to be used by DIR. Use the <path> option to perform a directory listing in a directory other than the directory that is current on the default drive or on <drive>. Use the <filename> option to list a single file. Use the <filename skeleton> option to list multiple files.

LIKE is optional and has no effect; it is included for backward compatibility with dBASE IV.

Description

DIR (or DIRECTORY) is a utility command that lets you perform a directory listing. The information provided on each file includes its name, its size in bytes, and the date of its last update. DIR also shows the total number of bytes used by the listed files, the number of bytes left on disk, and the total disk space.

DIR with no arguments displays information only on files with .DBF extensions in the current directory; in addition to the information normally displayed, DIR displays the number of records in each database.

You can use the wildcard characters * and ? to identify multiple files with similar names. DIR with no arguments, DIR *.DBF, and DIR * are all equivalent commands. DIR N* displays all .DBF files beginning with N. DIR N???? displays all .DBF files that have five-letter names beginning with N. DIR N*.* displays all files beginning with N, regardless of extension. DIR N*. displays all files beginning with N that have no file-name extension.

If you want to specify a drive and path or file name information without using ON or LIKE, you must follow <drive> with a colon. DIR ON C LIKE \*.BAT and DIR C:\*.BAT are equivalent commands.

A path must end with a backslash (\), as shown in the following example:

* the following returns the .dbf file names
DIR C:\DBASEWIN\SAMPLES\
* the following returns "0 bytes in 0 files"
DIR C:\DBASEWIN\SAMPLES

If you have not used ON KEY or SET FUNCTION to reassign the F4 key, pressing F4 is a quick way to execute DIR.

The output presented by DIR is affected by the settings made by SET DATABASE and SET DBTYPE.


DIR/DIRECTORY Example

The following examples use DIR:

DIR  && Shows all tables in current subdirectory
DIR ON B: && Shows all tables on B drive
DIR A:    && Shows all tables on A drive
DIR *.prg && Shows all program files
DIR LIKE *.* ON C:\DBASE
* Shows all files on C:\DBASE


Portability

The ON and LIKE options are not supported in dBASE III PLUS.


See Also

DISPLAY FILES

FILE( )

LIST FILES

FSIZE( )

ON KEY

SET DATABASE

SET DEFAULT

SET DBTYPE

SET FUNCTION


DISKSPACE( )

See Also	Example	Portability	Disk and File Utilities

Returns the number of bytes available on the default or specified drive's disk.

Syntax

DISKSPACE([<drive expN>])

<drive expN>

A drive number from 1 to 26. For example, the numbers 1 and 2 correspond to drives A and B, respectively.

Without <drive expN> or if <drive expN> is 0, DISKSPACE( ) returns the number of bytes available on the default drive.

If <drive expN> is less than 0 or greater than 26, DISKSPACE( ) returns the number of bytes available on the drive from which you load dBASE.

Description

Use DISKSPACE( ) to determine how much space is left on a disk.

DISKSPACE( ) can be used in conjunction with RECCOUNT( ) and RECSIZE( ) in application programs that automatically back up database files. This function lets you know if there is sufficient space on the disk for the backup file.


DISKSPACE( ) Example

The following examples use DISKSPACE( ):

? DISKSPACE()   && current drive
? DISKSPACE(2)  && drive B
? DISKSPACE(-1) && dBASE


Portability

The optional argument <drive expN> is not supported in dBASE IV or dBASE III PLUS.


See Also

HOME( )

RECCOUNT( )

RECSIZE( )

SET DEFAULT


DISPLAY

See Also	Example	Table Organization

Displays records from the current table in the result pane of the Command window.

Syntax

DISPLAY
[<scope>]
[FOR <condition 1>]
[WHILE <condition 2>]
[[FIELDS] <exp list>]
[OFF]
[TO FILE <filename> | ? | <filename skeleton>] | [TO PRINTER]

<scope>

The number of records to DISPLAY. RECORD <n> identifies a single record by its record number. NEXT <n> identifies n records, beginning with the current record. ALL specifies all records. REST specifies all records from the current record to the end of the file.

FOR <condition 1>
WHILE <condition 2>

Determines which records appear with DISPLAY. FOR restricts DISPLAY to records that meet <condition 1>, starting at the first record of the table or scope and continuing until the end of the table or scope. WHILE starts processing with the current record and continues with each subsequent record as long as <condition 2> is true.

FIELDS <exp list>

Field names or expressions whose contents (values) you want to display; the names of the fields in the list are separated by commas. If you do not list any, dBASE for Windows displays the values of all fields for the current record or the records you specify. The FIELDS keyword is included for readability only; it has no affect on the operation of the command.

OFF

Suppresses display of the record number. Record numbers are not displayed for Paradox or SQL tables.

[TO FILE <filename> | ? | <filename skeleton> ] | [TO PRINTER]

Sends output to a file or to a printer. TO FILE directs output to the text file <filename>, as well as to the Command window (unless SET CONSOLE is OFF). By default, dBASE for Windows assigns a .TXT extension to <filename> and saves the file in the current directory. The ? and <filename skeleton> options display a dialog box, in which you specify the name of the target file and the directory to save it in. TO PRINTER directs output to the printer, as well as to the results pane of the Command window.

Description

Use DISPLAY to view one or more records of the current table in the results pane of the Command window. Issuing DISPLAY without any arguments displays only the current record whereas LIST displays all records. If SET HEADINGS is OFF, dBASE for Windows does not display field names when you issue DISPLAY.

DISPLAY pauses when the results pane is full and displays a dialog box prompting you to display additional information. Scroll the output up or down by doing any of the following:

Press Enter or PgDn to scroll down to the next window.

Click near the bottom of the vertical scroll bar to scroll down to the next window.

Press PgUp to scroll up to the next window.

Click near the top of the vertical scroll bar to scroll up to the next window.

Press the Up or Down arrows to scroll up or down, respectively, one line.

Click the vertical scroll bar up or down arrows to scroll up or down, respectively, one line.

Press Spacebar to scroll up one line.

Type <expN> and press Enter to scroll up the specified number of lines.

DISPLAY is similar to LIST, except that LIST does not pause at the end of the first window of information but rather lists the information continuously, halting at the last window.

If the information output to the results pane is more than the dBASE buffer can contain, you might not be able to scroll back up to information you have scrolled down through. Use the TO FILE or TO PRINTER options to save all information to a file or as printer output.


DISPLAY Example

The following example uses DISPLAY to display selected data from the Clients table:

USE Clients
DISPLAY
* display all fields in the current record

DISPLAY ALL
* display all fields in all records. On completion
* record counter is positioned at end of table

GOTO 2      && go to 2nd record in the table
DISPLAY REST FIELDS Company, Contact
* display company and contact fields in rest of table

SET FIELDS TO Company, Contact, Phone
DISPLAY all
* combine the set fields and display commands
* to display company, contact and phone fields
* in all records


See Also

DISPLAY STRUCTURE

LIST

SET HEADINGS

SET FIELDS


DISPLAY COVERAGE

See Also	Example	Portability	Error Handling and Debugging

Displays the contents of a coverage file (.COV) in the results pane of the Command window.

Syntax

DISPLAY COVERAGE
<.COV filename> | ? | <filename skeleton>
[ALL]
[SUMMARY]
[TO FILE <filename> | ? | <filename skeleton>] | [TO PRINTER]

<.COV filename | ? | <filename skeleton>

The coverage file that dBASE creates or modifies when SET COVERAGE is ON, and you call a program, or call a procedure or UDF in a procedure file. The ? and <filename skeleton> options display a dialog box from which you can select a coverage file. If you specify a file without including its path, dBASE looks for the file in the current directory, then in the path you specify with SET PATH. If you specify a file without including its extension, dBASE assumes .COV.

ALL

Displays in the results pane of the Command window the following information:

The contents of the coverage file for <filename 1>'s program and of the coverage files for each executed program or procedure file called by <filename 1>'s program

The total number of logical blocks entered and exited in all the program files combined

The percentage of logical blocks entered and exited in all the program files combined

SUMMARY

If ALL is not specified, displays the following information about <filename 1>'s program. If ALL is specified, displays the following information about <filename 1>'s program and about all programs called by <filename 1>'s program:

The logical blocks not entered and exited

The total number of logical blocks entered and exited

The percentage of logical blocks entered and exited

TO FILE <filename 2> | ? | <filename skeleton>

Directs output to <filename 2> and to the results pane of the Command window. By default, dBASE assigns a .TXT extension to <filename 2> and saves the file in the current directory. The ? and <filename skeleton> options display a dialog box in which you specify the name of the target file and the directory to save it in.

TO PRINTER

Directs output to the printer and to the results pane of the Command window.

Description

A coverage file contains the results of the coverage analysis of a program, procedure, or UDF. You cause dBASE to analyze a program, procedure, or UDF and store the results of the analysis in a coverage file with the SET COVERAGE ON command. You can issue DISPLAY COVERAGE in a program file or in the Command window.

DISPLAY COVERAGE displays the contents of <filename 1> and the results of percentage calculations using <filename 1>'s contents. The output appears in the results pane of the Command window, starting at the beginning of the main program's coverage file. DISPLAY COVERAGE displays the first window of output and pauses when the window is full. See the description of DISPLAY for information about how to navigate in the window.

The amount of memory available determines the size of the results pane of the Command window buffer. If the information output is more than the buffer can contain, you might not be able to scroll back up to information that has already been displayed. In that case, use either the TO FILE or TO PRINTER option to send all information to a file or printer.

DISPLAY COVERAGE is the same as LIST COVERAGE, except that LIST COVERAGE does not pause with the first window of information but rather continuously lists the information, halting at the last window. As with DISPLAY COVERAGE output, you can scroll LIST COVERAGE output.


DISPLAY COVERAGE Example

See SET COVERAGE for an example of using DISPLAY COVERAGE.


Portability

Not supported in dBASE IV or dBASE III PLUS.


See Also

#pragma

DISPLAY

LIST

SET COVERAGE


DISPLAY FILES

See Also	Example	Portability	Disk and File Utilities

Displays information about files on disk in the results pane of the Command window.

Syntax

DISPLAY FILES
[[LIKE] <filename 1> | <filename skeleton>]
[ON <drive>]
[TO FILE <filename 2> | ? | <filename skeleton>] | [TO PRINTER]

[LIKE] <filename 1> | <filename skeleton>

The file you want to display information on. DISPLAY FILES <filename skeleton> displays the names of all files matching a template that uses the wildcard characters ? and *. If you specify a file, and the file is not in the default directory or in the path you specify with SET PATH, then <filename> must include the drive and path. LIKE has no effect on the operation of the command; include it for readability only.

ON <drive>

The disk drive containing the files you want to display information on. By default, dBASE looks for the file or files you specify in the current drive and directory.

TO FILE <filename 2> | ? | <filename skeleton>

Directs output to the text file <filename 2> and to the results pane of the Command window. By default, dBASE assigns a .TXT extension to <filename 2> and saves the file in the current directory. The ? and <filename skeleton> options display a dialog box in which you specify the name of the target file and the directory to save it in.

TO PRINTER

Directs output to the printer and to the results pane of the Command window.

Description

DISPLAY FILES is a utility command that lets you perform a directory listing. The information provided on each file includes its name, its size in bytes, and the date of its last update. DISPLAY FILES also shows the total number of bytes used by the listed files, the number of bytes left on disk, and the total disk space.

DISPLAY FILES with no options lists only table files (.DBF) in the current default directory. The number of records is displayed for each table, along with its size in bytes, and the date of its last update.

You can use the wildcard characters * and ? to identify multiple files with similar names. For example, although DISPLAY FILES * is equivalent to DISPLAY FILES with no argument (only .DBF files are displayed), DISPLAY FILES N* displays all .DBF files beginning with N. DISPLAY FILES N*.* displays all files beginning with N, regardless of extension. DISPLAY FILES N????.DBF displays all .DBF files that have five-letter names beginning with N.

DISPLAY FILES pauses at the start of the output when the window is full. See the description of DISPLAY for information about how to navigate in the window.

If the information output is more than dBASE's buffer can contain, you might not be able to scroll back up to information you have scrolled down through. Use either the TO FILE or TO PRINTER option to send all information to a file or printer.

DISPLAY FILES is the same as LIST FILES, except that LIST FILES does not pause with the first window of information but rather continuously lists the information, halting at the last window. As with DISPLAY FILES output, you can scroll LIST FILES output.

The SET DATABASE and SET DBTYPE settings affect DISPLAY FILES and LIST FILES output.


DISPLAY FILES Example

The following examples use DISPLAY FILES:

DISPLAY FILES
* Shows all tables in current subdirectory
DISPLAY FILES ON B: && Shows all tables on B drive
DISPLAY FILES A:    && Shows all tables on A drive
DISPLAY FILES *.prg && Shows all program files
DISPLAY FILES LIKE *.* ON C:\DBASE
* Shows all files on C:\DBASE


Portability

Not supported in dBASE III PLUS. The ON <drive> and TO FILE ? options are not supported in dBASE IV.

In dBASE IV, if you use TO FILE <filename 2> and do not include an extension, dBASE IV adds a .PRT extension. dBASE for Windows adds a .TXT extension instead.


See Also

DIR

DISPLAY

FILE( )

LIST

SET DATABASE

SET DBTYPE

SET DEFAULT


DISPLAY MEMORY

See Also	Portability	Environment

Displays information about memory variables in the results pane of the Command window.

Syntax

DISPLAY MEMORY
[TO FILE <filename> | ? | <filename skeleton>] | [TO PRINTER]

TO FILE <filename> | ? | <filename skeleton>

Directs output to the text file <filename>, also called the target file, and to the results pane of the Command window. By default, dBASE assigns a .TXT extension to <filename> and saves the file in the current directory. The ? and <filename skeleton> options display a dialog box in which you specify the name of the target file and the directory to save it in.

TO PRINTER

Directs output to the printer and to the results pane of the Command window.

Description

Use DISPLAY MEMORY to display the contents and size of a memory variable list. If you haven't used ON KEY or SET FUNCTION to reassign the F7 key, pressing F7 is a quick way to execute DISPLAY MEMORY.

DISPLAY MEMORY displays information about both user-defined and system memory variables. The following information on user-defined memory variables is displayed.

Name

Scope (public, private, local, static or hidden)

Data type

Value

Number of active memory variables

Number of memory variables still available for use

Number of bytes of memory used by character variables

Number of bytes of memory still available for user character variables

Name of the program that initialized private memory variables

The following information on system memory variables is displayed.

Name

Scope (public, private, or hidden)

Data type

Current value

DISPLAY MEMORY displays the first window of output and pauses when the window is full. See the description of DISPLAY for information about how to navigate in the window.

The amount of memory available determines the size of the results pane of the Command window buffer. If the information output is more than the buffer can contain, you might not be able to scroll back up to information that has already been displayed. In that case, use either the TO FILE or TO PRINTER option to send all information to a file or printer.

If SET SAFETY is ON and a file exists with the same name as the target file, dBASE displays a dialog box asking if you want to overwrite the file. If SET SAFETY is OFF, any existing file with the same name is overwritten without warning.

DISPLAY MEMORY is the same as LIST MEMORY, except that LIST MEMORY displays the information without pauses, halting at the last window. As with DISPLAY MEMORY output, you can scroll LIST MEMORY output.


Portability

Only a TO PRINT option is supported in dBASE III PLUS. The ? and <filename skeleton> options are not supported in dBASE IV. If you don't specify a file-name extension with the TO FILE <filename> option, dBASE IV adds .PRT instead of .TXT.


See Also

LIST

LOCAL

PRIVATE

PUBLIC

SET FUNCTION

SET SAFETY

ON KEY

STATIC

STORE


DISPLAY STATUS

See Also	Portability	Environment

Displays information about the current dBASE environment in the results pane of the Command window.

Syntax

DISPLAY STATUS
[TO FILE <filename> | ? | <filename skeleton>] | [TO PRINTER]

TO FILE <filename> | ? | <filename skeleton>

Directs output to the text file <filename>, also called the target file, and to the Results pane of the Command window. By default, dBASE assigns a .TXT extension to <filename> and saves the file in the current directory. The ? and <filename skeleton> options display a dialog box in which you specify the name of the target file and the directory to save it in.

TO PRINTER

Directs output to the printer and to the Results pane of the Command window.

Description

Use DISPLAY STATUS to identify open tables and index files and to check the status of the SET commands. DISPLAY STATUS shows information related to the current session only.

If you haven't used ON KEY, SET, or SET FUNCTION to reassign the F6 key, pressing F6 is a quick way to execute DISPLAY STATUS.

DISPLAY STATUS displays the following information:

Name and alias of open tables in each work area

Names of all open memo files in each work area

Name of any open format file in each work area

Names of all open indexes and their index key expressions in each work area

SET ORDER setting in each work area

Master index, if any, in each work area

Database relations in each work area

Filter conditions in each work area

SET PATH file search path

SET DEFAULT drive setting

Current work area

SET PRINTER or SET DEVICE setting

DBTYPE setting

Numeric settings for SET MARGIN, SET DECIMALS, SET MEMOWIDTH, SET HISTORY, SET TYPEAHEAD, SET ODOMETER, SET REFRESH, and SET REPROCESS

ON KEY, ON ESCAPE, and ON ERROR settings

SET ON/OFF command settings

Programmable function key and SET FUNCTION settings

DISPLAY STATUS displays the first window of output and pauses when the window is full. See the description of DISPLAY for information about how to navigate in the window.

The amount of memory available determines the size of the Results pane of the Command window buffer. If the information output is more than the buffer can contain, you might not be able to scroll back up to information that has already been displayed. In that case, use either the TO FILE or TO PRINTER option to send all information to a file or printer.

If SET SAFETY is ON and a file exists with the same name as the target file, dBASE displays a dialog box asking if you want to overwrite the file. If SET SAFETY is OFF, any existing file with the same name is overwritten without warning.

DISPLAY STATUS is the same as LIST STATUS, except that LIST STATUS displays the information without pauses, halting at the last window. As with DISPLAY STATUS output, you can scroll LIST STATUS output.


Portability

Only a TO PRINT option is supported in dBASE III PLUS. The ? and <filename skeleton> options are not supported in dBASE IV. If you don't specify a file-name extension with the TO FILE <filename> option, dBASE IV adds .PRT instead of .TXT.


See Also

LIST

SET( )

SETTO( )

SET SAFETY


DISPLAY STRUCTURE

See Also	Example	Table Basics

Displays the field definitions of the specified table.

Syntax

DISPLAY STRUCTURE
[IN <alias>]
[TO FILE <filename> | ? | <filename skeleton>] | [TO PRINTER]

IN <alias>

Identifies the work area of the open table whose structure you want to display rather than that of the current table. You can enter a work area number (1 through 225), letter (A through J), or alias name. The work area letter or alias name must be enclosed in quotes.

[TO FILE <filename> | ? | <filename skeleton>] | [TO PRINTER]

Sends output to a file or to a printer. TO FILE directs output to the text file <filename>, as well as to the Command window. By default, dBASE for Windows assigns a .TXT extension to <filename> and saves the file in the current directory. The ? and <filename skeleton> options display a dialog box, in which you specify the name of the target file and the directory to save it in. TO PRINTER directs output to the printer, as well as to the results pane of the Command window.

Description

Use DISPLAY STRUCTURE to view the structure of the current or a specified table in the results pane of the Command window. DISPLAY STRUCTURE displays the following information about the current or specified table:

Name of the table

Type of table (Paradox, dBASE, or SQL)

Number of records

Date of last update

Fields

Field number

Field name (if SET FIELDS is ON, the greater-than symbol (>) appears next to each field specified with the SET FIELDS TO command)

Type

Length

Number of bytes per record (the sum of field lengths plus one additional byte reserved for storing the asterisk that marks a record for deletion)

Multiply the total number of bytes per record by the number of records in the table to estimate the size of a dBASE table (excluding the size of the table file header).

DISPLAY STRUCTURE pauses when the results pane of the Command window is full and displays a dialog box prompting you to display additional information. See the description of DISPLAY for information about how to navigate in the Command window.

If the information output to the results pane of the Command window is more than the dBASE for Windows buffer can hold, you might not be able to scroll back up to information you have scrolled down through. Use the TO FILE or TO PRINTER options to save all information to a file or as printer output. You can send output to either a file or printer, but not both at the same time.

DISPLAY STRUCTURE is similar to LIST STRUCTURE, except that LIST STRUCTURE does not pause when the Command window fills, but rather lists the information continuously.

Neither DISPLAY STRUCTURE nor LIST STRUCTURE permit modification of an existing table structure. To alter the structure, use MODIFY STRUCTURE.


DISPLAY STRUCTURE Example

The following example uses DISPLAY STRUCTURE and LIST STRUCTURE to display the structure of a table:

USE Clients
LIST STRUCTURE TO FILE Clients.TXT

The following text is saved in a text file named CLIENTS.TXT by the LIST STRUCTURE command:

Structure for table   : C:\DBASEWIN\SAMPLES\CLIENTS.DBF
Table type            : DBASE
Number of records     : 100
Last update           : 05/01/94
-----------------------------------------------------
Field  Field Name    Type       Length    Dec   Index

    1  CLIENT_ID     CHARACTER       5              N
    2  COMPANY       CHARACTER      35              N
    3  CONTACT       CHARACTER      20              N
    4  ADDRESS       CHARACTER      30              N
    5  CITY          CHARACTER      15              N
    6  STATE         CHARACTER       2              N
    7  ZIP           CHARACTER       5              N
    8  AREACODE      CHARACTER       3              N
    9  PHONE         CHARACTER       8              N
   10  EXTENSION     CHARACTER       5              N
   11  STARTBAL      NUMERIC         8      2       N
   12  BALDATE       DATE            8              N
   13  CUISINE       CHARACTER      15              N
   14  TYPE          NUMERIC         1              N
   15  NOTES         MEMO           10              N
-----------------------------------------------------
** Total **                        171


See Also

DISPLAY

LIST

MODIFY STRUCTURE

SET FIELDS


DMY( )

See Also	Example	Portability	Date and Time Data

Returns a specified date expression as a character string in DD MONTH YY or DD MONTH YYYY format.

Syntax

DMY(<expD>)

<expD>

The date expression to return as a character string in DD MONTH YY or DD MONTH YYYY format.

Description

DMY( ) returns a date in DD MONTH YY or DD MONTH YYYY format, where DD is the day number, MONTH is the full month name, and YY is the year number. If SET CENTURY is OFF (the default), DMY( ) returns the year as 2 digits. If SET CENTURY is ON, DMY( ) returns the year as 4 digits.

Enter <expD> in the current date format as determined by SET DATE, DBASEWIN.INI, or the International option of the Windows Control Panel (in that order). That is, SET DATE settings override those in DBASEWIN.INI, and settings in DBASEWIN.INI override those in the Windows Control Panel. Be sure <expD> matches the date format in use when your program runs.

If you pass an invalid date to DMY( ), it converts the date to a valid one and returns that date in DD MONTH YY or DD MONTH YYYY format. If you pass an empty or non-date expression delimited with braces ({ }) to DMY( ), it returns "0 Unknown 00" or "0 Unknown 0000". If you pass a non-date expression or an expression that is not delimited with braces to DMY( ), dBASE returns an error.


DMY( ) Example

The following example uses DMY( ) to display a date field value in the form day number, month spelled out and year as determined by SET CENTURY:

SET TALK OFF
USE Clients
Cnt=1
DO WHILE .NOT. EOF()
CLEAR
? CENTER("Client Database Report",80)
? CENTER("Run on " + CDOW(DATE()) + ;
      ", " + DMY(DATE()),80,"-")
?
? "Company" AT 2, "Phone" AT 40, ;
    "First Contact" AT 55
DO WHILE Cnt <= 10 .AND. .NOT. EOF()
  ? Company AT 2, Phone AT 40, CDOW(Baldate)+", ";
    +DMY(Baldate) AT 55
  SKIP
  Cnt=Cnt+1
ENDDO
Cnt=1
WAIT
ENDDO
CLOSE ALL


Portability

Not supported in dBASE III PLUS.


See Also

CDOW( )

CMONTH( )

DAY( )

DOW( )

MDY( )

MONTH( )

SET CENTURY

SET DATE

YEAR( )


DO

See Also	Example	Portability	Programs

Runs a program, procedure, or user-defined function (UDF).

Syntax

DO <filename> | ? | <filename skeleton> |
<procedure name> |
<UDF name>
[WITH <parameter list>]

<filename> | ? | <filename skeleton>

The program file to execute. The ? and <filename skeleton> options display a dialog box from which you can select a file. If you specify a file without including its path, dBASE looks for the file in the current directory, then in the search path in search order. See "Search path and order" later in this topic for more information.

If you specify a file without including its extension, dBASE assumes a .PRO extension (a compiled object file). If dBASE cannot find a .PRO file, it looks for a .PRG file (a source file), which, if found, it compiles. By default, dBASE creates the .PRO in the same directory as the .PRG, which might not be the current directory.

<procedure name> | <UDF name>

The procedure or UDF in an open program file to execute. The procedure or UDF must be in the program file containing the DO command that calls it, or in a separate open file on the search path. The search path is described later in this section.

WITH <parameter list>

Specifies memory variable values, field values, or any other valid expressions to pass as parameters to a program, procedure, or UDF. See the description of PROCEDURE for information on parameter passing.

Description

Use DO to run programs from the Command window or to run procedures or other programs from a program. If you enter DO in the Command window, control returns to the Command window when the program, procedure, or UDF ends. If you use DO in a program to execute another program, procedure, or UDF, control returns to the program line following the DO statement when the program, procedure, or UDF ends.

The limit on the number of nested DOs calls depends on the amount of available memory and the number of files you have open (a DO command might open a file). Avoid using DO recursively because you can quickly exceed the limit of nested DOs.

When dBASE encounters a DO statement in a program file, it looks in that file for a procedure or UDF of the specified name. If the current program file contains a procedure and a UDF with the same name, dBASE executes the first one declared. If dBASE does not find a PROCEDURE or FUNCTION definition of the specified name in the same program file, it looks for a program, procedure, or UDF of the specified name on the search path in search order.

Search path and order

If the name you specify with DO does not include a path or a file-name extension, it can be a program, procedure, UDF, or file name. To resolve the ambiguity, dBASE searches for the name in specific places (the search path) in a specific order (the search order) and runs the first program or subroutine of the specified name that it finds. The search path and order dBASE uses is as follows:

1.	The executing program's object file (.PRO)

2.	Other open object files (.PRO) in the call chain, in most recently opened order

3.	The file specified by SYSPROC = <filename> in DBASEWIN.INI

4.	Any files opened with SET PROCEDURE, SET PROCEDURE...ADDITIVE, or SET LIBRARY statements, in the order in which they were opened

5.	The object file (.PRO) with the specified name in the search path

6.	The program file (.PRG) with the specified name in the search path, which dBASE automatically compiles.


DO Example

The following example uses DO to run procedures:

DO Client_Rpt
DO SalesReport WITH "CA"
DO AddRecord WITH "Smith","John",25

PROC Client_Rpt
* ...
RETURN

PROC SalesReport
Parameters State
* ...
RETURN

PROC AddRecord
PARAMETERS Lastname, Firstname, Age
* ...
RETURN


Portability

Calling a UDF with DO is not supported in dBASE IV or dBASE III PLUS. The search path and search order of dBASE IV and dBASE III PLUS differ from that of dBASE for Windows. Both dBASE IV and dBASE III PLUS create compiled object files with .DBO extensions, and place them in the current directory, by default.


See Also

!

CLEAR PROGRAM

COMPILE

DOS

PROCEDURE

RETURN

RUN

RUN( )

SET DEVELOPMENT

SET ESCAPE

SET LIBRARY

SET PROCEDURE


DO...UNTIL

See Also	Example	Portability	Programs

Executes the statements between DO and UNTIL as long as a specified condition is false or until dBASE encounters an EXIT command.

Syntax

DO
<statements>
[LOOP]
[EXIT]
UNTIL <condition expL>

<statements>

Program lines consisting of any combination of commands, functions, user-defined functions (UDFs), and LOOP and EXIT options.

LOOP

Passes program control to the end of the DO...UNTIL loop and evaluates <condition expL> without executing the commands that follow LOOP and precede UNTIL.

EXIT

Transfers program control out of the DO...UNTIL loop to the command following UNTIL <condition expL> without reevaluating <condition expL> or executing the commands that follow EXIT and precede UNTIL.

UNTIL <condition expL>

A required command that marks the end of the DO...UNTIL loop. The <condition expL> argument is a logical expression that determines if dBASE executes the statements in the DO...UNTIL loop. If the expression evaluates to .F., program control returns to the DO command and dBASE executes the commands in the DO...UNTIL loop. If the expression evaluates to .T., program control transfers out of the loop to the line following UNTIL.

Description

Use DO...UNTIL to execute specified statements for as many times as a specified condition is false. When dBASE first encounters a DO...UNTIL loop, it executes the statements between DO and UNTIL until it encounters LOOP, EXIT, or UNTIL. If it encounters UNTIL, dBASE evaluates the condition to determine if it goes through the loop again. Because dBASE evaluates the condition after executing the statements, the statements in a DO...UNTIL loop always execute at least once, even when the condition is initially true.

You can nest loops and other structures, including other DO...UNTIL loops, in a DO...UNTIL loop. You can nest up to 116 DO...UNTIL loops in a procedure or function; the maximum depends on the number of other loops, such as DO WHILE, that are also running.

DO...UNTIL and DO WHILE...ENDDO are opposite constructs. DO...UNTIL executes commands while a condition is false (until the condition is true), while DO WHILE...ENDDO executes commands while a condition is true (until the condition is false). Unlike DO...UNTIL, DO WHILE...ENDDO evaluates the condition before executing commands; thus, the commands between DO WHILE and ENDDO do not execute at all if the condition is initially false.

Use DO...UNTIL when you want commands to execute at least once, as with data entry programs in which you require at least one entry and allow any number of further entries. This type of program often requires an explicit response to reexecute the commands in the DO...UNTIL loop. The program evaluates this response with UNTIL <condition expL>.

In other situations, the choice between DO...UNTIL and DO WHILE can also depend on which command saves a few program lines or makes a program more readable. You can often rephrase a negative condition for one into a positive condition for the other.


DO...UNTIL Example

The following example uses DO...UNTIL to show one screen full of information about flights. The DO...UNTIL loop ends either at row 20 or when the end of file is reached:

SET TALK OFF
USE Flights EXCLUSIVE
CLEAR
? CENTER("Flight Information")
? "Flight","Origin","Dest","Departure","Arrival"
DO
  ? Flight_no, Origin, Dest, Departure, Arrival
  SKIP
UNTIL row()>= 20 .OR. EOF()
CLOSE DATABASE


Portability

Not supported in dBASE IV or dBASE III PLUS.


See Also

DO WHILE

IF

FOR...NEXT


DO CASE

See Also	Example	Programs

Conditionally processes statements by evaluating one or more conditions and executing the statements following the first condition that evaluates to true.

Syntax

DO CASE
CASE <condition expL 1>
<statements>
[CASE <condition expL 2>
<statements>...]
[OTHERWISE
<statements>]
ENDCASE

CASE <condition expL>

If the condition is true, executes the set of commands between CASE and the next CASE, OTHERWISE, or ENDCASE command, and then transfers control to the line following ENDCASE. If the condition is false, control transfers to the next CASE, OTHERWISE, or ENDCASE command.

<statements>

One or more program lines consisting of any combination of commands, functions, and user-defined functions (UDFs).

OTHERWISE

Executes a set of statements if all the CASE statements evaluate to false.

ENDCASE

A required command that marks the end of the DO CASE structure.

Description

DO CASE is similar to IF...ELSE...ENDIF. As with IF conditions, dBASE evaluates DO CASE conditions in the order they are listed in the structure. However, DO CASE acts on only the first true condition in the structure, even if several apply. In situations where you want only the first true instance to be processed, use DO CASE instead of a series of IF commands.

Also, use DO CASE when you want to program a number of exceptions to a condition. The CASE <condition> statements can represent the exceptions, and the OTHERWISE statement the remaining situation.

Starting with the first CASE condition, dBASE does the following.

Evaluates each CASE condition until it encounters one that is true

Executes the statements between the first true CASE statement and the next CASE, OTHERWISE, or ENDCASE

Exits the DO CASE structure without evaluating subsequent CASE conditions

Moves program control to the first line after the ENDCASE command

If none of the conditions are true, dBASE executes the statements under OTHERWISE if it is included. If no OTHERWISE statement exists, dBASE exits the structure without executing any statements and transfers program control to the first line after the ENDCASE command.

If you include command pairs such as IF...ENDIF and DO WHILE...ENDDO, you must nest them within separate DO CASE statements. You can also nest DO CASE structures.


DO CASE Example

Compare this example with the examples of the IF command. The following CASE construct determines the magnitude of a variable and displays an appropriate message:

nM_value = 225

DO CASE
  CASE nM_value > 1000
    ? "Value is over 1000."
  CASE nM_value > 100
    ? "Value is over 100."
  CASE nM_value > 10
    ? "Value is over 10."
  CASE nM_value > 1
    ? "Value is over 1."
  OTHERWISE
    ? "The value is 1 or less."
ENDCASE


See Also

DO WHILE

DO...UNTIL

FOR...NEXT

IF

IIF( )

SCAN


DO WHILE

See Also	Example	Programs

Executes the statements between DO WHILE and ENDDO as long as a specified condition is true or until dBASE encounters an EXIT command.

Syntax

DO WHILE <condition expL>
<statements>
[LOOP]
[EXIT]
ENDDO

<condition expL>

A logical expression that determines if dBASE executes the statements following the DO WHILE statement. If the expression evaluates to .F., dBASE skips the statements following DO WHILE and executes the command line following ENDDO. If the expression evaluates to .T., dBASE executes the commands in the DO WHILE loop.

<statements>

Program lines consisting of any combination of commands, functions, user-defined functions (UDFs), and LOOP and EXIT options.

LOOP

Returns program control to the top of the DO WHILE loop without executing the statements that follow LOOP and precede ENDDO.

EXIT

Transfers program control out of the DO WHILE loop to the command following ENDDO without executing the statements that follow EXIT and precede ENDDO.

ENDDO

A required command that marks the end of the DO WHILE loop.

Description

Use DO WHILE...ENDDO to execute specified statements for as many times as a specified condition is true. When dBASE encounters a DO WHILE statement, it determines whether <condition expL> is true or false. If <condition expL> is true, dBASE executes the statements in the DO WHILE loop one by one until it encounters ENDDO, LOOP, or EXIT. If <condition expL> is false, dBASE skips the loop and executes the command line following ENDDO.

ENDDO and LOOP return program control to the DO WHILE statement and cause dBASE to evaluate <condition expL> again. EXIT transfers program control out of the DO WHILE loop to the command following ENDDO.

You can nest loops and other structures, including other DO WHILE loops, in a DO WHILE loop. You can nest up to 125 DO WHILE loops in a procedure or function; the maximum depends on the number of other loops, such as DO UNTIL, that are also running..

DO WHILE...ENDDO and DO...UNTIL are opposite constructs. DO WHILE...ENDDO executes commands while a condition is true (until the condition is false), while DO...UNTIL executes commands while a condition is false (until the condition is true). Because DO...UNTIL executes commands before evaluating the condition, the commands between DO and UNTIL execute at least once, even when the condition is true. Because DO WHILE...ENDDO evaluates the condition before executing commands, the commands between DO WHILE and ENDDO do not execute at all if the condition is initially false.


DO WHILE Example

The following example uses DO WHILE to step through a table one record at a time and bring up the edit window if a record is missing a phone number. This process repeats until the EOF( ) marker is encountered or the user answers "N" to the continue prompt:

SET EXCAPE OFF
USE Clients
CLEAR
DO WHILE .NOT. EOF()
  IF ISBLANK(Phone)
    mRec = Recno()
    EDIT NOAPPEND NODELETE RECORD MREC
    SKIP
    ACCEPT "Continue?(Y/N)" TO mCont
      IF UPPER(mCont) = "N"
        EXIT
      ENDIF
      CLEAR
  ELSE
    SKIP
ENDIF
ENDDO
RETURN


See Also

DO CASE

DO...UNTIL

FOR...NEXT

IF

SCAN


DOS

See Also	Example	Portability	Disk and File Utilities

Interrupts dBASE and displays the DOS prompt, allowing execution of DOS commands. dBASE resumes when EXIT is typed at the DOS prompt.

Syntax

DOS

Description

Use the DOS command to temporarily leave dBASE and perform commands in DOS. Enter commands in DOS as you normally do and use EXIT to return to dBASE after the desired commands have been executed.

When you issue commands that run in a DOS window, dBASE loads COMMAND.COM using DBASEWIN.PIF in the _dbwinhome directory. You can use the Windows PIF Editor to customize the settings in DBASEWIN.PIF. For more information about .PIF files, see your Windows documentation.

To execute single DOS commands without exiting dBASE, use ! or RUN. To execute Windows applications, use RUN( ).


DOS Example

DOS takes you out to DOS:

DOS

Type EXIT from the DOS prompt to return to dBASE.


Portability

Not supported in dBASE IV or dBASE III PLUS.


See Also

_dbwinhome

RUN

RUN( )


DOW( )

See Also	Example	Date and Time Data

Returns the day of the week corresponding to a specified date expression as a number from 1 to 7.

Syntax

DOW(<expD>)

<expD>

The date expression, in the current date format, whose corresponding weekday number to return.

Description

DOW( ) returns the number of the day of the week on which a date falls. Sunday is equal to 1, Monday to 2, and so on through Saturday, which is equal to 7. To return the name of the day of the week instead of the number, use CDOW( ).

You must enter <expD> in the current date format as determined by SET DATE, DBASEWIN.INI, or the International option of the Windows Control Panel (in that order). That is, SET DATE settings override those in DBASEWIN.INI, and settings in DBASEWIN.INI override those in the Windows Control Panel. Be sure <expD> matches the date format in use when your program runs.

If you pass an invalid date to DOW( ), dBASE converts the date to a valid one and returns the weekday number of that date. If you pass an empty or non-date expression delimited with braces ({ }) to DOW( ), it returns 0. If you pass a non-date expression or an expression that is not delimited with braces to DOW( ), it returns an error.


DOW( ) Example

The following example determines how many records in the flight table have a Date field value that equates to Saturday (value of 7) or Sunday (value of 1):

CLEAR
USE Flights
COUNT FOR DOW(Date)=1 .OR. DOW(Date)=7 TO Weekend
? Weekend
RETURN


See Also

CDOW( )

CMONTH( )

SET CENTURY

SET DATE


DTOC( )

See Also	Example	Expressions and Type Conversion

Returns a specified date expression as a character expression.

Syntax

DTOC(<expD>)

<expD>

The date expression, in the current date format, to return as a character expression.

Description

Use DTOC( ) to convert a date expression to a character expression. Once you convert date data to character data, you can manipulate it as you would any string. For example, if you want to print the current date on a report, use DTOC(DATE( )). To convert a date expression to a character string suitable for indexing or sorting, use DTOS( ).

Specify <expD> in the current date format. dBASE uses the value set by SET DATE, DBASEWIN.INI, or the International option of the Windows Control Panel (in that order) to determine the value of <expD>. That is, SET DATE settings override those in DBASEWIN.INI, and settings in DBASEWIN.INI override those in the Windows Control Panel. Be sure <expD> matches the date format in use when your program runs. DTOC( ) returns a character expression in the current date format.

If you pass an invalid date to DTOC( ), it converts the date to a valid one and returns that date as a character expression. If you pass an empty date ({  /  /  } or { }) to DTOC( ), it returns an empty string expression in the current date format. For example, if the SET DATE format is AMERICAN, DTOC({ }) returns "  /  /  ". If you pass a non-date expression or an expression that is not delimited with braces ({ }) to DTOC( ), it returns an error.


DTOC( ) Example

The following example uses DTOC( ) to convert date values in the BalDate field to a character string so that they can be concatenated with a character field (Client_ID) in an array element variable. Also note the conversion of a numeric value (StartBal) to character with STR( ). The example program stores a three-field string for each record to array String, then outputs the array contents to the Command window results pane:

SET TALK OFF
USE Clients
DECLARE String[RECCOUNT()]
Cnt = 1
SCAN
  STRING[Cnt]=Client_ID+"*"+DTOC(BalDate)+"*"+;
    LTRIM(STR(StartBal,7,2))
  Cnt=Cnt+1
ENDSCAN
* The following FOR...NEXT loop verifies the contents
* of the array.
FOR i=1 TO RECCOUNT()
  ? STRING[i] AT 10
NEXT i


See Also

CTOD( )

DATE( )

DTOS( )

SET DATE

SET CENTURY


DTOR( )

See Also	Example	Portability	Numeric Data

Returns the radian value of an angle whose measurement is given in degrees.

Syntax

DTOR(<expN>)

<expN>

A negative or positive integer or float that is the size of the angle in degrees.

Description

DTOR( ) converts the measurement of an angle from degrees to radians. DTOR( ) returns a float. To convert degrees to radians, dBASE

Multiplies the number of degrees by pi

Divides the result by 180

Returns the quotient

A 180-degree angle is equivalent to pi radians.

Use DTOR( ) in the trigonometric functions SIN( ), COS( ), and TAN( ) because these functions require the angle value in radians. For example, to find the sine of a 45-degree angle, use SIN(DTOR(45)), which returns .71 if the default number of decimal places is 2.

Use SET DECIMALS to set the number of decimal places DTOR( ) displays.


DTOR( ) Example

The following examples show some ways to use DTOR( ):

? DTOR(180)     && Returns 3.14 (pi)
? DTOR(0)       && Returns 0
? DTOR(360)     && Returns 6.28 (2*pi)
? DTOR(90)      && Returns 1.57 (pi/2)
? DTOR(-90)     && Returns -1.57

The following example converts 60 degrees 30 minutes 15 seconds to radians:

? DTOR(60.525)  && Returns 1.06


Portability

Not supported in dBASE III PLUS.


See Also

ACOS( )

ASIN( )

ATAN( )

ATN2( )

COS( )

PI( )

RTOD( )

SET DECIMALS

SIN( )

TAN( )


DTOS( )

See Also	Example	Portability	Expressions and Type Conversion

Returns a specified date expression as a character string in YYYYMMDD format.

Syntax

DTOS(<expD>)

<expD>

The date expression, in the current format, to return as a character string in YYYYMMDD format.

Description

Use DTOS( ) to convert a date expression to a character string suitable for indexing or sorting. For example, you can use DTOS( ) when indexing on a date field in combination with another field of a different type. DTOS( ) always returns a character string in YYYYMMDD format, even if SET CENTURY is OFF.

You must enter <expD> in the current date format as determined by SET DATE, DBASEWIN.INI, or the International option of the Windows Control Panel (in that order). That is, SET DATE settings override those in DBASEWIN.INI, and settings in DBASEWIN.INI override those in the Windows Control Panel. Be sure <expD> matches the date format in use when your program runs.

If you want to ensure that records in a table are sorted by date regardless of the current date format in use, and need to concatenate the date field with another field in the table, use DTOS( ) instead of DTOC( ). DTOS( ) always returns YYYYMMDD, while the value returned by DTOC( ) depends on the current date format. This means that with DTOS( ), dBASE sorts updated records into the table the same way, regardless of the date format in effect. If you use DTOC( ), however, the same date format must be current whenever the index is updated; if the date format changes, the index will not be updated correctly.

If you pass an invalid date to DTOS( ), dBASE converts the date to a valid one and returns that date as a character string. If you pass an empty or non-date expression delimited with curly braces to DTOS( ), it returns an empty string (""). If you pass an expression that is not delimited with curly braces to DTOS( ), it returns an error.


DTOS( ) Example

The following examples show the difference between DTOS( ) and DTOC( ).

SET CENTURY OFF
date1 = {4/1/94}
? DTOC(date1)                && Returns 04/01/94
? DTOS(date1)                && Returns 19940401
SET CENTURY ON
? DTOC(date1)                && Returns 04/01/1994
? DTOS(date1)                && Returns 19940401
SET CENTURY OFF

The following example uses DTOS( ) to convert date field information to a character string with the year first to facilitate searching for a specific year.

SET TALK OFF
USE Clients EXCLUSIVE
INDEX ON DTOS(Baldate) TAG Bal_date
yr = "1992"
? CENTER("Report for: "+yr+" - Run on: " +  DTOC(DATE()))
?                        && Spacing line
  SCAN FOR SUBSTR(DTOS(Baldate),1,4) = yr
    ? Company + DTOC(Baldate) AT 5
  ENDSCAN
SET TALK ON
CLOSE ALL


Portability

Not supported in dBASE III PLUS.


See Also

DTOC( )

INDEX

SET CENTURY

SET DATE


EDIT

See Also	Example	Fields and Records

Displays fields in the current table for editing.

Syntax

EDIT
[<starting record expN > | <bookmark>]
[<scope>]
[FOR <condition 1>]
[WHILE <condition 2>]
[COLOR [<standard text>] [, [<enhanced text>] [, <border>]]]
[COLUMNAR]
[COMPRESS]
[FIELDS <field 1> [<field option list 1>] |
<calculated field 1> = <exp 1> [<calculated field option list 1>]
[, <field 2> [<field option list 2>] |
<calculated field 2> = <exp 2> [<calculated field option list 2>]  ...]]
[FORMAT]
[FREEZE <field 3>]
[KEY <exp 3> [, <exp 4>]]
[LOCK <expN>]
[NOAPPEND]
[NODELETE]
[NOEDIT | NOMODIFY]
[NOFOLLOW]
[NOINIT]
[NORMAL]
[NOTOGGLE]
[NOWAIT]
[TITLE <expC 1>]
[WIDTH <expN>]
[WINDOW <window name>]

<starting record expN> | <bookmark>

The record number or bookmark (for tables that do not use record numbers) to edit.

<scope>

The number of records to edit. RECORD <n> identifies a single record by its record number. NEXT <n> identifies n records, beginning with the current record. ALL specifies all records. REST specifies all records from the current record to the end of the file.

FOR <condition 1>
WHILE <condition 2>

Determines which records are affected by EDIT. FOR restricts EDIT to records that meet <condition 1>. WHILE starts processing with the current record and continues with each subsequent record as long as <condition 2> is true.

COLOR

Specifies the colors of standard text, enhanced text, and the perimeter of the Table Records window. To specify the colors of these elements separately, use the <standard text>, <enhanced text>, and <perimeter> options. You can also use the <background> option if you have a monitor with a uniform background.

<standard text>	Color attributes of command messages and screen output. For example, the output of the ? and @...SAY commands appear in standard text.
<enhanced text>	Color attributes of enhanced text areas, such as @...GET fields and highlighted BROWSE data cells.
<perimeter>	Color attributes of the perimeter bordering the area displaying text on the screen.
<background>	Color attributes of the background for display systems with uniform backgrounds. <background> includes two parameters: a background color and an attribute.
The <standard text> and <enhanced text> attributes include three settings: a foreground color, a background color, and an optional color for creating blended (hatched) backgrounds. Separate each setting with a forward slash (/).

For more information about color settings, see SET COLOR TO and SET COLOR OF.

COLUMNAR

Arranges the fields in columns on the editing form.

COMPRESS

Reduces the number of rows used to display field names in the Table Records window.

FIELDS <field 1> [<field option list 1>] |
<calculated field 1> = <exp 1> [<calculated field option list 1>]
[, <field 2> [<field option list 2>] |
<calculated field 2> = <exp 2> [<calculated field option list 2>] ... ]]

Displays the specified fields, in the order they are listed, for browsing. Options for <field option list 1>, <field option list 2>, which apply to <field 1>, <field 2>, and so on, affect the way these fields are displayed. These options are as follows:

\B = <exp 1>, <exp 2> [\F]	RANGE option; forces any value entered in <field 1> to fall within <exp 1> and <exp 2>, inclusive RANGE REQUIRED option; the \F option prevents a previously entered value from being accepted if it does not fall between <exp 1> and <exp 2>, inclusive
\H = <expC>	HEADER option; causes <expC> to appear above the field column in the Table Records window, replacing the field name
\P = <expC>	PICTURE option; displays <field 1> according to the PICTURE or FUNCTION clause <expC>
\R	READ-ONLY option; specifies that <field 1> is read-only and cannot be edited
\V = <condition> [\F] [\E = <expC>]	VALID option; allows a new <field 1> value to be entered only when <condition> evaluates to .T. VALID REQUIRED option; the \F option prevents the cursor from leaving <field 1> and the editing session from ending until <condition> evaluates to .T. ERROR MESSAGE option; \E = <expC> causes <expC> to appear when <condition> evaluates to .F.
\W = <condition>	WHEN option; allows <field 1> to be edited only when <condition> evaluates to .T.
Note:	You may also use the the "/" character when specifying only a single option in a field option list.

Read-only calculated fields are composed of an assigned field name and an expression that results in the calculated field value, as with Commission = Rate * Saleprice. Options for calculated fields affect the way these fields are displayed. These options are as follows:

\<column width>	The width of the column within which <calculated field 1> is displayed
\H = <expC>	Causes <expC> to appear above the calculated field column in the Table Records window, replacing the calculated field name
FORMAT

Causes EDIT to accept and display input according to the specifications of a format file opened with SET FORMAT. Data entered must conform to any PICTURE, FUNCTION, RANGE, and VALID clauses in the format file.

FREEZE <field 3>

Restricts editing to <field 3>, although other fields are visible when you change to browse mode.

KEY <exp 3> [,<exp 4>]

When the table has a master index, displays records whose key field value matches or comes after <exp 3>, or falls between <exp 3> and <exp 4>.

LOCK <expN >

Causes the first <expN 2> fields in the table, or the first <expN> fields in the field list, to continue to appear in place when you move the cursor to fields to the right in the Table Records window.

NOAPPEND

Prevents you from adding records in either browse or edit modes.

NODELETE

Prevents the marking of records for deletion from within the Table Records window.

NOEDIT | NOMODIFY

Prevents you from modifying records from the Table Records window.

NOFOLLOW

When the current table has a master index, causes the cursor to remain in place when you change the key field in a record, rather than follow the record to its new location in the indexing order. Without NOFOLLOW, dBASE reindexes the table as soon as you move to another record when a master index for the table is open.

NOINIT

Causes EDIT to execute the options specified with the previous EDIT command. Use NOINIT if a program calls EDIT several times or if you issue EDIT several times from the Command window, and you want the same options. Specify the command options the first time you use EDIT, and issue EDIT NOINIT for subsequent use in the same session.

NORMAL

When EDIT is issued from an active window, displays the Table Records window in normal, full-screen mode with their default or defined colors, ignoring the defined colors of the window. When you exit EDIT, dBASE returns you to the active window. Without NORMAL, the table records appears in the active window.

NOTOGGLE

Prevents toggling from EDIT to BROWSE.

NOWAIT

Continues execution of a program after a Table Records window is displayed; otherwise, program execution is suspended until after the Table Records window is closed.

TITLE <expC 1>

Displays <expC> as the title of the Table Records window.

WIDTH <expN>

Specifies the display width for character fields in the Table Records window. If a field is wider than the specified width, you can scroll the field within the specified width. The <expN> argument must evaluate to a positive number.

WINDOW <window name>

Activates the window <window name> and displays table records in the window.

Description

Use EDIT to display and change the contents of one or more table records. EDIT without the FIELDS option displays all fields of the current record. Use SET RELATION command to view fields from records in linked tables.

To move between records in the Table Records window, you can press PgUp and PgDn to move backward or forward, one record at a time. You can also use the window controls and the mouse and choose from various menu options to control operations performed with EDIT. See Displaying and Editing Table Records or the User's Guide for more information on performing operations and navigating in the Table Records window.

When you are through viewing or editing a table in the Table Records window, press Ctrl+W to exit EDIT or choose File|Save and Close. To exit EDIT without saving changes to the current record, press Ctrl+Q, choose File|Abandon and Close, or double-click the Control menu. .If you are using EDIT or BROWSE in a program, exiting EDIT returns program control to the command line immediately following the EDIT command line.

To view and modify a memo field, move the cursor to the memo field and press Ctrl+Home, or double-click the memo field. To save the modified memo field, press Ctrl+W.

To append a new record (unless you use EDIT...NOAPPEND), move the cursor to the last field of the last record in the table and press PgDn.

Many of the EDIT options are the same as those provided by BROWSE. (Press F2 to toggle between the two modes.)

Use FIELDS followed by a list of table field names or calculated field names to control the fields EDIT and BROWSE display, and whether you can edit data in a particular field.

A calculated field is a read-only field that displays the value of an expression. The expression typically includes one or more fields in the current table, such as

Name = Firstname + " " + Lastname
Total = Price + (Salestax * Price)
Monthdue = CMONTH(Billdate + 30)

The expression to the left of = specifies the name of the calculated field, and the expression on the right evaluates to each calculated field's contents.

The Table Records window displays fields according to the @...SAY...GET statements of an open format file, whether you use the FORMAT option or not. Use the FORMAT option as a reminder when a format file is open. To open the format file, use SET FORMAT TO and the format file name. If you open a format file, the FIELDS option of EDIT has no effect, and EDIT and BROWSE display only the fields specified in the format file. Although the format file does not affect the format of the Table Records window, data entered in the Table Records window must conform to any PICTURE, FUNCTION, RANGE, or VALID clauses in the format file.

EDIT can alter only the contents of a table. To modify the table structure, use MODIFY STRUCTURE. EDIT and CHANGE are equivalent commands.


EDIT Example

The following example uses EDIT to open a Table Records window window containing a subset of the total fields with specified editing limitations:

USE Company IN SELECT() EXCLUSIVE
INDEX ON CompCode TAG CompCode
EDIT FIELDS CompCode, Company, ;
   Street1, City, State_Prov, Zip_P_Code ;
   NOFOLLOW NOAPPEND NODELETE

CLOSE ALL


See Also

APPEND

BROWSE

MODIFY STRUCTURE

SET FORMAT

SET RELATION


EJECT

See Also	Example	Printing

Advances printer paper to the top of the next page.

Syntax

EJECT

Description

Use EJECT to position printed output on the page. If you are using a tractor-feed printer (such as a dot matrix printer) and the paper is correctly positioned, EJECT advances the paper to the top of the next sheet. If you are using a single-sheet printer (such as a laser printer), EJECT prints any data in the print queue and ejects the page. Before printing or executing EJECT, connect and turn on the printer.

EJECT works in conjunction with _padvance, _plength, and _plineno. If _padvance is set to "FORMFEED" (the default), issuing the EJECT command from dBASE is equivalent to using your printer's formfeed button or sending the formfeed character (ASCII 12) to the printer. If _padvance is set to "LINEFEEDS", issuing EJECT sends individual linefeeds to the printer until _plineno equals _plength, then resets _plineno to 0. Then, _pageno is incremented by 1. For more information, see _padvance.

EJECT is often used in when printing reports. For example, if PROW( ) returns a value that is close to the bottom of the page, issue EJECT to continue the report at the top of the next page. EJECT automatically resets the printhead to the top left corner of the new page, which is where PROW( ) = 0 and PCOL( ) = 0.

EJECT is the same as EJECT PAGE, except EJECT PAGE also executes any page-handling routine you have defined with ON PAGE.


EJECT Example

In this example, one line is written to the printer and EJECT is then used to ensure that further commands are written on the next page:

SET PRINTER ON
? "This page left intentionally blank"
EJECT


See Also

_padvance

_plength

_plineno

EJECT PAGE

ON PAGE

PCOL( )

PROW( )

SET PRINTER

SET PROW


EJECT PAGE

See Also	Example	Portability	Printing

Advances printer paper to the top of the next page and executes any ON PAGE command.

Syntax

EJECT PAGE

Description

Use EJECT PAGE with ON PAGE to control the ejection of pages by a printer. If you define a page-handling routine with ON PAGE AT LINE <expN> and then issue EJECT PAGE, dBASE checks to see if the current line number (_plineno) is greater than the line number specified by <expN>. If _plineno is less than the ON PAGE line, EJECT PAGE sends sufficient linefeeds to trigger the ON PAGE page-handling routine.

If _plineno is greater than the ON PAGE line, or if you do not have an ON PAGE page-handling routine, EJECT PAGE advances the output as follows:

If _padvance is set to "FORMFEED" and SET PRINTER is ON, dBASE issues a formfeed (ASCII code 12).

If _padvance is set to "LINEFEEDS" and SET PRINTER is ON, dBASE issues sufficient linefeeds (ASCII code 10) to advance to the next page. It uses the formula _plength - _plineno to calculate the number of linefeeds.

If you direct output to a destination other than the printer (for example, if you use SET ALTERNATE or SET DEVICE), dBASE uses the formula _plength - _plineno to calculate the number of linefeeds.

After ejecting a page, EJECT PAGE increments _pageno by 1 and resets _plineno to 0.


EJECT PAGE Example

See ON PAGE for an example of EJECT PAGE.


Portability

Not supported in dBASE III PLUS.


See Also

?

??

_padvance

_pageno

_plength

_plineno

EJECT

ON PAGE

PRINTJOB...ENDPRINTJOB

SET ALTERNATE

SET DEVICE

SET PRINTER

SET PROW


ELAPSED( )

See Also	Example	Portability	Date and Time Data

Returns the number of seconds elapsed between two specified times.

Syntax

ELAPSED(<stop time expC>, <start time expC>)

<stop time expC>

The time expression, in the format HH:MM:SS, at which to stop timing seconds elapsed. The <stop time expC> argument should be a later time than <start time expC>; if it is not, dBASE returns a negative value.

<start time expC>

The time expression, in the format HH:MM:SS, at which to start timing seconds elapsed. The <start time expC> argument should be an earlier time than <stop time expC>; if it is not, dBASE returns a negative value.

Description

Use ELAPSED( ) with TIME( ) to determine benchmarks for a program--that is, to determine how long a program takes to execute when you use different programming strategies. You can also use ELAPSED( ) to determine a particular computer's processing speed; you can then slow down screen displays that would otherwise execute too quickly. You can also use ELAPSED( ) to design timeout features in automated demonstration programs and tutorials.

ELAPSED( ) subtracts the value of <start time expC> from <stop time expC>. If <start time expC> is the later time, ELAPSED( ) returns a negative integer. Both <stop time expC> and <start time expC> must be in HH:MM:SS format, where HH is the hour, MM the minutes, and SS the seconds; however, you do not need to specify minutes and seconds if you want to designate them as 0.


ELAPSED( ) Example

The following example uses ELAPSED( ) to compute elapsed time in hours between two entered times:

LOCAL f
f = NEW GFORM()
f.Open()

CLASS GFORM OF FORM
   this.Left =         53.00
   this.Height =         15.00
   this.Width =         43.00
   this.Text = "Time worked today?"
   this.HelpId = ""
   this.HelpFile = ""
   this.Top =          5.59

   DEFINE TEXT T1 OF THIS;
       PROPERTY;
         Left          4.00,;
         Height          1.00,;
         ColorNormal "N/W",;
         Width         28.00,;
         Border .F.,;
         Text "Enter Start Time (24 hr):",;
         Top          3.00

   DEFINE ENTRYFIELD F1 OF THIS;
       PROPERTY;
         Left         34.00,;
         Height          1.00,;
         Width          5.00,;
         Value "  :  ",;
         Picture "99:99",;
         Border .T.,;
         Top          3.00

   DEFINE TEXT T2 OF THIS;
       PROPERTY;
         Left          4.00,;
         Height          1.00,;
         ColorNormal "N/W",;
         Width         28.00,;
         Border .F.,;
         Text "Enter Quit Time (24 hr):",;
         Top          5.00

   DEFINE ENTRYFIELD F2 OF THIS;
       PROPERTY;
         Left         34.00,;
         Height          1.00,;
         Width          5.00,;
         Value "  :  ",;
         Picture "99:99",;
         Border .T.,;
         Top          5.00

   DEFINE PUSHBUTTON COMPUTE OF THIS;
       PROPERTY;
         Left         12.00,;
         Height          2.00,;
         ColorNormal "N/W",;
         Width         19.00,;
         OnClick {;myResult="Time worked today: " +   LTRIM(STR(ELAPSED(Form.F2.Value,  Form.F1.Value)/3600,6,2)) + " Hours"  ; Form.WorkTime.Text=myResult},;
         Text "Elapsed Time",;
         Default .T.,;
         Top          9.00

   DEFINE TEXT WORKTIME OF THIS;
       PROPERTY;
         Left          4.00,;
         Height          1.00,;
         ColorNormal "R+/W",;
         Width         30.00,;
         Border .F.,;
         Text "Time worked today: ",;
         Top          7.00

ENDCLASS


Portability

Not supported in dBASE IV or dBASE III PLUS.


See Also

SECONDS( )

TIME( )


EMPTY( )

See Also	Example	Portability	Expressions and Type Conversion

Returns .T. if a specified expression or field is 0 or blank, .F. if it contains any other value.

Syntax

EMPTY(<exp>)

<exp>

An expression of any data type.

Description

EMPTY( ) returns .T. if a specified expression is blank or 0, .F. if it contains data or a numeric value other than 0.

EMPTY( ) is almost identical to ISBLANK( ). However, ISBLANK( ) differentiates between zero and blank values in numeric fields, while EMPTY( ) does not. For more information, see ISBLANK( ).


EMPTY( ) Example

The following example compares the use of AVERAGE when used with no conditions, with ISBLANK( ), and with EMPTY( ).

   File Blnktest.DBF contains 4 records, with
   the following values:
   Record #       NUMFIELD
          1            0
          2           10
          3           20
          4         (blank)

The following includes all records, so it does not calculate a true average if blank values can be included.

AVERAGE numfield TO nAver1      && Returns 7.5 (30/4)

The following ignores blank records, but includes those with a value of 0. This is the most accurate average if 0 values are valid.

AVERAGE numfield TO nAver2 ;
 FOR .NOT. ISBLANK(numfield)    && Returns 10 (30/3)

The following ignores records that are blank or have a value of 0. Use this if you want to exclude records with no value, or with a value of 0.

AVERAGE numfield TO nAver3 ;
  FOR .NOT. EMPTY(numfield)     && Returns 15 (30/2)


Portability

Not supported in dBASE III PLUS or dBASE IV.


See Also

BLANK

ISBLANK( )

SPACE( )

TYPE( )


EOF( )

See Also	Example	Fields and Records

Indicates if the record pointer is at the end of the file.

Syntax

EOF( [<alias>] )

<alias>

A work area number (1 through 225), letter (A through J), or alias name. The work area letter or alias name must be enclosed in quotes.

Description

EOF( ) returns .T. when the record pointer in the current or specified table is positioned past the last record or when the record pointer is positioned past the last record in the master index file. Otherwise, EOF( ) returns .F. Also, if no table is open in the specified work area, EOF( ) returns .F.

EOF( ) returns .T. after SCAN processes the last record in a table, when you use SKIP to pass the last record in a table or index file, when you use LIST with no options, or when CONTINUE, FIND, GO, LOCATE, LOOKUP( ), SEEK( ), or SEEK fails to find the specified record (and SET NEAR is OFF).


EOF( ) Example

The following example uses EOF( ) to test for the end of file during a DO...UNTIL loop. When the record pointer skips past the last record, EOF( ) becomes true and the DO...UNTIL loop ends:

USE COMPANY
DO
  * ...
  SKIP                  && skip to next record
UNTIL EOF()             && test for EOF()

The following example defines a form and two pushbuttons for moving the record pointer. BOF( ) and EOF( ) are used to avoid a BOF( ) or EOF( ) error alert at either end of the table:

SET PROCEDURE TO PROGRAM(1) ADDITIVE
USE Clients
DEFINE FORM F1
DEFINE PUSHBUTTON Pb1 OF F1 AT 10,10;
  PROPERTY Text "Previous",;
    Width 8, OnClick Back
DEFINE PUSHBUTTON Pb2 OF F1 AT 10,22;
  PROPERTY Text "Next",;
    Width 8, OnClick Forward
OPEN FORM F1

FUNCTION Back
IF .NOT. BOF()
  SKIP-1
ENDIF
RETURN .T.

FUNCTION Forward
IF .NOT. EOF()
  SKIP
ENDIF
RETURN .T.


See Also

BOF( )

FIND

FOUND( )

LOCATE

RECNO( )

SEEK

SEEK( )


ERASE

See Also	Example	Portability	Disk and File Utilities

Removes a file from a disk.

Syntax

ERASE <filename> | ? | <filename skeleton>

<filename> | ? | <filename skeleton>

Identifies the file to remove. ? and <filename skeleton> display a dialog box from which you can select a file.

If you specify a file without including its path, dBASE looks for the file in the current directory, then in the path you specify with SET PATH. If you specify a file without including its extension, dBASE does not assume an extension.

Description

ERASE is a utility command that deletes a file from a disk. ERASE and DELETE FILE are equivalent commands.

ERASE is nearly identical to the ERASE (or DEL) command in DOS. Unlike the DOS command, however, including the wildcard characters * and ? in a file-name skeleton opens a dialog box from which to choose file names to erase. Also unlike the DOS command, you can delete only one file at a time with ERASE. A file must be closed before ERASE can remove it.

If the file that you want to remove has an extension, you must include that extension in <filename>. If the file is not on the default drive you must specify a drive designation, and if the file is not in the current directory or in the path you specify with SET PATH, you must specify the directory path.

If <filename> is present in the current directory and also exists in the SET PATH directory, ERASE <filename> without path information removes only the file in the current directory. SET SAFETY has no effect on ERASE.

ERASE does not automatically remove a .DBT file when the .DBF file it is associated with is removed. To remove all files associated with a table, use DELETE TABLE.


ERASE Example

The following examples use ERASE:

ERASE Temp.prg
ERASE ?
* Displays the open source dialog box


Portability

The <filename skeleton> argument is not supported in dBASE IV or dBASE III PLUS.


See Also

DELETE TABLE

RENAME

SET DIRECTORY

SET PATH

SET SAFETY


ERROR( )

See Also	Example	Portability	Error Handling and Debugging

Returns the number of the most recent dBASE error.

Syntax

ERROR( )

Description

Use ERROR( ) to determine the error number when an error occurs. ERROR( ) is initially set to 0. ERROR( ) returns an error number when an error occurs, and remains set to that number until one of the following happens:

Another error occurs

RETRY is issued

The subroutine in which the error occurs completes execution

The following table compares the functionality of CERROR( ), DBERROR( ), DBMESSAGE( ), ERROR( ), MESSAGE( ), SQLERROR( ), and SQLMESSAGE( ).

Function	Returns

CERROR( )	Compiler error number

DBERROR( )	IDAPI error number

DBMESSAGE( )	IDAPI error message

ERROR( )	dBASE error number

MESSAGE( )	dBASE error message

SQLERROR( )	Server error number

SQLMESSAGE( )	Server error message

See Error Messages for a listing of all error codes.


ERROR( ) Example

See ON ERROR for an example of using ERROR( ).


Portability

The error codes of some errors in dBASE IV and dBASE III PLUS are different from the error codes for the same errors in dBASE for Windows. See Error Messages for more information.

An ON ERROR command does not need to be active in dBASE for Windows for ERROR( ) to return an error code.


See Also

CERROR( )

DBERROR( )

DBMESSAGE( )

MESSAGE( )

ON ERROR

RETRY

SQLERROR( )

SQLMESSAGE( )


EXP( )

See Also	Example	Numeric Data

Returns e raised to a specified power.

Syntax

EXP(<expN>)

<expN>

The positive, negative, or zero power (exponent) to raise the number e to.

Description

EXP( ) returns a float equal to e (the base of the natural logarithm) raised to the <expN> power. For example, EXP(2) returns 7.39 because e^2=7.39.

EXP( ) is the inverse of LOG( ). For example, if Y=EXP(X), then LOG(Y)=X.

Use SET DECIMALS to set the number of decimal places EXP( ) displays.


EXP( ) Example

The following example uses EXP( ) to determine the exponential of several values:

SET DECIMALS TO 6
? EXP(1)            && Returns 2.718282;
                       the value of e
? EXP(0)            && Returns 1.000000
? EXP(-1)           && Returns 0.367879
? EXP(-10)          && Returns .000045
? EXP(-50)          && Returns 0.000000

The following example shows how to calculate 25*25 using e and natural logarithms:

dec = SET("DECIMALS")
SET DECIMALS TO 2
x = 25
y = LOG(x) + LOG(x) && y = 6.44
? EXP(y)            && Returns 625.00
SET DECIMALS TO dec


See Also

LOG( )

LOG10( )

SET DECIMALS


EXTERN

See Also	Example	Portability	Windows Programming

Declares a prototype for a non-dBASE function contained in a DLL file.

Syntax

EXTERN [CDECL] <return type> <function name>
([<parameter type list>])
[<path>] <filename>

or

EXTERN [CDECL] <return type> <user-defined function name>
([<parameter type list>])
[<path>] <filename>
FROM <export function name> | <ordinal number>

Since you create a function prototype with EXTERN, parentheses are required as with other functions. Parentheses affect the way data types are promoted and converted.

CDECL

Makes EXTERN use the C calling convention. If you omit CDECL, dBASE uses the Pascal calling convention. (See the following table.)

<function name>

The export name of the function. The export name of an external function is contained in the .REF file associated with the DLL file that holds the function.

<return type> and <parameter type>

Specifies the data type of the value returned by the function, and the data type of each argument you send to the function, respectively. The following table lists the keywords you can use.

	Keyword	dBASE  data type	C data type	Pascal  data type	ASM  data type
Parameters or return values	CDOUBLE	Numeric	long double (80 bit)	Double	N/A
	CHANDLE	Numeric	Handles, such as HANDLE, HWND, HFONT, HDC	Handles, such as Hwnd, HFont, HDC	dw
	CINT	Numeric	int	Integer	dw (16 bit)
	CLOGICAL	Logical	short Int	Integer	dw (16 bit)
	CLONG	Numeric	long int (32 bit)	Long Int	dd (32 bit)
	CSTRING	Character	char far * (zero terminated)	PChar	dw (16 bit)
	CVOID	N/A	void	Procedure	N/A
	CWORD	Numeric	short int (16 bit)	WORD	dw (16 bit)
Parameters only	CPTR	N/A	void *	Pointer	dd (32 bit)
For example, a C function may expect a 32-bit unsigned long value as a parameter, and return a char * string. In your EXTERN command, you specify CLONG as the parameter in <parameter type list> and CSTRING as the <return type>. When you call the function, you pass a dBASE numeric variable and store the returned value to a character variable.

<user-defined function name>

The name you give to the external function instead of the export name. When you specify <user-defined function name> (instead of <function name>), you must use the FROM <expC> | <expN> clause to identify the function in the DLL file.

FROM <export function name> | <ordinal number>

Identifies the function in the DLL file specified by <filename>. <export function name> identifies the function by its name, which is stored in the .DEF file that is associated with the DLL file. <ordinal number> identifies the function with a number, which is also stored in the .DEF file.

When the function you call does not return a value, specify CVOID for <return type>.

<filename>

The name of the DLL file in which the external function is stored. This name must include the extension if the DLL file is not already in memory. The file name of any DLL that you load in memory must be unique; for example, you cannot load SCRIPT.DLL and SCRIPT.FON into memory concurrently, even though they have different file-name extensions.

If the DLL file is not already loaded into memory, EXTERN loads it automatically. If the DLL file is already in memory, EXTERN increments the reference counter once. Therefore, it is not necessary to execute LOAD DLL before using EXTERN.

The reference counter is incremented only once per dBASE session, regardless of how many times you execute the LOAD DLL and EXTERN commands.

<path>

The directory path to the DLL file in which the external function is stored. When you omit <path>, dBASE looks in the following directories for the DLL by default:

1.	The current directory.

2.	The Windows directory (for example, C:\WINDOWS).

3.	The Windows SYSTEM subdirectory (for example, C:\WINDOWS\SYSTEM).

4.	The directory containing DBASEWIN.EXE, or the directory in which the .EXE file of your compiled program is located.

5.	The directories in the current DOS path.

6.	The directories mapped for search in a network.

The <path> specification is necessary only when the DLL file is not in one of these directories.

Description

Use EXTERN to declare a prototype for an external function written in a language other than dBASE. A prototype tells dBASE to convert its arguments to data types the external function can use, and to convert the value returned by the external function into a data type dBASE can use.

To call an external DLL function, first prototype it with EXTERN. Then, using the name of the function you specified with EXTERN, call the function as you would any dBASE function. You must prototype an external function before you can call that function in your dBASE program.

The external function is held in a C library such as Windows API or a customized DLL file you create in C, Pascal, or ASM. (For more information on using EXTERN and DLL files, see Chapter 25 in the Programmer's Guide.) Although most library code is contained in files with extensions of .DLL, such code can be held in .EXE files, or even in .DRV or .FON files.


EXTERN Example

The following example is a dBASE program that uses EXTERN to call a C program (cSample1.PRG). Explanations of included functions are as follows:

* Reverse():
*   Uses the FROM option to specify a new name for
*   the function (StrRevC) in the .DLL that has the
*   ordinal number 2.  In this example the var
*   myString is passed by reference, it is then
*   modified by the function StrRevC() in the dll
*   and the modified string is then displayed in
*   dBASE.
* GetDOSEnv():
*   This example shows returning a address of a
*   String to display in dBASE from a .dll, the
*   String is one of the DOS Environment strings.
* GetDOSEnvNum():
*   This example shows returning a number to dBASE
*   from a .dll, the number is the number of null
*   terminated strings in the DOS Environment. Use
*   this first to find how many strings to get from
*   GetDOSEnv().
* GetDOSEnvLen():
*   This example shows returning a number to dBASE
*   from a .dll, the number is the length of all the
*   strings in the DOS Environment.
***************************************************
CLEAR
EXTERN CVOID   Reverse(CSTRING) cSample1.dll FROM 2
* 2 is the ORDINAL number in the DLL cSample.dll
EXTERN CSTRING GetDOSEnv(CWORD) cSample1.dll
EXTERN CWORD   GetDOSEnvLen()   cSample1.dll
EXTERN CWORD   GetDOSEnvNum()   cSample1.dll
myString = "AbCdE"
? "Original Str: ",myString
Reverse(myString)
? "From StrRevC: ",myString
nSize=GetDOSEnvLen()
? "The Size of the DOS Environment Sting is: ",nSize
?
? "The DOS Environment is:"
FOR i = 1 to GetDOSEnvNum()   && for 1 to Number of;
                                 Strings in DOS Env
   ? GetDOSEnv(i)             && print each String;
                                 from the DOS Env
NEXT

The C source code for creating the .DLL file is as follows: (cSample1.C)

#include <windows.h>
#include <string.h>
#pragma argsused
int FAR PASCAL LibMain(HINSTANCE hInstance,
  WORD wDataSeg, WORD wHeapSize, LPSTR lpszCmdline){
         if (wHeapSize > 0) UnlockData (0) ;
         return 1;}
#pragma argsused
int FAR PASCAL WEP(int wParameter) {
         return 1;}
/* ########################################
   ##  Function StrRevC()                ##
   ########################################*/
#pragma argsused
void FAR PASCAL StrRevC(LPSTR lpstrString) {
          strrev(lpstrString);}
/* ########################################
   ##  Functions related to  GetDOSEnv() ##
   ########################################*/
#pragma argsused
LPSTR FAR PASCAL GetDOSEnv(UINT index) {
        LPSTR p;
        UINT  i;
          for(i=1,p=GetDOSEnvironment();
            i<index && *p != '\0';
            p += (lstrlen(p)+1),++i);
          return p;}
#pragma argsused
UINT FAR PASCAL GetDOSEnvLen(void) {
        return (UINT)
        (GetDOSEnv((UINT)-1) - GetDOSEnv(1)) + 1;}
#pragma argsused
UINT FAR PASCAL GetDOSEnvNum(void) {
        LPSTR p;
        UINT  i;
        for(i=0,p=GetDOSEnvironment(); *p != '\0';
          p += (lstrlen(p)+1),++i);
        return i;}

The C source code for creating the .DEF file is as follows(cSample1.DEF):

LIBRARY        CSAMPLE1
DESCRIPTION    'A Sample DLL for dBASE for Windows'
EXETYPE        WINDOWS
CODE           PRELOAD MOVEABLE DISCARDABLE
DATA           PRELOAD SINGLE
HEAPSIZE       1400

EXPORTS
               WEP               @1
               STRREVC           @2
               GETDOSENV         @3
               GETDOSENVLEN      @4
               GETDOSENVNUM      @5

The following section demonstates the FROM option of EXTERN (using the name of the function in the .DLL): This code segment displays a messagebox with an 'i' icon, title of 'MyBox', message of 'Hello World', and 2 buttons, 'OK' and 'Cancel'.

EXTERN CWORD MyBox(CHANDLE,CSTRING,CSTRING,CWORD);
  user.exe FROM "MessageBox"
? MyBox(0,"Hello World","MyBox",65)

Example 2: Calling a PASCAL dll. In this example the variable myString is passed by reference. It is then modified by the function StrRevP( ) in the dll and the modified string is returned.

* dBASE Program (pStrRev.PRG)
EXTERN CVOID StrRevP(CSTRING) pStrRev.dll
myString = "ABCD"
StrRevP(myString)
? myString

DLL Source Code (pStrRev.PAS)

Library pStrRev;
Uses
  Strings;
Function StrRevP(str : PChar) : PChar; Export;
Var
  endstr : PChar;
  ch     : Char;
Begin
  StrRevP := str;
  If Assigned(str) And (str^ <> #0) Then
    Begin
      endstr := StrEnd(str);
      Dec(endstr);
      While endstr > str Do
        Begin
          ch := str^;
          str^ := endstr^;
          endstr^ := ch;
          Inc(str);
          Dec(endstr)
        End
    End
End;
Exports
  StrRevP Index 1;
Begin
End.


Portability

Not supported in dBASE IV or dBASE III PLUS.


See Also

LOAD DLL

RELEASE DLL


FCLOSE( )

See Also	Example	Portability	Low-Level Access

Closes a file previously opened with FCREATE( ) or FOPEN( ). Returns .T. if successful, .F. if unsuccessful.

Syntax

FCLOSE(<file handle expN>)

<file handle expN>

The file handle number of the file to close. When you open a file with FCREATE( ) or FOPEN( ), these functions return a file handle number. Use this number as <file handle expN>. If you specify a file handle number that has not previously been returned by FCREATE( ) or FOPEN( ), dBASE returns an error message.

Description

FCLOSE( ) closes a file you have opened with FCREATE( ) or FOPEN( ). FCLOSE( ) returns .T. if it is able to close the file. If the file is no longer available (for example, the file was on a floppy disk that has been removed) and there is data in the buffer that has not yet been written to disk, FCLOSE( ) returns .F.

FCLOSE( ) does not close files that were opened by any means other than FCREATE( ) or FOPEN( ).

To close all open files, including those opened with FCREATE( ) and FOPEN( ), use CLOSE ALL or CLEAR ALL. To save the file to disk without closing it, use FFLUSH( ).


FCLOSE( ) Example

The following example uses FCLOSE( ) to close the README.TXT file after adding text:

IF FILE("C:\DBASEWIN\README.TXT")
Handle=FOPEN("README.TXT","RW")   && Opens Read-Write
FSEEK(Handle,0,2)                 && Move to EOF
FPUTS(Handle,"The End")           && Write to file
  IF .NOT. FCLOSE(Handle)         && Try closing file
    ? "Couldn't close the file"
    ? "The DOS error number is:", FERROR()
  ENDIF
ENDIF


Portability

Not supported in dBASE III PLUS.


See Also

CLEAR ALL

CLOSE...

FCREATE( )

FERROR( )

FFLUSH( )

FOPEN( )


FCREATE( )

See Also	Example	Portability	Low-Level Access

Creates and opens a specified file. Returns the file handle number of the file if successful or -1 if unsuccessful.

Syntax

FCREATE(<filename expC>[, <access expC>] )

<filename expC>

The name of the file to create and open and whose file handle number to return. By default, FCREATE( ) creates the file in the current directory. To create the file in another directory, specify a full path name for <filename expC>.

<access expC>

The access level of the file to create, as shown in the following table. Write means you can change (overwrite) data in the file, and append means you can add data to the end of the file. If you try to overwrite data in a file that has append access but not write access, the data is added to the end of the file.

<access expC>	Access level
not supplied	Read, write, and append
"R"	Read-only
"W"	Write-only
"A"	Append-only
"RW" or "WR"	Read and write
"AR" or "RA"	Read and append
"AW" or "WA"	Write and append
Description

Use FCREATE( ) to create a file with a name you specify, assign the file the level of access you specify, open the file, and return the file handle number DOS assigns to the file. If dBASE cannot create the file (for example, if the file is already open), FCREATE( ) returns -1.

SET SAFETY has no effect on FCREATE( ). If <filename expC> already exists, it is overwritten without warning. To see if a file with the same name already exists, use FILE( ) before issuing FCREATE( ).

To use other low-level functions, such as FREAD( ) and FWRITE( ), first open a file with FCREATE( ) or FOPEN( ). Both FCREATE( ) and FOPEN( ) return the file handle number you need to pass to other low-level functions.

When you open a file with FCREATE( ), the file pointer is positioned at the first character in the file. Use FSEEK( ) to position the file pointer before reading from or writing to a file.


FCREATE( ) Example

The following example uses FCREATE( ) to create a file named JACK.TXT with Read and Append access levels:

Filename="Jack.TXT"
? FILE(Filename)    && Returns .F.;
                    file does not currently exit
Handle=FCREATE(Filename,"RA")
IF Handle>0
  FPUTS(Handle,"This is a test file.")
  FCLOSE(Handle)
  FOPEN(Filename)
  ? FGETS(Handle)   && Returns "This is a test file."
ENDIF
WAIT
CLEAR ALL


Portability

Not supported in dBASE III PLUS.


See Also

FCLOSE( )

FERROR( )

FGETS( )

FILE( )

FOPEN( )

FREAD( )

FSEEK( )

SET ALTERNATE

SET DEVICE

SET SAFETY


FDATE( )

See Also	Example	Portability	Disk and File Utilities

Returns the date stamp for the specified file.

Syntax

FDATE(<filename expC>)

<filename expC>

The name of the file to evaluate. Wildcard characters are not supported.

If you specify a file without including its path, dBASE looks for the file in the current directory, then in the path you specify with SET PATH. If you specify a file without including its extension, dBASE does not assume an extension.

Description

Use FDATE( ) to determine the date on which the last change was made to a file on disk.

When you update a file, dBASE changes the file's date stamp to the current operating system date when the file is written to disk. For example, when the user edits a table, dBASE changes the date stamp on the table file when the file is closed. FDATE( ) reads the date stamp and returns its current value.

If the file that you want to evaluate has an extension, you must include that extension in <filename expC>. If the file is not on the default drive you must specify a drive designation, and if the file is not in the current directory or in the path you specify with SET PATH, you must specify the directory path.

If dBASE cannot find the file, it returns an error. Therefore, you may want to test for its existence with FILE( ) before issuing FDATE( ). FLUSH does not update a file's time stamp.

If <filename expC> is present in the current directory and also exists in the SET PATH directory, FDATE(<filename expC>) (without path information) returns information on the file in the current directory.


FDATE( ) Example

This example compares the date and time stamps on COMPANY.DBF and its backup on the B drive. If the backup is dated earlier than the current table then a backup is recommended:

IF FDATE("B:Company.dbf")< FDATE("Company.dbf");
    .AND.;
    FTIME("B:Company.dbf") < FTIME("Company.dbf")
  ? "Time to do a backup"
  Difference= ;
    FDATE("Company.dbf") - FDATE("B:Company.dbf")
  ? Difference, " days since last backup"
  WAIT
ENDIF


Portability

Not supported in dBASE III PLUS.


See Also

FILE( )

FLUSH

FSIZE( )

FTIME( )

SET DIRECTORY

SET PATH


FDECIMAL( )

See Also	Example	Portability	Fields and Records

Returns the number of decimal places in a specified field of a table.

Syntax

FDECIMAL(<field number expN> [, <alias>] )

<field number expN>

The position of the field that you want to evaluate.

<alias>

A work area number (1 through 225), letter (A through J), or alias name. The work area letter or alias name must be enclosed in quotes.

Description

FDECIMAL( ) returns the number of decimal places in a specified field of a table. FDECIMAL( ) returns zero if the field has no decimal places or if the table does not contain a field in the specified position. FDECIMAL( ) returns an error if you specify a non-numeric field.

Fields in the table are numbered from 1 to 1024 based on their position in the table structure. If you do not specify a work area, FDECIMAL( ) evaluates the table in the current work area.


FDECIMAL( ) Example

The following example uses FDECIMAL( ) to return the number of decimal places in the numeric field StartBal of the Clients table:

CLEAR
SET TALK OFF
USE Clients
DISPLAY STRUCTURE      && StartBal is field number 11
STORE FDECIMAL(11,1) TO m_places
? FIELD(11) + " has " + LTRIM(STR(m_places)) + ;
  " decimal places."   && Returns a value of 2
SET TALK ON

See FLENGTH( ) for another example of FDECIMAL( ).


Portability

Not supported in dBASE IV and dBASE III PLUS.


See Also

FIELD( )

FLENGTH( )


FEOF( )

See Also	Example	Portability	Low-Level Access

Returns .T. if the file pointer is at the end of a file previously opened with FCREATE( ) or FOPEN( ).

Syntax

FEOF(<file handle expN>)

<file handle expN>

The file handle number of the file whose file-pointer position to determine. When you open a file with FCREATE( ) or FOPEN( ), these functions return a file handle number. Use this number as <file handle expN>. If you specify a file handle number that has not previously been returned by FCREATE( ) or FOPEN( ), dBASE returns an error message.

Description

FEOF( ) determines if the file pointer of the file you specify is at the end of the file (EOF), and returns .T. if it is. The file pointer is considered to be at EOF if it is positioned at the byte after the last character in the file.

You can move the file pointer to the end of the file with FSEEK( ). For example, FSEEK(fnum,0,2) moves the file pointer to the end of the file whose file handle number is stored in the variable fnum.


FEOF( ) Example

The following example opens the README.TXT file and displays or prints the file one line at a time until reaching the end of the file:

SET PATH TO C:\DBASEWIN
Handle=FOPEN("Readme.TXT","R")    && Opens, read only
SET PRINTER ON                    && optional
DO WHILE .NOT. FEOF(Handle)       && loops until EOF
  ? FGETS(Handle)                 && sends 1 line to;
                                  display or printer
ENDDO
SET PRINTER OFF


Portability

Not supported in dBASE III PLUS.


See Also

FCLOSE( )

FCREATE( )

FERROR( )

FOPEN( )

FSEEK( )


FERROR( )

See Also	Example	Portability	Low-Level Access

Returns the error number of the most recent low-level input or output error, or 0 if the most recent low-level function was successful.

Syntax

FERROR( )

Description

Use the number that FERROR( ) returns in an error-handling routine to respond to low-level errors. The following table lists the low-level function errors that FERROR( ) returns.

Error number	Cause of error
2	File or directory not found
3	Bad path name
4	No more file handle numbers available
5	Cannot access file
6	Bad file handle
8	No more directory entries available
9	Error trying to set the file pointer
13	No more disk space
14	End of file


FERROR( ) Example

The following example attempts to open a file with FOPEN( ) when the file name is misspelled. The IF/ELSE branch uses FERROR( ) to return the DOS error message that was returned when FOPEN( ) failed:

SET PATH TO C:\DBASEWIN
Filename="Reedme.TXT"
* Filename misspelled
IF FOPEN(Filename) = -1
* Returns -1 if open or not successful
  ? "The DOS error number is: ", LTRIM(STR(FERROR()))
* FERROR() returns 2 - File or directory not found
ENDIF
RETURN


Portability

Not supported in dBASE III PLUS.


See Also

FCLOSE( )

FCREATE( )

FEOF( )

FFLUSH( )

FGETS( )

FOPEN( )

FPUTS( )

FREAD( )

FSEEK( )

FWRITE( )

ON ERROR


FFLUSH( )

See Also	Example	Portability	Low-Level Access

Writes to disk a file previously opened with FCREATE( ) or FOPEN( ), without closing the file. Returns .T. if successful, .F. if unsuccessful.

Syntax

FFLUSH(<file handle expN>)

<file handle expN>

The file handle number of the file to write to disk. When you open a file with FCREATE( ) or FOPEN( ), these functions return a file handle number. Use this number as <file handle expN>. If you specify a file handle number that has not previously been returned by FCREATE( ) or FOPEN( ), dBASE returns an error message.

Description

Use FFLUSH( ) to save a file in the file buffer to disk, flush the file buffer, and keep the file open. If FFLUSH( ) is successful, it returns .T.

Flushing a buffer to disk is similar to saving the file and continuing to work on it. Until you flush an open file buffer to disk, any data in the buffer is stored only in RAM (random-access memory). If the power to the computer fails or dBASE ends abnormally, data in RAM is lost. However, if you have used FFLUSH( ) to write the file buffer to disk, you lose only data that was added between the time you issued FFLUSH( ) and the time the system failed.

To save the file to disk and close the file, use FCLOSE( ).


FFLUSH( ) Example

The following example creates a file named JACK.TXT, inputs a text string into the file and writes to disk with FFLUSH( ) without closing the file. FPUTS( ) adds additional text which is subsequently displayed with the DO WHILE .NOT. FEOF( ) loop:

Handle=FCREATE("Jack.TXT","RW")
Filename="Jack.Txt"
FPUTS(Handle,"Borland means")     && Text to file
FFLUSH(Handle)                    && Saved to disk;
                                  file still open
FSEEK(Handle,0,0)                 && Move pointer to;
                                  beginning of file
? FGETS(Handle)                   && Displays text
WAIT                              && Pauses program
CLEAR                             && Clears screen
FPUTS(Handle,"Quality in Software Craftsmanship");
                                  && Appends text
FCLOSE(Handle)                    && Close Jack.TXT
Handle =FOPEN(Filename,"R")       && Reopen file
DO WHILE .NOT. FEOF(Handle)
  ? FGETS(Handle)                 && Display contents
ENDDO
RETURN


Portability

Not supported in dBASE III PLUS.


See Also

FCLOSE( )

FCREATE( )

FEOF( )


FGETS( )

See Also	Example	Portability	Low-Level Access

Returns a character string from a file previously opened with FCREATE( ) or FOPEN( ).

Syntax

FGETS(<file handle expN> [, <characters expN>] [, <end-of-line exp>])

<file handle expN>

The file handle number of the file whose characters to read and return. When you open a file with FCREATE( ) or FOPEN( ), these functions return a file handle number. Use this number as <file handle expN>. If you specify a file handle number that has not previously been returned by FCREATE( ) or FOPEN( ), dBASE returns an error message.

<characters expN>

The number of characters to read and return before a carriage return is reached. Acceptable values are 0 to 32766; if <characters expN> is less than 0 or greater than 32766, dBASE uses 0 or 32766, respectively.

<end-of-line exp>

The end-of-line indicator, which can be one or two characters. The following table lists standard codes for use as end-of-line indicators. Do not enclose them in quotes. You can combine two characters with a plus (+) sign, for example, CHR(141) + CHR(138).

<end-of-line exp>	Represents
not supplied	Hard CR/LF (0D0A Hex)
CHR(141)	Soft carriage return (U.S.) (8D Hex)
CHR(255)	Soft carriage return (Europe) (FF Hex)
CHR(138)	Soft linefeed (U.S.) (8A Hex)
CHR(0)	Soft linefeed (Europe) (00 Hex)
CHR(13)	Hard carriage return (0D Hex)
CHR(10)	Hard linefeed (0A Hex)
You cannot enter hexadecimal numbers directly for <end-of-line exp>, but you can combine them by adding their decimal equivalents. For example, 0D0A Hex equals CHR(13) + CHR(10); CHR(13) is 0D Hex, and CHR(10) is 0A Hex. Use HTOI( ) to convert a Hex number to its decimal equivalent.

Description

FGETS( ) reads and returns a character string from the file you specify, starting at the file pointer position and continuing up to but not including the first end-of-line character it encounters. If you do not specify a number of characters to return with <characters expN>, the maximum number of characters FGETS( ) can return is 32766. If FGETS( ) encounters the end-of-line character before reading the number of characters you specify with <characters expN>, it returns the number of characters before the end-of-line character.

FGETS( ) truncates the return string at the first 00 hexadecimal character, CHR(0), it encounters. If you think the file contains 00 hexadecimal characters, use FREAD( ) and read one byte at a time to locate them.

FGETS( ) returns an empty string ("") if it is unsuccessful, such as when the file pointer is at the end of the file. Use FEOF( ) and FERROR( ) to determine if the file pointer is at the end of the file or if another condition exists which would prevent FGETS( ) from returning a value.

If FGETS( ) encounters an end-of-line character, it positions the file pointer at the character after that character. Otherwise, FGETS( ) positions the file pointer at the character after the last character it returns. Use FSEEK( ) to move the file pointer before or after using FGETS( ).

Except for one feature, FREAD( ) and FGETS( ) are identical; FREAD( ) returns end-of-line characters while FGETS( ) does not. That is, if FGETS( ) encounters an end-of-line character, it stops reading, even if it has not yet read <characters expN> characters. FREAD( ), on the other hand, includes end-of-line characters in the string it returns.


FGETS( ) Example

The following example creates a text file named TEST.TXT and appends 9 lines of the string "123456789". The program then uses FGETS( ), in combination with a character counter (Cnt) and a line counter (Cnt2), to output 9 progressively longer lines of text starting with 1 character and increasing to the full 9 character string. FSEEK( ) and Cnt2 incremented in 11 byte intervals positions the file pointer at each successive line:

nHandle=FCREATE("Test.TXT","RW")  && Create file
* Input text data
FOR i=1 TO 9                      && Loop for 9 lines
  FPUTS(nHandle,"123456789")      && Append text
NEXT i                            && Increment Cnt
* Output text data
FSEEK(nHandle,0,0)                && Moves pointer;
                                     to top of file
CLEAR                             && Clear results pane ;
                                     of the Command window
Cnt=1
Cnt2=11                           && 11 bytes/line
DO WHILE .NOT. FEOF(nHandle)
  ? FGETS(nHandle,Cnt)            && Display string;
                                     of length Cnt
  FSEEK(nHandle,Cnt2)             && Position pointer
  Cnt=Cnt+1                       && Increment Cnt
  Cnt2=Cnt2+11                    && Increment Cnt2
ENDDO
FCLOSE(nHandle)                   && Close Test.TXT


Portability

Not supported in dBASE III PLUS.


See Also

FCREATE( )

FEOF( )

FERROR( )

FOPEN( )

FPUTS( )

FREAD( )

FSEEK( )

HTOI( )


FIELD( )

See Also	Example	Fields and Records

Returns the name of the field in a specified position of a table.

Syntax

FIELD(<field number expN> [, <alias>])

<field number expN>

The position of the field whose name you want returned.

<alias>

A work area number (1 through 225), letter (A through J), or alias name. The work area letter or alias name must be enclosed in quotes.

Description

FIELD( ) returns the name of a field in a table based on the specified <field number expN> parameter. Fields are numbered from 1 to 1024 based on their position in the table structure.

If you do not specify a work area, FIELD( ) returns the name of the field in the current table. FIELD( ) returns an empty string ("") if the table does not contain a field in the specified position.


FIELD( ) Example

The following example uses FIELD( ) to return names of the fields in a table to generate a data entry form. This code could be used as a generic data entry procedure when the table is undetermined:

SET TALK OFF
CLEAR
USE Clients                  && Use any table
APPEND BLANK
Fldcnt=1
DO WHILE LEN(FIELD(Fldcnt))<>0
     mField=FIELD(Fldcnt)
     @ ROW()+1,0 SAY mField+;
     REPLICATE(".",25-LEN(mField)) GET &mField
     Fldcnt = Fldcnt + 1
ENDDO
READ
CLEAR
SET TALK ON


See Also

DBF( )

FLENGTH( )


FILE( )

See Also	Example	Disk and File Utilities

Tests for the existence of a file. Returns .T. if the file exists and .F. if it does not.

Syntax

FILE(<filename expC>)

<filename expC>

The name of the file that is searched for. Wildcard characters are not supported.

If you specify a file without including its path, dBASE looks for the file in the current directory, then in the path you specify with SET PATH. If you specify a file without including its extension, dBASE does not assume an extension.

Description

Use FILE( ) to determine whether a file exists.

If the file that you want to search for has an extension, you must include that extension in <filename expC>. If the file is not on the default drive, you must specify a drive designation, and if the file is not in the current directory or in the path you specifiy with SET PATH, you must specify the directory path.


FILE( ) Example

The following examples use FILE( ):

? FILE("C:\Command.com") && .T.
? FILE("Company.dbf")    && .T.
? FILE("Bak\Nosuch")     && .F.

FILE( ) is often used to test for the existence of a table before opening it:

DO WHILE .NOT. FILE("B:Company.dbf")
  ? "Insert the back up disk in drive B"
  WAIT
ENDDO
USE B:Company


See Also

DIR

DISPLAY FILES

GETFILE( )

PUTFILE( )

SET DIRECTORY

SET PATH


FIND

See Also	Example	Table Organization

Locates the first record of an indexed table whose key value matches the specified key value.

Syntax

FIND <search key literal>

<search key literal>

Part or all of the index key value of a record to search for. Do not enclose <search key literal> in quotes (single or double) or square brackets.

Description

The FIND command positions the record pointer to the first record in an indexed table that matches the specified literal key value. FIND can search only for characters or a numeric or float value contained in the index key field. The match with the index key must be exact if SET EXACT is ON.

An indexed search is similar to looking up a topic in a book index and turning directly to the appropriate page. Once an index is created, FIND or SEEK can use it to quickly identify appropriate records.

FIND begins searching at the top of the index and stops when either a match is found or the end of the index is reached. If a match is found (FOUND( ) returns .T.), the record pointer of the associated table is positioned at the record containing the match.

Other records whose key field matches the specified characters or number can be accessed by using SKIP. SKIP advances the record pointer to the next indexed record, which includes other records with matching key fields if they exist.

Unlike using the CONTINUE command following the LOCATE command, SKIP does not search for a match; it moves the pointer one record whether or not you skipped to a record that matches the FIND argument.

If FIND is unsuccessful, dBASE returns the message Find not successful and positions the record pointer beyond the last record of the index. (EOF( ) is .T.; FOUND( ) is .F.)

Unless the key field contains leading spaces, the command-line argument need not be delimited (enclosed in single or double quotation marks or brackets). The entered expression is considered to start with the first nonblank character. However, if you are searching for a key containing leading spaces, delimiters must be used. Within the delimiters, enter the exact character string, including leading spaces. You can also store a literal character string or numeric value in a memory variable and use the memory variable to specify the search expression in the FIND command.

The search commands FIND, SEEK, and LOCATE are designed for different situations. FIND and SEEK conduct more rapid searches than LOCATE, but can be used only in limited situations. Both require an indexed file and can search only for values of the key expression. SEEK offers greater flexibility than FIND by accepting any expression.

If the information you are searching for is in an unindexed file or is not contained in the key field of an indexed file, use LOCATE. LOCATE accepts an expression of any data type as input and can search any field of a table for that value. For large tables, a sequential search using LOCATE can be slow. In such cases, use INDEX to create a new index, and then use SEEK or FIND.


FIND Example

The following example uses FIND to locate the first occurrence of a company in Illinois:

USE Company EXCLUSIVE
INDEX ON State_Prov TAG State
FIND IL  && Find the first Illinois record
IF FOUND()
   ? "All Companies in Illinois"
   LIST FIELDS Company, State_Prov ;
     WHILE State_Prov="IL"
ELSE
   ? "Illinois was not  found"
ENDIF


See Also

CONTINUE

EOF( )

FOUND( )

LOCATE

SEEK

SEEK( )

SET EXACT

SKIP


FKLABEL( )

See Also	Example	Portability	Keyboard and Mouse Events

Returns the name of a programmable function key.

Syntax

FKLABEL(<expN>)

<expN>

The programmable function key whose name to return. Use FKLABEL(0) to return the value of the first programmable function key, FKLABEL(1) to return the second, etc.

Description

Use FKLABEL( ) to return the name assigned to a function key by the current system. You can then use the returned value with SET FUNCTION, SET KEY, or ON KEY LABEL to assign a statement or command to a function key.

Since different computer manufacturers give different names to function keys, your application may lack portability if you reference a function key by name. FKLABEL( ) extracts the function key's name from the current system, ensuring that the name is correct when you move your application from system to system.

On most IBM-compatible computers, programmable function keys include F1 to F10, Ctrl+F1 to Ctrl+F10, and Shift+F1 to Shift+F10. In dBASE for Windows, you can also program Alt+F1 to Alt+F10 with ON KEY or SET KEY. dBASE for Windows does not support assigning values to F11 or F12.


FKLABEL( ) Example

The following examples use FKLABEL( ) in the SET FUNCTION command:

SET FUNCTION FKLABEL(1) TO "hello there"
SET FUNCTION FKLABEL(2) TO "DO MySub;"
* Pressing F2 is equivalent to
*  typing "hello there"
* Pressing F3 will call subroutine MySub

Notice that:

? FKLABEL(0)         &&  returns F1
? FKLABEL(9)         &&  returns F10
? FKLABEL(10)        &&  returns CTRL-F1
? FKLABEL(19)        &&  returns CTRL-F10
? FKLABEL(20)        &&  returns SHIFT-F1
? FKLABEL(29)        &&  returns SHIFT-F10


See Also

FKMAX( )

ON KEY

SET FUNCTION

SET KEY


FKMAX( )

See Also	Example	Keyboard and Mouse Events

Returns the number of programmable function keys.

Syntax

FKMAX( )

Description

Different computer manufacturers provide different sets of function keys, and you may need to allow for this when you transfer your application to other systems. FKMAX( ) detects how many function keys are available in the current system, letting you provide for alternative function key assignments when a particular system lacks certain function keys. Function key assignments are made with SET FUNCTION, SET KEY, and ON KEY LABEL.

On most IBM-compatible computers, programmable function keys include F1 to F10, Ctrl+F1 to Ctrl+F10, and Shift+F1 to Shift+F10. In dBASE for Windows, you can also program Alt+F1 to Alt+F10 with ON KEY or SET KEY. dBASE for Windows does not support programming F11 or F12.


FKMAX( ) Example

STORE FKMAX() TO Keycount


See Also

FKLABEL( )

ON KEY

SET FUNCTION

SET KEY


FLDCOUNT( )

See Also	Example	Fields and Records

Returns the number of fields in a table.

Syntax

FLDCOUNT( [<alias>] )

<alias>

A work area number (1 through 225), letter (A through J), or alias name. The work area letter or alias name must be enclosed in quotes.

Description

FLDCOUNT( ) returns the number of fields in the current or a specified table. If you do not specify a work area, the current work area is assumed. FLDCOUNT( ) returns a value of 0 if no table is open in the specified work area.


FLDCOUNT( ) Example

The following example uses FLDCOUNT( ) to return the number of fields in two tables to derive a total field count for a one dimensional array that stores the field names of both tables:

SET TALK OFF
USE Company IN 1
Fldcnt = FLDCOUNT(1)
USE Contact IN 2
Fldcnt = Fldcnt + FLDCOUNT(2)
DECLARE Fld_Arr[Fldcnt]
x = 1
FOR Select = 1 TO 3
   FOR x_fld = 1 TO FLDCOUNT(Select)
      fld_arr[x] = FIELD(x_fld,Select)
      x = x + 1
   NEXT
NEXT
Cnt = 1
DO WHILE Cnt <= FldCnt     && Displays array contents
  ? Fld_arr[Cnt]
  Cnt=Cnt+1
ENDDO
SET TALK ON
CLOSE ALL
CLEAR ALL


See Also

FIELD( )

DISPLAY STRUCTURE

LIST STRUCTURE

RECCOUNT( )

TYPE( )


FLDLIST( )

See Also	Example	Portability	Fields and Records

Returns the fields and calculated field expressions of a SET FIELDS TO list.

Syntax

FLDLIST( [<field number expN>] )

<field number expN>

The position of the field or calculated field expression in a SET FIELDS TO list whose name you want returned. If you do not specify a field number, FLDLIST( ) returns the entire field list, up to 254 characters.

Description

FLDLIST( ) returns the field or calculated field expression in a SET FIELDS TO list that corresponds to a specified field number. If you do not specify a field number, FLDLIST( ) returns the entire field list, up to 254 characters; remaining characters are truncated. Each field name or expression in the field list is separated by a comma. FLDLIST( ) always returns fully-qualified field names, that is, it includes the table or alias name. For read-only fields, FLDLIST( ) appends "/R" to the field name.

FLDLIST( ) returns a value even if SET FIELDS is OFF. If the specified field number exceeds the number of items in the field list, FLDLIST( ) returns an empty string ("").


FLDLIST( ) Example

The following example demonstates using FLDLIST( ) with and without an alias value:

USE Company IN 1
USE Contact Alias Reps IN 2
SELECT 1
SET FIELDS TO Company, City
? FLDLIST(1)          && Returns Company->Company
SELECT 2
SET FIELDS TO CompCode, Contact
? FLDLIST(1)          && Returns Company->Company
? FLDLIST(2)          && Returns Company->City
? FLDLIST(3)	      && Returns Reps->CompCode
? FLDLIST()           && Returns full list


Portability

Not supported in dBASE III PLUS.


See Also

SET FIELDS


FLENGTH( )

See Also	Example	Portability	Fields and Records

Returns the length of the field in a specified position of a table.

Syntax

FLENGTH(<field number expN> [, <alias>] )

<field number expN>

The position of the field whose length you want returned. Fields are numbered from 1 to 1024 according to their position in the table structure.

<alias>

A work area number (1 through 225), letter (A through J), or alias name. The work area letter or alias name must be enclosed in quotes.

Description

FLENGTH( ) returns the length of a field in a table based on the specified <field number expN> parameter. The field length for numeric and float fields includes decimal digits and 1 digit for the decimal point character. FLENGTH( ) returns 1 for date and memo fields. It returns 0 if the table does not contain a field in the specified position.

If you do not specify a work area, FLENGTH( ) returns the length of the field in the current table.


FLENGTH( ) Example

The following example uses FLENGTH( ) to return the width of the Company field (from the structure). This value is then used to compute the number of hyphens to print by subtracting the number of characters present in the field of the current record (derived from LEN(TRIM(Company)). The number 13 is then added to this amount because of the 15 space margin between columns provided by the expression AT FLENGTH(2)+15 associated with the Contact column:

USE Clients
? CENTER("List of Client Companys and Contacts")
?
SCAN
? Trim(Company)+REPLICATE("-",(FLENGTH(2)-LEN(TRIM;
  (Company))+13)), Contact AT FLENGTH(2)+15
ENDSCAN


Portability

Not supported in dBASE IV or dBASE III PLUS.


See Also

FDECIMAL( )

FIELD( )


FLOAT( )

See Also	Example	Portability	Expressions and Type Conversion

Returns a specified number as a float number.

Syntax

FLOAT(<expN>)

<expN>

A numeric or float number to return as a float number.

Description

Use FLOAT( ) to add a decimal and decimal places (as zeros) to an integer. For example, FLOAT(5) returns 5.00 if the number of decimal places you have set to display with SET DECIMAL is 2. If you pass a float type number to FLOAT( ), it returns the same number.


FLOAT( ) Example

The following example uses FLOAT( ) to ensure that the returned value will display or print 2 decimal places:

USE Country
SET DECIMALS TO 2
? CENTER("GNP Per Citizen Listed by Country ")
? CENTER("in U.S. Dollars")
?
SCAN
  ? Name AT 20, FLOAT((GNP*1000000)/Population) AT 40
ENDSCAN
RETURN


Portability

Not supported in dBASE III PLUS. In dBASE IV, FLOAT( ) converts Binary Coded Decimal (BCD) numbers to float type numbers. This functionality is not required in dBASE for Windows because it does not store numbers in BCD format.


See Also

INT( )

SET DECIMALS


FLOCK( )

See Also	Example	Portability	Shared Data

Locks the current table or a specified alias table, returning .T. if successful.

Syntax

FLOCK([<alias>])

<alias>

A work area number (1 through 225), letter (A through J), or alias name. The work area letter or alias name must be enclosed in quotes. If you don't include <alias>, FLOCK( ) locks the current table.

Description

Use FLOCK( ) to lock the current table or an alias table file, preventing others from using the table.

When you lock a table with FLOCK( ), only you can make changes to it. However, unlike USE...EXCLUSIVE and SET EXCLUSIVE ON, FLOCK( ) does let other users view the locked table while you are using it. When you lock a table with FLOCK( ), it remains locked until you issue UNLOCK or close the table.

FLOCK( ) is similar to RLOCK( ), except that FLOCK( ) locks an entire table, while RLOCK( ) lets you lock specific records of a table. Use FLOCK( ), therefore, when you need to have sole access to an entire table or related tables--for example, when you need to update multiple tables related by a common key.

All commands that change table data cause dBASE to attempt to execute an automatic record or file lock. If dBASE fails to execute an automatic record or file lock, it returns an error. You might want to use FLOCK( ) for event trapping, testing for its return value rather than for an error condition.

FLOCK( ) can lock a shared table even if another network user is viewing data contained in the table. FLOCK( ) is unsuccessful only if another user has explicitly locked the table or a record in the table, or is using a command that automatically locks the table or a record in the table.

When SET REPROCESS is set to 0 (the default) and FLOCK( ) cannot immediately lock a table, dBASE prompts you to attempt the lock again or cancel the function. Until you choose to cancel the function, FLOCK( ) repeatedly attempts to lock the table. Use SET REPROCESS to eliminate being prompted to cancel the FLOCK( ) function, or to set the number of locking attempts. If FLOCK( ) returns .F., you can reissue FLOCK( ).

When you set a relation to a parent table with SET RELATION and then lock the table with FLOCK( ), dBASE attempts to lock all child tables. For more information about relating tables, see SET RELATION.


FLOCK( ) Example

This example loops until it can lock the file with FLOCK( ) or until the user decides to stop trying:

RecordWasRead=.f.
Again=.t.
SET REPROCESS TO 10
USE Company SHARED  && exclusive off
DO WHILE Again
  IF FLOCK()        && Can dBASE Lock the file?
    DO Compmod      && Yes: Update Company.DBF
    RecordWasRead=.t.
    Again=.f.
    UNLOCK          && Allow other users to change
                    && the file.
  ELSE              && FLOCK() returns .F.
    CLEAR
    ? "Company cannot be locked."
    Wait "Try Again? " TO Ans
    IF UPPER(Ans)="Y"
      Again = .t.
    ELSE
      Again = .f.
    ENDIF
  ENDIF
ENDDO
USE
SET REPROCESS TO 0  && The default


Portability

Not supported in dBASE III PLUS.


See Also

BEGINTRANS( )

LOCK( )

RLOCK( )

SET EXCLUSIVE

SET LOCK

SET RELATION

SET REPROCESS

UNLOCK

USE


FLOOR( )

See Also	Example	Portability	Numeric Data

Returns the nearest integer that is less than or equal to a specified number.

Syntax

FLOOR(<expN>)

<expN>

A numeric or float number, from which to determine and return the integer that is less than or equal to it.

Description

FLOOR( ) returns the nearest integer that is less than or equal to <expN>. If you pass a number with any digits other than zero (0) as decimal digits, FLOOR( ) returns the nearest integer that is less than the number. If you pass an integer to FLOOR( ), or a number with only zeros for decimal digits, it returns the integer equal to the number.

For example, if the default number of decimal places is 2,

FLOOR(2.10) returns 2.00

FLOOR(-2.10) returns -3.00

FLOOR(2.00) returns 2.00

FLOOR(2) returns 2

FLOOR(-2.00) returns -2.00

Use SET DECIMALS to set the number of decimal places FLOOR( ) displays.

When you pass a positive number to it, FLOOR( ) operates exactly like INT( ). See the table in the description of INT( ) that compares INT( ), FLOOR( ), CEILING( ), and ROUND( ).

The value returned by FLOOR( ) has the same data type as <expN>.


FLOOR( ) Example

The following example uses FLOOR( ) to return the passed value, rounded down to the next whole number:

SET DECIMALS TO 2
price = 129.95
tax   = .075
total = price + (price*tax)
? "The price of the upgrade is " + STR(price,6,2)
? "     The state sales tax is " + ;
   STR(tax*100,5,2) + "%"
? "          The amount due is " + ;
   STR(total,6,2)
?
? "'NO CHANGE REQUIRED' Sale Price is " + ;
   STR(FLOOR(total),6,2)

Another example of FLOOR( ) is shown in the example for INT( ).


Portability

Not supported in dBASE III PLUS. In dBASE IV, FLOOR( ) doesn't display any decimal places, regardless of the value of SET DECIMALS.


See Also

CEILING( )

INT( )

ROUND( )

SET DECIMALS


FLUSH

See Also	Example	Portability	Fields and Records

Writes data buffers to disk and releases unallocated memory.

Syntax

FLUSH

Description

Use FLUSH to protect data integrity and maximize available memory.

When you open a table and its associated index and memo files, dBASE for Windows loads a certain number of records from the file into a memory buffer, along with the portion of each open index that pertains to those records. When the buffer is full or when you close tables or indexes (with CLOSE DATABASES, USE, CLOSE INDEXES, CLOSE ALL, or SET INDEX TO), dBASE for Windows writes the records back to disk, storing any modifications you have made. FLUSH allows you to save information from the data buffer to disk without first closing tables or indexes. FLUSH saves information in tables and associated files open in work areas other than the current work area.

Use FLUSH when you need to store critical information to disk that could otherwise be lost. However, do not use FLUSH too frequently, as it slows execution. For example, in an order-entry application in which only a few orders are entered each hour, FLUSH can save data that might be lost if the power is inadvertently turned off; since orders are entered infrequently, the time needed to execute FLUSH is not important.


FLUSH Example

The following example uses FLUSH after two different data input scenarios to clear the buffers when AUTOSAVE is set to OFF:

USE Company IN SELECT()
SELECT Company
SET AUTOSAVE OFF
APPEND BLANK
@  2, 2 SAY "Company Code" GET Company->CompCode
@  3, 2 SAY "Company Name" GET Company->Company
@  5, 8 SAY "Street" GET Company->Street1
@  6,15 GET Company->Street2
@  7,10 SAY "City" GET Company->City
@  7,35 SAY "State" GET Company->State_Prov
@  8,35 SAY "Zip" GET Company->Zip_P_Code
READ
FLUSH
CLEAR
APPEND
FLUSH
CLOSE ALL


Portability

Not supported in dBASE IV or dBASE III PLUS.


See Also

CLEAR

CLOSE...

MEMORY( )


FOPEN( )

See Also	Example	Portability	Low-Level Access

Opens a specified file. Returns the file handle number of the file if successful or --1 if unsuccessful.

Syntax

FOPEN(<filename expC> [, <access expC>])

<filename expC>

The name of the file to open and whose file handle number to return. By default, dBASE looks for the file in the current directory, then the directory specified in SET PATH. Specify a full path name for <filename expC> to open a file in another directory.

<access expC>

The access level of the file being opened, as shown in the following table. Write means you can change (overwrite) data in the file, and append means you can add data to the end of the file. If you try to overwrite data in a file that has append access but not write access, the data is added to the end of the file.

<access expC>	Access level
not supplied	Read-only
"R"	Read-only
"W"	Write-only
"A"	Append-only
"RW" or "WR"	Read and write
"AR" or "RA"	Read and append
"AW" or "WA"	Write and append
Description

Use FOPEN( ) to open a file with a name you specify, assign the file the level of access you specify, and return the file handle number DOS assigns to the file. If dBASE cannot open the file (for example, if the file is already open), FOPEN( ) returns -1.

To use other low-level functions, such as FREAD( ) and FWRITE( ), first open a file with FOPEN( ) or FCREATE( ). Both functions also provide you with the file handle number you need to pass to other low-level functions.

When you open a file with FOPEN( ), the file pointer is positioned at the first character in the file. Use FSEEK( ) to position the file pointer before reading from or writing to a file.


FOPEN( ) Example

The following example uses FOPEN( ) to open the README file located on the default install directory and sends it to the printer by using SET PRINTER ON, a FEOF( ) loop and FGETS( ):

SET PATH TO C:\DBASEWIN          && Parent directory
IF FILE("Readme.TXT")            && Check for file
  nHandle=FOPEN("Readme.TXT","R")&& Open read only
ENDIF
IF nHandle>0                     && Did file open?
  SET PRINTER TO LPT1            && Output to print
  DO WHILE .NOT. FEOF(nHandle)
    ? FGETS(nHandle)             && Return a line
  ENDDO
  SET PRINTER TO
ELSE
  ? "Unable to open file. File error #:",;
    LTRIM(STR(FERROR()))
ENDIF
IF nHandle=-1
  ? "Unable to close file.  File error #:",;
    LTRIM(STR(FERROR()))
ELSE
  IF FCLOSE(nHandle)
    ?
    ? "File closed"
  ELSE
    ? "Unable to close file. File error #:",;
      LTRIM(STR(FERROR()))
  ENDIF
ENDIF
RETURN


Portability

Not supported in dBASE III PLUS.


See Also

FCLOSE( )

FCREATE( )

FERROR( )

FILE( )

GETFILE( )

SET PATH


FOR( )

See Also	Example	Portability	Table Organization

Returns the FOR clause used to create a specified index file or tag.

Syntax

FOR( [[<.mdx filename expC>,] <index position expN> [,<alias>]] )

<.mdx filename expC>

The multiple index file that contains the index tag you want to check.

<index position expN>

The position of an index tag in an .MDX file or the position of an index file in the list of open indexes for the current or a specified table.

<alias>

A work area number (1 through 225), letter (A through J), or alias name. The work area letter or alias name must be enclosed in quotes.

Description

FOR( ) returns the FOR clause used with the INDEX command to create a specified .MDX tag for the current or specified table. The FOR( ) function evaluates the FOR clause for the master index for the current table, the index tag in a specified position within the list of open indexes for a table, or the index tag within a specified .MDX file.

If no .MDX file name is specified, FOR( ) evaluates the index in a specified position within the list of all open indexes in the same work area. The FOR( ) function first checks .NDX and production .MDX tags, then checks index tags in other .MDX files.

FOR( ) returns an empty string ("") if there is not an index tag in the specified position, the index in the specified position is an .NDX file, or the specified index tag was not created with a FOR clause. FOR( ) also returns an empty string ("") if you do not specify an index tag position and the table does not have a master index.

You can use TAGNO( ) to determine the index order number of a specified index or index tag. The order of open indexes for a specified table remains the same until you specify another index order with USE, SET INDEX, or INDEX.


FOR( ) Example

The following example uses FOR( ) to determine the conditions set in the index's FOR clause:

DELETE FILE Comptemp.mdx
* Create a temporary MDX file
USE Company EXCLUSIVE
INDEX ON CompCode ;
  TAG CompCode OF Comptemp FOR CompCode = "D"
INDEX ON Company  ;
  TAG Company  OF Comptemp
INDEX ON City     ;
  TAG City     OF Comptemp FOR Zip_Postal = "9"
?
? "Tag and For Clause"
?
? TAG(1),FOR(1)
* TAG(1) and FOR(1) return the TAG and FOR
* clause for the first index in the production
* MDX file, Company.mdx
? "1", TAG("Comptemp",1), FOR("Comptemp",1)
* FOR() clause of COMPCODE index is CompCode = "D"
? "2", TAG("Comptemp",2), FOR("Comptemp",2)
* FOR() clause of COMPANY index is empty
? "3", TAG("Comptemp",3), FOR("Comptemp",3)
* FOR() clause of CITY index is Zip_Postal="9"


Portability

Not supported in dBASE III PLUS.


See Also

INDEX

SET INDEX

SET ORDER

TAG( )

TAGCOUNT( )

TAGNO( )

USE


FOR...NEXT

See Also	Example	Portability	Programs

Executes the statements between FOR and NEXT the number of times indicated by the FOR statement.

Syntax

FOR <memvar> = <start expN> TO <end expN> [STEP <step expN>]
<statements>
[LOOP]
[EXIT]
NEXT

<memvar>

The memory variable that is incremented or decremented and then tested each time through the loop. On a normal exit from the loop (one done without the EXIT command), the value of <memvar> is greater or less than <end expN> by the amount of <step expN>.

<start expN>

The initial value of <memvar>.

<end expN>

The final allowed value of <memvar>. If you change this value in the FOR loop, the loop does not recognize the change and thus continues to execute until the original value is reached.

STEP <step expN>

Defines a step size (<step expN>) by which dBASE increments or decrements <memvar> each time the loop executes. By default, dBASE increments by 1. If you change this value in the FOR loop, the loop does not recognize the change and thus continues to increment or decrement <start expN> by the original <step expN> value.

When <step expN> is positive, dBASE increments <memvar> until it is greater than <end expN>. When <step expN> is negative, dBASE decrements <memvar> until it is less than <end expN>.

The <step expN> argument can be an integer, a fraction, or a floating-point number. STEP <step expN> must be on the same line as the FOR command.

<statements>

Program lines consisting of any combination of commands, functions, user-defined functions (UDFs), and LOOP and EXIT options.

LOOP

Returns program control to the top of the FOR loop and increments <memvar> by 1 (or increments or decrements by <step expN>) without executing the statements that follow LOOP and precede NEXT.

EXIT

Transfers program control out of the FOR loop to the statement following NEXT without reevaluating <memvar> or executing the statements that follow EXIT and precede NEXT. The <memvar> value remains the same as when dBASE encountered the EXIT statement.

NEXT

A required command that marks the end of the FOR loop. When dBASE encounters NEXT, it increments or decrements <memvar> according to the associated FOR statement and either returns to the associated FOR statement if the value of <memvar> has not reached its limit or transfers program control to the next command line.

Description

Use FOR...NEXT to execute a block of statements a specified number of times. When dBASE first encounters a FOR loop, it sets <memvar> to <start expN> and then performs the following steps:

If <memvar> is in the range from <start expN> through <end expN>, dBASE executes the statements between FOR and NEXT one by one until it encounters LOOP, EXIT, or NEXT.

If dBASE encounters LOOP or NEXT, it increments <memvar> by 1 (or by <step expN> if you used the STEP option) and returns program control to FOR.

If <memvar> still evaluates to a number in the range from <start expN> to <end expN>, dBASE executes the statements in the loop again.

If <memvar> evaluates to a number greater than <end expN> (or less than <end expN> if <step expN> is negative), the program exits the FOR loop and executes the line following NEXT.

If dBASE encounters EXIT, it immediately transfers program control out of the loop to the statement following the associated NEXT command without incrementing or decrementing <memvar> or executing any of the statements following EXIT and preceding NEXT.

You can nest loops and other structures, including other FOR...NEXT loops, in a FOR loop. You can nest up to 20 FOR loops in a procedure or function.

Use FOR loops to move displays in a window, process characters in a string, or access table records or array cells sequentially.


FOR...NEXT Example

The following example uses ALEN( ) in a FOR...NEXT loop to print out the contents of an array:

USE Clients
DECLARE acContact[RECCOUNT(),1]
COPY TO ARRAY acContact
USE
ShowArray(acContact)
RETURN

FUNCTION ShowArray
PARAMETER avArray
FOR i = 1 to ALEN(avArray)
  ? STR(i,3,0)+" - "+avArray[i,1]
NEXT
RETURN .T.


Portability

Not supported in dBASE IV or dBASE III PLUS.


See Also

DO...UNTIL

DO WHILE

IF

SCAN


FOUND( )

See Also	Example	Table Organization

Indicates if the last-issued FIND, LOCATE, CONTINUE, SEEK, LOOKUP( ), or SEEK( ) command or function finds a match.

Syntax

FOUND( [<alias>] )

<alias>

A work area number (1 through 225), letter (A through J), or alias name. The work area letter or alias name must be enclosed in quotes.

Description

FOUND( ) returns .T. if LOCATE, CONTINUE, LOOKUP( ), FIND, SEEK, or SEEK( ) finds a match in the current or specified table. FOUND( ) returns .F. if no previous search has been performed in the same work area, or if a search is unsuccessful. You can perform searches in different work areas and maintain the status of each FOUND( ) operation, independent of the other work areas.

If tables are linked by a SET RELATION TO command, dBASE for Windows searches the related tables as you move in the active table with the FIND, LOCATE, SEEK, or CONTINUE commands or using the SEEK( ) or LOOKUP( ) functions. If you move the record pointer with any other command or function, FOUND( ) returns .F.

When SET NEAR is ON,

FOUND( ) returns .T. if an exact match occurs.

FOUND( ) returns .F. for a near match, and the record pointer is moved to the record whose key immediately follows the value searched for.

When SET NEAR is OFF, FOUND( ) returns .F. if a match does not occur.


FOUND( ) Example

See the examples in SEEK, FIND, or LOCATE for an example of FOUND( ).


See Also

CONTINUE

EOF( )

FIND

LOCATE

LOOKUP( )

SEEK

SEEK( )

SET NEAR

SET RELATION


FPUTS( )

See Also	Example	Portability	Low-Level Access

Writes a character expression and one or two end-of-line characters to a file previously opened with FCREATE( ) or FOPEN( ) and positions the file pointer after the last character written. Returns the number of characters added if successful, 0 if unsuccessful, or 1 if an error occurs.

Syntax

FPUTS(<file handle expN>, <string expC>
[, <characters expN>] [, <end-of-line exp>] )

<file handle expN>

The file handle number of the file to write the specified characters and end-of-line character to. When you open a file with FCREATE( ) or FOPEN( ), these functions return a file handle number. Use this number as <file handle expN>. If you specify a file handle number that has not previously been returned by FCREATE( ) or FOPEN( ), dBASE returns an error message.

<string expC>

The character expression to write to the specified file. If you want to write only a portion of <string expC> to the file, use the <characters expN> argument.

<characters expN>

The number of characters of the specified character expression <string expC> to write to the specified file, starting at the first character in <string expC>. The valid range is 0 to 32766.

<end-of-line exp>

The end-of-line indicator, which can be one or two characters, to write to the specified file after the character expression. The following table lists standard codes for use as end-of-line indicators. Do not enclose them in quotes. You can combine two characters with a plus (+) sign, for example, CHR(141) + CHR(138).

<end-of-line exp>	Represents
not supplied	Hard CR/LF (0D0A Hex)
CHR(141)	Soft carriage return (U.S.) (8D Hex)
CHR(255)	Soft carriage return (Europe) (FF Hex)
CHR(138)	Soft linefeed (U.S.) (8A Hex)
CHR(0)	Soft linefeed (Europe) (00 Hex)
CHR(13)	Hard carriage return (0D Hex)
CHR(10)	Hard linefeed (0A Hex)

You cannot enter hexadecimal numbers directly for <end-of-line exp>, but you can combine them by adding their decimal equivalents. For example, 0D0A Hex equals CHR(13) + CHR(10); CHR(13) is 0D Hex, and CHR(10) is 0A Hex. Use HTOI( ) to convert a Hex number to its decimal equivalent.

Description

FPUTS( ) writes a character string and one or two end-of-line characters to a file. If successful, FPUTS( ) returns the number of bytes written to the file, including one or two for the end-of-line character or characters. If you don't have write or append access to the file, FPUTS( ) returns 0 and dBASE returns FERROR( ) number 5. If an error occurs, FPUTS( ) returns -1. When FPUTS( ) finishes executing, the file pointer is located at the character immediately after the last character written, which is the end-of-line character.

Except for one feature, FPUTS( ) and FWRITE( ) are identical; FPUTS( ) follows the character expression it writes with an end-of-line character while FWRITE( ) does not.

FPUTS( ) writes to the file you specify starting at the current file pointer position. Use FSEEK( ) to move the file pointer before or after you use FPUTS( ).

If the file pointer is at the end of the file, FPUTS( ) appends the specified string and the end-of-line character to the file. If the file pointer is not at the end of the file and you have write access to the file, FPUTS( ) overwrites existing text at the file pointer position. If you have append access (but not write access) to the file, FPUTS( ) appends text to the end of the file, regardless of the file pointer position, and dBASE does not return an error.


FPUTS( ) Example

The following example creates a text file named TEST.TXT and appends a progressively larger number of characters from the memory variable "String". The first pass through the FOR...NEXT loop appends the character "1" of "String" followed by soft carriage return and soft line feed characters. Subsequent passes append additional characters from String as i increments to 9. The program then uses FGETS in a .NOT. FEOF( ) loop to output the contents of TEST.TXT, which will display 9 lines of text counting from 1 to 9 starting with 1 character:

nHandle=FCREATE("Test.TXT","RW")  && Create file
* Input text data
String="123456789"
FOR i=1 TO 9                      && Loop for 9 lines
  FPUTS(nHandle,String,i,CHR(13)+CHR(10))
* Append i number of characters from String
* followed by a CR/LF.
NEXT i                            && increments i
* Output text data
FSEEK(nHandle,0,0)                && Moves pointer;
                                     to top of file
CLEAR                             && Clear results pane ;

                                     of the Command window
DO WHILE .NOT. FEOF(nHandle)
  ? FGETS(nHandle)                && Display line
ENDDO
FCLOSE(nHandle)                   && Close Test.TXT


Portability

Not supported in dBASE III PLUS. In dBASE IV, FPUTS( ) fails and dBASE returns an error when used with a file that doesn't have write or append access.


See Also

FCREATE( )

FEOF( )

FERROR( )

FGETS( )

FOPEN( )

FSEEK( )

FWRITE( )

HTOI( )

SUBSTR( )


FREAD( )

See Also	Example	Portability	Low-Level Access

Returns a specified number of characters from a file previously opened with FCREATE( ) or FOPEN( ) and positions the file pointer after the last character returned.

Syntax

FREAD(<file handle expN>, <characters expN>)

<file handle expN>

The file handle number of the file whose characters to read and return. When you open a file with FCREATE( ) or FOPEN( ), these functions returns a file handle number. Use this number as <file handle expN>. If you specify a file handle number that has not previously been returned by FCREATE( ) or FOPEN( ), dBASE returns an error message.

<characters expN>

The number of characters to return from the specified file. Acceptable values are 0 to 32766; if <characters expN> is less than 0 or greater than 32766, dBASE uses 0 or 32766, respectively.

Description

FREAD( ) returns the number of characters you specify from the file you specify. FREAD( ) starts reading and storing characters from the current file pointer position and repositions the file pointer to the character immediately after the last character read. Use FSEEK( ) to move the file pointer before or after you use FREAD( ).

Except for one feature, FREAD( ) and FGETS( ) are identical; FREAD( ) returns end-of-line characters while FGETS( ) does not. For more information, see FGETS( ).


FREAD( ) Example

The following example uses FREAD( ) to display 600 characters at a time from the README.TXT file. The WAIT command within the loop allows the user to review the file one page at a time.

SET PATH TO C:\DBASEWIN         && Parent directory
nHandle=FOPEN("Readme.TXT","R") && Open read only
DO WHILE .NOT. FEOF(nHandle)
  ? FREAD(nHandle,600)          && Display next;
                                   600 characters
  ?                             && Spacing above Wait
  WAIT "Browse at your leisure-;
    Press any key to continue"
  ?                             && Spacing below Wait
ENDDO
RETURN


Portability

Not supported in dBASE III PLUS.


See Also

FCREATE( )

FEOF( )

FERROR( )

FGETS( )

FOPEN( )

FSEEK( )

FWRITE( )


FSEEK( )

See Also	Example	Portability	Low-Level Access

Moves the file pointer a specified number of bytes in a file previously opened with FCREATE( ) or FOPEN( ), and returns the number of bytes from the beginning of the file to the file pointer.

Syntax

FSEEK( <file handle expN>, <bytes expN> [, <position expN>] )

<file handle expN>

The file handle number of the file in which to move the file pointer. When you open a file with FCREATE( ) or FOPEN( ), these functions return a file handle number. Use this number as <file handle expN>. If you specify a file handle number that has not previously been returned by FCREATE( ) or FOPEN( ), dBASE returns an error message.

<bytes expN>

The number of bytes to move the file pointer in the specified file. If <bytes expN> is negative, the file pointer moves toward the beginning of the file. If <bytes expN> is 0, the file pointer moves to the position you specify with <position expN>. If <bytes expN> is positive, the file pointer moves toward the end of the file or beyond the end of the file.

<position expN>

The number 0, 1, or 2, indicating a position relative to the beginning of the file (0), to the file pointer's current position (1), or to the end of the file (2). The default is 0.

Description

FSEEK( ) moves the file pointer in the file you specify, and returns the number of bytes from the beginning of the file to the file pointer's new position. If an error occurs, FSEEK( ) returns -1.

The movement of the file pointer is relative to the beginning of the file unless you specify otherwise with <position expN>. For example, FSEEK(filenum, 5) moves the file pointer five characters from the beginning of the file while FSEEK(filenum, five, 1) moves it five characters forward from its current position. You can move the file pointer beyond the end of the file, but you cannot move it before the beginning of the file.

To move the file pointer to the beginning of a file, use FSEEK(<file handle expN>, 0). To move it to the end of a file, use FSEEK(<file handle expN>, 0, 2).

FGETS( ), FPUTS( ), FREAD( ), and FWRITE( ) also move the file pointer as they read from or write to the file.


FSEEK( ) Example

See FGETS( ) for an example of using FSEEK( ).


Portability

Not supported in dBASE III PLUS.


See Also

FCREATE( )

FEOF( )

FOPEN( )

FREAD( )

FWRITE( )


FSIZE( )

See Also	Example	Portability	Disk and File Utilities

Returns the size of a file in bytes.

Syntax

FSIZE(<filename expC>)

<filename expC>

The name of the file to evaluate. Wildcard characters are not supported.

If you specify a file without including its path, dBASE looks for the file in the current directory, then in the path you specify with SET PATH. If you specify a file without including its extension, dBASE does not assume an extension.

Description

Use FSIZE( ) to determine the size of a file on disk.

When you update a file, dBASE changes the file's size, which appears next to the file name in a directory listing. For example, when the user edits a table, dBASE changes the size on the table file when the file is closed. FSIZE( ) reads the size and returns its current value.

If the file that you want to evaluate has an extension, you must include that extension in <filename expC>. If the file is not on the default drive, you must specify a drive designation, and if the file is not in the current directory or in the path you specify with SET PATH, you must specify the directory path.

If dBASE cannot find the file, it returns an error. Therefore, you may want to test for its existence with FILE( ) before issuing FSIZE( ). FLUSH does not update a file's size.

If <filename expC> is present in the current directory and also exists in the SET PATH directory, FSIZE(<filename expC>) without path information returns information on the file in the current directory.


FSIZE( ) Example

The following example finds the size of the Company table and, if there is enough space on drive B, writes a copy to that drive:

Needed1=FSIZE("Company.dbf")
Needed2=FSIZE("Company.dbt")  && the memo file
Needed=Needed1+Needed2
Available=DISKSPACE(2)
IF Needed <= Available
  RUN COPY Company.dbf B:
  RUN COPY Company.dbt B:
ELSE
  ? "Available", Available
  ? "Needed   ", Needed
  WAIT "Warning. Not enough space on drive B:"
ENDIF


Portability

Not supported in dBASE III PLUS.


See Also

FDATE( )

FILE( )

FLUSH

FTIME( )

SET DIRECTORY

SET PATH


FTIME( )

See Also	Example	Portability	Disk and File Utilities

Returns the time stamp for the file named <filename expC>.

Syntax

FTIME(<filename expC>)

<filename expC>

The name of the file to evaluate. Wildcard characters are not supported.

If you specify a file without including its path, dBASE looks for the file in the current directory, then in the path you specify with SET PATH. If you specify a file without including its extension, dBASE does not assume an extension.

Description

Use FTIME( ) to determine the time of day when the last change was made to a file on disk.

When you update a file, dBASE changes the file's time stamp to the current operating system time when the file is written to disk. For example, when the user edits a table, dBASE changes the time stamp on the table file when the file is closed. FTIME( ) reads the time stamp and returns its current value.

If the file that you want to evaluate has an extension, you must include that extension in <filename expC>. If the file is not on the default drive you must specify a drive designation, and if the file is not in the current directory or in the path you specify with SET PATH, you must specify the directory path.

If dBASE cannot find the file, it returns an error. Therefore, you may want to test for its existence with FILE( ) before issuing FTIME( ). FLUSH does not update a file's time stamp.

If <filename expC> is present in the current directory and also exists in the SET PATH directory, FTIME(<filename expC>) without path information returns information on the file in the current directory.


FTIME( ) Example

This example compares the date and time stamps on COMPANY.DBF and its backup on the B drive. If the backup is the same day as the current table but an earlier time then a backup is recommended:

DO CASE
CASE FDATE("B:Company.dbf") = FDATE("Company.dbf");
     .AND.;
     FTIME("B:Company.dbf") < FTIME("Company.dbf")
   * same day but different times
   ? "Backup recommended"
   WAIT
CASE FDATE("B:Company.dbf") < FDATE("Company.dbf")
  * backup is earlier date than current table
  Difference= ;
    FDATE("Company.dbf") - FDATE("B:Company.dbf")
  ? Difference, " days since last backup"
  ? "Backup recommended"
  WAIT
ENDCASE


Portability

Not supported in dBASE III PLUS.


See Also

FILE( )

FLUSH

FSIZE( )

FDATE( )

SET DIRECTORY

SET PATH


FUNCTION

Portability	Programs

Defines a user-defined function (UDF) in a program file. This command is supported primarily for compatibility with dBASE IV, in which there were significant syntactic and functional differences between UDFs and procedures (defined with the PROCEDURE command). In dBASE for Windows, procedures and UDFs use the same syntax, and can be used and called in the same ways. Therefore, making a distinction between procedures and functions is no longer necessary, and using PROCEDURE is recommended in dBASE for Windows. For more information, see PROCEDURE.


Portability

In dBASE IV, you could have a procedure and a UDF with the same name available at the same time, because they were called differently. In dBASE for Windows, if a procedure and a UDF of the same name are available, the first one declared is the only one recognized. For more portability information, see PROCEDURE.


FUNIQUE( )

See Also	Example	Disk and File Utilities

Creates a unique file name.

Syntax

FUNIQUE(<expC>)

<expC>

A file-name skeleton, which can include wildcards and any valid file-name characters.

Description

Use FUNIQUE( ) to create a unique file name with random numbers and letters you specify. For example, use FUNIQUE( ) to create temporary files without overwriting existing files.

To specify a file name of a specific length, or to specify which characters in the file name should be random numbers, use the ? wildcard character.

FUNIQUE( ) generates the new file name by replacing each wildcard character with a random number, then looking in the current or specified directory for a file name that matches the new file name. If no match is found, FUNIQUE( ) creates the file name and returns the name. If a match is found, FUNIQUE( ) tries again until a unique file name is found. If no combination of random numbers is successful, FUNIQUE( ) returns an empty string.

If you omit <expC>, FUNIQUE( ) creates an 8-character file name with no extension, composed entirely of random numbers.


FUNIQUE( ) Example

The following example uses FUNIQUE( ) to obtain a unique file name for a temporary table to which totals are calculated. The temporary table is then removed:

Temptable=FUNIQUE("Temp????.dbf")
* Using FUNIQUE, Temp???? returns Temp followed by 4
* numbers and .dbf e.g. Temp7990.dbf, Temp8832.dbf

USE Orders EXCLUSIVE
INDEX ON Customer_n TAG Customer_n
TOTAL ON Customer_n TO &Temptable
* Temptable now has the totals
* for orders for each customer

USE &Temptable
BROWSE FIELDS Customer_n, Total_inv, Amt_paid
USE

ERASE &Temptable


Portability

Not supported in dBASE IV or dBASE III PLUS.


See Also

FCREATE( )

FERROR( )

FILE( )

FOPEN( )


FV( )

See Also	Example	Portability	Numeric Data

Returns a float that is the future value of an investment.

Syntax

FV(<payment expN>, <interest expN>, <term expN>)

<payment expN>

The amount of the periodic payment. Specify the payment in the same time increment as the interest and term. The payment can be negative or positive.

<interest expN>

The interest rate per period expressed as a positive decimal number. Specify the interest rate in the same time increment as the payment and term.

<term expN>

The number of payments. Specify the term in the same time increment as the payment and interest.

Description

Use FV( ) to calculate the amount realized (future value) after equal periodic payments (deposits) at a fixed interest rate. FV( ) returns a float representing the total of the payments plus the interest generated and compounded.

Express the interest rate as a decimal. For example, if the annual interest rate is 9.5%, <interest expN> is .095 (9.5/100) for payments made annually.

Express <payment expN>, <interest expN>, and <term expN> in the same time increment. For example, if the payment is monthly, express the interest rate per month, and the number of payments in months. You would express an annual interest rate of 9.5%, for example, as .095/12, which is 9.5/100 divided by 12 months.

The formula dBASE uses to calculate FV( ) is as follows:

                     term
            (1 + int)^    -  1
fv = pmt * -------------------
                 int

where int = rate / 100

For the future value an investment of $350 made monthly for five years, earning 9% interest, the formula expressed as a dBASE expression looks like this:

? FV(350,.09/12,60)               && Returns 26398.45
? 350*((1+.09/12)^60-1)/(.09/12)  && Returns 26398.45

In other words, if you invest $350/month for the next five years into an account that pays an annual interest rate of 9%, at the end of five years you will have $26398.45.

Use SET DECIMALS to set the number of decimal places FV( ) displays.


FV( ) Example

The following example uses FV( ) to calculate the future value of monthly payments made over a set period at a known interest rate:

LOCAL f
f = NEW GFORM()
f.Open()

CLASS GFORM OF FORM
   this.Left =         49.00
   this.Height =         15.00
   this.ColorNormal = "BG+/BG"
   this.Width =         50.00
   this.Text = "Future Value"
   this.HelpId = ""
   this.HelpFile = ""
   this.Top =          5.82

   DEFINE TEXT TXT1 OF THIS;
       PROPERTY;
         Left          5.00,;
         Height          1.00,;
         ColorNormal "BG+/BG",;
         Width         26.00,;
         Border .F.,;
         Text "Monthly installment?",;
         Top          3.00

   DEFINE ENTRYFIELD AMNT OF THIS;
       PROPERTY;
         Left         30.00,;
         Height          1.00,;
         Width          5.00,;
         Value          0,;
         Picture "9999",;
         Border .T.,;
         Top          3.00

   DEFINE TEXT TXT2 OF THIS;
       PROPERTY;
         Left          5.00,;
         Height          1.00,;
         ColorNormal "BG+/BG",;
         Width         26.00,;
         Border .F.,;
         Text "Interest rate expected?",;
         Top          5.00

   DEFINE ENTRYFIELD INT OF THIS;
       PROPERTY;
         Left         33.00,;
         Height          1.00,;
         Width          5.00,;
         Value          0.00,;
         Picture "99.99",;
         Border .T.,;
         Top          5.00

   DEFINE TEXT TXT3 OF THIS;
       PROPERTY;
         Left          5.00,;
         Height          1.00,;
         ColorNormal "BG+/BG",;
         Width         34.00,;
         Border .F.,;
         Text "How many monthly payments?",;
         Top          7.00

   DEFINE ENTRYFIELD PYMTS OF THIS;
       PROPERTY;
         Left         40.00,;
         Height          1.00,;
         Width          4.00,;
         Value          0,;
         Picture "999",;
         Border .T.,;
         Top          7.00

   DEFINE PUSHBUTTON RESULTS OF THIS;
       PROPERTY;
         Left         14.00,;
         Height          2.00,;
         ColorNormal "N/W",;
         Width         19.00,;
         OnClick {;myResult="Future Value will be: $" +    LTRIM(STR(FV(Form.Amnt.Value,    (Form.Int.Value/100)/12,Form.Pymts.Value),13,2))    ; Form.FV.Text=myResult},;
         Text "Future Value",;
         Default .T.,;
         Top         11.00

   DEFINE TEXT FV OF THIS;
       PROPERTY;
         Left          5.00,;
         Height          1.00,;
         ColorNormal "BG+/BG",;
         Width         33.00,;
         Border .F.,;
         Text "Future Value: ",;
         Top          9.00

ENDCLASS


Portability

Not supported in dBASE III PLUS.


See Also

PAYMENT( )

PV( )

SET DECIMALS


FWRITE( )

See Also	Example	Portability	Low-Level Access

Writes a character expression to a specified file and positions the file pointer after the last character written. Returns the number of characters added if successful, 0 if unsuccessful, or 1 if an error occurs.

Syntax

FWRITE(<file handle expN>, <string expC> [, <characters expN>] )

<file handle expN>

The file handle number of the file to write the specified characters and end-of-line character to. When you open a file with FCREATE( ) or FOPEN( ), these functions returns a file handle number. Use this number as <file handle expN>. If you specify a file handle number that has not previously been returned by FCREATE( ) or FOPEN( ), dBASE returns an error message.

<string expC>

The character expression to write to the specified file. If you want to write only a portion of <string expC> to the file, use the <characters expN>argument.

<characters expN>

The number of characters of the specified character expression <string expC> to write to the specified file, starting at the first character in <string expC>. The valid range is 0 to 254, inclusive.

Description

FWRITE( ) writes a character string to a file. Except for one feature, FWRITE( ) and FPUTS( ) are identical; FPUTS( ) follows the character expression it writes with an end-of-line character while FWRITE( ) does not. For more information, see FPUTS( ).


FWRITE( ) Example

The following example uses FWRITE( ) within a SCAN loop to write the contents of the Name field of each record in the Animals table to a text file. The program then uses FGETS( ) within a DO WHILE .NOT. FEOF( ) loop to output the contents of the text file to the Command window.

nFile="Animals.TXT"
nHandle=FCREATE(nFile,"RW")      && Create text file
SET PATH TO C:\DBASEWIN\SAMPLES  && Make Samples;
                                 directory available
USE ANIMALS
* input data
SCAN
  FWRITE(nHandle,Trim(Name)+CHR(13)+CHR(10))
* Append Name field contents plus CR/LF to text file.
ENDSCAN

* output data
FSEEK(nHandle,0,0)               && File pointer to;
                                    top of file
CLEAR                            && Clear results pane ;
                                    of the Command window
DO WHILE .NOT. FEOF(nHandle)
  ? FGETS(nHandle)               && Display line
ENDDO
FCLOSE(nHandle)                  && Close Animals.TXT


Portability

Not supported in dBASE III PLUS.


See Also

FCREATE( )

FEOF( )

FERROR( )

FOPEN( )

FPUTS( )

FREAD( )

FSEEK( )


GENERATE

See Also	Example	Portability	Error Handling and Debugging

Adds random records to the current table.

Syntax

GENERATE [<expN>]

<expN>

A number of random-data records to add to the current table. The <expN> argument must be between 1 and 1,000,000,000 inclusive and cannot result in the generation of more than 2,000,000,000 bytes (2,000MB), the maximum size of a dBASE table. If you specify a <expN> value that is less than or equal to 0, dBASE does not generate any records. If you do not specify a value for <expN>, dBASE prompts you for a number and waits for input.

Description

GENERATE fills a table with sample data so you can thoroughly test and debug a program. If a table contains existing records, GENERATE leaves them intact and adds <expN> records to the table.

When you use the GENERATE command with a table containing a memo field, dBASE creates a memo field for each record but does not fill its associated memo file with data.


GENERATE Example

The following example uses GENERATE to add 10 new records to a temporary table created from CLIENTS.DBF.

USE Clients
COUNT       && Returns number of records
COPY TO Temp
USE Temp
GENERATE 10
COUNT       && Returns previous number +10
BROWSE      && Note the addition of 10 random records


Portability

Not supported in dBASE IV or dBASE III PLUS.


See Also

APPEND

BROWSE

CHANGE

DEBUG

DISPLAY COVERAGE

EDIT

SET COVERAGE


GETCOLOR( )

See Also	Portability	Colors and Fonts

Calls a dialog box in which you can define a custom color or select a color from the color palette. Returns a character string containing the red, green, and blue values for the color selected.

Syntax

GETCOLOR( [<title expC>] )

<title expC>

A character string up to 78 characters long that appears as the title of the dialog box.

Description

Use GETCOLOR( ) to open a dialog box in which you can choose a color from a palette of predefined colors or create a customized color. In this dialog box, you choose and create colors in the same way you do if you use the Color Palette available when you choose Color in the Windows Control Panel.

GETCOLOR( ) returns a string in the format "red value, green value, blue value", as shown in the following example.

mRed = GETCOLOR()   && choose a pure red color
? mRed              && returns "255,0,0"
mBlue = GETCOLOR()  && create a light blue color
? mBlue             && returns "164,200,240"

You can use the string returned by GETCOLOR( ) in a related command, DEFINE COLOR, to use a specific color in a program.


Portability

Not supported in dBASE IV or dBASE III PLUS.


See Also

DEFINE COLOR


GETDIRECTORY( )

See Also	Example	Portability	Disk and File Utilities

Displays a dialog box from which you can select a directory for use with subsequent commands.

Syntax

GETDIRECTORY( [<directory expC>] )

<directory expC>

The initial directory to appear in the dialog box. If <directory expC>is omitted, the current directory appears as the initial directory.

Description

Use GETDIRECTORY( ) to return a directory name for use in subsequent commands, such as FCREATE( ), SET DIRECTORY, or SET PATH.

GETDIRECTORY( ) does not return a final backslash at the end of the directory name it returns. If you want to create a full path name by concatenating a file name onto the value GETDIRECTORY( ) returns, include the backslash in your directory name in one of the following ways:

* Add backslash to directory returned
mCpath = GETDIRECTORY() + "\"
* Add backslash when concatenating to directory
mCfilename = "abc.txt"
mCfullname = GETDIRECTORY() + "\" + mCfilename


GETDIRECTORY( ) Example

The following shows three examples of GETDIR( ):

Newdir=GETDIR()
* open the directory dialog box
* If user chooses Cancel then Newdir is empty
Newdir=GETDIR("D:\Examples")
USE Company
Fullname=GETDIR()+"\"+DBF()


Portability

Not supported in dBASE IV or dBASE III PLUS.


See Also

FCREATE( )

GETFILE( )

SET DIRECTORY

SET PATH


GETENV( )

See Also	Example	Disk and File Utilities

Returns the value of a DOS environment variable.

Syntax

GETENV(<expC>)

<expC>

The name of the DOS environment variable to evaluate.

Description

Use GETENV( ) to return the current value of a DOS environment variable.

DOS environment variables are similar to dBASE memory variables. These variables are usually created with DOS commands like SET and PATH. For example, SET NAME=HARRY creates an environment variable NAME containing the character string "HARRY", and PATH=C:\DOS changes the DOS variable PATH or creates a new one.

If dBASE can't find the environment variable specified by <expC>, it returns a null string.


GETENV( ) Example

The following examples use GETENV( ):

? GETENV("comspec") && where is command.com
? GETENV("Path")    && the current path
? GETENV("Prompt")  && the prompt


See Also

OS( )

SET PATH


GETEXPR( )

See Also	Example	Portability	Expressions and Type Conversion

Displays a dialog box in which you can create or edit an expression, and returns the expression you specify.

Syntax

GETEXPR([<expression expC> [, <title expC> [, <data type expC>]]])

<expression expC>

A character expression to edit. If you specify <expression expC>, a dialog box opens with <expression expC> in the Expression field. Without <expression expC>, the dialog box opens with nothing in the Expression field.

<title expC>

A character string that appears as the title of the dialog box. Without <title expC>, the default title of the dialog box displays. If you want to specify a value for <title expC>, you must also specify a value or empty string ("") for <expression expC>.

<data type expC>

A single character specifying the data type of the result of the expression you specify in the dialog box. The data type appears as the Result type in the dialog box. If you want to specify a value for <data type expC>, you must also specify a value or empty string for <expression expC> and <title expC>.

Use the following characters in <data type expC>for the corresponding data types:

C for character

D for date

L for logical

N for numeric

F for float

X for any

Description

GETEXPR( ) displays the dBASE Expression Builder tool. Use it to build valid dBASE expressions to insert into the Text Editor, the Command window, and certain dialog box fields. For example, a user could use the Expression Builder to create a condition you then apply to a table with a SET FILTER statement.

The Expression Builder only builds expressions; it does not assign them. You can issue GETEXPR( ) in a program or in the Command window, and you can assign a variable to it so that the variable gets the value of what GETEXPR( ) returns.

In addition to using GETEXPR( ), you can also call the Expression Builder in the following ways:

Choose Edit|Build Expression from the menu

Press Ctrl+E


GETEXPR( ) Example

The following example uses GETEXPR( ) to branch to the Edit an Expression dialog box for entry of a state to search for:

USE Clients
cState      =  SPACE( LEN(Clients->State_Prov) )
cExpression = "UPPER(State_Prov)"
cCaption    = " Magic!! Build an Expression "
cType       = "L"
cKey        = ""
CLEAR
@ 1,1 SAY "Enter a state's name: " ;
      GET cState                   ;
      PICTURE "@!"
READ
IF .NOT. ISBLANK( cState )
  cExpression = cExpression + " = " + "'" + cState;
  + "'"
  cKey = GETEXPR(cExpression,cCaption,cType)
  LOCATE FOR &cKey.
    IF FOUND()
      ? Company, City
    ELSE
      CLEAR
      ? "There are no entries for " + cState
    ENDIF
ENDIF
USE


Portability

Not supported in dBASE IV or dBASE III PLUS.


See Also

SET FILTER


GETFILE( )

See Also	Example	Portability	Disk and File Utilities

Displays a dialog box, from which the user can choose or enter an existing file name, and returns the file name. Returns an empty string if the user exits the dialog box by any method except by double-clicking on a file name or choosing OK.

Syntax

GETFILE([<filename skeleton expC>
[, <title expC>
[, <filetype expL>
[, <change filetype expL>]]]] )

<filename skeleton expC>

A character string that matches selected file names with the wildcard characters ? and *. The GETFILE( ) dialog box lists only those file names in the current directory that match the file name skeleton. Without <filename skeleton expC>, the dialog box lists all file names.

<title expC>

A title displayed in the top of the dialog box. <title expC> can be up to 60 characters long. Without <title expC>, the GETFILE( ) dialog box displays the default title. If you want to specify a value for <title expC>, you must also specify a value or empty string ("") for <filename skeleton>.

<filetype expL>

A logical value that determines whether the dialog box opens with a list of all file types (.T.) or with a list of tables in a database (.F.). The default is .T. If you want to specify a value for <filetype expL>, you must also specify a value or empty string ("") for <filename skeleton> and <title expC>.

<change filetype expL>

A logical value that determines whether the user can switch between database tables and all file types while in the dialog box (.T.) or cannot switch between file types (.F.). The default is .F. If you want to specify a value for <change filetype expL>, you must also specify a value or empty string ("") for <filename skeleton> and for <title expC>, and you must specify a value for <filetype expL>.

Description

Use GETFILE( ) to retrieve a file name of your choice from a dialog box. Once the file name is retrieved, you can use it in other commands and function calls. For example, you can use GETFILE( ) to return a table file name so you can open a table with USE, or return the name of a text file for an editor object you create with DEFINE EDITOR. GETFILE( ) does not open any files.

The GETFILE( ) dialog box includes names of files whether they are currently open or closed. dBASE returns the full path name of the file whether SET FULLPATH is ON or OFF.

By default, the dialog box opened with GETFILE( ) displays file names from the current directory the first time you issue GETFILE( ). After the first time you use GETFILE( ) and exit successfully, the subdirectory you choose becomes the default the next time you use GETFILE( ).


GETFILE( ) Example

The following examples use GETFILE( ):

F1=GETFILE()  && Simply opens the dialog box
F2=GETFILE("*.prg") && displays only program files
F3=GETFILE("*.dbf","Choose any table")
* selects tables and puts title "Choose any table"
F4=GETFILE("*.dbf","Only a table",.f.)
* Only allow user to choose tables

? "F1",F1
? "F2",F2
? "F3",F3
? "F4",F4


Portability

Not supported in dBASE IV or dBASE III PLUS.


See Also

FILE( )

PUTFILE( )

SET FULLPATH


GETFONT( )

See Also	Portability	Colors and Fonts

Calls a dialog box in which you select a character font. Returns a string containing the font name, point size, font style (if you choose a style other than Regular), and family.

Syntax

GETFONT( [<title expC>] )

<title expC>

A character string up to 78 characters long that appears as the title of the dialog box.

Description

Use GETFONT( ) to place the values associated with a specified font into a character string, as shown in the following examples. If you want to add a font to the [Fonts] section of DBASEWIN.INI but do not know its exact name or family, use GETFONT( ). Then add the information GETFONT( ) returns into DBASEWIN.INI.

mNormal = GETFONT()  && choose Arial, Regular, 10-pt
? mNormal            && returns "Arial,10,Swiss"
mBold = GETFONT()    && choose Helvetica bold, 12-pt
? mBold              && returns "Helvetica,12,B,Swiss"


Portability

Not supported in dBASE IV or dBASE III PLUS.


See Also

?


GO

See Also	Example	Fields and Records

Moves the record pointer to the specified position in a table. For Paradox and SQL tables, you can move to a specific record using bookmarks.

Syntax

GO[TO]
BOTTOM | TOP | <bookmark> | [RECORD] <expN>
[IN <alias>]

TO

Include for readability only; TO has no affect on the operation of the command.

BOTTOM | TOP | <bookmark> | RECORD <expN>

Specifies where to move the record pointer. The following table describes each of the available keywords or options.

Option	Description
BOTTOM	If the specified table has no master index, moves the record pointer to the last record of the table. If the table has a master index, moves the record pointer to the last record of the index.
TOP	If the specified table has no master index, moves the record pointer to the first record of the table. If the table has a master index, moves the record pointer to the first record of the index.
<bookmark>	A marker for a specific row (similar to a record pointer) for tables that do not support record numbers.
RECORD <expN>	The record number to move the record pointer to. Entering a number in the Command window is equivalent to GO <expN>. The RECORD keyword is included for readability only; it has no affect on the operation of the command.
IN <alias>

Specifies an open table other than the current one, in which to move the record pointer. You can specify a work area number (1 through 225), letter (A through J), or alias name. The work area letter or alias name must be enclosed in quotes.

Description

GO positions the record pointer in the current or specified table or index file. GO <expN> or GO RECORD <expN> moves the record pointer to a specific record, regardless of whether a master index is open or where that record number occurs in an indexed order.

For tables that do not support record numbers (that is, Paradox and SQL tables), GO <expN> returns an error. For these type of tables, you specify a <bookmark> in place of a record pointer value. Bookmarks are a special data type that cannot be displayed or printed directly. You can return a bookmark of a specific record, for example, using the RECNO( ) or BOOKMARK( ) function. Optionally, you can store the bookmark in a memory variable and substitute that variable in the <bookmark> argument provided with the GO command.

If an index is not in use, TOP and BOTTOM refer to the first and last records in a table. If an index file is in use for a table, TOP and BOTTOM refer to the first and last records in the index file.

With SET DELETED ON, you can move the record pointer to a record that is marked for deletion by directly specifying its number. GOTO can also move the record pointer to records that are restricted by SET FILTER, although you cannot access such records with EDIT.

If a relation is set up among several tables, moving the record pointer in the parent table with GOTO repositions the record pointer in a child table to a related record. If there is no related record, the child table record pointer is positioned at the end of the file. Moving the record pointer in a child table, however, does not reposition the record pointer in the parent table.


GO Example

The following example uses GO to move the record pointer in an open table:

SET TALK OFF
USE Clients EXCLUSIVE
INDEX ON Client_ID TAG Client_ID
SEEK "A5577"
? RECNO(), Client_ID, Company, Zip_P_Code
rec_num = RECNO()
GO TOP
? RECNO(), Client_ID, Company, Zip_P_Code
GO BOTTOM
? RECNO(), Client_ID, Company, Zip_P_Code
rec_mark = BOOKMARK()
GO rec_num
? RECNO(), Client_ID, Company, Zip_P_Code
GO rec_mark
? RECNO(),  Client_ID, Company, Zip_P_Code
CLOSE ALL


See Also

EOF( )

RECNO( )

SELECT

SET DELETED

SET FILTER

SET RELATION

SKIP


HELP

See Also	Example	Windows Programming

Activates the dBASE Help system.

Syntax

HELP
[<help topic>]

<help topic>

The Help topic you access with HELP.

Description

Use the HELP command to provide information on dBASE.

The <help topic> option is a character string consisting of a single letter or a group of letters. dBASE locates the first Help topic beginning with this string and opens the Search dialog box with the topic highlighted.

Pressing F1 executes the HELP command automatically unless you reprogram F1 with ON KEY LABEL or SET FUNCTION.

For information on creating a customized Help system, see Chapter 14 in the Programmer's Guide.


HELP Example

The command HELP, used in a program or in the Command window, can provide explanations of individual commands, features, or a user overview of Views and Tools, the Debugger or language. To access information on Views and Tools, issue the following command:

HELP Views and Tools

To access Help information on a specific command type (for example)

HELP CLASS

To access information on a feature type (for example)

HELP SPEEDBARS


See Also

HelpFile

HelpID

SET HELP

SET TOPIC


HOME( )

See Also	Example	Portability	Disk and File Utilities

Returns the path to the directory where the DBASEWIN.EXE in use is located.

Syntax

HOME( )

Description

Use HOME( ) to identify the directory in which the currently running copy of DBASEWIN.EXE is located. When you install dBASE, the installation program (by default) installs DBASEWIN.EXE in the DOS directory \DBASEWIN\BIN. HOME( ) returns this directory. HOME( ) returns the full path name whether SET FULLPATH is ON or OFF.

To identify the dBASE home directory, use _dbwinhome.


HOME( ) Example

HOME( ) returns the dBASE directory from which DBASEWIN.EXE was launched:

? HOME()      && F:\DBASEWIN\BIN\
* This is different from _dbwinhome
? _dbwinhome  && \DBASEWIN\


Portability

Not supported in dBASE III PLUS.


See Also

_dbwinhome

CD

MKDIR

SET DIRECTORY

SET FULLPATH

SET PATH


HTOI( )

See Also	Example	Portability	Expressions and Type Conversion

Returns the decimal-number equivalent of a specified hexadecimal number.

Syntax

HTOI(<expC>)

<expC>

The hexadecimal number whose decimal-number equivalent to return.

Description

Use HTOI( ) to convert a hexadecimal number to a decimal number of float type. HTOI( ) is the inverse function of ITOH( ), which accepts numeric and float numbers and returns a hexadecimal equivalent as a character string. Use both functions with Windows Application Programming Interface (API) calls that require hexadecimal values.


HTOI( ) Example

The following examples use HTOI( ) to return the numeric value of the passed hexadecimal values:

? HTOI("FAFA")               && Returns 64250.0000
? HTOI("40FA")               && Returns 16634.0000
? ITOH(12345,8)              && Returns 00003039
? HTOI("    3013")           && Returns 12307.0000


Portability

Not supported in dBASE IV or dBASE III PLUS.


See Also

ITOH( )


ID( )

See Also	Example	Portability	Shared Data

Returns the name of the current user on a local area network (LAN) or other multiuser system.

Syntax

ID( )

Description

ID( ) accepts no arguments and returns the name of the current user as a character string. ID( ) returns an empty string when you call it on a single-user system or when a user name is not registered on a multiuser system.


ID( ) Example

The following example keeps track of the last network user to update a record. It updates a network database and puts ID( ), the current user, into a field called USER:

PROCEDURE OkToChange	&& Updates a network database and logs user name
IF ID() <> ""
   REPLACE NAME WITH cName, USER with ID()
ELSE
   CLEAR
   ? "You have lost your network connection. Data not saved."
   WAIT
ENDIF
RETURN


Portability

Not supported in dBASE III PLUS.


See Also

CONVERT

LKSYS( )

NETWORK( )


IF

See Also	Example	Portability	Programs

Conditionally processes statements by evaluating one or more conditions and executing the statements following the first condition that evaluates to true.

Syntax

IF <condition expL 1>
<statements>

[ELSEIF <condition expL 2>
<statements>

[ELSEIF <condition expL 3>
<statements>...]]

[ELSE
<statements>]

ENDIF

<condition expL>

A logical expression that determines if the set of statements between IF and the next ELSE, ELSEIF, IF, or ENDIF command execute. If the condition is true, the statements execute. If the condition is false, control passes to the next ELSE, ELSEIF, or ENDIF.

<statements>

One or more program lines consisting of any combination of commands, functions, and preprocessor directives.

ELSEIF <condition expL> <statements>

Specifies that when the previous IF or ELSEIF condition is false, control passes to this ELSEIF <condition expL>. As with IF, if the condition is true, only the set of statements between this ELSEIF and the next ELSEIF, ELSE, or ENDIF execute. If the condition is false, control passes to the next ELSEIF, ELSE, or ENDIF.

You can enter this option as either ELSEIF or ELSE IF. The ellipsis (...) in the syntax statement indicates that you can have multiple ELSEIF statements.

ELSE <statements>

Specifies statements to execute if all previous conditions are false.

ENDIF

A required command that marks the end of the IF structure.

Description

Use IF...ELSEIF...ENDIF to evaluate one or more conditions and execute only the set of statements following the first condition that evaluates to true. For the first true condition, dBASE executes the statements between that program line and the next ELSEIF, ELSE, or ENDIF, then skips everything else in the IF structure and executes the program line following ENDIF. If no condition is true and an associated ELSE command exists, dBASE executes the set of statements after ELSE and then executes the program line following ENDIF.

Use IF...ENDIF to test one condition and IF...ELSEIF...ENDIF to test two or more conditions. If you have more than three conditions to test, consider using DO CASE instead of IF. Compare the example in this section with the example for DO CASE.

You can nest IF statements to test multiple conditions; however, the ELSEIF option is an efficient alternative. When you use ELSEIF, you do not need to keep track of which ELSE applies to which IF, nor do you have to put in an ending ENDIF.

You can put many commands in each set of commands. If the number of commands in a set makes the code hard to read, consider putting them in a procedure and calling the procedure from the IF statement instead.


IF Example

The following example of nested IF constructs determines the magnitude of a previously declared memory variable and displays an appropriate message. Contrast this code segment with the simpler ELSEIF construct of the second section:

nM_value=523
IF nM_value > 1000
   ? "Value is over 1000."
ELSE
   IF nM_value > 100
      ? "Value is over 100."
   ELSE
      IF nM_value > 10
         ? "Value is over 10."
      ELSE
         IF nM_value > 1
            ? "Value is over 1."
         ELSE
            ? "Value is 1 or less."
         ENDIF
      ENDIF
   ENDIF
ENDIF

The following example of a nested IF construct uses ELSEIF to determine the magnitude of a previously declared memory variable and displays an appropriate message:

IF nM_value > 1000
   ? "Value is over 1000."
ELSEIF nM_value > 100
   ? "Value is over 100."
ELSEIF nM_value > 10
   ? "Value is over 10."
ELSEIF nM_value > 1
   ? "Value is over 1."
ELSE
   ? "Value is 1 or less."
ENDIF


Portability

ELSEIF is not supported in dBASE IV or dBASE III PLUS.


See Also

DO CASE

DO...UNTIL

DO WHILE

FOR...NEXT

IIF( )

SCAN


IIF( )

See Also	Example	Programs

Returns one of two values depending on the result of a specified logical expression.

Syntax

IIF(<expL>, <exp1>, <exp2>)

<expL>

The logical expression to evaluate to determine whether to return <exp1> or <exp2>.

<exp 1>

The character, date, logical, numeric, or float expression to return if <expL> evaluates to .T.

<exp 2>

The character, date, logical, numeric, or float expression to return if <expL> evaluates to .F. The data type of <exp 2> does not have to be the same as that of <exp 1>.

Description

IIF( ) stands for "immediate IF" and is a shortcut to the IF...ELSE...ENDIF programming construct. Use IIF( ) where expressions are allowed but programming constructs are not, such as in reports and labels, and to restrict a value to one of two possibilities.


IIF( ) Example

The following example uses IIF( ) to pass either of two results back to the variable or command using IIF( ):

x = IIF(SUBSTR(LDRIVER(),6,2)="US", "AMERICAN", ;
   "FRENCH")
SET DATE TO &x
? DATE()

The next example uses IIF( ) to index a table such that a selected state appears at the top of the ordered database rather than in its usual character or numeric value order.

USE Clients EXCLUSIVE
INDEX ON IIF(State_Prov="CA","A","Z") + STATE_PROV ;
   TAG TopState
LIST FIELDS Company, Contact, State_Prov OFF NEXT 30
CLOSE ALL


See Also

IF


IMPORT

See Also	Example	Table Basics

Creates a dBASE table from data stored in files with different formats.

Syntax

IMPORT FROM <filename> | ?
[[TYPE] WB1 | WK1]
[HEADING]

<filename> | ?

The name of the file you want to import. IMPORT ? displays a dialog box, from which you can select a file to import. If you specify a file without including its path, dBASE for Windows looks for the file in the current directory, then in the path you specify with SET PATH.

[TYPE] WB1 | WK1

Specifies the format of data you are importing. The TYPE keyword is included for readability only; it has no effect on the operation of the command. The following table provides a description of the different file formats that are supported:

Type	Description
WB1	A Quattro Pro for Windows spreadsheet file. Spreadsheet rows form table records; spreadsheet columns form table fields. If you do not specify an extension, dBASE for Windows assumes .WB1.
WK1	A Lotus 1-2-3 spreadsheet. Spreadsheet rows form table records; spreadsheet columns form table fields. If you do not specify an extension, dBASE for Windows assumes .WK1.
[HEADING]

Specifies using the label headings of spreadsheet columns as the new field names of the table created by IMPORT. Labels . Labels used as field names are truncated at 10 characters. Spaces are converted to the underscore character and other characters are mapped to valid dBASE field name characters.

Description

Use the IMPORT command to import data from files in non-dBASE formats. You need to specify the extension of a file, if it is something other than the default extension.

IMPORT creates the table in which data is imported in the same drive and directory as the original file and opens the table in the current work area. To display information about the imported file, use DISPLAY STATUS and DISPLAY STRUCTURE.


IMPORT Example

The following example uses IMPORT FROM to create a new .DBF table from a Quattro Pro .WB1 file:

SET DBTYPE TO DBASE
IMPORT FROM C:\QPW\SAMPLES\LOANPMT.WB1 TYPE WB1
CD C:\QPW\SAMPLES
USE LOANPMT
BROWSE
CLOSE ALL


See Also

APPEND

DISPLAY STATUS

DISPLAY STRUCTURE

USE


INDEX

See Also	Example	Portability	Table Organization

Creates an index for the current table. For Paradox and SQL tables, you can define index tags, but you do not specify the name of an index file.

Syntax

INDEX ON <key exp>
TO <.ndx filename> | ? | <.ndx filename skeleton>
[UNIQUE]

or

INDEX ON <key exp> | <field list>
TAG <tag name>
[OF <.mdx filename> | ? | <.mdx filename skeleton>]
[FOR <condition>]
[DESCENDING]
[UNIQUE]

You can use a special form of this command, INDEX ON <field list> PRIMARY, to create a primary index on a Paradox table.

<key exp> | <field list>

For dBASE tables, <key exp> specifies the name of a character, numeric, float, or date field, or it can be a dBASE expression of up to 220 characters that includes operators or functions that manipulate field values, or a combination of field names and expressions. The maximum length of the key, the result of the evaluated index <key exp>, is 100 characters.When <key exp> is based on more than one field, all elements of the expression must evaluate to the character type. You can join multiple fields or expressions using string concatenation operators (+ or -).

For Paradox and SQL tables, indexes cannot include expressions; however, you can create indexes based on one or more fields. In that case, you specify the index key as a <field list>, separating the name of each field with a comma.

TAG <tag name>

Specifies the name of the index tag added to an .MDX multiple index file. If you do not specify an .MDX file, index tags are added to the production .MDX file.

OF <.mdx filename 2> | ? | <.mdx filename skeleton>

Specifies the .MDX multiple index file that dBASE adds new index tags to. OF ? and OF <filename skeleton> display a dialog box, in which you can select an existing .MDX file. If you specify a file that does not exist, dBASE for Windows creates it and adds the index tag name. By default, dBASE for Windows assigns an .MDX extension and saves the file in the current directory.

TO <.ndx filename 1> | ? | <.ndx filename skeleton>

Specifies the name of an .NDX index file. By default, dBASE for Windows assigns an .NDX extension to <filename 1> and saves the file in the current directory. The ? and <.ndx filename skeleton> options display a dialog box, in which you specify the name of the target file and the directory to save it in.

FOR <condition>

Restricts the records dBASE for Windows includes in the index to those meeting the specified <condition>. Without the FOR <condition> or UNIQUE options, all records of the table are included in the index.

DESCENDING

Creates the index in descending order (Z to A, 9 to 1, later dates to earlier dates). Without DESCENDING, INDEX creates an index in ascending order.

UNIQUE

Prevents multiple records with the same <key expC> value from being included in the index; dBASE for Windows includes in the index only the first record with that value. Without the UNIQUE or FOR <condition> options, all records of the table are included in the index. For SQL tables, specifies creating a unique index which prevents entry of duplicate index keys in a table.

Description

Use INDEX to organize data for rapid retrieval and ordered display. INDEX does not actually change the order of the records in a table but rather creates an index file in which records are arranged in numeric, float, character, or date order based on the value of a key expression. Like the index of a book, with ordered entries and corresponding page numbers, an index file contains ordered key expressions with corresponding record numbers. When the table is used with a master index, the contents of the table appear in the order specified by the index.

At the end of an indexing operation, the new index file is the master index, and the record pointer is positioned at the first record of the indexed table. dBASE for Windows closes all other indexes except those whose tag names are in the production .MDX file, if one exists, with the same name as the table.

In an index, records are usually arranged in ascending order, with lowest key values at the beginning of the index. Using the DOS Code Page 437 (U.S.) character set, character keys are ordered in ASCII order (from A to Z and then from a to z); numeric and float keys are ordered from lowest to highest numbers; and date keys are ordered from earliest to latest date. Include the UPPER( ) function in the key expression to convert all lowercase letters to uppercase and achieve alphabetical order for character-type fields.

Note:	Most non-U.S. character sets provide a different sort order for characters than the DOS Code Page 437 character set.

You can reverse the order of an index, arranging records in descending order, by including the DESCENDING keyword. (You can use DESCENDING only when building .MDX tags.)

If a function is used in a key expression, keep in mind that the index is ordered according to the function output. Thus, when you use FIND or SEEK, or otherwise access the key value of a record, include the entire key expression. For example, INDEX ON SOUNDEX(Name) TO Names creates an index ordered by the values SOUNDEX( ) returns. When attempting to find data by the key value, you must include the entire key expression, such as SEEK SOUNDEX("Jones") rather than SEEK "Jones". Do not use functions such as CHR( ), LTRIM( ), RTRIM( ), TRIM( ), or IIF( ) that vary the field length in the key expression.

In some tables, multiple records may share the same <key value>. Use the UNIQUE option to include only the first such record in the index. INDEX with the UNIQUE option has the same effect as indexing a table with SET UNIQUE ON.

FOR <condition> limits the records whose key expression values dBASE includes in the index to those meeting the specified condition. For example, if you use INDEX ON Lastname + Firstname TO Salaried FOR Salary > 24000, dBASE for Windows includes only records of employees with salaries higher than $24,000 in the index. The FOR condition cannot include calculated fields.

Once a table has been indexed, use LOOKUP( ), SEEK, SEEK( ), and FIND to retrieve data. The structure of an index file allows these commands to quickly locate values of the key expression.

When you execute APPEND, BROWSE, CHANGE, EDIT, INSERT, PACK, REPLACE, @...GET, or UPDATE, dBASE for Windows automatically updates all open index files. Index files closed when changes are made in a table can be opened and then updated using REINDEX.

Multiple index files simplify updating indexes, since dBASE for Windows updates all indexes with tag names listed in .MDX files specified with USE...ORDER or SET ORDER. dBASE for Windows automatically opens a production .MDX file, if one exists, when you use the associated table.

INDEX...TAG creates an index and adds the tag name to a multiple index file. If you do not include OF <filename>, INDEX...TAG adds the tag name to the production .MDX file. dBASE for Windows creates the production .MDX or the specified file if it does not already exist.

INDEX...TAG closes all open indexes except those with tag names in the production .MDX file, or within the same .MDX file you specify. If indexes with tag names listed in the specified .MDX file are not open, dBASE for Windows opens them.

INDEX is similar to SORT, another command that allows ordering of a table. Unlike INDEX, though, SORT physically rearranges the table records, a time-consuming process for large files. To maintain the sorted order, either new records must be placed in their proper position using INSERT, or the entire table must be resorted. Also, SORT does not support SEEK, SEEK( ), or FIND, making the process of locating data in a sorted table slower.


INDEX Example

The following example uses INDEX to create index tags for the current table:

USE Clients EXCLUSIVE
INDEX ON Company TAG Company
* creates an index by Company
BROWSE TITLE "Indexed by Company"
INDEX ON  State_Prov+City ;
   TAG StateCity DESCENDING
* Combine State and City index
BROWSE TITLE "Indexed by State & City Descending"
INDEX ON City;
   TAG CA ;
   FOR State_Prov = "NY" && only cities in New York State
BROWSE TITLE "Indexed by City, NY only"


Portability

The file-name skeleton option is not available in dBASE IV. TAG, FOR and .MDX options not available in dBASE III PLUS.


See Also

FIND

KEY( )

LOOKUP( )

ORDER( )

REINDEX

SEEK

SEEK( )

SET INDEX

SET ORDER

SET UNIQUE

SORT

TAG( )

USE


INKEY( )

See Also	Example	Portability	Keyboard and Mouse Events

Returns the decimal value associated with the first key or key combination held in the keyboard typeahead buffer and removes the keystroke from the buffer. Can also be used to wait for a keystroke and return its value.

Syntax

INKEY([<seconds expN>] [, <mouse expC>])

<seconds expN>

The number of seconds INKEY( ) waits for a keystroke. If <expN> is zero, INKEY( ) waits indefinitely for a keystroke.

<mouse expC>

Determines whether INKEY( ) returns a value when you click the mouse. If <expC> is M or m, INKEY( ) returns -100. If <expC> is not M or m, INKEY( ) ignores a mouse click and waits for a keystroke.

Description

The keyboard typeahead buffer stores keystrokes the user enters while dBASE is busy processing other data. Use INKEY( ) to identify and delete a keystroke held in the keyboard typeahead buffer. If the typeahead buffer is empty, INKEY( ) returns the value of zero.

For example, if you press C and then Alt+P, dBASE stores the values 67 and -420 in the typeahead buffer. INKEY( ) returns 67, and a second INKEY( ) returns -420. See INKEY( ) Values and READKEY( ) Values for a complete list of the values returned by INKEY( ). See Appendix E in the Language Reference for a list of decimal values corresponding to keys.

To determine a value in the buffer in a position other than the first position, or to determine a buffer value without removing it from the buffer, use NEXTKEY( ).


INKEY( ) Example

The following example continuously executes a loop that shows the value of INKEY( ) and the character typed. The loop ends when the Escape key (ASCII 27) is pressed:

CLEAR
SET ESCAPE OFF
* ESCAPE ON will interrupt the program and the
* Escape key will not be trapped by INKEY()
? "Press Esc to continue"
k=0
DO WHILE k <> 27
  k=INKEY()
  ? k
  IF k>0
    ?? CHR(k)  && show the key and the ascii char
  ENDIF
ENDDO
SET ESCAPE ON

The following example displays a message and waits up to 10 seconds or until any key or mouse button is clicked:

? "This message will display for 10 seconds max"
Pause=inkey(10,"m")
IF Pause=0
  ? "You waited the 10 seconds"
ENDIF


Portability

The <seconds expN> option is not supported in dBASE III PLUS. The <mouse expC> option is not supported in dBASE IV or dBASE III PLUS. For some keys, dBASE for Windows returns values different from those in earlier versions of dBASE. See INKEY( ) Values and READKEY( ) Values for a complete list of returned values.


See Also

CLEAR TYPEAHEAD

KEYBOARD

LASTKEY( )

NEXTKEY( )

ON KEY

READKEY( )

SET TYPEAHEAD


INPUT

See Also	Example	Input/Output

Accepts a user-entered expression and stores it to a memory variable. INPUT can accept character, numeric, float, date, or logical data. This command is supported primarily for compatibility with dBASE IV. In dBASE for Windows, use DEFINE with the Text and EntryField classes for displaying and accepting information on a form.

Syntax

INPUT [<prompt expC>] TO <memvar>

<prompt expC>

A character expression that prompts the user for input.

TO <memvar>

Assigns the user input to the memory variable you specify for <memvar>. If <memvar> does not exist, dBASE creates it. If <memvar> does exist, INPUT overwrites it.

Description

Use INPUT primarily in program files to prompt the user for these types of keyboard input:

Non-character data

Character data, entered in quotes or square brackets

Complex expressions

The user terminates data entry by pressing Enter. If the user presses Enter without typing any characters, dBASE continues to prompt for input until the user enters something.

If SET ESCAPE is ON, pressing Esc in response to an INPUT terminates a program.

The type of expression the user inputs determines the type of memory variable INPUT creates:

Expression	Rules for entering	<memvar> variable type
Integer	Enter directly	Numeric
Decimal	Enter directly	Float
Character	Delimit with ' ' or " " or [ ]	Character
Date	Delimit with { }	Date
Logical	.T. or .F.	Logical
The SET DECIMALS setting affects how numeric keyboard entries with decimals are displayed.

To ensure that the user enters the correct type of data, use <prompt expC>to indicate what the user should enter. For example, <prompt expC> could be "Enter today's date surrounded by braces ({ })". You could then use TYPE( ) to test the type of data the user enters.

Other commands that let programs read data from the keyboard are ACCEPT and WAIT.


INPUT Example

The following examples demonstrate the use of INPUT to enter different types of variables:

CLEAR
amount=0
INPUT "How much? " TO Amount
* Amount will be overwritten
? Amount,type("Amount")
INPUT "Enter a date (e.g. {01/01/01} " TO Enterdate
? Enterdate, type("Enterdate")
INPUT 'Enter your name (e.g. "John") ' TO Name
? Name, type("Name")

Enterdate and Name are not guaranteed to contain a date and a name. They could contain .T., "abc", or 5.7, and be a logical, string, or numeric type.


See Also

ACCEPT

CTOD( )

DEFINE

SET DECIMALS

SET ESCAPE

TYPE( )

WAIT


INSERT

See Also	Example	Fields and Records

Adds a new record to the current table at the current record location.

Syntax

INSERT
[BLANK]
[BEFORE]
[NOWAIT]

BLANK

Inserts a blank record, but does not display a window to update field values in the new record.

BEFORE

When no master index is in use, inserts a new record before the current record rather than after.

NOWAIT

Invokes the form to edit a new record but does not move focus there. If used in a program, execution continues to statement following the INSERT NOWAIT command.

Description

Use INSERT to add a single record within an existing table. If dBASE tables are linked with the SET RELATION command, the CONSTRAIN and INTEGRITY options control operations that add new records to child and parent tables. For more information, see the SET RELATION command.

When adding a record to an indexed table, INSERT adds the new record to the end of the table (with a record number one greater than the previous highest record number) and also correctly inserts the record in all open indexes. Index files closed at the time a new record is inserted in a table may be updated using REINDEX.

If you INSERT a record at the end of a file, INSERT (but not INSERT BLANK) functions like APPEND, continuing to add new records until you exit.

If SET CARRY is OFF, the default setting, newly inserted records are blank before editing. If SET CARRY is ON, each new record is filled with the contents of the preceding record.

INSERT BLANK adds a record to the current table and moves the record pointer to the new record, just as INSERT does, but does not display a window to update values in the blank record.

In a table without a master index, issuing the INSERT command without the BEFORE option adds a blank record immediately following the current record, also updating any open indexes. In a table with a master index, INSERT adds the record to the end of the table and updates all open indexes when you save the new record.


INSERT Example

The following example uses INSERT BLANK to insert a blank record after the current record:

SET TALK OFF
USE Clients EXCLUSIVE
SKIP 3
?  RECNO(), Company     && Note recno() and company
SKIP-1                  && Moves record pointer back
INSERT BLANK
SKIP                    && Advance record pointer 1
? RECNO(), Company      && Former record is now 1;
                           record number higher
CLOSE ALL

The next example uses INSERT BEFORE to insert a blank record before the current record and present an entry window for user input.

USE Clients EXCLUSIVE
SKIP 4
? RECNO(), Company
INSERT BEFORE           && Edit window presented
? RECNO(), Company      && Newly added record in old;
                           record position
SKIP                    && Advance record pointer 1
? RECNO(), Company      && Old record
CLEAR
CLOSE ALL


See Also

APPEND

INSERT AUTOMEM

REINDEX

REPLACE

SET CARRY

SET FIELDS

SET RELATION

STORE

USE


INSERT AUTOMEM

See Also	Example	Portability	Fields and Records

Adds a new record to the current table using values stored in automem variables.

Syntax

INSERT AUTOMEM
[BEFORE]

BEFORE

Inserts the new record before the current record.

Description

INSERT AUTOMEM adds a new record to a table using the values stored in automem variables. If no master index exists, INSERT AUTOMEM without the BEFORE option adds the record immediately after the current record. If a master index exists, INSERT AUTOMEM adds the record to the end of the table and updates all open indexes.

A full discussion of the use of automem variables for adding data to a table is included under APPEND AUTOMEM.

The only difference between INSERT AUTOMEM and APPEND AUTOMEM is that, in an unindexed table, INSERT AUTOMEM adds the record immediately after (or before) the current record, while APPEND AUTOMEM adds the record to the end of the table. INSERT AUTOMEM assigns the new record a record number one greater than (or less than) the current record and also changes all record numbers beyond the new record; APPEND AUTOMEM assigns the new record the last record number in the table.

When a master index is open, APPEND AUTOMEM and INSERT AUTOMEM work identically. Both assign the new record the last record number in the table and update all open indexes.

INSERT AUTOMEM provides advantages over INSERT BLANK since INSERT AUTOMEM updates a table only once, while INSERT BLANK updates a table first when it adds a blank record, and again when you use REPLACE to update the blank values.


INSERT AUTOMEM Example

The following example seeks a specified record, uses STORE AUTOMEM to hold field names and values for the current record, checks to determine the presence of a Collect table and uses INSERT AUTOMEM to transfer the selected record's data to the Collect table:

CLEAR
SET TALK OFF
USE Clients ORDER Client_ID
Lookup = "A3367"
SEEK Lookup
IF FOUND()
  STORE AUTOMEM
ELSE
  RETURN
ENDIF
IF .NOT. FILE("Collect.DBF")
  COPY STRUCTURE TO Collect
ENDIF
USE Collect EXCLUSIVE
INSERT AUTOMEM
BROWSE
CLOSE ALL
SET TALK ON
RETURN


Portability

Not supported in dBASE IV or dBASE III PLUS.


See Also

APPEND AUTOMEM

INSERT


INSPECT( )

See Also	Example	Portability	Objects

Opens the Object Inspector, a window that lists object properties and lets you change their settings.

Syntax

INSPECT(<object reference>)

<object reference>

A reference to the object that you want to inspect. dBASE generates a variable containing an object reference when you create an object with the NEW operator or the DEFINE command. This variable has the same name you gave to the object.

Description

Use INSPECT( ) to examine and change object properties directly. For example, during program development you can use INSPECT( ) to evaluate objects and experiment with different property settings.

The Object Inspector is modeless, and does not affect program execution.

Note:	You can access the Object Inspector from the Form Designer by right-clicking the form or one of its objects and selecting Object Inspector from the SpeedMenu.

You can get help on any property in the Object Inspector by selecting the property and pressing F1.


INSPECT( ) Example

The following example uses INSPECT( ) to open a dialog box that displays the current properties of spinbox Spin1 after changing the spinbox value:

PUBLIC F1
USE COUNTRY
SET PROCEDURE TO PROGRAM(1) ADDITIVE
DEFINE FORM F1 FROM 2,2 TO 15,40;
  PROPERTY Text "SpinBoxDemo"
DEFINE SPINBOX Spin1 OF F1;
  PROPERTY;
    Datalink "Country->GNP",;
    Top 2,;
    Left 4,;
    Height 2,;
    Step 1000
DEFINE PUSHBUTTON Proceed OF F1;
  PROPERTY;
    OnClick Check,;
    Top 5,;
    Left 6,;
    TEXT  "Proceed"
OPEN FORM F1

PROCEDURE Check
  ? INSPECT(F1.Spin1)
  CLOSE FORMS F1
  RETURN


Portability

Not supported in dBASE IV or dBASE III PLUS.


See Also

DISPLAY MEMORY

DISPLAY STATUS


INT( )

See Also	Example	Numeric Data

Returns the integer portion of a specified number.

Syntax

INT(<expN>)

<expN>

A numeric or float number whose integer value to determine and return.

Description

Use INT( ) to remove the decimal digits of a numeric or float number and retain only the integer portion, the whole number. INT( ) returns an integer whose data type is numeric.

If you pass a number with decimal places to a function or command that uses an integer as an argument, such as _pageno or SLEEP, dBASE automatically truncates that number, in which case you do not need to use INT( ).

The following table compares INT( ), FLOOR( ), CEILING( ), and ROUND( ). (In these examples, the value of the second ROUND( ) argument is 0.)

<expN>	INT( )	FLOOR( )	CEILING( )	ROUND( )
2.56	2	2.00	3.00	2.60
-2.56	-2	-3.00	-2.00	-2.60
2.54	2	2.00	3.00	2.50
-2.54	-2	-3.00	-2.00	-2.50


INT( ) Example

The following example uses INT( ) to display the contents of a field:

SET TALK OFF
CLEAR
STORE 0 TO rate, min_time, total
STORE "U" TO up_down
STORE "$  " TO set_cur
@  4, 8 SAY "What currency do you want to use " + ;
   "($, DM, FR, YEN)" GET set_cur FUNCTION "@!"
@  5,32 SAY "What is the billing rate?" ;
   GET rate PICTURE "999.99"
@  6,19 SAY "What is the billing time (in minutes)?";
   GET min_time PICTURE "9999"
@  7,25 SAY "Do you want to round Up or Down?" ;
   GET up_down PICTURE "!" VALID up_down $ "UD"
@  8,12 SAY ;
   "What is the total billable time (in minutes)?";
   GET total PICTURE "9999"
READ

time = INT(total/60) + (MOD(total,60)/60)
bill = IIF(up_down = "U", ;
   CEILING(total/min_time), ;
   FLOOR(total/min_time))
@ 10,12 SAY "The total billable time is " + ;
   LTRIM(STR(time,7,2)) + " hours"
dec = SET("DECIMALS")
SET DECIMALS TO 2
cur = SET("CURRENCY")
SET CURRENCY TO TRIM(set_cur)
IF set_cur = "YEN"
   SET CURRENCY RIGHT
ENDIF
IF set_cur = "DM" .OR. set_cur = "FR"
   sep   = SET("SEPARATOR")
   point = SET("POINT")
   SET SEPARATOR TO "."
   SET POINT TO ","
ENDIF
@ 11,12 SAY "For a total of "
@ 11,27 SAY bill * rate PICTURE "$$999,999.99"
SET DECIMALS TO dec
SET CURRENCY TO cur
IF set_cur = "YEN"
   SET CURRENCY LEFT
ENDIF
IF set_cur = "DM" .OR. set_cur = "FR"
   SET SEPARATOR TO sep
   SET POINT TO point
ENDIF


See Also

ABS( )

CEILING( )

FLOOR( )

ROUND( )


ISALPHA( )

See Also	Example	Portability	String Data

Returns .T. if the first character of a string is alphabetic.

Syntax

ISALPHA(<expC> | <memo field>)

<expC> | <memo field>

The character string or memo field to test.

Description

ISALPHA( ) tests the first character of a character expression or memo field and returns .T. if it is an alphabetic character. ISALPHA( ) returns .F. if the character is not alphabetic or if the character expression or memo field is empty.

The current language driver defines the character values that are lowercase and uppercase alphabetic. In a U.S. language driver, a lowercase alphabetic character is from a to z, and an uppercase alphabetic character is from A to Z. See Appendix C in the Programmer's Guide for more information about language drivers.


ISALPHA( ) Example

The following example uses ISALPHA( ) to determine if the first character of each string is an alphabetic character:

? ISALPHA("Borland")               && Returns .T.
? ISALPHA(" Borland")              && Returns .F.
? ISALPHA("")                      && Returns .F.
? ISALPHA('100 Borland Way')       && Returns .F.

The next example uses ISALPHA( ) to determine whether a character location specified by SUBSTR( ) is alphabetic. With the variable Is_Alpha initialized to .F., the Street procedure steps through the contents of Address field until it encounters an alphabetic character and returns the string that follows:

CLEAR
SET TALK OFF
USE Clients
DO WHILE .NOT. EOF()
  ? Street(Address)  && just the street name
  SKIP
ENDDO

FUNCTION Street
Parameter Full_Addr
Full  = TRIM(Full_Addr)
Len   = LEN(Full)
Start = 0
IF Len > 0                     && Check if longer;
                               than 0
   Is_Alpha = .F.
   Char_Pos =  1
   DO WHILE .NOT. Is_Alpha     && Check until alpha
      Is_Alpha = ISALPHA(SUBSTR(Full,Char_Pos,1))
      Start    = Start + 1
      Char_Pos = Char_Pos + 1
   ENDDO
   Street = SUBSTR(Full,Start,Len-Start)
ELSE
   Street =  ""
ENDIF
RETURN Street                  && Return the;
                               street name only


Portability

The <memo field> argument is not supported in dBASE IV or dBASE III PLUS.


See Also

CHARSET( )

ISLOWER( )

ISUPPER( )

LDRIVER( )

LOWER( )

UPPER( )


ISBLANK( )

See Also	Example	Portability	Expressions and Type Conversion

Determines if a specified field or expression is blank.

Syntax

ISBLANK(<exp>)

<exp>

An expression of any data type.

Description

ISBLANK( ) returns .T. if a specified expression is blank, .F. if it contains data. A field is blank if it has never contained a value or if you used the BLANK command on it. ISBLANK( ) returns a different result from EMPTY( ) when used on numeric fields; ISBLANK( ) differentiates between zero and blank values, while EMPTY( ) does not.

ISBLANK( ) is especially useful when performing functions such as averaging, since it ensures that blank values are not included in the calculation. If you do not need to differentiate between 0 or blank values in numeric fields, you can use either ISBLANK( ) or EMPTY( ).


ISBLANK( ) Example

The following interactive commands from the Command window demonstrate the functionality of ISBLANK( ):

Empty = SPACE(20)
? ISBLANK(Empty)             && Returns .T.
Empty = "        "
? ISBLANK(Empty)             && Returns .T.
mDate = {  /  /  }           && or {}
? ISBLANK(mDate)             && Returns .T.
USE Clients
APPEND BLANK                 && adds new blank record
? ISBLANK(StartBal)          && Returns .T.
REPLACE StartBal WITH 0
? ISBLANK(StartBal)          && Returns .F.
BLANK FIELDS StartBal
? ISBLANK(StartBal)          && Returns .T.
? ISBLANK(Notes)             && Returns .T.  for memo
REPLACE Notes WITH "Something for the memo field"
? ISBLANK(Notes)             && Returns .F. for ;
                                memo field

Use ISBLANK( ) to exclude blank records from calculations.

CALCULATE AVG(StartBal) FOR .NOT. ISBLANK(StartBal)

The following example uses ISBLANK( ) to select only those records with non-blank values in the StartBal field of the Clients table to create a report:

SET SAFETY OFF
SET TALK OFF
USE Clients EXCLUSIVE
INDEX ON Company TAG Company
BLANK FIELDS StartBal FOR StartBal = 0
? CENTER("Start Balance Report")
?
SCAN
  IF .NOT. ISBLANK(StartBal)
    ? COMPANY + "Balance Due " + ;
      TRANSFORM(StartBal,"@$999,999,999.99")
  ENDIF
ENDSCAN
RETURN

See EMPTY( ) for additional examples of ISBLANK( ).


Portability

Not supported in dBASE III PLUS.


See Also

APPEND

BLANK

EMPTY( )

SPACE( )

TYPE( )


ISCOLOR( )

See Also	Example	Colors and Fonts

Returns .T. if system monitor is color, .F. if it is monochrome. ISCOLOR( ) is supported primarily for compatibility with dBASE IV. dBASE for Windows determines the color palette to use from the Color settings specified in the Windows Control Panel.

Syntax

ISCOLOR( )

Description

Use ISCOLOR( ) to determine if the current system has a color monitor.

ISCOLOR( ) helps you anticipate and prevent problems that happen when an application is transferred from system to system. For example, using the SET COLOR TO or SET COLOR OF command on a monochrome system can cause text to "disappear" for some of the options. Programs that are used on a variety of systems should use ISCOLOR( ) to determine the type of system before using these commands.


ISCOLOR( ) Example

In the following example, if a monochrome monitor is used, color is set to white/black; otherwise., the default color is set to white/blue in the foreground and blue/green in the background:

IF ISCOLOR()
  SET COLOR TO w/b,b/g
  CLEAR
  ? "Testing color"
ELSE
  SET COLOR TO w+
  CLEAR
  ? "Monochrome display"
ENDIF


See Also

SET COLOR TO

SET COLOR OF


ISLOWER( )

See Also	Example	Portability	String Data

Returns .T. if the first character of a string is alphabetic and lowercase.

Syntax

ISLOWER(<expC> | <memo field>)

<expC> | <memo field>

The character string or memo field to test.

Description

ISLOWER( ) tests the first character of a character expression or memo field and returns .T. if it is a lowercase alphabetic character. ISLOWER( ) returns .F. if the character is not lowercase or if the character expression or memo field is empty.

The current language driver defines the character values that are lowercase and uppercase alphabetic. In a U.S. language driver, a lowercase alphabetic character is from a to z, and an uppercase alphabetic character is from A to Z. See Appendix C in the Programmer's Guide for more information about language drivers.


ISLOWER( ) Example

The following example uses ISLOWER( ) to determine if the first character of each string is a lowercase letter:

? ISLOWER("Borland")                   && Returns .F.
? ISLOWER(" Borland")                  && Returns .F.
? ISLOWER("")                          && Returns .F.
? ISLOWER('100 Borland Way')           && Returns .F.
? ISLOWER("software craftmanship")     && Returns .T.


Portability

The <memo field> argument is not supported in dBASE IV or dBASE III PLUS.


See Also

CHARSET( )

ISALPHA( )

ISUPPER( )

LDRIVER( )

LOWER( )

UPPER( )


ISMOUSE( )

See Also	Example	Portability	Keyboard and Mouse Events

Returns a logical true (.T.) when a mouse driver is currently installed on your system, or false (.F.) when no mouse driver is present.

Syntax

ISMOUSE( )

Description

Use ISMOUSE( ) to determine if a mouse driver is installed on the current system. For example, you may want to use ISMOUSE( ) to control whether a message says "Click OK to continue" or "Choose OK to continue."


ISMOUSE( ) Example

The following example uses ISMOUSE( ) to determine if a mouse is enabled and returns the appropriate message to the Command window results pane:

IF ISMOUSE()
  ? "The mouse is enabled" AT 5
ELSE
  ? "The mouse is disabled" AT 5
ENDIF


Portability

Not supported in dBASE III PLUS.


See Also

INKEY( )

MDOWN( )

MCOL( )

MROW( )

ON MOUSE


ISTABLE( )

See Also	Example	Table Basics

Tests for the existence of a table in a specified database and returns .T. if the table exists or .F. if it does not.

Syntax

ISTABLE(<table name>)

<table name>

The name of the table to search for. You must also provide the full path if the table is not in the current directory or a directory specified with SET PATH. You can also specify a path relative to the current directory.

You can also check for the existence of a table in a database (defined using the IDAPI Configuration Utility) by specifying the database as a prefix (enclosed in colons) to the name of the table, that is, :database name:table name. If the database is not already open, dBASE for Windows displays a dialog box in which you specify the parameters, such as a login name and password, necessary to establish a connection to that database.

Description

Use ISTABLE( ) to confirm the existence of a table of the type specified by SET DBTYPE. If the table is not in the current default directory, you must include the directory path with the name of the table. You can also specify a database if you want to search for a table that is not in the current database.


ISTABLE( ) Example

The following example uses ISTABLE( ) to check for the existence of a specified Paradox table on the SAMPLES directory, and if present, opens the table in a Browse:

CLOSE ALL
CLEAR
IF ISTABLE("C:\DBASEWIN\SAMPLES\Customer.DB")
  USE Customer
  BROWSE
ELSE
  ? "No such table exists"
ENDIF
RETURN


See Also

DIR

DISPLAY FILES

FILE( )

GETFILE( )

PUTFILE( )

SET DEFAULT

SET DATABASE

SET DBTYPE

SET DIRECTORY

SET PATH


ISUPPER( )

See Also	Example	Portability	String Data

Returns .T. if the first character of a string is alphabetic and uppercase.

Syntax

ISUPPER(<expC> | <memo field>)

<expC> | <memo field>

The character string or memo field to test.

Description

ISUPPER( ) tests the first character of a character expression or memo field and returns .T. if it is an uppercase alphabetic character. ISUPPER( ) returns .F. if the character is not uppercase or if the character expression or memo field is empty.

The current language driver defines the character values that are lowercase and uppercase alphabetic. In a U.S. language driver, a lowercase alphabetic character is from a to z, and an uppercase alphabetic character is from A to Z. See Appendix C in the Programmer's Guide for more information about language drivers.


ISUPPER( ) Example

The following example uses ISUPPER( ) to determine if the first character of each string is an uppercase letter:

? ISUPPER("Borland")                   && Returns .T.
? ISUPPER(" Borland")                  && Returns .F.
? ISUPPER("")                          && Returns .F.
? ISUPPER('100 Borland Way')           && Returns .F.
? ISUPPER("Software Craftmanship")     && Returns .T.


Portability

The <memo field> argument is not supported in dBASE IV or dBASE III PLUS.


See Also

CHARSET( )

ISALPHA( )

ISLOWER( )

LDRIVER( )

LOWER( )

UPPER( )


ITOH( )

See Also	Example	Portability	Expressions and Type Conversion

Returns the hexadecimal equivalent of a specified decimal number as a character string.

Syntax

ITOH(<expN 1>[, <expN 2>])

<expN 1>

The decimal number whose hexadecimal equivalent to return.

<expN 2>

The number of characters to include in the returned hexadecimal character string. If <expN 2> is greater than the number of characters returned, ITOH( ) pads the returned string with leading 0's to make it <expN 2> characters long. For example, ITOH(21) returns the string "15", while ITOH(21,4) returns "0015".

If expN2 is smaller than the length of the returned string, it is ignored.

Description

Use ITOH( ) to convert a decimal number to a character string representing its hexadecimal equivalent. ITOH( ) is the inverse function of HTOI( ), which accepts hexadecimal numbers in the form of character expressions and returns a decimal equivalent. Use both functions with Windows Application Programming Interface (API) calls that require hexadecimal values.


ITOH( ) Example

 ? ITOH(13824,4)  && Returns 3600


Portability

Not supported in dBASE III PLUS or dBASE IV.


See Also

HTOI( )


JOIN

See Also	Example	Table Organization

Combines records of the current table with records of a specified table to create a new table.

Syntax

JOIN WITH <alias> TO <filename> | ? | <filename skeleton>
[[TYPE] [PARADOX | DBASE] ]
FOR <condition>
[FIELDS <field list>]

<alias>

The alias table with which to combine the current table's records to create <filename>.

TO <filename> | ? | <filename skeleton>

Creates the table file <filename>. By default, dBASE for Windows assigns a .DBF extension to <filename> and saves the file in the current directory. The ? and <filename skeleton> options display a dialog box, in which you specify the name of the target file and the directory to save it in.

You can also create a table in a database (defined using the IDAPI Configuration Utility) by specifying the database as a prefix (enclosed in colons) to the name of the table, that is, :database name:table name. If the database is not already open, dBASE for Windows displays a dialog box, in which you specify the parameters, such as a login name and password, necessary to establish a connection to that database.

[TYPE] PARADOX | DBASE

Specifies the type of table you want to create. The TYPE keyword is included for readability only; it has no effect on the operation of the command.

Specifying DBASE creates a dBASE table (the default). If you do not include an extension for <filename>, dBASE for Windows assigns a .DBF extension.

Specifying PARADOX creates a Paradox table with a .DB extension.

FOR <condition>

Restricts JOIN to records in the current table that meet the specified <condition>.

FIELDS <field list>

Limits the fields of the new table to those included in <field list>. Enter field names from the current table directly and field names of the alias table in the form alias>field. Without FIELDS, the new table contains all fields of both tables.

Description

Use JOIN to create new tables joining the records of two existing tables. The fields list can specify any type of field from either table, except for binary, memo, and OLE fields.

You can use the SET FIELDS command before JOIN, rather than specifying a fields list. In that case, only the fields listed in SET FIELDS are included in the new table. If you do not specify a fields list, field assignments are first made from the current table and then from the second table. If both tables contain a field with the same name, only the field from the first table is added to the new table; the field in the second table is ignored.

The FOR condition typically compares the values of fields in records of one table with the value of fields in records of another table. In the simplest case, the equality operator (=) determines whether the values of one table's fields are identical to the other table's fields (regardless of whether the field names are the same). Use care when formulating the FOR condition to ensure that only the records you want are included in the new table, as the JOIN command can potentially create a very large table (equal to the number of records in the current table multiplied by the number of records in the alias table).

Because of the number of records compared during the JOIN operation, JOIN is also potentially a very time-consuming command. To provide temporary combinations of data from more than one table, without taking the time required by JOIN, use the SET RELATION command.


JOIN Example

The following example uses JOIN to create a new table with specified fields drawn from both the original tables based on a stated relation between the two tables:

CLOSE DATABASE
USE Company IN SELECT() && Work area 1
USE Contact IN SELECT() && Work area 2
SELECT Contact
JOIN WITH Company ;
   FOR Contact->CompCode = Company->CompCode ;
   FIELDS Contact->CompCode, Company->Company,;
     Contact->Contact;
   TO CompCntc

The CompCntc table has been created with a structure of the fields in the FIELDS clause. There is now a single table with fields Compcode, Company, and Contact. The FOR clause was necessary to ensure that each company was linked to the contacts at that company.

SELECT 3
USE CompCntc
LIST OFF


See Also

SELECT

SET RELATION

USE


KEY( )

See Also	Example	Portability	Table Organization

Returns the key expression used to create the specified index.

Syntax

KEY( [<.mdx filename expC>,] <index position expN> [, <alias>] )

<.mdx filename expC>

Specifies a multiple index file that contains the index tag you want to check.

<index position expN>

Selects an index file or tag by the position of an index tag in an .MDX file or the position of an index file in the list of open indexes for the current or a specified work area.

<alias>

A work area number (1 through 225), letter (A through J), or alias name. The work area letter or alias name must be enclosed in quotes.

Description

The KEY( ) function returns the key expression that was used to create a specified index. If you have several open .NDX indexes or several indexes with tag names listed in multiple index files, you can use KEY( ) to determine the key expression of each index.

If no index is open in the current or specified work area, or if <index position expN> does not evaluate to the position of any index in the index list, KEY( ) returns an empty string ("").


KEY( ) Example

The following example uses KEY( ) to retrieve the indexes key statement.

USE Company  EXCLUSIVE
INDEX ON CompCode TAG CompCode
INDEX ON Zip_Postal+Company TAG ZipCompany

TagCompCode=TAGNO("CompCode")
* Get the Tag number of CompCode
TagZipCompany=TAGNO("ZipCompany")
* Get the Tag number of ZipCompany

? TagCompCode, TAG(TagCompCode), KEY(TagCompCode)
? TagZipCompany, TAG(TagZipCompany),;
                 KEY(TagZipCompany)


Portability

Not supported in dBASE III PLUS.


See Also

INDEX

NDX( )

ORDER( )

SET INDEX

SET ORDER

TAG( )

TAGCOUNT( )

TAGNO( )

USE


KEYBOARD

See Also	Example	Portability	Keyboard and Mouse Events

Puts the value of <expC> into the typeahead buffer. This command is supported primarily for compatibility with dBASE IV. In dBASE for Windows, forms do not use the typeahead buffer.

Syntax

KEYBOARD <expC>
[CLEAR]

<expC>

A character, character string, the CHR( ) function, or a mnemonic string representing a key label.

CLEAR

Empties the typeahead buffer before inserting <expC>.

Description

The keyboard typeahead buffer stores keystrokes the user enters while dBASE is busy processing other data. Use KEYBOARD to simulate keystrokes by placing them in the typeahead buffer. Use INKEY( ) to check the decimal value of the first character in the typeahead buffer and to remove that character from the buffer.

KEYBOARD can place any number of characters in the typeahead buffer, up to the limit (if any) specified by SET TYPEAHEAD.


KEYBOARD Example

The following examples show KEYBOARD used with ON KEY LABEL:

ON KEY LABEL F2 KEYBOARD "510"
* F2 types in the area code

ON KEY LABEL F3 KEYBOARD DTOC(DATE())
* F3 types in today's date

USE ORDERS
ON KEY LABEL F4 KEYBOARD "BROWSE" + CHR(13)
ON KEY LABEL F5 KEYBOARD [BROWSE] + [{13}]
ON KEY LABEL F6 KEYBOARD [BROWSE] + "{CTRL-M}"
* These three commands are each equivalent to
* typing in BROWSE followed by the ENTER key

ON KEY LABEL F7 KEYBOARD CHR(27)
* Equivalent to the Escape key

ON KEY LABEL F8 KEYBOARD "{CTRL-W}"
* F8 is used in a BROWSE to close the
* browse and save the current record

ON KEY LABEL F9 KEYBOARD "{DNARROW}"
* F9 is used in a BROWSE in place of
* the down arrow.

ON KEY LABEL F10;
  KEYBOARD TRIM(RTRIM(STR(Orders->Amt_Paid,9,2)))
* F10 keys in the value in Amt_Paid
* It is programmed for a data entry person
* who has to re-enter details when
* printing a check


Portability

Not supported in dBASE III PLUS.


See Also

CLEAR TYPEAHEAD

INKEY( )

NEXTKEY( )

SET TYPEAHEAD


KEYMATCH( )

See Also	Example	Portability	Table Organization

Indicates if a specified expression is found in an index.

Syntax

KEYMATCH (<exp> [,<index position expN> |
[<.mdx filename expC>,]<tag expN>
[, <alias>]])

<exp>

Specifies the expression of any data type that you want to look for. For Paradox and SQL tables, you can specify one or more values (separated by commas) that match single or composite index key fields.

<index position expN>

Specifies an .NDX file by the position of the index in the list of open indexes for the current or a specified table.

<.mdx filename expC>

Specifies a multiple index file that contains the index tag you want to check.

<tag expN>

Specifies an index tag by the position of an index tag in an .MDX file for the current or a specified table.

<alias>

Specifies the work area where the specified .NDX or .MDX is open. You can specify a work area number (1 through 225), letter (A through J), or alias name. The work area letter or alias name must be enclosed in quotes.

Description

The KEYMATCH( ) function determines if specified key expressions are found in a particular index. KEYMATCH( ) returns .T. or .F. to indicate whether the specified expression was found. SET EXACT controls whether exact matches of character string data is required.

A primary use of the KEYMATCH( ) function is to check for duplicate values during an APPEND operation.

KEYMATCH( ) looks only in the specified index file or tag. It ignores the settings for SET DELETED, SET FILTER, and SET KEY, ensuring the integrity of data in a table even when you work with a subset of the table records.

If you specify only an expression (<exp>) whose value you want to match, KEYMATCH( ) searches the current master index for an index key with the same value. If a matching index key is found, KEYMATCH( ) returns .T.


KEYMATCH( ) Example

The following example uses KEYMATCH( ) to determine if a passed value is found in the index:

SET EXACT OFF  && KEYMATCH is affected by SET EXACT
USE Company EXCLUSIVE
INDEX ON Company  TAG CompanyCa;
  FOR State_Prov = "CA"
INDEX ON City TAG City OF Location
? KEYMATCH("Cons",TAGNO("CompanyCa"))
? KEYMATCH("Compton","Location",TAGNO("City"))

Both answers return .T. from the sample table.


Portability

Not supported in dBASE III PLUS.


See Also

INDEX

KEY( )

MDX( )

NDX( )

ORDER( )

SET INDEX

SET ORDER

USE


LABEL FORM

See Also	Example	Portability	Input/Output

Generates and displays or prints a label report, using the label format stored in a specified label file and information derived from records in the current table.

Syntax

LABEL FORM <filename 1> | ? | <filename skeleton 1>
[<scope>] [FOR <condition 1>] [WHILE <condition 2>]
[SAMPLE]
[TO FILE <filename 2> | ? |<filename skeleton 2>] | [TO PRINTER]

<filename 1> | ? | <filename skeleton>

The file to get label formats from. The ? and <filename skeleton> options display a dialog box from which you can select a file. If you specify a file without including its path, dBASE looks for the file in the current directory, then in the path you specify with SET PATH. If you specify a file without including its extension, dBASE looks for .RPL, .LBG, or .LBL, in that order.

<scope>

The number of records in the current table from which to derive labels. RECORD <n> identifies a single record by its record number. NEXT <n> identifies n records, beginning with the current record. ALL specifies all records. REST specifies all records from the current record to the end of the file.

FOR <condition 1>
WHILE <condition 2>

Determines which records are affected by LABEL FORM. FOR restricts LABEL FORM to records that meet <condition 1>. WHILE starts processing with the current record and continues with each subsequent record as long as <condition 2> is true.

SAMPLE

Displays or prints a label containing asterisks for text and then prompts you for more samples.

TO FILE <filename 2> | ? | <filename skeleton 2>

Directs output to the text file <filename>. By default, dBASE assigns a .TXT extension to <filename> and saves the file in the current directory. The ? and <filename skeleton> options display a dialog box in which you specify the name of the target file and the directory to save it in.

TO PRINTER

Directs output to the printer.

Description

Use LABEL FORM to print or display labels in a format that you have defined in the Report Designer using CREATE LABEL or MODIFY LABEL. For information about using the Report Designer, see Designing Reports and Labels or the Crystal Reports documentation. If you do not specify a <scope>, WHILE <condition 1>, or FOR <condition 2> option, LABEL FORM prints the label specifications for each record in record number or index order.

When printing or displaying a label report that includes groups of data or group subtotals, either the current table must be in sorted order or its master index must be in use. The sorted file or index must be arranged according to the value of the field on which the data is grouped.

LABEL FORM without the TO FILE or TO PRINTER options displays the labels in the results pane of the Command window or current user-defined window.


LABEL FORM Example

This example opens the Company database and then generates labels using the Complbl1 label form:

CLOSE DATABASE
USE Company
LABEL FORM Complbl1 TO PRINT
* This label format produces one across labels,
* 6 lines per label, with Company, Street,
* City, State and Zip code:
* General Consolidated
* 35 Libra Plaza
* Nashua  NH               09242
*
*
*
* Consolidated Brands, Inc.
* 3 Independence Parkway
* Rivendell  CA            93456
*
*
*


Portability

The <filename skeleton> option is not supported in dBASE IV or dBASE III PLUS.


See Also

CREATE LABEL


LASTKEY( )

See Also	Example	Portability	Keyboard and Mouse Events

Returns the value of the key or key combination that was pressed to terminate execution of a full-screen command. This command is supported primarily for compatibility with dBASE IV. In dBASE for Windows, use properties such as OnClick to initiate actions based on how a user exits a form.

Syntax

LASTKEY( )

Description

Use LASTKEY( ) to determine the last key pressed when the user exits an editing session.

Most editing sessions are executed with full-screen editing commands such as APPEND, BROWSE, and EDIT, or with @...GET in combination with READ. When a full-screen editing command is terminated with a keystroke, LASTKEY( ) returns the decimal number representing that key. See INKEY( ) Values and READKEY( ) Values for a complete list of values returned by LASTKEY( ).

READKEY( ) also returns a number indicating the key(s) pressed when you exit a full-screen command, but the numbers READKEY( ) returns have a different meaning from those returned by LASTKEY( ). Also, READKEY( ) returns different values depending on whether data was changed in the editing session. For more information, see READKEY( ).


LASTKEY( ) Example

The following example displays the current time and a prompt to press Esc when complete. LASTKEY( ) is used to return the ASCII equivalent of any key pressed. The DO...UNTIL loop continues until LASTKEY( ) returns 27 for the Escape code. INKEY(1) pauses for up to 3 second:

CLEAR
SET ESCAPE OFF
* ESCAPE ON will interrupt the program and the
* Escape key will not be trapped
End=0
DO
  CLEAR
  ? TIME()
  ? CHR(LASTKEY())   && Display lastkey value
  ? "Press Esc to proceed"
  PAUSE = INKEY(3 )
  End = LASTKEY()
UNTIL End = 27
SET ESCAPE ON
CLEAR


Portability

Not supported in dBASE III PLUS.


See Also

INKEY( )

NEXTKEY( )

OnClick

READKEY( )


LDRIVER( )

See Also	Example	Portability	Environment

Returns the name of the language driver the current table or a specified table is using. If no table is open and you issue LDRIVER( ) without an argument, it returns the global language driver in use.

Syntax

LDRIVER( [<alias>] )

<alias>

A work area number (1 through 225), letter (A through J), or alias name. The work area letter or alias name must be enclosed in quotes.

Description

Use LDRIVER( ) to learn which language driver the current table or a specified table is using. If you do not pass LDRIVER( ) an argument, it returns the name of the language driver of the current table or, if no tables are open, the global language driver in use. LDRIVER( ) also returns information on Paradox and SQL databases.

The language driver associated with a table depends on the DOS code page or the IDAPI language driver setting that was in effect when the table was created. With dBASE for Windows, you can choose the language driver that applies to your dBASE data in the [CommandSettings] section in the DBASEWIN.INI file. For example, you can load a German language driver to work with a table created while that driver was active.


LDRIVER( ) Example

This example shows the LDRIVER( ) function and a sample response:

? LDRIVER()  && DB437US0

This example first closes all tables and obtains the global language driver. Then it opens a table and checks whether the table was created with the global language driver. If not, a warning is displayed:

CLOSE ALL
SET LDCHECK OFF
* this program replaces the LDCHECK alert message
GlobalDriver=LDRIVER()
USE Customer
TableLangDriver=LDRIVER()
SET EXACT ON
IF GlobalDriver<>TableLangDriver
  ? "Warning: this table was created"+;
    "with a different language driver"
  ? "Global Language Driver: "+GlobalDriver
  ? DBF()+" Language Driver: "+TableLangDriver
  WAIT
ENDIF
SET EXACT OFF


Portability

Not supported in dBASE IV or dBASE III PLUS.


See Also

ANSI( )

CHARSET( )

OEM( )

SET LDCHECK


LEFT( )

See Also	Example	Portability	String Data

Returns a specified number of characters from the beginning of a character string or memo field.

Syntax

LEFT(<expC> | <memo field>, <length expN>)

<expC> | <memo field>

The string or memo field to extract characters from.

<length expN>

The number of characters to extract from the beginning of the string or memo field.

Description

Starting with the first character of a character expression or a memo field, LEFT( ) returns a specified number, <length expN>, of characters. LEFT( ) returns a maximum of 32766 characters, the maximum length of a string.

If <length expN> is greater than the number of characters in the specified string or memo field, LEFT( ) returns the string as it is, without adding space characters to achieve the specified length. You can use LEN( ) to determine the actual length of the returned string.

If <length expN> is less than or equal to zero, LEFT( ) returns an empty string. If <length expN> is greater than or equal to zero, LEFT(<expC>, <length expN>) achieves the same results as SUBSTR(<expC>, 1, <length expN>).

When LEFT( ) returns characters from a memo field, it counts two characters for each carriage-return and linefeed combination (CR/LF).


LEFT( ) Example

The following example uses LEFT( ) to return a portion of a text string, starting from the left end of the string:

? LEFT("dBASE",1)                && Returns "d"
? LEFT("dBASE",3)                && Returns "dBA"
? LEFT("dBASE",9)                && Returns "dBASE"
? LEFT("dBASE",0)                && Returns ""

The next example uses ISALPHA( ) and SUBSTR( ) to determine the character position of the first alpha character in a string (Address). The derived variable (To) is then used as the length parameter of LEFT( ) to display only the street number portion of the Address field:

CLOSE DATABASES
SET TALK OFF
CLEAR
USE Clients
DO WHILE .NOT. EOF()
? Street_No(Address)             && Returns just
                                 && the street number
SKIP
ENDDO
CLOSE DATABASES

FUNCTION Street_No
Parameter Full_Addr
Full  = TRIM(Full_Addr)
Len   = LEN(full)
To    = 0
IF Len > 0                       && Check if longer
   Is_Alpha = .F.                && than 0
   Char_Pos =  1
   DO WHILE .NOT. Is_Alpha       && Check til alpha
      Is_Alpha = ISALPHA(SUBSTR(full,char_pos,1))
      IF .NOT. Is_Alpha          && Add to variable
         To = To + 1             && to if ISALPHA()
      ENDIF                      && returns .F.
      Char_Pos = Char_Pos + 1
   ENDDO
   Street = LEFT(Full,To-1)
ELSE
   Street = ""
ENDIF                            && Return the
RETURN Street                    && street number


Portability

The <memo field> argument is not supported in dBASE III PLUS. Both dBASE III PLUS and dBASE IV limit the return value of LEFT( ) to 254 characters.


See Also

AT( )

LEN( )

RIGHT( )

SUBSTR( )


LEN( )

See Also	Example	Portability	String Data

Returns the number of characters in a specified character string or memo field.

Syntax

LEN(<expC> | <memo field>)

<expC> | <memo field>

The character string or memo field whose length to find.

Description

LEN( ) returns the number of characters (the length) of a character string or memo field. The length of an empty character string or empty memo field is zero. LEN( ) counts an embedded null character, CHR(0), as one character. When LEN( ) calculates the length of a memo field, it counts two characters for each carriage-return and linefeed combination (CF/LF).

To find the length of numeric or float data, use LENNUM( ).

To find the number of lines in a memo field, use MEMLINES( ). To find the length of a particular line of a memo field, use LEN( ) with MLINE( ). For example, LEN(MLINE(Descrip,3)) returns the length of the third line in the memo field Descrip.


LEN( ) Example

The following examples use LEN( ) to determine the length of text strings:

? LEN("Aloha!")                    && Returns 6
? LEN("")                          && Returns 0
? LEN("Hello" + " There")          && Returns 11

The next example uses LEN( ) to determine the number of characters in the Notes memo field. If Notes has no contents, LEN( ) returns 0:

USE Clients
SCAN
    ? IIF(LEN(Notes)>0,Notes,"Record ";
    + LTRIM(STR(RECNO()))+" has no Notes")
ENDSCAN
CLOSE DATABASES


Portability

The <memo field> argument is not supported in dBASE III PLUS, and dBASE III PLUS and dBASE IV do not count null characters.


See Also

LENNUM( )

MEMLINES( )

MLINE( )

TRIM( )


LENNUM( )

See Also	Example	Portability	Numeric Data

Returns the display length of a specified number, including leading spaces.

Syntax

LENNUM(<expN>)

<expN>

The numeric or float number whose display length to return.

Description

Use LENNUM( ) before formatting a display involving numeric values of varying lengths.

If you pass LENNUM( ) the name of a numeric field, it returns the length of the field.

If a number has eight or fewer whole-number digits and no decimal point, it is by default a numeric-type number; the default display length for numeric-type numbers is 10. For example, LENNUM(123) returns 10.

If a number has more than eight whole-number digits or has a decimal point (or both), it is by default a float-type number. The default display length for float-type numbers is 10 for digits to the left of the decimal point, one place for the decimal point, and the number of places set by SET DECIMALS for digits to the right of the decimal point. For example, if SET DECIMALS is 5, LENNUM(3.14159) returns 16.


LENNUM( ) Example

The following example uses LENNUM( ) to determine the character length of a number:

CLEAR
dec = SET("DECIMALS")
FOR x = 3 TO 9 STEP 1
   SET DECIMALS TO x
   num_val = 3.2 * 1.53
   ? "The results of 3.2 * 1.53 - " + ;
      STR(num_val,7 + x,x) + " - is " + ;
      LTRIM(STR(LENNUM(num_val),2,0)) + ;
      " characters in length"
   ? "  when DECIMALS is SET TO " + ;
      LTRIM(STR(x,1,0))
   ?
NEXT
SET DECIMALS TO dec


Portability

Not supported in dBASE III PLUS or dBASE IV. In dBASE III PLUS and dBASE IV, a number is of numeric type by default, regardless of its length and whether it has a decimal point and digits to the right of the decimal point. In dBASE IV, you must use FLOAT( ) to make the number a float type.


See Also

FLOAT( )

LEN( )

SET DECIMALS

STR( )


LIKE( )

See Also	Example	Portability	String Data

Returns .T. if a specified string matches a specified skeleton string.

Syntax

LIKE(<skeleton expC>, <expC> | <memo field>)

<skeleton expC>

A string containing a combination of characters and wildcards. The wildcards are ? and *.

<expC> | <memo field>

The string or memo field to compare to the skeleton string.

Description

Use LIKE( ) to compare one string to another. The <skeleton expC> argument contains wildcard characters and represents a pattern; the <expC> or <memo field> argument is compared to this pattern. LIKE( ) returns .T. if <expC> or <memo field> evaluates to a string that matches <skeleton expC>. To compare the phonetic similarity between two strings rather than the character-by-character similarity, use DIFFERENCE( ).

Use the wildcard characters ? and * to form the pattern for <skeleton expC>. An asterisk (*) stands for any number of characters, including zero characters. The question mark (?) stands for any single character. Both wildcards can appear anywhere and more than once in <skeleton string>. Wildcard characters in <skeleton expC> can stand for uppercase or lowercase letters.

If * or ? appears in <expC> or <memo field>, they are interpreted as literal, not wildcard, characters, as shown in the following example.

LIKE("a*d","abcd") && returns .T.
LIKE("a*d","aBCd") && returns .T.
LIKE("abcd","a*d") && returns .F.

LIKE( ) is case-sensitive. Use UPPER( ) or LOWER( ) for case-insensitive comparisons with LIKE( ). This is shown in the following example.

LIKE("*xyz","uvwxyz") && returns .T.
LIKE("*xyz","UVWXYZ") && returns .F.
LIKE(LOWER("*xyz"),LOWER("UVWXYZ")) && returns .T.

LIKE( ) returns .T. if both arguments are empty strings. LIKE( ) returns .F. if one argument is empty and the other is not.

LIKE( ) is not affected by SET EXACT or by the current language driver.


LIKE( ) Example

The following example uses LIKE( ) to determine whether two text strings are similar:

? LIKE("abc","abc")                && Returns .T.
? LIKE("abc","Abc")                && Returns .F.
? LIKE("a?c","abc")                && Returns .T.
? LIKE("a*c","abc")                && Returns .T.
? LIKE("a*","abc")                 && Returns .T.
? LIKE("*bc","abc")                && Returns .T.
? LIKE("?abc","abc")               && Returns .F.

The next example uses LIKE( ) to list only those records that contain "COMPUTER" in the company field:

USE Clients
LIST FIELDS Company, Contact ;
  FOR LIKE("*COMPUTER",UPPER(Company))
CLOSE DATABASES


Portability

Not supported in dBASE III PLUS. The <memo field> argument is not supported in dBASE IV.


See Also

AT( )

DIFFERENCE( )

LDRIVER( )

LOWER( )

RAT( )

SET EXACT

SUBSTR( )

UPPER( )


LINENO( )

See Also	Example	Portability	Error Handling and Debugging

Returns the number of the current program line in the current program, procedure, or user-defined function (UDF).

Syntax

LINENO( )

Description

Use LINENO( ) to track program flow. Use it in conjunction with PROGRAM( ) to learn when a program executes a given line of code. You can also use LINENO( ) with ON ERROR to find out which line produces an error.

LINENO( ) is meaningful only when issued from within a program, procedure, or UDF. When issued in the Command window, LINENO( ) returns 0.

LINENO( ) always returns the actual program line number; the number does not reflect the order in which the line executes within the program.


LINENO( ) Example

See ON ERROR for an example of using LINENO( ).


Portability

Not supported in dBASE III PLUS.


See Also

ERROR( )

MESSAGE( )

PROGRAM( )

RESUME

SUSPEND


LIST

See Also	Example	Table Organization

Displays records from the current table in the result pane of the Command window.

Syntax

LIST
[<scope>]
[FOR <condition 1>]
[WHILE <condition 2>]
[[FIELDS] <exp list>]
[OFF]
[TO FILE <filename> | ? | <filename skeleton>] | [TO PRINTER]

<scope>

The number of records to LIST. RECORD <n> identifies a single record by its record number. NEXT <n> identifies n records, beginning with the current record. ALL specifies all records. REST specifies all records from the current record to the end of the file.

FOR <condition 1>
WHILE <condition 2>

Determines which records appear with LIST. FOR restricts LIST to records that meet <condition 1>, starting at the first record of the table or scope and continuing until the end of the table or scope. WHILE starts processing with the current record and continues with each subsequent record as long as <condition 2> is true.

FIELDS <exp list>

Field names or expressions whose contents (values) you want to display; the names of the fields in the list are separated by commas. If you do not list any, dBASE for Windows displays the values of all fields for the current record or the records you specify. The FIELDS keyword is included for readability only; it has no affect on the operation of the command.

OFF

Suppresses display of the record number. Record numbers are not displayed for Paradox or SQL tables.

[TO FILE <filename> | ? | <filename skeleton> ] | [TO PRINTER]

Sends output to a file or to a printer. TO FILE directs output to the text file <filename>, as well as to the Command window (unless SET CONSOLE is OFF). By default, dBASE for Windows assigns a .TXT extension to <filename> and saves the file in the current directory. The ? and <filename skeleton> options display a dialog box, in which you specify the name of the target file and the directory to save it in. TO PRINTER directs output to the printer, as well as to the results pane of the Command window.

Description

Use LIST to view one or more records of the current table in the results pane of the Command window. Issuing DISPLAY without any arguments displays only the current record whereas LIST displays all records. If SET HEADINGS is OFF, dBASE for Windows does not display field names when you issue LIST.

All LIST commands have equivalent DISPLAY commands that output the same information; both LIST and DISPLAY output to the results pane of the Command window. The difference is that LIST commands list continuously, halting after the last window of information, while DISPLAY commands start with and pause at the first window of information. See DISPLAY for a description of how to navigate through DISPLAY and LIST output in the results pane. See the complementary DISPLAY commands for descriptions of the information each DISPLAY and LIST command produces.

If the information output to the results pane is more than the dBASE for Windows buffer can contain, you might not be able to scroll back up to information you have scrolled down through. Use the TO FILE or TO PRINTER options to save all information to a file or as printer output.


LIST Example

The following example uses LIST to show selected data from the Clients table:

USE Clients EXCLUSIVE
LIST ALL
* list all fields in all records

GO TOP       && begin at the first record
LIST NEXT 10 FIELDS Company, Contact OFF
* list only Company and Contact fields
* in the next 10 records
* OFF turns off the record number

INDEX ON COMPANY TAG COMPANY
* create an index by Company
SEEK "C" && find the first Company beginning with "C"
LIST COMPANY WHILE COMPANY="C" OFF
* show Company names so long as the Company begins
* with the letter "C"


See Also

DISPLAY

DISPLAY COVERAGE

DISPLAY FILES

DISPLAY MEMORY

DISPLAY STATUS

DISPLAY STRUCTURE


LIST COVERAGE

See Also	Example	Portability	Error Handling and Debugging

Displays the contents of a coverage file (.COV) in the results pane of the Command window.

Syntax

LIST COVERAGE
<.COV filename> | ? | <filename skeleton>
[ALL]
[SUMMARY]
[TO FILE <filename> | ? | <filename skeleton>] | [TO PRINTER]

<filename 1> | ? | <filename skeleton>

The coverage file that dBASE creates or modifies when SET COVERAGE is ON, and you call a program, or call a procedure or UDF in a procedure file. The ? and <filename skeleton> options display a dialog box from which you can select a coverage file. If you specify a file without including its path, dBASE looks for the file in the current directory, then in the path you specify with SET PATH. If you specify a file without including its extension, dBASE assumes .COV.

ALL

Displays in the results pane of the Command window the following information:

The contents of the coverage file for <filename 1>'s program and of the coverage files for each executed program or procedure file called by <filename 1>'s program

The total number of logical blocks entered and exited in all the program files combined

The percentage of logical blocks entered and exited in all the program files combined

SUMMARY

If ALL is not specified, displays the following information about <filename 1>'s program. If ALL is specified, displays the following information about <filename 1>'s program and about all programs called by <filename 1>'s program:

The logical blocks not entered and exited

The total number of logical blocks entered and exited

The percentage of logical blocks entered and exited

TO FILE <filename 2> | ? | <filename skeleton>

Directs output to <filename 2> and to the results pane of the Command window. By default, dBASE assigns a .TXT extension to <filename 2> and saves the file in the current directory. The ? and <filename skeleton> options display a dialog box in which you specify the name of the target file and the directory to save it in.

TO PRINTER

Directs output to the printer and to the results pane of the Command window.

Description

A coverage file contains the results of the coverage analysis of a program, procedure, or UDF. You cause dBASE to analyze a program, procedure, or UDF and store the results of the analysis in a coverage file with the SET COVERAGE ON command. You can issue LIST COVERAGE in a program file or in the Command window.

LIST COVERAGE displays the contents of <filename 1> and the results of percentage calculations using <filename 1>'s contents. The output appears in the results pane of the Command window, starting at the beginning of the main program's coverage file.

The amount of memory available determines the size of the results pane of the Command window buffer. If the information output is more than the buffer can contain, you might not be able to scroll back up to information that has already been displayed. In that case, use either the TO FILE or TO PRINTER option to send all information to a file or printer.

DISPLAY COVERAGE is the same as LIST COVERAGE, except that LIST COVERAGE does not pause with the first window of information but rather continuously lists the information, halting at the last window. As with DISPLAY COVERAGE output, you can scroll LIST COVERAGE output.


LIST COVERAGE Example

See SET COVERAGE for an example of using LIST COVERAGE.


Portability

Not supported in dBASE IV or dBASE III PLUS.


See Also

#pragma

DISPLAY

LIST

SET COVERAGE


LIST FILES

See Also	Example	Portability	Disk and File Utilities

Displays information about files on disk in the results pane of the Command window.

Syntax

LIST FILES
[[LIKE] <filename 1> | <filename skeleton>]
[ON <drive>]
[TO FILE <filename 2> | ? | <filename skeleton>] | [TO PRINTER]

[LIKE] <filename 1> | <filename skeleton>

The file you want to display information on. LIST FILES <filename skeleton> displays the names of all files matching a template that uses the wildcard characters ? and *. If you specify a file, and the file is not in the default directory or in the path you specify with SET PATH, then <filename> must include the drive and path. LIKE has no effect on the operation of the command; include it for readability only.

ON <drive>

The disk drive containing the files you want to display information on. By default, dBASE looks for the file or files you specify in the current drive and directory.

TO FILE <filename 2> | ? | <filename skeleton>

Directs output to the text file <filename 2> and to the results pane of the Command window. By default, dBASE assigns a .TXT extension to <filename 2> and saves the file in the current directory. The ? and <filename skeleton> options display a dialog box in which you specify the name of the target file and the directory to save it in.

TO PRINTER

Directs output to the printer and to the results pane of the Command window.

Description

LIST FILES is a utility command that lets you perform a directory listing. The information provided on each file includes its name, its size in bytes, and the date of its last update. LIST FILES also shows the total number of bytes used by the listed files, the number of bytes left on disk, and the total disk space.

LIST FILES with no options lists only table files (.DBF) in the current default directory. The number of records is displayed for each table, along with its size in bytes, and the date of its last update.

You can use the wildcard characters * and ? to identify multiple files with similar names. For example, although LIST FILES * is equivalent to LIST FILES with no argument (only .DBF files are displayed), LIST FILES N* displays all .DBF files beginning with N. LIST FILES N*.* displays all files beginning with N, regardless of extension. LIST FILES N????.DBF displays all .DBF files that have five-letter names beginning with N.

If the information output is more than dBASE's buffer can contain, you might not be able to scroll back up to information you have scrolled down through. Use either the TO FILE or TO PRINTER option to send all information to a file or printer.

DISPLAY FILES is the same as LIST FILES, except that LIST FILES does not pause with the first window of information but rather continuously lists the information, halting at the last window. As with DISPLAY FILES output, you can scroll LIST FILES output.

The SET DATABASE and SET DBTYPE settings affect DISPLAY FILES and LIST FILES output.


LIST FILES Example

The following examples use LIST FILES:

LIST FILES
* Shows all tables in current subdirectory
LIST FILES ON B: && Shows all tables on B drive
LIST FILES A:    && Shows all tables on A drive
LIST FILES *.prg && Shows all program files
LIST FILES LIKE *.* ON C:\DBASE
* Shows all files on C:\DBASE


Portability

Not supported in dBASE III PLUS. The ON <drive> and TO FILE ? options are not supported in dBASE IV.

In dBASE IV, if you use TO FILE <filename 2> and do not include an extension, dBASE IV adds a .PRT extension. dBASE for Windows adds a .TXT extension instead.


See Also

DIR

DISPLAY

FILE( )

LIST

SET DATABASE

SET DBTYPE

SET DEFAULT


LIST MEMORY

See Also	Portability	Environment

Displays information about memory variables in the results pane of the Command window.

Syntax

LIST MEMORY
[TO FILE <filename> | ? | <filename skeleton>] | [TO PRINTER]

TO FILE <filename> | ? | <filename skeleton>

Directs output to the text file <filename>, also called the target file, and to the results pane of the Command window. By default, dBASE assigns a .TXT extension to <filename> and saves the file in the current directory. The ? and <filename skeleton> options display a dialog box in which you specify the name of the target file and the directory to save it in.

TO PRINTER

Directs output to the printer and to the results pane of the Command window.

Description

Use LIST MEMORY to display the contents and size of a memory variable list. If you haven't used ON KEY or SET FUNCTION to reassign the F7 key, pressing F7 is a quick way to execute LIST MEMORY.

LIST MEMORY displays information about both user-defined and system memory variables. The following information on user-defined memory variables is displayed.

Name

Scope (public, private, local, static or hidden)

Data type

Value

Number of active memory variables

Number of memory variables still available for use

Number of bytes of memory used by character variables

Number of bytes of memory still available for user character variables

Name of the program that initialized private memory variables

The following information on system memory variables is displayed.

Name

Scope (public, private, or hidden)

Data type

Current value

The amount of memory available determines the size of the results pane of the Command window buffer. If the information output is more than the buffer can contain, you might not be able to scroll back up to information that has already been displayed. In that case, use either the TO FILE or TO PRINTER option to send all information to a file or printer.

If SET SAFETY is ON and a file exists with the same name as the target file, dBASE displays a dialog box asking if you want to overwrite the file. If SET SAFETY is OFF, any existing file with the same name is overwritten without warning.

DISPLAY MEMORY is the same as LIST MEMORY, except that LIST MEMORY displays the information without pauses, halting at the last window. As with DISPLAY MEMORY output, you can scroll LIST MEMORY output.


Portability

Only a TO PRINT option is supported in dBASE III PLUS. The ? and <filename skeleton> options are not supported in dBASE IV. If you don't specify a file-name extension with the TO FILE <filename> option, dBASE IV adds .PRT instead of .TXT.


See Also

LIST

LOCAL

PRIVATE

PUBLIC

SET FUNCTION

SET SAFETY

ON KEY

STATIC

STORE


LIST STATUS

See Also	Portability	Environment

Displays information about the current dBASE environment in the Results pane of the Command window.

Syntax

LIST STATUS
[TO FILE <filename> | ? | <filename skeleton>] | [TO PRINTER]

TO FILE <filename> | ? | <filename skeleton>

Directs output to the text file <filename>, also called the target file, and to the Results pane of the Command window. By default, dBASE assigns a .TXT extension to <filename> and saves the file in the current directory. The ? and <filename skeleton> options display a dialog box in which you specify the name of the target file and the directory to save it in.

TO PRINTER

Directs output to the printer and to the Results pane of the Command window.

Description

Use LIST STATUS to identify open tables and index files and to check the status of the SET commands. LIST STATUS shows information related to the current session only.

If you haven't used ON KEY, SET, or SET FUNCTION to reassign the F6 key, pressing F6 is a quick way to execute LIST STATUS.

LIST STATUS displays the following information:

Name and alias of open tables in each work area

Names of all open memo files in each work area

Name of any open format file in each work area

Names of all open indexes and their index key expressions in each work area

SET ORDER setting in each work area

Master index, if any, in each work area

Database relations in each work area

Filter conditions in each work area

SET PATH file search path

SET DEFAULT drive setting

Current work area

SET PRINTER or SET DEVICE setting

DBTYPE setting

Numeric settings for SET MARGIN, SET DECIMALS, SET MEMOWIDTH, SET HISTORY, SET TYPEAHEAD, SET ODOMETER, SET REFRESH, and SET REPROCESS

ON KEY, ON ESCAPE, and ON ERROR settings

SET ON/OFF command settings

Programmable function key and SET FUNCTION settings

The amount of memory available determines the size of the Results pane of the Command window buffer. If the information output is more than the buffer can contain, you might not be able to scroll back up to information that has already been displayed. In that case, use either the TO FILE or TO PRINTER option to send all information to a file or printer.

If SET SAFETY is ON and a file exists with the same name as the target file, dBASE displays a dialog box asking if you want to overwrite the file. If SET SAFETY is OFF, any existing file with the same name is overwritten without warning.

DISPLAY STATUS is the same as LIST STATUS, except that LIST STATUS displays the information without pauses, halting at the last window. As with DISPLAY STATUS output, you can scroll LIST STATUS output.


Portability

Only a TO PRINT option is supported in dBASE III PLUS. The ? and <filename skeleton> options are not supported in dBASE IV. If you don't specify a file-name extension with the TO FILE <filename> option, dBASE IV adds .PRT instead of .TXT.


See Also

LIST

SET( )

SETTO( )

SET SAFETY


LIST STRUCTURE

See Also	Example	Table Basics

Displays the field definitions of the specified table.

Syntax

LIST STRUCTURE
[IN <alias>]
[TO FILE <filename> | ? | <filename skeleton>] | [TO PRINTER]

IN <alias>

Identifies the work area of the open table whose structure you want to display rather than that of the current table. You can enter a work area number (1 through 225), letter (A through J), or alias name. The work area letter or alias name must be enclosed in quotes.

[TO FILE <filename> | ? | <filename skeleton>] | [TO PRINTER]

Sends output to a file or to a printer. TO FILE directs output to the text file <filename>, as well as to the Command window. By default, dBASE for Windows assigns a .TXT extension to <filename> and saves the file in the current directory. The ? and <filename skeleton> options display a dialog box, in which you specify the name of the target file and the directory to save it in. TO PRINTER directs output to the printer, as well as to the results pane of the Command window.

Description

Use LIST STRUCTURE to view the structure of the current or a specified table in the results pane of the Command window. LIST STRUCTURE displays the following information about the current or specified table:

Name of the table

Type of table (Paradox, dBASE, or SQL)

Number of records

Date of last update

Fields

Field number

Field name (if SET FIELDS is ON, the greater-than symbol (>) appears next to each field specified with the SET FIELDS TO command)

Type

Length

Number of bytes per record (the sum of field lengths plus one additional byte reserved for storing the asterisk that marks a record for deletion)

Multiply the total number of bytes per record by the number of records in the table to estimate the size of a dBASE table (excluding the size of the table file header).

If the information output to the results pane of the Command window is more than the dBASE for Windows buffer can hold, you might not be able to scroll back up to information you have scrolled down through. Use the TO FILE or TO PRINTER options to save all information to a file or as printer output. You can send output to either a file or printer, but not both at the same time.

DISPLAY STRUCTURE is similar to LIST STRUCTURE, except that LIST STRUCTURE does not pause when the Command window fills, but rather lists the information continuously.

Neither DISPLAY STRUCTURE nor LIST STRUCTURE permit modification of an existing table structure. To alter the structure, use MODIFY STRUCTURE.


LIST STRUCTURE Example

The following example uses DISPLAY STRUCTURE and LIST STRUCTURE to display the structure of a table:

USE Clients
LIST STRUCTURE TO FILE Clients.TXT

The following text is saved in a text file named CLIENTS.TXT by the LIST STRUCTURE command:

Structure for table   : C:\DBASEWIN\SAMPLES\CLIENTS.DBF
Table type            : DBASE
Number of records     : 100
Last update           : 05/01/94
-----------------------------------------------------
Field  Field Name    Type       Length    Dec   Index

    1  CLIENT_ID     CHARACTER       5              N
    2  COMPANY       CHARACTER      35              N
    3  CONTACT       CHARACTER      20              N
    4  ADDRESS       CHARACTER      30              N
    5  CITY          CHARACTER      15              N
    6  STATE         CHARACTER       2              N
    7  ZIP           CHARACTER       5              N
    8  AREACODE      CHARACTER       3              N
    9  PHONE         CHARACTER       8              N
   10  EXTENSION     CHARACTER       5              N
   11  STARTBAL      NUMERIC         8      2       N
   12  BALDATE       DATE            8              N
   13  CUISINE       CHARACTER      15              N
   14  TYPE          NUMERIC         1              N
   15  NOTES         MEMO           10              N
-----------------------------------------------------
** Total **                        171


See Also

DISPLAY

LIST

MODIFY STRUCTURE

SET FIELDS


LISTCOUNT( )

See Also	Example	Portability	Objects

Returns the number of prompts in a list box.

Syntax

LISTCOUNT(<form reference>.<list box reference>)

<form reference>.<list box reference>

<form reference> is an object reference variable pointing to the form in which the list box is placed. <list box reference> is an object reference variable pointing to the list box you evaluate.

You can create <form reference> and <list box reference> with the DEFINE command:

* Create an object reference variable, MyForm.
DEFINE FORM MyForm
* Create an object reference variable, xChoose.
DEFINE LISTBOX xChoose OF MyForm

You can also create <form reference> and <list box reference> with the NEW operator:

MyForm = NEW FORM()
xChoose = NEW LISTBOX("MyForm")

Description

Use LISTCOUNT( ) when you cannot anticipate the number of prompts a list box may have at run time. For example, when you specify "FILE*.*" for the DataSource property, the number of prompts varies when files are added or deleted from the default directory.

You can use LISTCOUNT( ) to control loops that evaluate user choices in a multiple-choice list box. For example, you can see which prompts were chosen by evaluating each prompt with the LISTSELECTED( ) function in a DO...WHILE loop.

You make a list box multiple-choice by setting the Multiple property to true (.T.).


LISTCOUNT( ) Example

The following example defines a form that contains a listbox that displays names from the ANIMALS.DBF table. Property Multiple .T. provides that the user can select more than one listbox prompt. The OnRightMouseDown property calls procedure Checked, which uses LISTCOUNT( ) and LISTSELECTED( ) to send the selected prompts to the Command window results pane with each OnRightMouseDown:

LOCAL f
f = NEW GFORM()
f.Open()

CLASS GFORM OF FORM
   this.Left =         58.60
   this.Height =         10.12
   this.Width =         41.00
   this.Text = "Animals of the World"
   this.OnRightMouseDown = CHECKED
   this.HelpId = ""
   this.HelpFile = ""
   this.Top =          9.35

   DEFINE LISTBOX LB1 OF THIS;
       PROPERTY;
         Left          9.00,;
         Height          4.00,;
         ColorNormal "N/W*",;
         Width         20.00,;
         DataSource "FIELD ANIMALS->NAME",;
         ColorHighLight "W+/B",;
         Multiple .T.,;
         Top          3.00

ENDCLASS

PROCEDURE Checked
FOR i=1 TO LISTCOUNT(Form.LB1)
  ? LISTSELECTED(Form.LB1,i)
NEXT i
RETURN


Portability

Not supported in dBASE IV or dBASE III PLUS.


See Also

DO WHILE

FOR...NEXT

LISTSELECTED( )

Multiple


LISTSELECTED( )

See Also	Example	Portability	Objects

Returns a list box prompt.

Syntax

LISTSELECTED(<form reference>.<list box reference> [, expN])

<form reference>.<list box reference>

<form reference> is an object reference variable pointing to the form in which the list box is placed. <list box reference> is an object reference variable pointing to the list box you evaluate.

You can create <form reference> and <list box reference> with the DEFINE command:

* Create an object reference variable, MyForm.
DEFINE FORM MyForm
* Create an object reference variable, xChoose.
DEFINE LISTBOX xChoose OF MyForm

You can also create <form reference> and <list box reference> with the NEW operator:

MyForm = NEW FORM()
xChoose = NEW LISTBOX("MyForm")

<expN>

The number of the prompt to evaluate. If you include <expN>, LISTSELECTED( ) returns the prompt of the specified item only if it is selected. If you omit <expN>, LISTSELECTED( ) returns the currently-chosen prompt in a single-choice list box or the most recently chosen prompt in a multiple-choice list box.

Description

Use LISTSELECTED( ) to evaluate which list box prompt or prompts are selected.

Use LISTSELECTED( ) in conjunction with LISTCOUNT( ) to evaluate user choices in a multiple-choice list box. For example, you can determine which prompts were chosen by evaluating each prompt with the LISTSELECTED( ) function in a DO...WHILE loop. (If the list box has an uncertain number of prompts, you use LISTCOUNT( ) to determine the number of times to execute the loop.)

You make a list box multiple-choice by setting the Multiple property to true (.T.).


LISTSELECTED( ) Example

The following example defines a form that contains a listbox that displays names from the ANIMALS.DBF table. Property Multiple .T. provides that the user can select more than one listbox prompt. The OnClose procedure Checked uses LISTCOUNT( ) and LISTSELECTED( ) to send the selected record prompts to the Command window results pane with OnRightMouseDown:

LOCAL f
f = NEW GFORM()
f.Open()

CLASS GFORM OF FORM
   this.Left =         58.60
   this.Height =         10.12
   this.Width =         41.00
   this.Text = "Animals of the World"
   this.OnRightMouseDown = CHECKED
   this.HelpId = ""
   this.HelpFile = ""
   this.Top =          9.35

   DEFINE LISTBOX LB1 OF THIS;
       PROPERTY;
         Left          9.00,;
         Height          4.00,;
         ColorNormal "N/W*",;
         Width         20.00,;
         DataSource "FIELD ANIMALS->NAME",;
         ColorHighLight "W+/B",;
         Multiple .T.,;
         Top          3.00

ENDCLASS

PROCEDURE Checked
FOR i=1 TO LISTCOUNT(Form.LB1)
  ? LISTSELECTED(Form.LB1,i)
NEXT i
RETURN


Portability

Not supported in dBASE IV or dBASE III PLUS.


See Also

DO WHILE

FOR...NEXT

LISTCOUNT( )


LKSYS( )

See Also	Example	Portability	Shared Data

Returns information about a locked record or file.

Syntax

LKSYS(<expN>)

<expN>

A number representing the information for LKSYS( ) to return:

<expN>	Returns
0	Time when lock was placed
1	Date when lock was placed
2	Login name of user who locked record or file
3	Time of last update or lock
4	Date of last update or lock
5	Login name of user who last updated or locked record or file
Description

LKSYS( ) returns multiuser information contained in a _dbaselock field of a table. For LKSYS( ) to return information, the current table must have a _dbaselock field. Use CONVERT to add a _dbaselock field to a table. If the current table does not contain a _dbaselock field, LKSYS( ) returns an empty string for any value of <expN>.

When a record is locked, either explicitly or automatically, the time, date, and login name of the user placing the lock are stored in the _dbaselock field of the record. When a file is locked, this same information is stored in the _dbaselock field of the first record of the table.

Passing 0, 1, or 2 as arguments to LKSYS( ) returns values only after an attempted file or record lock has failed. If a file or record lock on a converted table file fails, the information for LKSYS( ) arguments 0, 1, and 2 is written to a buffer from the table's _dbaselock field. If you then pass 0, 1, or 2 to LKSYS( ), the information is read from the buffer. The buffer is not overwritten until you attempt another lock that fails. Thus, 0, 1, and 2 always return the information that was current at the time of the last lock failure.

You can pass 3, 4, or 5 as arguments to LKSYS( ) whether or not the current record or file is currently locked. These arguments return information about the last successful record or file lock. When you pass any of these arguments to LKSYS( ), it returns information directly from the _dbaselock field rather than from an internal buffer.

If you pass 2 or 5 to obtain a user login name, and the _dbaselock field is only 8 characters wide, LKSYS( ) returns an empty string. The first 8 characters of a _dbaselock field are the count, time, and date information of the last update or lock, so the field must be wider than 8 characters to fit part or all of the login user name. Set the width of the field with CONVERT.

Note:	LKSYS( ) does not return locking information about SQL databases or Paradox tables.


LKSYS( ) Example

The following example uses RLOCK( ) to lock a record of the Company table. If not successful, LKSYS( ) returns time, date and user id information on the network user who has locked the record. If the lock is successful the user will branch to a data entry procedure:

CLEAR
USE Company SHARED
GoTo 2
mRetry="Y"
DO WHILE UPPER(mRetry)="Y"
  IF .NOT. RLOCK()
    LckTime = LKSYS(0)
    LckDate = LKSYS(1)
    LckUser = LKSYS(2)
      ? "Lock Info: ",LckTime, LckDate, LckUser
      ?
      Wait "Try again? (Y/N)" to mRetry
  ELSE
    ? "Lock successful - proceed with data entry"
    mRetry=""
  ENDIF
ENDDO
?
WAIT


Portability

Not supported in dBASE III PLUS.


See Also

CHANGE( )

CONVERT

FLOCK( )

RLOCK( )

SET LOCK

UNLOCK


LOAD DLL

See Also	Example	Portability	Windows Programming

Initiates a DLL file.

Syntax

LOAD DLL [<path>] <DLL filename>

[<path>] <DLL name>

The name of the DLL file. <path> is the directory path to the DLL file in which the external function is stored.

Description

Use LOAD DLL to make the resources of a DLL file available to your application.

You can also use LOAD DLL to check for the existence of a DLL file. For example, you can use the ON ERROR command to execute an error trapping routine each time the LOAD DLL command cannot find a specified DLL file.

LOAD DLL does not use the dBASE path to find DLL files. Instead, it searches the following directories:

1.	The current default directory

2.	The Windows directory (the directory containing WIN.COM)

3.	The Windows system directory (the directory containing GDI.EXE)

4.	The directory containing DBASEWIN.EXE

5.	The directories listed in the DOS environment variable PATH

6.	The directories mapped in a network (if any)

A DLL file is a precompiled library of external routines written in non-dBASE languages such as C and Pascal. A DLL file can have any extension, although most have extensions of .DLL.

When you initialize a DLL file with LOAD DLL, dBASE can access its resources; however, it does not become resident in memory until your program or another Windows program uses its resources.

To access a DLL function, create a dBASE function prototype with EXTERN. Then, using the name you specified with EXTERN, call the routine as you would any dBASE function.

LOAD DLL also loads and registers VBX controls.


LOAD DLL Example

The following example uses LOAD DLL to initialize an image resource from a .DLL file:

LOAD DLL MyPicts.DLL
DEFINE FORM Pics FROM 2,2 TO 20,40
DEFINE Image MyPict OF Pics;
  PROPERTY;
  DataSource "Resource MyPicts.DLL 1001",;
  Top 5, Left 5
OPEN FORM Pics


Portability

Not supported in dBASE IV or dBASE III PLUS.


See Also

EXTERN

RELEASE DLL


LOCAL

See Also	Example	Portability	Memory Variables

Declares memory variables that are visible only in the subroutine where they are declared.

Syntax

LOCAL <memvar list>

<memvar list>

The list of memory variables to declare local.

Description

Use LOCAL to declare a list of memory variables available only to the subroutine in which the command is issued. Local variables differ from those declared PRIVATE in one way; private variables are available to lower-level subroutines, while local variables are not. Local variables are accessible only to the subroutine--the program, procedure, or user-defined function (UDF)--in which they are declared.

A variable that is local to a subroutine is in effect a different variable from one with the same name in a higher-level or unrelated routine. Once a local variable is assigned a value, DISPLAY MEMORY and LIST MEMORY indicate a variable of the same name in a higher-level subroutine as hidden.

To declare a variable LOCAL, do so before initializing it to a particular value. Declaring a variable LOCAL, however, does not create it. After declaring a variable LOCAL, you can create and initialize it to a value with STORE or =. You cannot declare local arrays. Local variables are erased from memory when the subroutine that creates them finishes executing.

For more information, see PUBLIC for a table that compares the scope and availability of public, private, local, and static variables.


LOCAL Example

The following example uses LOCAL to declare the variable Today as a memory variable available only in Procedure Results:

SET PROCEDURE TO PROGRAM(1) ADDITIVE
DEFINE FORM Tenure FROM 0,0 TO 15,40
DEFINE TEXT T1 OF Tenure AT 3,4;
  PROPERTY Text "Start Date? (Month/Day/Year)",;
  Width 30
DEFINE Entryfield F1 OF Tenure AT 3,28;
  PROPERTY Value {}, Picture "99/99/99",;
  Width 9
DEFINE EntryField F2 OF Tenure AT 5,28;
  PROPERTY OnGotFocus Results,;
  Value " ", Width 9
DEFINE TEXT T2 OF Tenure AT  5,4;
  PROPERTY TEXT "Years with the company",;
  Width 22
OPEN FORM Tenure

PROCEDURE Results
Local Today
Today = Date()
Form.F2.Value = (Today-Form.F1.Value)/365
RETURN


Portability

Not supported in dBASE IV or dBASE III PLUS.


See Also

CLEAR MEMORY

PRIVATE

PUBLIC

RELEASE

STATIC

STORE


LOCATE

See Also	Example	Table Organization

Searches a table for the first record that matches a specified condition.

Syntax

LOCATE
[<scope>]
[FOR <condition 1>]
[WHILE <condition 2>]

<scope>

The number of records to locate. RECORD <n> identifies a single record by its record number. NEXT <n> identifies n records, beginning with the current record. ALL specifies all records. REST specifies all records from the current record to the end of the file.

FOR <condition 1>
WHILE <condition 2>

Determines which records are affected by LOCATE. FOR restricts LOCATE to records that meet <condition 1>. WHILE starts processing with the current record and continues with each subsequent record as long as <condition 2> is true.

Description

LOCATE performs a sequential search of a table and tests each record for a match to the specified conditions. If a match is found (FOUND( ) returns .T.), the record pointer of the table is positioned at that record. Entering CONTINUE resumes a search, allowing additional records meeting the specified condition to be found.

If no records meet the specified conditions or the bottom of the table is reached, dBASE for Windows returns the message End of LOCATE scope (if SET TALK is ON) and positions the record pointer at the end of file (EOF( ) returns .T., and FOUND( ) returns .F.). dBASE for Windows also returns this message if entering CONTINUE fails to find a record meeting the condition specified in the previous LOCATE.

LOCATE ALL and LOCATE FOR <condition> begin a search at the beginning of the current table, regardless of the position of the record pointer. However, LOCATE WHILE <condition>, LOCATE NEXT <n>, and LOCATE REST begin the search with the current record, rather than with the first record.

LOCATE does not require an indexed table; however, if an index is in use, LOCATE follows its index order. LOCATE uses the rules established by SET EXACT to determine whether a record meets the specified conditions. If SET EXACT is OFF (the default setting), only the beginning characters of the string on the right side of an equals sign need to match the string entered on the left side for LOCATE to determine that a condition has been met. If SET EXACT is ON, the strings must be identical to meet the condition.

The search commands LOCATE, SEEK, and FIND are each designed for use under particular conditions. LOCATE is the most flexible, accepting expressions of any data type as input and searching any field of a table. For large tables, however, a sequential search using LOCATE might be slow.

Use FIND or SEEK for greater speed. Both conduct an indexed search, similar to looking up a topic in a book index and turning directly to the appropriate page, allowing information to be found almost immediately. Once you use the INDEX command to create an index for a table, FIND and SEEK use this index to quickly identify an appropriate record. SEEK offers greater flexibility than FIND by accepting dBASE expressions as well as character and numeric input in specifying values of the key expression.


LOCATE Example

The following example uses LOCATE to find the first company in the file that is in Texas:

USE Clients EXCLUSIVE
LOCATE FOR State_Prov="TX"
* locate does not depend on the index
IF FOUND()
   DISPLAY FIELDS Company, City, State_Prov
ELSE
   ? "No companies in Texas"
ENDIF


See Also

CONTINUE

FIND

FOUND( )

LOOKUP( )

SEEK

SEEK( )

SET EXACT


LOCK( )

See Also	Example	Portability	Shared Data

Locks the current record or a specified list of records in the current table or a specified alias table, and returns .T. if successful.

Syntax

LOCK([<record list expC>] | [<bookmark list expC>]
[,<alias>])

<list expC>

The list of record numbers to lock, separated by commas.

<bookmark list expC>

The list of bookmarks (record indicators) returned by BOOKMARK( ) specifying a record in a non-dBASE table, such as a Paradox table, that does not have natural record-order record numbers. Separate bookmarks by commas.

<alias>

A work area number (1 through 225), letter (A through J), or alias name. The work area letter or alias name must be enclosed in quotes. If you don't include <alias>, LOCK( ) acts on the current table.

You don't have to specify record numbers or bookmarks if you want to specify a value for <alias>. However, if you have specified record numbers or bookmarks, you must precede <alias> with a comma (,).

Description

LOCK( ) is equivalent to RLOCK( ). For more information, see RLOCK( ).


LOCK( ) Example

See RLOCK( ). which is identical to LOCK( ).


Portability

Not supported in dBASE III PLUS. The <bookmark list expC> option is not supported in dBASE IV.


See Also

FLOCK( )

RLOCK( )

SET LOCK

SET RELATION

SET REPROCESS

UNLOCK


LOG( )

See Also	Example	Numeric Data

Returns the logarithm to the base e (natural logarithm) of a specified number.

Syntax

LOG(<expN>)

<expN>

A positive nonzero number that equals e raised to the log. If you specify 0 or a negative number for <expN>, dBASE returns an error.

Description

LOG( ) returns the natural logarithm of <expN>, expressed as a float number. The natural logarithm is the power (exponent) to which you raise the mathematical constant e to get <expN>. For example, LOG(5) returns 1.61 because e^1.61=5.

LOG( ) is the inverse of EXP( ). For example, if LOG(Y)=X, then Y=EXP(X).

Use SET DECIMALS to set the number of decimal places LOG( ) displays.


LOG( ) Example

The following example uses LOG( ) to return the base value and uses EXP( ) to find the cube roots for a set of passed values:

CLEAR
SET DECIMALS TO 2
? "Values" AT 7,"Log" AT 20, ;
    "Exponential of cube" AT 29
? "root of Log values" AT 29
FOR Value = 45 TO 270 STEP 15
? Value AT 3, LOG(Value) AT 12, ;
    EXP(LOG(Value)/3) AT 28
NEXT


See Also

EXP( )

LOG10( )

SET DECIMALS


LOG10( )

See Also	Example	Portability	Numeric Data

Returns the logarithm to the base 10 of a specified number.

Syntax

LOG10(<expN>)

<expN>

A positive nonzero number which equals 10 raised to the log. If you specify 0 or a negative number for <expN>, dBASE returns an error.

Description

LOG10( ) returns the common logarithm of <expN>, expressed as a float number. The common logarithm is the power (exponent) to which you raise 10 to get <expN>. For example, LOG10(100) returns 2 because 10^2=100.

Use SET DECIMALS to set the number of decimal places LOG10( ) displays.


LOG10( ) Example

The following example uses LOG10( ) to return base 10 values:

SET DECIMAL TO 2
?
? "Values" AT 7, "Base 10" AT 19,;
  "Exponential of base 10 values" AT 29
FOR value = 50 TO 200 STEP 10
   @ ROW() + 1, 3 SAY value
   @ ROW(),13 SAY LOG10(value)
   @ ROW(),23 SAY LOG10(EXP(value))
NEXT


Portability

Not supported in dBASE III PLUS.


See Also

EXP( )

LOG( )

SET DECIMALS


LOOKUP( )

See Also	Example	Portability	Table Organization

Searches a field for a specified expression and, if the expression is found, returns the value of a field within the same record.

Syntax

LOOKUP(<return field 1>, <exp>, <lookup field 2>)

<return field 1>

The field of the current or specified table whose value you want to return if a match is found.

<exp>

The expression to look for in the <lookup field 2>. Specify an alias when referring to fields outside the current work area.

<lookup field 2>

The field of the current or a specified table whose value must match <exp>. If <return field 2> is a memo field, <exp> must be a character expression.

Description

The LOOKUP( ) function searches for values of <lookup field 2> that match the specified expression <exp>. If it finds a match, LOOKUP( ) positions the record pointer to the first record where a match occurred and returns the value of <return field 1>.

If no match is found, LOOKUP( ) returns an empty string (""), 0, an empty date, or .F., depending on the data type of <lookup field 1>. Also, EOF( ) returns .T., FOUND( ) returns .F., and the record pointer is positioned at the end of the file.

LOOKUP( ) performs a sequential search, unless an index whose key matches <return field 2> is open as a master index. To minimize the time LOOKUP( ) takes to search a table, you can specify a master index.

When you use LOOKUP( ) after executing a SET RELATION command, the <exp> and <lookup field 2> can be in the parent table, and <return field 1> can be in the child table.


LOOKUP( ) Example

The following example uses LOOKUP( ) to find the first company in Chicago:

USE Company
Answer=LOOKUP(Company,"Chicago",City)
* Answer now contains the name of a company in
* Chicago or else is empty
IF .NOT. EMPTY(Answer)
  ? "In Chicago :"+ Answer
ELSE
  ? "No one in Chicago"
ENDIF

The following example takes each record in the Company table and uses LOOKUP( ) to look up in the Contact table the name of a contact at that company:

CLOSE DATA
USE CONTACT
SELECT 2
USE Company EXCLUSIVE
SCAN
  ? Company,LOOKUP(Contact->Contact,;
                   Compcode,Contact->Compcode)
ENDSCAN


Portability

Not supported in dBASE III PLUS.


See Also

EOF( )

FOUND( )

LOCATE

SEEK

SEEK( )

SET EXACT

SET INDEX

SET ORDER


LOWER( )

See Also	Example	Portability	String Data

Converts all uppercase characters in a string to lowercase and returns the resulting string.

Syntax

LOWER(<expC> | <memo field>)

<expC> | <memo field>

The character string or memo field to convert to lowercase.

Description

LOWER( ) converts the uppercase alphabetic characters in a character expression or memo field to lowercase. LOWER( ) ignores digits and other characters. LOWER( ) returns a maximum of 32766 characters, the maximum length of a string.

The current language driver defines the character values that are lowercase and uppercase alphabetic. In a U.S. language driver, a lowercase alphabetic character is from a to z, and an uppercase alphabetic character is from A to Z. See Appendix C in the Programmer's Guide for more information about language drivers.


LOWER( ) Example

The following example uses LOWER( ) to convert uppercase text to lowercase:

? LOWER("Technical")           && Returns "technical"
? LOWER("")                    && Returns ""
? LOWER("12 APPLES")           && Returns "12 apples"

In a field containing names in the format FIRSTNAME (Space) LASTNAME all in capital letters, UPPER( ) and LOWER( ) can be used to change the name string to upper- and lowercase as follows:

USE Contact
REPLACE ALL Contact WITH UPPER(SUBSTR(Contact,1,1))+;
  LOWER(SUBSTR(Contact,2,AT(" ",Contact)-2))+ " " +;
  UPPER(SUBSTR(Contact,AT(" ",Contact)+1,1))+;
  LOWER(SUBSTR(Contact,AT(" ",Contact)+2,16))

While this example demonstrates the use of UPPER( ), LOWER( ), and SUBSTR( ) to manipulate text strings, the previous task could also be accomplished by the following command.

REPLACE ALL Contact with PROPER(Contact)


Portability

The <memo field> argument is not supported in dBASE IV or dBASE III PLUS.


See Also

CHARSET( )

ISALPHA( )

ISLOWER( )

ISUPPER( )

LDRIVER( )

PROPER( )

UPPER( )


LTRIM( )

See Also	Example	Portability	String Data

Returns a string with no leading space characters.

Syntax

LTRIM(<expC> | <memo field>)

<expC> | <memo field>

The string or memo field to remove the leading space characters from.

Description

LTRIM( ) returns a character expression or memo field with no leading space characters. LTRIM( ) returns a maximum of 32766 characters, the maximum length of a string.

Using LTRIM( ) with a memo field removes leading spaces only at the beginning of the first line of the field. To remove leading spaces from a particular line of a memo field, use LTRIM( ) with MLINE( ).

To remove trailing space characters from a string or memo field, use RTRIM( ) or TRIM( ).


LTRIM( ) Example

The following example uses LTRIM( ) to remove leading spaces from text in a character field:

? STR(11.95,8,2)             && Returns 11.95
? LTRIM(STR(11.95,8,2))      && Returns 11.95

Numeric data defaults to the right in a table while character data defaults left. Further, when numeric data is stored to a memory variable, the variable defaults to 10 spaces long. The following example uses LTRIM( ) and STR( ) to left-justify numeric data:

USE Clients
96                 && Positions record pointer;
                      at record number 96
X=Startbal         && store contents of Startbal to X
? X                && Returns 56.36
Y=LTRIM(STR(X,13,2))
? Y                && Returns 56.36


Portability

The <memo field> argument is not supported in dBASE IV or dBASE III PLUS, and dBASE IV and dBASE III PLUS limit the return value of LTRIM( ) to 254 characters.


See Also

LEFT( )

MLINE( )

RIGHT( )

RTRIM( )

STR( )

SUBSTR( )

TRIM( )


LUPDATE( )

See Also	Example	Fields and Records

Returns the date of the last change to the current or a specified table.

Syntax

LUPDATE( [<alias>] )

<alias>

A work area number (1 through 225), letter (A through J), or alias name. The work area letter or alias name must be enclosed in quotes.

Description

LUPDATE( ) displays the last update date of the specified table. If no table is open, LUPDATE( ) returns a blank date. LUPDATE( ) returns the date in the form mm/dd/yy. This format can be modified with the SET CENTURY, SET DATE, and SET MARK commands.


LUPDATE( ) Example

The following example uses LUPDATE( ) to return the date that a specified table was last updated:

USE Company IN SELECT()
USE Contact IN SELECT()
? "The table - Company - was last updated on " + ;
   DTOC(LUPDATE("Company"))
? "The table - Contact - was last updated on " + ;
   DTOC(LUPDATE("Contact"))
CLOSE ALL


See Also

DTOC( )

SET CENTURY

SET DATE


MAX( )

See Also	Example	Portability	Expressions and Type Conversion

Compares two expressions of the same data type and returns the greater value. If comparing two logical expressions, returns .T. if one or both expressions are true.

Syntax

MAX(<exp 1>, <exp 2>)

<exp 1>

An expression (character, date, logical, float, or numeric) to compare to a second expression of the same data type. You can compare float to numeric type numbers.

<exp 2>

An expression of the same data type as <exp 1> to compare to <exp 1>. You can compare float to numeric type numbers.

Description

Use MAX( ) to compare two numbers, two character strings, two dates, or two logical values to determine the greater of the two values compared. MAX( ) returns:

The greater of two numbers

The character string with the higher collation value of two character strings. Collation values are determined by the language driver in use. For more information on language drivers, see Appendix C in the Programmer's Guide.

The later of two dates

True if one or both of two logical expressions evaluate to true

If <exp 1> and <exp 2> are equal, MAX( ) returns their value. For example, if you issue STORE 100 TO mvar1 and STORE 50+50 TO mvar2, MAX(mvar1,mvar2) returns 100.

If you use MAX( ) with character strings, first issue SET EXACT ON to ensure accurate results. When comparing character strings, MAX( ) is case-sensitive.


MAX( ) Example

The following example uses MAX( ) to compare a YTD_Sales field value with a memory variable that holds a computed average and returns the greater value:

CLEAR
SET TALK OFF
USE Company
AVERAGE YTD_Sales FOR YTD_Sales<>0 TO Midpt
GO TOP
? CENTER("Subsidiaries Exceeding Corporate Average ;
  Sales")
?
? "Company", "Subsid Avg" AT 27, "YTD Sales" AT 42, ;
  "Excess" AT 56
? REPLICATE("*",7) AT 0, REPLICATE("*",10) AT 27, ;
  REPLICATE("*",9) AT 42, REPLICATE("*",6) AT 56
DO WHILE .NOT. EOF()
  IF MAX(YTD_Sales,MidPt)=Ytd_Sales
    ? Company, Midpt AT 25, YTD_Sales, ;
      YTD_Sales - Midpt
  ENDIF
  SKIP
ENDDO
RETURN
CLOSE ALL


Portability

In dBASE III PLUS, MAX( ) supports only numeric expressions. In dBASE IV, MAX( ) doesn't support logical expressions.


See Also

CALCULATE

IIF( )

MIN( )

LDRIVER( )

SET EXACT

SET LDCHECK


MCOL( )

See Also	Example	Portability	Keyboard and Mouse Events

Returns the current column position of the mouse pointer. This command is supported primarily for compatibility with dBASE IV. In dBASE for Windows, use properties such as OnLeftMouseDown to manage mouse actions in forms.

Syntax

MCOL( )

Description

Use MCOL( ) to determine the horizontal position of the mouse pointer during the last mouse event. MCOL( ) returns 0 if ISMOUSE( ) is .F.

The dBASE interface and applications you design with dBASE provide automatic mouse support. Use MDOWN( ) to determine if the mouse button is being pressed, and MROW( ) and MCOL( ) to determine the row and column coordinates of the mouse pointer at the time of the event.


MCOL( ) Example

The following example presents four large colored buttons for selecting alternative programs to run. MROW( ) and MCOL( ) are used to return the row and column position of the mouse when MDOWN( ) returns .T.:

SET TALK OFF
SET CURSOR OFF
CLEAR
STORE .F. TO End
@ 1,35 FILL TO 5,45 COLOR W+/BG
@ 3,37 SAY "Billing" COLOR W+/BG
@ 7,35 FILL TO 11,45 COLOR W+/G
@ 9,37 SAY "Updates" COLOR W+/G
@ 13,35 FILL TO 17,45 COLOR W+/RB
@ 15,36 SAY "Customers" COLOR W+/RB
@ 19,35 FILL TO 23,45 COLOR W+/W
@ 21,38 SAY "Exit" COLOR W+/W

DO WHILE .NOT. End
x=mrow()
y=mcol()
  IF MDOWN()
    DO CASE
      CASE 0 < MROW() .AND. MROW() < 6 .AND. ;
34 < MCOL() .AND. MCOL() < 46
        DO BILLING
      CASE 6 < MROW() .AND. MROW() < 12 .AND. ;
34 < MCOL() .AND. MCOL() < 46
        DO UPDATES
      CASE 12 < MROW() .AND. MROW() < 18 .AND. ;
34 < MCOL() .AND. MCOL() < 46
        DO CUSTOMERS
      CASE 18 < MROW() .AND. MROW() < 24 .AND. ;
34 < MCOL() .AND. MCOL() < 46
        End=.T.
    ENDCASE
  ENDIF
  @ 0,0  SAY mrow()   && display mouse location
  @ 0,10 SAY mcol()
  WAIT
ENDDO
SET CURSOR ON
SET TALK ON
CLEAR
RETURN

PROCEDURE Billing
@ 2,2 SAY "This is Billing.prg  "
RETURN

PROCEDURE Updates
@ 2,2 SAY "This is Updates.prg  "
RETURN

PROCEDURE Customers
@ 2,2 SAY "This is Customers.prg"
RETURN


Portability

Not supported in dBASE III PLUS.


See Also

ISMOUSE( )

MDOWN( )

MROW( )

OnLeftMouseDown


MD

See Also	Example	Portability	Disk and File Utilities

Creates a new DOS directory.

Syntax

MD <directory>

<directory>

The directory you want to create.

Description

MD and MKDIR are equivalent commands. See the description of MKDIR for more information.


MD Example

See MKDIR for an example of MD.


Portability

Not supported in dBASE IV or dBASE III PLUS.


See Also

CD

MKDIR

SET DIRECTORY


MDOWN( )

See Also	Example	Portability	Keyboard and Mouse Events

Returns .T. if the mouse button is pressed, .F. if it is not.You do not use this command in an event-driven environment. In dBASE for Windows, use properties such as OnLeftMouseDown to manage mouse actions in forms.

Syntax

MDOWN( )

Description

Use MDOWN( ) to determine when the mouse button is pressed.

The dBASE interface and applications you design with dBASE provide automatic mouse support. Use MDOWN( ) to determine if the mouse button is being pressed, and MROW( ) and MCOL( ) to determine the row and column coordinates of the mouse pointer at the time of the event.


MDOWN( ) Example

The following example reacts to the value returned by MDOWN( ). It repositions a window on the screen when you click the mouse button and drag the mouse pointer, or when you move the mouse pointer and click:

CLEAR
SET CURSOR OFF
SET TALK OFF
STORE .F. TO Done
ON KEY LABEL Ctrl-Q STORE .T. TO Done
DEFINE WINDOW W1 FROM 4,2 TO 10,60;
COLOR BG/RB, , R/W
ACTIVATE WINDOW W1
@ 2,2 SAY "Drag the mouse to move window or press;
Ctrl-Q to Quit"
WAIT
DO WHILE .NOT. Done
  DO WHILE MDOWN()
    MOVE WINDOW W1 TO;
      MIN(16,MROW()),MIN(68,MCOL())
  ENDDO
ENDDO
DEACTIVATE WINDOW W1
CLEAR
SET CURSOR ON
SET TALK ON


Portability

Not supported in dBASE III PLUS or dBASE IV.


See Also

ISMOUSE( )

MCOL( )

MROW( )

OnLeftMouseDown

ON MOUSE


MDX( )

See Also	Example	Portability	Table Organization

Returns the name of an .MDX file open in the current or a specified work area.

Syntax

MDX(<index tag expN> [, <alias>] )

<index tag expN>

The position of an index tag in the open multiple index file whose name you want to return.

<alias>

A work area number (1 through 225), letter (A through J), or alias name. The work area letter or alias name must be enclosed in quotes.

Description

MDX( ) returns the name of the .MDX file open in the current or specified work area that contains a specified index tag. The index tag position corresponds to the .MDX file position in the index file list specified by SET INDEX TO, SET ORDER TO, or USE commands. If SET FULLPATH is ON, MDX( ) also returns the drive and directory location of the .MDX file in addition to its name.

If you do not specify an index order number, MDX( ) returns the name of the .MDX file that contains the master index tag. If you do not specify an index order number and the master index is an .NDX file, MDX( ) returns an empty string (""). MDX( ) also returns an empty string if there is no .MDX file open or no index tag in the specified position.


MDX( ) Example

The following example uses MDX( ) to determine the .MDX files that are open for the current table:

USE Company EXCLUSIVE
? 1,MDX(1)
? 2,MDX(2)
? " Only one MDX is open"
INDEX ON City     TAG City     OF Location
? 1,MDX(1)
? 2,MDX(2)
? "Now two MDXs are open"


Portability

Not supported in dBASE III PLUS.


See Also

FOR( )

INDEX

NDX( )

SET FULLPATH

SET INDEX

SET ORDER

TAG( )

TAGCOUNT( )

TAGNO( )

USE


MDY( )

See Also	Example	Portability	Date and Time Data

Returns a specified date as a character string in MONTH DD, YY format.

Syntax

MDY(<expD>)

<expD>

The date expression to return as a character string in MONTH DD, YY format.

Description

MDY( ) returns a date in MONTH DD, YY or MONTH DD, YYYY format, where MONTH is the full month name, DD is the day number, and YY is the year number. If SET CENTURY is OFF (the default), MDY( ) returns the year as 2 digits. If SET CENTURY is ON, MDY( ) returns the year as 4 digits. MDY( ) always returns the day portion as 2 digits.

Enter <expD> in the current date format as determined by SET DATE, DBASEWIN.INI, or the International option of the Windows Control Panel (in that order). That is, SET DATE settings override those in DBASEWIN.INI, and settings in DBASEWIN.INI override those in the Windows Control Panel. Be sure <expD> matches the date format in use when your program runs.

If you pass an invalid date to MDY( ), dBASE converts the date to a valid one and returns that date in MONTH DD, YY or MONTH DD, YYYY format. If you pass an empty or non-date expression delimited with braces ({ }) to MDY( ), it returns "Unknown 00, 00" or "Unknown 00, 0000". If you pass a non-date expression or an expression that is not delimited with braces to MDY( ), it returns an error.


MDY( ) Example

See DMY( ) for an example of using MDY( ), substituting MDY( ) for any DMY( ) reference.


Portability

Not supported in dBASE III PLUS.


See Also

CDOW( )

CMONTH( )

DAY( )

DMY( )

DOW( )

MONTH( )

SET CENTURY

YEAR( )


MEMLINES( )

See Also	Example	Portability	Fields and Records

Returns the number of lines in a memo field.

Syntax

MEMLINES(<memo field> [,<line length expN>] )

<memo field>

The memo field the MEMLINES( ) function operates on.

<line length expN>

Specifies the line length used in calculating the number of lines in a memo field. <expN> can be set to any number from 8 to 255. If <expN> is not specified, MEMLINES( ) calculates each line using the memo width specified using the SET MEMOWIDTH command.

Description

The MEMLINES( ) function returns the number of lines in a memo field based on the memo width specified by the line length parameter. If you do not specify a line length, MEMLINES( ) treats the memo field text as if it were wordwrapped within a display--50 characters wide unless you specify another display width with the SET MEMOWIDTH command.

If a word does not completely fit within the remainder of a line, MEMLINES( ) includes that word at the beginning of the next line. If the number of characters in a word is longer than the default or specified memo field line length, MEMLINES( ) truncates the word at the end of the line and includes the remainder of the word at the beginning of the next line.


MEMLINES( ) Example

The following example uses MEMLINES( ) to return the number of lines in a memo field as a function of a user entered MEMOWIDTH. As a line counter variable is incremented down the page, MEMLINE( ) is used to determine whether the next memo will fit on the current page:

SET TALK OFF
CLEAR
colwidth = 10
@ 6,12 SAY "Report will be how many columns wide? " ;
  GET colwidth PICTURE "99" ;
   VALID colwidth > 9 .AND. colwidth < 68
READ
mwidth = SET("MEMOWIDTH")
SET MEMOWIDTH TO colwidth
USE Company
output_to = "S"
IF output_to = "S"
   pglngth   = 15
ELSE
   pglngth   = 58
ENDIF
linecnt = 1
memoline = 1
DO WHILE .NOT. EOF()
   CLEAR
   linecnt = 1
   DO WHILE linecnt + MEMLINES(Notes) <= ;
      pglngth .AND. .NOT. EOF()
      ? Company AT 2
      linecnt  = linecnt + 1
      memoline = 1
      DO WHILE memoline <= MEMLINES(Notes) ;
         .AND. MEMLINES(Notes) <> 0
         ? MLINE(Notes,memoline)AT 12
         linecnt  = linecnt + 1
         memoline = memoline + 1
      ENDDO
      SKIP
   ENDDO
   WAIT "Press any key to continue"
ENDDO
CLOSE ALL
SET MEMOWIDTH TO mwidth


Portability

Not supported in dBASE III PLUS. The line length argument is not supported in dBASE IV.


See Also

MLINE( )

SET MEMOWIDTH

STORE MEMO


MEMORY( )

See Also	Example	Portability	Environment

Returns the number of kilobytes currently available in random access memory (RAM).

Syntax

MEMORY([<expN>])

<expN>

dBASE for Windows ignores this parameter; it is included for backward compatibility with dBASE IV.

Description

Use MEMORY( ) to determine how much memory is available in the system. The value MEMORY( ) returns includes memory made available by the use of a Windows swap file.

You might want to check available memory before using a command such as RUN or RUN( ) from within an application, to make sure the called application will load and run properly.


MEMORY( ) Example

The following example warns if the user has less than a megabyte of RAM available:

IF MEMORY()>=1000
  ? "You have at least a megabyte of RAM"
ELSE
 ?? "Warning: You have less than a megabyte of RAM:"
 ? MEMORY(),"Kb"
ENDIF


Portability

Not supported in dBASE III PLUS. In dBASE IV, <expN> can be a value from 0 to 7, with each value returning memory information relevant in a DOS environment.


See Also

DIR

DISPLAY MEMORY

FLUSH

LIST

RUN

RUN( )


MENU( )

See Also	Example	Portability	dBASE IV Menus

Returns the name of the current dBASE IV menu bar as an uppercase character string. This command is supported primarily for compatibility with dBASE IV. In dBASE for Windows, use INSPECT( ) to return information associated with objects in forms.

Syntax

MENU( )

Description

MENU( ) returns the name of a menu bar created with DEFINE MENU.

MENU( ) returns an empty string when:

No menu bar is active.

The window containing the menu bar is closed.


MENU( ) Example

In the following example, MENU( ) is used to determine the name of the current menu and then branch to the appropriate program:

* Entree.prg
* This program creates a menu structure for
* choosing from a selection of entrees:
SET TALK OFF
CLEAR
DEFINE MENU Entree
DEFINE PAD Pad1 OF Entree PROMPT "Breakfast       "
DEFINE PAD Pad2 OF Entree PROMPT "Lunch           "
DEFINE PAD Pad3 OF Entree PROMPT "Dinner          "
DEFINE PAD Pad4 OF Entree PROMPT "Snacks & Dessert"
DEFINE PAD Pad5 OF Entree PROMPT "Exit   "
FOR i = 1 TO 5
STORE LTRIM(STR(i)) TO pdcount
ON SELE PAD Pad&pdcount OF Entree DO AllOrders
NEXT
ACTIVATE MENU Entree
CLEAR
SET TALK ON

* Beverage.prg
* This program creates a menu structure for
* choosing from a selection of beverages
SET TALK OFF
CLEAR
DEFI MENU Beverage
DEFINE PAD Pad1 OF Beverage PROMPT "Wine and Beer"
DEFINE PAD Pad2 OF Beverage PROMPT "Soft Drinks  "
DEFINE PAD Pad3 OF Beverage PROMPT "Coffee & Tea "
DEFINE PAD Pad4 OF Beverage PROMPT "Juices etc. "
DEFINE PAD Pad5 OF Beverage PROMPT "Exit         "
FOR i = 1 TO 5
  STORE LTRIM(STR(i)) TO pdcount
  ON SELECTION PAD Pad&pdcount OF Beverage DO AllOrders
NEXT
ACTIVATE MENU Beverage
CLEAR
SET TALK ON

* AllOrders.prg
* Called by Entree.prg and Beverage.prg
* This program uses MENU() to determine where to
* branch when the user chooses any of the menu pads
Procedure AllOrders
IF MENU() = "ENTREE"
  IF PAD() = "PAD1"
    WAIT "Brkfast.prg executing..."
  ELSEIF PAD() = "PAD2"
    WAIT "Lunch.prg executing..."
  ELSEIF PAD() = "PAD3"
    WAIT "Dinner.prg executing..."
  ELSEIF PAD() = "PAD4"
    WAIT "Dessert.prg executin..."
  ENDIF
ELSEIF MENU() = "BEVERAGE"
  IF PAD() = "PAD1"
    WAIT "Wine.prg executing..."
  ELSEIF PAD() = "PAD2"
    WAIT "Softdrnk.prg executing..."
  ELSEIF PAD() = "PAD3"
    WAIT "Coffee.prg executing..."
  ELSEIF PAD() = "PAD4"
    WAIT "Juice.prg executing..."
  ENDIF
ENDIF
IF PAD() = "PAD5"
  DEACTIVATE MENU
ENDIF
CLEAR


Portability

Not supported in dBASE III PLUS.


See Also

ACTIVATE MENU

DEFINE

INSPECT( )


MESSAGE( )

See Also	Example	Portability	Error Handling and Debugging

Returns the error message of the most recent dBASE error.

Syntax

MESSAGE( )

Description

Use MESSAGE( ) with other error-trapping commands and functions, such as ON ERROR, RETRY, and ERROR( ), to substitute specific responses and actions for dBASE default responses to errors.

MESSAGE( ) is initially set to an empty string. MESSAGE( ) returns an error message when an error occurs, and remains set to that error message until one of the following happens:

Another error occurs

RETRY is issued

The subroutine in which the error occurs completes execution

To learn the IDAPI error message of the last IDAPI error generated by the current table, use DBMESSAGE( ).

See the table in the description of ERROR( ) that compares CERROR( ), ERROR( ), MESSAGE( ), DBERROR( ), DBMESSAGE( ), SQLERROR( ), and SQLMESSAGE( ).

See Error Messages for a listing of all dBASE error messages.


MESSAGE( ) Example

See ON ERROR for an example of using MESSAGE( ).


Portability

The error messages of some errors in dBASE IV and dBASE III PLUS are different from the error messages for the same errors in dBASE for Windows.


See Also

CERROR( )

DBERROR( )

DBMESSAGE( )

ERROR( )

ON ERROR

RETRY

SQLERROR( )

SQLMESSAGE( )


MIN( )

See Also	Example	Portability	Expressions and Type Conversion

Compares two expressions of the same data type and returns the lesser value. If comparing two logical expressions, returns .T. if one or both expressions are true.

Syntax

MIN(<exp 1>, <exp 2>)

<exp 1>

An expression (character, date, logical, float, or numeric) to compare to a second expression of the same data type. You can compare float to numeric type numbers.

<exp 2>

An expression of the same data type as <exp 1> to compare to <exp 1>. You can compare float to numeric type numbers.

Description

Use MIN( ) to compare two numbers, two character strings, two dates, or two logical values to determine the lesser of the two values compared. MIN( ) returns:

The smaller of two numbers

The character string with the lower collation value of two character strings. Collation values are determined by the language driver in use. For more information on language drivers, see Appendix C in the Programmer's Guide.

The earlier of two dates

False if one or both of two logical expressions evaluates to false

If <exp 1> and <exp 2> are equal, MIN( ) returns their value. For example, if you issue STORE 100 TO mvar1 and STORE 50+50 TO mvar2, MIN(mvar1,mvar2) returns 100.

If you use MIN( ) with character strings, first issue SET EXACT ON to ensure accurate results. When comparing character strings, MIN( ) is case-sensitive.


MIN( ) Example

The following example uses MIN( ) to compare a YTD_Sales field value with a memory variable that holds a computed average and returns the smaller amount:

CLEAR
SET TALK OFF
USE Company
AVERAGE YTD_Sales FOR YTD_Sales<>0 TO Midpt
GO TOP
? CENTER("Subsidiaries Below Corporate Average ;
  Sales")
?
? "Company", "Subsid Avg" AT 27, "YTD Sales" AT 42, ;
  "Amount Below Avg" AT 56
? REPLICATE("*",7) AT 0, REPLICATE("*",10) AT 27, ;
  REPLICATE("*",9) AT 42, REPLICATE("*",16) AT 56
DO WHILE .NOT. EOF()
  IF MIN(YTD_Sales,MidPt)=Ytd_Sales
    ? Company, Midpt AT 25, YTD_Sales, ;
      Midpt - YTD_Sales
  ENDIF
  SKIP
ENDDO
RETURN
CLOSE ALL


Portability

In dBASE III PLUS, MIN( ) supports only numeric expressions. In dBASE IV, MIN( ) doesn't support logical expressions.


See Also

CALCULATE

IIF( )

MAX( )

SET EXACT


MKDIR

See Also	Example	Portability	Disk and File Utilities

Creates a new DOS directory.

Syntax

MKDIR <directory>

<directory>

The directory you want to create.

Description

Use MKDIR to create a new directory without exiting dBASE. MD is equivalent to MKDIR.

MKDIR is equivalent to the DOS command MKDIR or MD. When <directory> is a single name, MKDIR creates a new directory of that name beneath the current directory. When <directory> includes a path, MKDIR creates a new directory in the specified path. The path name must be an existing path, with the name of the new directory at the end preceded by a backslash. If <directory> is preceded by a backslash, MKDIR creates a new directory under the root directory.

The new directory name must follow the same naming conventions as DOS directory names.

After you create the new directory, you can use CD or SET DIRECTORY to make the new directory the default directory. You can also use SET PATH to include the new directory in the dBASE search path.


MKDIR Example

The following examples use MKDIR or MD to create a subdirectory on drive D called Project, three subdirectories below Project and another subdirectory on the C drive:

MKDIR D:\Project
MKDIR D:\Project\Programs
MKDIR D:\Project\Data
MD    D:\Project\Backup
MD    C:\Editor

If you try to make a directory that already exists or is on a path that does not exist you will get an error message


Portability

Not supported in dBASE IV or dBASE III PLUS.


See Also

CD

SET DIRECTORY

SET PATH


MLINE( )

See Also	Example	Portability	Fields and Records

Extracts a specified line of text from a memo field in the current record.

Syntax

MLINE(<memo field> [, <line number expN> [, <line length expN>]])

<memo field>

The memo field the MLINE( ) function operates on.

<line number expN >

The number of the line in the memo field returned by the MLINE( ) function. The default for <line number expN> is 1.

<line length expN >

The number that determines the length of a line in the memo field. <line length expN> can be set to any number from 8 to 255. If <line length expN> is not set, the SET MEMOWIDTH setting specifies the length of the line. If <line number expN> of the memo field has less than <line length expN> characters, MLINE( ) adds characters to the end of the returned string from the line following <line number expN>.

Description

MLINE( ) returns a specified line of text from a memo field. MLINE( ) treats the text of the memo field as if it were wordwrapped within a display width specified by the SET MEMOWIDTH setting or by <line length expN>. If a word does not completely fit within the specified length, MLINE( ) includes that word at the beginning of the next line and does not include any portion of the word in the returned string. Thus, the text that appears on a particular line is determined by the length of each line and wordwrapping text.


MLINE( ) Example

See MEMLINES( ) for an example of MLINE( ).


Portability

Not supported in dBASE III PLUS. The line length argument is not supported in dBASE IV.


See Also

MEMLINES( )

REPLACE MEMO

SET MEMOWIDTH

STORE MEMO


MOD( )

See Also	Example	Numeric Data

Returns the modulus (remainder) of one number divided by another.

Syntax

MOD(<dividend expN>, <divisor expN>)

<dividend expN>

The number to be divided.

<divisor expN>

The number to divide by.

Description

MOD( ) divides <dividend expN> by <divisor expN> and returns the remainder as a whole number. For example MOD(X,Y) returns the remainder of x/y.

MOD( ) returns a positive number if <divisor expN> is positive, and returns a negative number if <divisor expN> is negative.

The modulus formula is

<dividend>-FLOOR(<dividend>/<divisor>)*<divisor>

where FLOOR( ) returns the greatest integer less than or equal to its argument.


MOD( ) Example

An example of MOD( ) is shown in the example for INT( ).


See Also

CEILING( )

FLOOR( )

INT( )


MODIFY APPLICATION

See Also	Example	Portability	Forms

Opens the Form Designer to create or modify a form interactively.

Syntax

MODIFY APPLICATION
[<filename> | ? | <filename skeleton>]

<filename> | ? | <filename skeleton>

The form to create or modify. MODIFY APPLICATION ? and MODIFY APPLICATION <filename skeleton> display a dialog box, from which you can select a file. If you specify a file without including its path, dBASE looks for the file in the current directory, then in the path you specify with SET PATH. If you specify a file without including its extension, dBASE assumes .WFM.

Description

MODIFY SCREEN, MODIFY APPLICATION, and MODIFY FORM are identical; all launch the Form Designer. See the description of MODIFY FORM for more information.


MODIFY APPLICATION Example

See the example of MODIFY FORM. In this example, MODIFY APPLICATION works the same as MODIFY FORM.


Portability

Not supported in dBASE III PLUS. In dBASE IV, MODIFY APPLICATION launches the dBASE IV Applications Generator.


See Also

CREATE APPLICATION

CREATE FORM

CREATE SCREEN

MODIFY FORM

MODIFY SCREEN

OPEN FORM


MODIFY COMMAND

See Also	Programs

Displays a specified program file for editing, or displays an empty editing window.

Syntax

MODIFY COMMAND
[<filename> | ? | <filename skeleton>]
[WINDOW <window name>]

<filename> | ? | <filename skeleton>

The file to display and edit. The ? and <filename skeleton> options display a dialog box from which you can select a file. If you specify a file without including its path, dBASE looks for the file in the current directory, then in the path you specify with SET PATH. If you specify a file without including its extension, dBASE assumes .PRG. If you issue MODIFY COMMAND without an option, dBASE displays an empty editing window.

[WINDOW <window name>]

Included for compatibility with dBASE IV. Displays the file in <window name>, previously opened with ACTIVATE WINDOW.

Default

By default, MODIFY COMMAND launches the dBASE internal Text Editor. You can specify an alternate editor by changing the EDITOR setting in DBASEWIN.INI. To do so, either use the SET command to specify the setting interactively, or enter the EDITOR parameter directly in DBASEWIN.INI.

Description

Use MODIFY COMMAND to create new or edit existing program files. Use DO to execute program files.

Note:	dBASE compiles programs before running them, and assigns the compiled files the same name as the original, but with the letter "O" as the last letter. For example, the compiled version of SALESRPT.PRG would be SALESRPT.PRO. If SALESPRT.PRO already exists, it is overwritten. For this reason, avoid using file names ending in "O" in directories containing compiled programs.

If you are creating a new program file, MODIFY COMMAND displays an editing window with no file. If you specify an existing file, MODIFY COMMAND displays the program in an editing window, with the cursor at the beginning of line 1.

The dBASE menu changes when an editing window is active. See Editing Text or the User's Guide for information on the internal Text Editor, including its menu and shortcut keys.


See Also

DO

MODIFY FILE

SET DEVELOPMENT

SET EDITOR


MODIFY FILE

See Also	Disk and File Utilities

Displays a specified text file for editing, or displays an empty editing window.

Syntax

MODIFY FILE
[<filename> | ? | <filename skeleton>]
[WINDOW <window name>]

<filename> | ? | <filename skeleton>

The text file to display and edit. The ? and <filename skeleton> options display a dialog box from which you can select a file. If you specify a file without including its path, dBASE looks for the file in the current directory, then in the path you specify with SET PATH. If you specify a file without including its extension, dBASE assumes .PRG. If you issue MODIFY FILE without an option, dBASE displays an empty editing window.

[WINDOW <window name>]

Included for compatibility with dBASE IV. Displays the file in <window name>, previously opened with ACTIVATE WINDOW.

Description

Use MODIFY FILE to create and edit text files using the dBASE for Windows internal text editor, or the editor specified in SET EDITOR.

MODIFY FILE is identical to MODIFY COMMAND, CREATE COMMAND and CREATE FILE. See MODIFY COMMAND for more information.


See Also

MODIFY COMMAND

SET EDITOR


MODIFY FORM

See Also	Example	Portability	Forms

Opens the Form Designer to create or modify a form.

Syntax

MODIFY FORM
[<filename> | ? | <filename skeleton>]

<filename> | ? | <filename skeleton>

The form to create or modify. MODIFY FORM ? and MODIFY FORM <filename skeleton> display the Save File dialog box, from which you can select a file. If you specify a file without including its path, dBASE looks for the file in the current directory, then in the path you specify with SET PATH. If you specify a file without including its extension, dBASE assumes .WFM.

Description

Use MODIFY FORM to open the Form Designer and create or modify a form interactively. The Form Designer automatically generates dBASE program code that defines the contents and format of a form, and stores this code in an editable text file (.WFM).

MODIFY SCREEN, MODIFY APPLICATION and MODIFY FORM are identical. For all these commands, the presence of a form file determines whether a create or modify operation occurs. If the .WFM file exists, the commands let you modify it in the Form Designer. If the file does not exist, the commands create a new file.

Since a .WFM file is a program file, you can edit it with MODIFY COMMAND.

See Designing Forms or the Forms chapters in the User's Guide for instructions on using the Form Designer.

Note:	The Forms Designer is a two-way tool. You can open a form in the Form Designer even if you have edited the code in the .WFM file.


MODIFY FORM Example

The following examples open the Save File dialog box with the cursor positioned at the File Name block to name a new form. The picklist of .WFM files on the current directory is available if you desire to use an existing form name to create a new form. By contrast, MODIFY FORM ? would edit an existing form:

MODIFY FORM ?
MODIFY FORM *.WFM

MODIFY FORM issued alone in the Command window will open an unnamed form design surface:

MODIFY FORM


Portability

Not supported in dBASE IV or dBASE III PLUS.


See Also

CREATE APPLICATION

CREATE SCREEN

MODIFY APPLICATION

MODIFY FORM

MODIFY SCREEN

OPEN FORM


MODIFY LABEL

See Also	Example	Portability	Input/Output

Opens the Report Designer to create or modify a label file.

Syntax

MODIFY LABEL
[<filename> | ? | <filename skeleton>]

<filename> | ? | <filename skeleton>

The label file to create or modify. The ? and <filename skeleton> options display a dialog box from which you can select a file. If you specify a file without including its path, dBASE looks for the file in the current directory, then in the path you specify with SET PATH. If you specify a file without including its extension, dBASE assumes .RPL.

If dBASE cannot find <filename>, it creates the file. By default, dBASE assigns an .RPL extension to <filename> and saves the file in the current directory.

MODIFY LABEL without an option opens the empty Report Designer to create a new label file.

Description

Use MODIFY LABEL to open the Report Designer and create or modify a label file. A label file contains the information that formats labels. For information about using the Report Designer, see Designing Reports and Labels or the Crystal Reports documentation. CREATE LABEL and MODIFY LABEL are identical commands.

Before issuing MODIFY LABEL, you must have a default printer selected. After you create or modify the label file, use LABEL FORM to print the labels.


MODIFY LABEL Example

This example opens a database table and then issues MODIFY LABEL to construct a label form:

CLOSE DATABASE
USE Company
MODIFY LABEL COMPLBL1
* If COMPLBL1.LBL already exists then it will be
* modified. Otherwise a new label form will be
* created.


Portability

The <filename skeleton> option is not supported in dBASE IV or dBASE III PLUS. In dBASE IV and dBASE III PLUS, the default label file extension is .LBL.


See Also

MODIFY REPORT

LABEL FORM


MODIFY MENU

See Also	Forms

Opens the Menu Designer to create or modify a menu file.

Syntax

MODIFY MENU
[<filename> | ? | <filename skeleton>]

<filename> | ? | <filename skeleton>

Specifies the name of a menu (.MNU) file to create or modify. The ? and <filename skeleton> options display a dialog box, in which you specify the name of the file.

Description

Use MODIFY MENU to design a menu for a form.

The menu you design is stored in a menu definition file (.MNU), which contains dBASE program code. You attach this program to a form via the form's Menu property.

For information on using the Menu Designer, see Designing Menus or Chapter 10 in the User's Guide.


See Also

CLASS MENU


MODIFY QUERY

See Also	Example	Table Organization

Opens the Query Designer to create or modify a query file.

Syntax

MODIFY QUERY
<filename> | ? | <filename skeleton>]

<filename> | ? | <filename skeleton>

Specifies the name of the file you want to create. MODIFY QUERY ? and MODIFY QUERY <filename skeleton> display a dialog box, in which you can specify the name of a new query file. If you specify a file without including its path, dBASE for Windows saves the file to the current drive and directory. If you specify a file without including an extension, dBASE for Windows assumes a .QBE extension.

Description

MODIFY QUERY performs the same operation as MODIFY VIEW. Use either command to invoke the Query Designer, an interactive environment in which you can create or modify a query. The Query Designer creates a .QBE file that displays only the fields and records that meet specified conditions. To activate a query (.QBE) file, you can use the SET VIEW command. For more information on using the Query Designer, see Designing Queries or the User's Guide.


MODIFY QUERY Example

MODIFY QUERY or MODIFY VIEW with no arguments opens the Query Designer and generates an untitled query, which the user will name later:

MODIFY QUERY

MODIFY QUERY followed by a file name creates a file of that name when the file is saved:

MODIFY QUERY Myquery

If Myquery.qbe already exists, you are asked if you want to overwrite it.


See Also

CREATE

SET VIEW


MODIFY REPORT

See Also	Example	Portability	Input/Output

Opens the Report Designer to create or modify a report file.

Syntax

MODIFY REPORT
<filename> | ? | <filename skeleton>]

CROSSTAB

Opens the Report Designer with the Cross-Tab dialog box displayed.

<filename> | ? | <filename skeleton>

The report file to create or modify. The ? and <filename skeleton> options display a dialog box from which you can select a file. If you specify a file without including its path, dBASE looks for the file in the current directory, then in the path you specify with SET PATH.

If you specify a file without including its extension, dBASE assumes .RPT if you haven't specified CROSSTAB, and .RPC if you have. If dBASE cannot find <filename>, it creates a file with the appropriate extension and saves it in the current directory.

MODIFY REPORT without any options opens the empty Report Designer to create a new report.

Description

Use MODIFY REPORT to open the Report Designer and create or modify a report file. A report file contains the information that formats a report. For information about using the Report Designer, see Designing Reports and Labels or the Crystal Reports documentation. CREATE REPORT and MODIFY REPORT are identical commands.

Before issuing MODIFY REPORT, you must have a default printer selected. After you create or modify the report file, use REPORT FORM to print the report.


MODIFY REPORT Example

This example opens a database table and then issues MODIFY REPORT to construct a report form:

CLOSE DATABASE
USE COMPANY
MODIFY REPORT Comprep1
* If Comprep1 already exists then it will be
* modified. Otherwise a new report form will be
* created


Portability

The <filename skeleton> option is not supported in dBASE IV or dBASE III PLUS. In dBASE IV and dBASE III PLUS, the default report file extension is .FRM.


See Also

REPORT FORM


MODIFY SCREEN

See Also	Example	Portability	Forms

Opens the Form Designer to create or modify a form.

Syntax

MODIFY SCREEN
<filename> | ? | <filename skeleton>]

<filename> | ? | <filename skeleton>

The form to create or modify. MODIFY SCREEN ? and MODIFY SCREEN <filename skeleton> display the Save File dialog box, from which you can select a file. If you specify a file without including its path, dBASE looks for the file in the current directory, then in the path you specify with SET PATH. If you specify a file without including its extension, dBASE assumes .WFM.

Description

MODIFY SCREEN, MODIFY APPLICATION, and MODIFY FORM are identical; all launch the Form Designer. See the description of MODIFY FORM for more information.


MODIFY SCREEN Example

See the example of MODIFY FORM. In this example, MODIFY SCREEN works the same as MODIFY FORM.


Portability

In dBASE III PLUS and dBASE IV, MODIFY SCREEN opens the dBASE III PLUS or dBASE IV Form Designer. These Form Designers create two files, .SCR and .FMT. You can use .FMT files in dBASE for Windows; however, you cannot modify them with dBASE for Windows.


See Also

CREATE APPLICATION

CREATE FORM

MODIFY APPLICATION

MODIFY FORM

MODIFY SCREEN

OPEN FORM


MODIFY STRUCTURE

See Also	Example	Table Basics

Allows you to modify the structure of the current table. You can modify the structure of both dBASE .DBF and Paradox .DB files, but not SQL tables.

Syntax

MODIFY STRUCTURE

Description

Use MODIFY STRUCTURE to change the structure of the current table by adding or deleting fields, or changing a field name, width, or data type. Issuing the MODIFY STRUCTURE command opens the Table Designer, an interactive environment in which you can create or modify the structure of a table. For more information about using the Table Designer, see Designing Table Structures or the User's Guide.

Before allowing changes to the structure of a dBASE table, dBASE for Windows makes a backup of the original table assigning the file a .DBK extension. dBASE for Windows then creates a new table file with the .DBF extension and copies the modified table structure to that file. When you have finished modifying a table structure, dBASE for Windows copies the content of the backup file into the new structure. If data is accidentally truncated or lost, you can recover the original data from the .DBK file. Before modifying the structure of a table, make sure that you have sufficient disk space to create the backup file plus any temporary storage required to copy records between the two tables (approximately twice the size of the original table).

If a table contains a memo field, MODIFY STRUCTURE also creates a backup memo file to store the original memo field data. This file has the same name as the table, but is given a .TBK extension.

You shouldn't change a field name and its width or type at the same time. If you do, dBASE for Windows will not be able to append data from the old field, and your new field will be blank. Change the name of a field, save the file, and then use MODIFY STRUCTURE again to change the field width or data type.

Also, do not insert or delete fields from a table and change field names at the same time. If you change field names, MODIFY STRUCTURE appends data from the old file by using the field position in the file. If you insert or delete fields as well as change field names, you change field positions and could lose data. You can, however, change field widths or data types at the same time as you insert or delete fields. In those cases, since MODIFY STRUCTURE appends data by field name, the data will be appended correctly.

dBASE for Windows successfully converts data between a number of field types. If you change field types, however, keep a backup copy of your original file, and check your new files to make sure the data has been converted correctly.

If you convert numeric fields to character fields, dBASE for Windows converts numbers from the numeric fields to right-aligned character strings. If you convert a character field to a numeric field, dBASE for Windows converts numeric characters in each record to digits until it encounters a non-numeric character. If the first character in a character field is a letter, the converted numeric field will contain zero.

You can convert logical fields to character fields, and vice versa. You can also convert character strings that are formatted as a date (for example, mm/dd/yy or mm-dd-yy) to a date field, or convert date fields to character fields. You cannot convert logical fields to numeric fields.

In general, dBASE for Windows attempts to make a conversion you request, but the conversion must be a sensible one or data may be lost. Numeric data can easily be handled as characters, but logical data, for example, cannot become numeric. To convert incompatible data types (such as logical to numeric), first add a new field to the file, use REPLACE to convert the data, then delete the old field.

If you modify the field name, length, or type of any fields that have an associated tag in the production (.MDX) file, the tag is rebuilt. If any indexes are open when you modify a table structure, dBASE automatically closes those indexes when saving the modified table. You should reindex the table after you modify its structure.


MODIFY STRUCTURE Example

The following example uses MODIFY STRUCTURE in the Command window to change the structure of a table:

USE Clients IN SELECT() EXCLUSIVE
MODIFY STRUCTURE
CLOSE DATABASES

The structure of a table can also be displayed but not changed by using the following commands in the Command window:

USE CLIENTS IN SELECT() NOUPDATE
DISPLAY STRUCTURE
CLOSE DATABASES


See Also

APPEND

APPEND MEMO

COPY STRUCTURE

CREATE

DISPLAY STRUCTURE

LIST STRUCTURE

REPLACE


MODIFY VIEW

See Also	Example	Table Organization

Starts the Query Designer.

Syntax

MODIFY VIEW
<filename> | ? | <filename skeleton>]

<filename> | ?

Specifies the name of the file you want to create. MODIFY VIEW ? displays a dialog box, in which you can specify the name of a new query file. If you specify a file without including its path, dBASE for Windows saves the file to the current drive and directory. If you specify a file without including an extension, dBASE for Windows assumes a .QBE extension.

Description

MODIFY VIEW performs the same operation as MODIFY QUERY. Use either command to invoke the Query Designer, an interactive environment in which you can create or modify a query. The Query Designer creates a .QBE file that displays only the fields and records that meet specified conditions. To activate a query (.QBE) file, you can use the SET VIEW command. For more information on using the Query Designer, see Designing Queries or the User's Guide.


MODIFY VIEW Example

MODIFY VIEW or MODIFY QUERY with no arguments opens the query designer and generates an untitled query which the user will name later:

MODIFY VIEW

MODIFY VIEW followed by a file name will create a file of that name when the file is saved.

MODIFY FILE Myquery

If Myquery.qbe already exists, you will be asked if you wish to overwrite it.

dBASE issues a CLOSE DATABASES command after MODIFY VIEW


See Also

SET VIEW


MONTH( )

See Also	Example	Date and Time Data

Returns the number of the month for a specified date expression.

Syntax

MONTH(<expD>)

<expD>

The date expression whose corresponding month number to return.

Description

MONTH( ) returns a date's month number--a value from 1 to 12.

Enter <expD> in the current date format as determined by SET DATE, DBASEWIN.INI, or the International option of the Windows Control Panel (in that order). That is, SET DATE settings override those in DBASEWIN.INI, and settings in DBASEWIN.INI override those in the Windows Control Panel. Be sure <expD> matches the date format in use when your program runs.

If you pass an invalid date to MONTH( ), dBASE converts the date to a valid one and returns the month number of that date. If you pass an empty or non-date expression delimited with braces ({ }) to MONTH( ), it returns 0. If you pass a non-date expression or an expression that is not delimited with braces to MONTH( ), it returns an error.


MONTH( ) Example

The following example uses MONTH( ) to determine the month number of the system date and combine it with a text string that includes the correct suffix:

IF SET("CENTURY") <> "OFF"
   SET CENTURY OFF
ENDIF
IF SET("DATE") <> "AMERICAN"
   SET DATE AMERICAN
ENDIF
month = MONTH(DATE())
mon_strng = LTRIM(STR(month))
DO CASE
   CASE month =  1
      mon_strng = "1st"
   CASE month =  2
      mon_strng = "2nd"
   CASE month =  3
      mon_strng = "3rd"
   CASE month =  4 .OR. month = 5 .OR. month = 6 ;
      .OR. month = 6 .OR. month = 7 .OR. month = 8 ;
      .OR. month = 9 .OR. month = 10 ;
      .OR. month = 11 .OR. month = 12
      mon_strng = mon_strng + "th"
ENDCASE
? "This is the " + mon_strng + " month of " + ;
   LTRIM(STR( YEAR(DATE()))) + " " + DTOC(DATE())


See Also

CMONTH( )

DAY( )

DATE( )

SET CENTURY

SET DATE


MOVE WINDOW

See Also	Example	Portability	dBASE IV Windows

Redefines the row and column coordinates of the existing dBASE IV-style window <window name>. The window size, shape, and contents are not affected. This command is supported primarily for compatibility with dBASE IV. In dBASE for Windows, use the Moveable property of a form to control whether the user can move the form.

Syntax

MOVE WINDOW <window name>
TO <row> [, <col>] |
BY <rows expN> [, <cols expN>]

TO <row> [, <col>]

Specifies the new row and column coordinates of the upper left corner of the window. If <col> is omitted, the column coordinate is unchanged.

BY <rows expN> [, <cols expN>]

Specifies the number of rows and columns by which MOVE WINDOW moves the upper left corner of the window relative to the current coordinates. If <cols> is omitted, the column coordinate is unchanged. <rows> and <cols> can be either positive or negative, and refer to character positions calibrated for the font of the parent window.

Description

Use MOVE WINDOW to reposition a window by changing its screen coordinates. The new coordinates become part of the window definition. If the window does not fit on the screen at its new position, dBASE returns an error, and the window does not move.

If the window is open when you use MOVE WINDOW, its position onscreen is changed to reflect the new coordinates. If the window is not open when you use MOVE WINDOW, the window is displayed at the new coordinates when you display and enable it with ACTIVATE WINDOW.

The TO <row>, <col> clause positions the upper left corner of the window to the specified coordinates. For example, MOVE WINDOW <window name> TO 5, 5 places the window upper left corner at row 5, column 5.

When you include the BY <rows expN>, <cols expN> clause, dBASE places the upper left corner of the window <rows expN> rows below the current row coordinate (if <rows expN> is positive) or <rows expN> rows above the current row (if <rows expN> is negative). dBASE places the upper left corner of the window <cols expN> columns to the right of the current column coordinate (if <cols expN> is positive), and <cols expN> columns to the left (if <cols expN> is negative).

To change a window column position while retaining the row coordinate, use the BY argument and specify <rows expN> as 0.

When you use SAVE WINDOW to store the window definition in a window file, and use RESTORE WINDOW later to place the window definition back in memory, the window is displayed at the new screen coordinates.


MOVE WINDOW Example

The following example uses MOVE WINDOW to move a window previously positioned in the lower center of the screen to a position in the upper center:

CLEAR
DEFINE WINDOW A FROM 5,15 TO 20,60;
COLOR W+/B,R+/RB,G+/R DOUBLE
ACTIVATE WINDOW A
?
?
?
?
? SPACE(15)+"This is a test"
? SPACE(2)+"which includes color and border options"
?
?
WAIT
DEACTIVATE WINDOW A
MOVE WINDOW A TO 1,15
ACTIVATE WINDOW A
?
?
? SPACE(5)+"Testing new location of Window A"
?
?
WAIT
DEACTIVATE WINDOW A
CLEAR WINDOWS
RETURN


Portability

Not supported in dBASE III PLUS. In dBASE IV, you must specify <col> or <cols expN>.


See Also

ACTIVATE WINDOW

DEFINE

DEFINE WINDOW

Moveable


MROW( )

See Also	Example	Portability	Keyboard and Mouse Events

Returns the current row position of the mouse pointer. This command is supported primarily for compatibility with dBASE IV. In dBASE for Windows, use properties such as OnLeftMouseDown to manage mouse actions in forms.

Syntax

MROW( )

Description

Use MROW( ) to determine the vertical position of the mouse pointer during a mouse event.

The dBASE interface and applications you design with dBASE provide automatic mouse support. Use MDOWN( ) to determine if the mouse button is being pressed, and MROW( ) and MCOL( ) to determine the row and column coordinates of the mouse pointer at the time of the event.


MROW( ) Example

For examples using MROW( ), see the MCOL( ) and MDOWN( ) command descriptions.


Portability

Not supported in dBASE III PLUS.


See Also

ISMOUSE( )

MCOL( )

MDOWN( )

ON MOUSE

OnLeftMouseDown


MSGBOX( )

See Also	Example	Portability	Forms

Opens a dialog box that displays a message and pushbuttons, and returns a numeric value that corresponds to the pushbutton the user chooses.

Syntax

MSGBOX(<message expC>, [<title expC>, [<box type expN>]])

<message expC>

The message to display in the dialog box.

<title expC>

The title to display in the title bar of the dialog box.

<box type expN>

A numeric value that determines which icon (if any) and which pushbuttons to display in the dialog box. To specify a dialog box with pushbuttons and no icon, use the following numbers:

<box type expN>	Pushbuttons
0	OK
1	OK, Cancel
2	Abort, Retry, Ignore
3	Yes, No, Cancel
4	Yes, No
5	Retry, Cancel
For example, the following command opens a dialog box with Yes, No, and Cancel pushbuttons, and no icon.

Verdict = MSGBOX("Click me", "Bye!", 3)

To specify a dialog box with pushbuttons and an icon, add any of the following numbers to <box type expN>:

Number to Add	Icon Displayed
16
32
48
64
For example, the following command opens the same dialog box as the previous one, this time with a blue i:

? MSGBOX("Click me", "Bye!", 67) && 3+64

When a dialog box has more than one pushbutton, the left most pushbutton is normally the default, However, if you add 258 to <box type expN>, the second pushbutton is the default, and if you add 512 to <box type expN>:, the third pushbutton is the default. For example, the following command opens the same dialog box as the previous one with the Cancel pushbutton as the default:

? MSGBOX("Click me", "Bye!", 579) && 3+64+512

If you omit <box type expN>, box type 0 is used by default.

Description

Use MSGBOX( ) to prompt the user to make a choice or acknowledge a message by clicking a pushbutton in a modal dialog box.

While the dialog box is open, program execution stops and the user cannot give focus to another window. When the user chooses a pushbutton, the dialog box disappears, program execution resumes, and MSGBOX( ) returns a numeric value that indicates which pushbutton was chosen.

Pushbutton	Return Value
OK	1
Cancel	2
Abort	3
Retry	4
Ignore	5
Yes	6
No	7
For example, you can use the return value to make branching decisions in an error handling routine. Each time an error condition occurs, the routine could use MSGBOX( ) to open a dialog box containing Abort, Retry, and Ignore pushbuttons. The routine could evaluate the number returned by MSGBOX( ) and take the appropriate action.


MSGBOX( ) Example

The following example uses an error-handling routine to display a dialog box offering Abort, Retry, and Ignore pushbuttons each time an error condition is generated. If the user clicks Abort, execution is terminated. If the user clicks Retry, control returns to the master routine. If the user clicks Ignore, execution continues after the command that failed.

* The master routine
SET TALK OFF
FOR i = 1 to 5
   DO MessUp
   ? "Try again" && This command executes only if
                 && user clicks the Retry button.
NEXT i
RETURN

PROCEDURE MessUp
  ON ERROR DO FixIt WITH;
     PROGRAM(), MESSAGE(), LINENO()

  ? COMPANY()      && This function does not exist,
                   && so it generates an error.
  DIR              && This command executes only if
                   && user clicks Ignore button.
RETURN

PROCEDURE FixIt(PRO, MES, LIN)
  Verdict = MSGBOX("Problem at line "+;
            LTRIM(STR(LIN))+;
            ", "+MES, "Routine's name: "+PRO, 18)
  DO CASE
     CASE Verdict = 3  && Abort (Stop execution)
          CANCEL
     CASE Verdict = 4  && Retry (Try again)
          RETURN TO MASTER
     CASE Verdict = 5  && Ignore (Go on)
          RETURN
  ENDCASE
RETURN


Portability

Not supported in dBASE IV or dBASE III PLUS.


See Also

ACCEPT

READMODAL( )

ReadModal( )

WAIT


NDX( )

See Also	Example	Table Organization

Returns the name of an .NDX file.

Syntax

NDX( [<index position expN> [, <alias>] ] )

<index position expN>

Selects an .NDX file by the position of an index file in the list of open indexes for the current or a specified table.

<alias>

A work area number (1 through 225), letter (A through J), or alias name. The work area letter or alias name must be enclosed in quotes.

Description

The NDX( ) function returns the name of an .NDX file based on the position of an index file in the list of open indexes for the current or a specified table. The position of indexes in the index file list is specified by SET INDEX, SET ORDER, or USE commands.

If you do not specify an index position, NDX( ) returns the name of the current master index file, or an empty string ("") if the master index is provided by an .MDX file. NDX( ) also returns an empty string if there is no index in the specified index position for the list of open indexes defined by the SET INDEX or USE commands.

If SET FULLPATH is ON, NDX( ) also returns the drive and directory location of the .NDX file in addition to its name.


NDX( ) Example

The following example creates three indexes and then uses NDX( ) to determine the names of .NDX files open for the current table:

USE Company EXCLUSIVE
INDEX ON CompCode TO CompCode
INDEX ON City  TO City
INDEX ON Zip_P_code      TO Zip
SET INDEX TO Zip, CompCode, City
* Now all 3 indexes are open
? "Index 1 ",NDX(1)
? "Index 2 ",NDX(2)
? "Index 3 ",NDX(3)


See Also

DBF( )

FIELD( )

KEY( )

MDX( )

ORDER( )

SET FULLPATH

SET INDEX

SET ORDER

TAG( )

USE


NETWORK( )

See Also	Example	Shared Data

Returns .T. if dBASE is running on a system in which a local area network (LAN) card or other multiuser system card has been installed.

Syntax

NETWORK( )

Description

Use NETWORK( ) to determine if a program might be running in a network environment. For example, your program might need to do something in a network environment that it does not need to do in a single-user environment, such as issue USE with the EXCLUSIVE option.

NETWORK( ) returns .T. if a network card is installed; it does not determine whether a user is currently running dBASE in a network environment. To determine whether a user is actually working in a network environment, use ID( ).


NETWORK( ) Example

This example uses NETWORK( ) to test if the user has a network card installed. The user will SET EXCLUSIVE ON only when it might be needed. Without a network card, SET EXCLUSIVE can be ON permenantly:

IF NETWORK()
  SET EXCLUSIVE OFF && set ON as needed
ELSE
  SET EXCLUSIVE ON  && No network
ENDIF


See Also

GETENV( )

OS( )

USE


NEXTKEY( )

See Also	Example	Portability	Keyboard and Mouse Events

Returns the decimal value associated with a key or key combination held in the keyboard typeahead buffer. NEXTKEY( ) does not remove the keystroke from the buffer.

Syntax

NEXTKEY([<expN>])

<expN>

The position of the key or key combination in the typeahead buffer. If <expN> is omitted, NEXTKEY( ) returns the value of the first keystroke in the buffer. If <expN> is larger than the number of keystrokes in the buffer, NEXTKEY( ) returns 0.

Description

The keyboard typeahead buffer stores keystrokes the user enters while dBASE is busy processing other data. Use NEXTKEY( ) to identify, but not delete, a keystroke held in the buffer. If the buffer is empty, NEXTKEY( ) returns a value of zero.

For example, if you press C and then Alt+P, dBASE stores the values 67 and -420 in the typeahead buffer. NEXTKEY(1) returns 67, and NEXTKEY(2) returns -420. See INKEY( ) Values and READKEY( ) Values for a complete list of the values returned by NEXTKEY( ). See Appendix E in the Language Reference for a complete list of decimal values corresponding to keys.

To determine the value of the first keystroke in the buffer and delete it from the buffer, use INKEY( ).


NEXTKEY( ) Example

The following example verifies whether SPACEBAR is the key pressed immediately after F6. If so, the SpaceBar routine is called; otherwise, the typeahead buffer is cleared:

WAIT
IF LASTKEY() = -5      && F6
  IF NEXTKEY() = 32    && SPACEBAR
    DO SpaceBar
  ELSE
    CLEAR TYPEAHEAD
  ENDIF
ELSE
  DO OtherKey          && Not F6
ENDIF

PROCEDURE SpaceBar
? "SpaceBar"

PROCEDURE OtherKey
? "OtherKey"


Portability

Not supported in dBASE IV or dBASE III PLUS.


See Also

BROWSE

CLEAR TYPEAHEAD

EDIT

INKEY( )

KEYBOARD

LASTKEY( )

ON KEY

READKEY( )

SET TYPEAHEAD


NOTE

See Also	Example	Programs

Marks an entire program line as a comment rather than an executable line.

Syntax

NOTE <comment>

<comment>

A sequence of up to 1019 characters on the same line. If the last character is a semicolon, dBASE recognizes the following line as a comment.

Description

NOTE is identical to *. See * for a description of this command.


NOTE Example

See * for an example of this command.


See Also

*

&&


OEM( )

See Also	Example	Portability	String Data

Returns a character string that is the Original Equipment Manufacturer (OEM) value of a specified American National Standards Institute (ANSI) character expression.

Syntax

OEM(<expC>)

<expC>

The ANSI character expression whose OEM value to return.

Description

OEM( ) is the inverse of ANSI( ). For more information, see ANSI( ).


OEM( ) Example

The following example displays the 255 characters that are possible with ASCII, ANSI, and OEM formats:

FOR i=1 to 255
  ASCII=CHR(i)
  ? i,ASCII,ANSI(ASCII),OEM(ASCII)
  * The next 3 commands cause a pause
  * every 10 lines
  IF MOD(i,10)=0
    WAIT
  ENDIF
NEXT i


Portability

Not supported in dBASE IV or dBASE III PLUS.


See Also

ANSI( )


ON BAR

See Also	Example	Portability	dBASE IV Menus

Executes a command when the user selects (highlights) a bar in a dBASE IV popup menu. This command is supported primarily for compatibility with dBASE IV. In dBASE for Windows, use DEFINE, OPEN FORM, and READMODAL( ) to create and activate menus associated with forms.

Syntax

ON BAR <bar expN>
OF <popup name>
[<command>]

<command>

The command that is executed when you select the popup menu item. If you omit <command>, the command previously assigned by ON BAR is disabled.

Description

ON BAR causes a specified command to execute when the user selects (highlights) a popup menu bar. If you assign a command to a popup menu bar with ON BAR, any command previously assigned with ON POPUP is disabled for that bar.


ON BAR Example

The following example uses ON BAR to initially open the Company table in a Browse, and then perform other actions when different popup menu options are clicked with the mouse:

SET TALK OFF
CLEAR
SELECT 1
USE Company
USE Contact IN 2

DEFINE POPUP Pop1 FROM 1,1
DEFINE BAR 1 OF Pop1 PROMPT "Company Info";
    MESSAGE "CTRL-W to Exit Browse"
DEFINE BAR 2 OF Pop1 PROMPT "Contact Info";
    MESSAGE "CTRL-W to Exit Browse"
DEFINE BAR 3 OF Pop1 PROMPT "Exit"
ON BAR 1 OF Pop1 DO ShowInfo WITH PROMPT()
ON BAR 2 OF Pop1 DO ShowInfo WITH PROMPT()
ON BAR 3 OF Pop1 DO ShowInfo WITH PROMPT()
ACTIVATE POPUP Pop1
RETURN

* Procedure ShowInfo
PROCEDURE ShowInfo
PARAMETERS prompt
DEFINE WINDOW ShowInfo FROM 6,1 TO 15,65
DO CASE
    CASE prompt = "Company Info"
    SELECT 1
    BROWSE WINDOW ShowInfo

    CASE prompt = "Contact Info"
    SELECT 2
    BROWSE WINDOW ShowInfo

    CASE prompt = "Exit"
    DEACTIVATE POPUP
ENDCASE
DEACTIVATE WINDOW ShowInfo
RETURN


Portability

Not supported in dBASE III PLUS.


See Also

DEFINE

ON POPUP

OPEN FORM

READMODAL( )


ON ERROR

See Also	Example	Error Handling and Debugging

Executes a specified command when an error occurs.

Syntax

ON ERROR
[<command>]

<command>

The command to execute when an error occurs in the program, procedure, or UDF. To execute more than one command when an error occurs, issue ON ERROR DO <filename>, where <filename> is a program or procedure file containing the sequence of commands to execute. ON ERROR without a <command> option disables any previous ON ERROR <command>.

Description

Use ON ERROR to control a program's response to run-time errors. For example, <command> can specify a new message in place of a standard error message. When ON ERROR is active, dBASE does not display its default run-time error messages.

While dBASE is executing an ON ERROR command, that particular ON ERROR <command> statement is disabled. Thus, if another error occurs during the execution of <command>, dBASE responds with its default error messages. You can, however, set another ON ERROR condition inside a subroutine called with ON ERROR.

ON ERROR <command> has no effect during the following commands:

APPEND

CREATE/MODIFY
APPLICATION/LABEL/REPORT/SCREEN/STRUCTURE/VIEW

MODIFY COMMAND/FILE

ON ERROR is similar to ON ESCAPE and ON KEY. ON ESCAPE specifies a command for dBASE to execute when SET ESCAPE is ON and Esc is pressed. ON KEY specifies a command for dBASE to execute when a specified key is pressed.

Avoid using a dBASE command recursively with ON ERROR.

See the table in the description of ERROR( ) that compares CERROR( ), ERROR( ), MESSAGE( ), DBERROR( ), DBMESSAGE( ), SQLERROR( ), and SQLMESSAGE( ).


ON ERROR Example

The following example uses ON ERROR to open a user defined window when a run-time error occurs. In the example, the command ? Company( ) will cause an error because Company function does not exist:

ON ERROR DO ErrHndlr WITH ERROR(), MESSAGE(),;
  PROGRAM(), LINENO()
USE Clients
? Company()
RETURN

PROCEDURE ErrHndlr
PARAMETERS nERRORno, cErrMessage, cProgram, nLineNo
DEFINE FORM HeadsUp from 10,25 TO 20,50
DEFINE TEXT Line1 OF HeadsUp AT 2,2 ;
  PROPERTY Text "An Error has occurred",;
  Width 22
DEFINE TEXT Line2 OF HeadsUp AT 4,2;
  PROPERTY Text "Error: " + cErrMessage,;
  Width 22
DEFINE TEXT Line3 OF HeadsUp AT 5,2;
  PROPERTY Text "Number: " + STR(nErrorno),;
  Width 22
DEFINE TEXT Line4 OF HeadsUp AT 6,2;
  PROPERTY Text "Program: "+ cProgram,;
  Width 22
DEFINE TEXT Line5 OF HeadsUp AT 7,2;
  PROPERTY Text "Line #: " + STR(nLineno),;
  Width 22
OPEN FORM HeadsUp


See Also

CERROR( )

ERROR( )

DBERROR( )

DBMESSAGE( )

MESSAGE( )

ON ESCAPE

ON KEY

ON READERROR

RETRY

RETURN

SET ERROR

SET ESCAPE

SQLERROR( )

SQLMESSAGE( )


ON ESCAPE

See Also	Example	Keyboard and Mouse Events

Executes a specified command when SET ESCAPE is ON and the Esc key is pressed during command or program execution.

Syntax

ON ESCAPE
[<command>]

<command>

The command to execute when the following conditions are in effect:

SET ESCAPE is ON

The user presses Esc during command or program execution

To execute more than one command when Esc is pressed, issue ON ESCAPE DO <filename>, where <filename> is a program or procedure file containing the sequence of commands to execute. ON ESCAPE without a <command> option disables any previous ON ESCAPE <command>.

If you issue ON ESCAPE <command> in a program, you should disable the current ON ESCAPE condition by issuing ON ESCAPE without a <command> option before the program ends. Otherwise, the ON ESCAPE condition remains in effect for any subsequent commands and programs you issue and run until you exit dBASE.

Description

When SET ESCAPE is ON (its default setting), pressing Esc interrupts program execution. If ON ESCAPE <command> is in effect, pressing Esc executes the specified command and then continues program execution. If no ON ESCAPE <command> is in effect, pressing Esc interrupts program execution and displays the dBASE Program Interrupted window.

You can issue ON ESCAPE <command> in the Command window to execute <command> when Esc is pressed during the execution of subsequent commands. In this case, dBASE returns control to the Command window when it finishes executing <command>.

Pressing Esc while a user-defined window, menu bar, pop-up menu, or pull-down menu is active deactivates the object and does not execute the command specified with ON ESCAPE. ON ESCAPE <command> also has no effect when Esc is pressed during commands such as CHANGE, EDIT, or READ.

ON ESCAPE is similar to ON ERROR and ON KEY. ON ERROR specifies a command for dBASE to execute when an error occurs in a program, procedure, or UDF. ON KEY specifies a command for dBASE to execute when a specified key, or any key, is pressed.

If SET ESCAPE is ON and both ON KEY and ON ESCAPE are in effect, ON ESCAPE takes precedence when Esc is pressed. See ON KEY for a table that summarizes the relationship between SET ESCAPE, ON ESCAPE, and ON KEY when Esc is pressed.


ON ESCAPE Example

The following example uses ON ESCAPE to substitute a small program, PrgEscape, for the Escape key. In this example, the programmer has wrongly programmed an endless loop that requires the use of Escape to debug. When escape is pressed, the program and line will be shown:

SET PROCEDURE TO PROGRAM(1) ADDITIVE
* So that other program files can access PrgEcape
SET ESCAPE ON
ON ESCAPE DO PrgEscape WITH PROGRAM(1),LINENO()
DO WHILE .t.   && set up an endless loop
  x="always allow a way out"
  y=" of a do while loop"
  z="Press Escape to stop"
  ? x
  ? y
  ? z
ENDDO

Procedure PrgEscape
PARAMETERS prg,line
? "Programmed Escape:",prg,line
SUSPEND


See Also

ON ERROR

ON KEY

SET ESCAPE

SET KEY


ON EXIT BAR

See Also	Example	Portability	dBASE IV Menus

Executes a command when the user exits a pop-up menu item. This command is supported primarily for compatibility with dBASE IV. In dBASE for Windows, use DEFINE, OPEN FORM, and READMODAL( ) to create and activate menus associated with forms.

Syntax

ON EXIT BAR <bar expN>
OF <popup name>
 [<command>]

<command>

The command that is executed when the user exits the pop-up menu item. If you omit <command>, the command previously assigned by ON EXIT BAR is disabled.

Description

ON EXIT BAR causes a specified command to execute when the user exits a particular pop-up menu bar, as when the highlight is moved to another bar, or another bar is selected with the mouse. If you assign a command to a pop-up menu bar with ON EXIT BAR, any command previously assigned with ON EXIT POPUP is disabled for that bar.


ON EXIT BAR Example

The following example uses ON EXIT BAR to display a listing of .DBF files on the current directory when the cursor is moved off bar 2 and to display a listing of .QBE files when the cursor is moved off bar 3:

SET TALK OFF
CLEAR
DEFINE POPUP P1 FROM 1,1
DEFINE BAR 1 OF P1 PROMPT "Files" SKIP
DEFINE BAR 2 OF P1 PROMPT "--------------" SKIP
DEFINE BAR 3 OF P1 PROMPT "Database Files"
DEFINE BAR 4 OF P1 PROMPT "Query Files"
ON EXIT BAR 3 OF P1 DO Showfiles WITH PROMPT()
ON EXIT BAR 4 OF P1 DO Showfiles WITH PROMPT()

ACTIVATE POPUP P1
RETURN

PROCEDURE Showfiles
PARAMETERS prompt
DEFINE WINDOW Showfiles FROM 7,0 TO 20,79
ACTIVATE WINDOW Showfiles
DO CASE
    CASE prompt = "Database Files"
        DIR
        WAIT
    CASE prompt = "Query Files"
        DIR *.QBE
        WAIT
ENDCASE
DEACTIVATE WINDOW Showfiles
RETURN


Portability

Not supported in dBASE III PLUS.


See Also

DEFINE

ON EXIT POPUP

OPEN FORM

READMODAL( )


ON EXIT MENU

See Also	Example	Portability	dBASE IV Menus

Executes a command when the user exits a pad in a dBASE IV menu bar if the pad is not assigned a command by ON EXIT PAD. This command is supported primarily for compatibility with dBASE IV. In dBASE for Windows, use DEFINE, OPEN FORM, and READMODAL( ) to create and activate menus associated with forms.

Syntax

ON EXIT MENU <menu name>
[<command>]

<command>

The command that is executed when you exit the pad. If you omit <command>, the command previously assigned by ON EXIT MENU is disabled.

Description

ON EXIT MENU identifies a command that is executed when the user moves the highlight off certain pads in a dBASE IV menu bar. The command assigned with ON EXIT MENU applies only to pads that are not assigned a command with ON EXIT PAD. If you assign a command to a menu pad with ON EXIT PAD, any command previously assigned with ON EXIT MENU is disabled for that pad.


ON EXIT MENU Example

The following program presents a menu bar for region selection with a state listing box for each region presented below. ON EXIT MENU command is used to run a Cleanup procedure. As the user moves from the original pad to a new pad, this procedure removes the original pad's state listing box from the screen:

CLEAR
SET TALK OFF
DEFINE MENU Main
* Define pads...
DEFINE PAD Pad1 OF Main AT 0,0 PROMPT "Plains States"
DEFINE PAD Pad2 OF Main AT 0,15 PROMPT "Heartland"
DEFINE PAD Pad3 OF Main AT 0,27 PROMPT "District of;
  Columbia"
DEFINE PAD Pad4 OF Main AT 0,50 PROMPT "Border ;
  States"
* Define pad actions...
ON EXIT MENU Main DO Cleanup
ON PAD Pad1 OF Main DO Explain WITH "Iowa", ;
    "Kansas","Minnesota", "Missouri","Nebraska",;
    "North Dakota","South Dakota"
ON PAD Pad2 OF Main DO Explain WITH "Illinois",;
    "Indiana","Michigan","Ohio","Wisconsin"
ACTIVATE MENU MAIN

* Procedure Explain
PROCEDURE Explain
PARAMETERS state1,state2,state3,state4,state5,;
    state6,state7
numstates=PCOUNT()
@ 10,1 to 12+numstates,45 DOUBLE
@ 11,3 SAY "This menu covers the following states:"
cntr=1
DO WHILE cntr<=numstates
    z="state"+LTRIM(STR(cntr))
    @ 11+cntr,6 say &z
    cntr=cntr+1
ENDDO
RETURN
*EOP Explain

PROCEDURE Cleanup
@ 10,1 CLEAR TO 19,45
RETURN
*EOP Cleanup


Portability

Not supported in dBASE III PLUS.


See Also

DEFINE

ON EXIT PAD

OPEN FORM

READMODAL( )


ON EXIT PAD

See Also	Example	Portability	dBASE IV Menus

Executes a command when the user exits a specified pad in a dBASE IV menu bar. This command is supported primarily for compatibility with dBASE IV. In dBASE for Windows, use DEFINE, OPEN FORM, and READMODAL( ) to create and activate menus associated with forms.

Syntax

ON EXIT PAD <pad name>
OF <menu name>
[<command>]

<command>

The command that is executed when you exit the pad. If you omit <command>, the command previously assigned by ON EXIT PAD is disabled.

Description

ON EXIT PAD causes a command to execute when the user exits a pad in a dBASE IV menu bar.


ON EXIT PAD Example

The following program presents a menu bar for region selection with a state listing box for each region presented below. ON EXIT PAD is used to run a Cleanup procedure when the user moves the cursor from Pad1 to a new pad. Procedure Cleanup removes the original pad's state listing box from the screen:

CLEAR
SET TALK OFF
DEFINE MENU Main
* Define pads...
DEFINE PAD Pad1 OF Main AT 0,0 PROMPT "Plains States"
DEFINE PAD Pad2 OF Main AT 0,15 PROMPT "Heartland"
DEFINE PAD Pad3 OF Main AT 0,27 PROMPT;
    "District of Columbia"
DEFINE PAD Pad4 OF Main AT 0,50 PROMPT;
    "Border States"
* Define pad actions...
ON PAD Pad1 OF Main DO Explain WITH "Iowa", ;
    "Kansas","Minnesota", "Missouri","Nebraska",;
    "North Dakota","South Dakota"
ON EXIT PAD Pad1 OF Main DO Cleanup
ACTIVATE MENU MAIN

* Procedure Explain
PROCEDURE Explain
PARAMETERS state1,state2,state3,state4,state5,;
    state6,state7
numstates=PCOUNT()
@ 10,1 to 12+numstates,45 DOUBLE
@ 11,3 SAY "This menu covers the following states:"
cntr=1
DO WHILE cntr<=numstates
    z="state"+LTRIM(STR(cntr))
    @ 11+cntr,6 say &z
    cntr=cntr+1
ENDDO
RETURN
*EOP Explain

PROCEDURE Cleanup
@ 10,1 CLEAR TO 19,45
RETURN
*EOP Cleanup


Portability

Not supported in dBASE III PLUS.


See Also

DEFINE

ON EXIT MENU

ON PAD

ON SELECTION PAD

OPEN FORM

READMODAL( )


ON EXIT POPUP

See Also	Example	Portability	dBASE IV Menus

Executes a command when the user exits a bar in a dBASE IV pop-up menu, if the bar is not assigned a command by ON EXIT BAR. This command is supported primarily for compatibility with dBASE IV. In dBASE for Windows, use DEFINE, OPEN FORM, and READMODAL( ) to create and activate menus associated with forms.

Syntax

ON EXIT POPUP <pop-up name>
[<command>]

<command>

The command that is executed when you exit the pop-up menu item. If you omit <command>, the command previously assigned by ON EXIT POPUP is disabled.

Description

ON EXIT POPUP causes a specified command to execute when the user exits a pop-up menu bar, as when the highlight is moved to another bar, or another bar is selected with the mouse. If you assign a command to a pop-up menu bar with ON EXIT BAR, any command previously assigned with ON EXIT POPUP is disabled for that bar.


ON EXIT POPUP Example

In the following example, the Scale pop-up menu is defined to play a musical scale. ON BAR executes the Soundoff procedure, ON SELECTION BAR executes the Frequency procedure, and the single ON EXIT POPUP command executes the Cleanup procedure for all bars.

MiddleC = 261.6
radio 1
DEFINE POPUP SCALE FROM 1,1
* Define bars
DEFINE BAR 1 OF Scale PROMPT "Middle C"
DEFINE BAR 2 OF Scale PROMPT "B"
.
.
.
* Define bar actions
ON EXIT POPUP Scale DO Cleanup
ON BAR 1 OF Scale DO Soundoff WITH 1
ON SELECTION BAR 1 OF Scale DO Frequency WITH 1
ON BAR 2 OF Scale DO Soundoff with 15/16
ON SELECTION BAR 2 OF Scale DO Frequency with 15/16
.
.
.


Portability

Not supported in dBASE III PLUS.


See Also

DEFINE

ON EXIT BAR

OPEN FORM

READMODAL( )


ON KEY

See Also	Example	Portability	Keyboard and Mouse Events

Executes a commandwhen a specified key or key combination is pressed during execution of a commandor a program.

Syntax

ON KEY
[LABEL <key label>]
[<command>]

LABEL <key label>

Identifies the key or key combination that, when pressed, causes <command> to execute. Without LABEL <key label>, dBASE executes <command> when you press any key. ON KEY LABEL is not case-sensitive.

<command>

The command that is executed when you press the key or key combination. If you omit <command>, the command previously assigned by ON KEY is disabled.

Description

Use ON KEY to specify a command that executes when the user presses a key or key combination. When the key is pressed, ON KEY causes dBASE to stop executing the current command and execute <command>. The interrupted command resumes when <command> finishes executing.

ON KEY interrupts most commands, but it does not interrupt commands that rely on uninterrupted processing to ensure data accuracy, such as SORT, INDEX, and PACK. ON KEY also does not affect the execution of some commands that require user input, such as ACCEPT and WAIT.

When you issue both ON KEY LABEL <key label> <command> and ON KEY <command>, the key or key combination you specify with ON KEY LABEL <key label> <command> takes precedence and executes its associated <command>.

When you do not include LABEL, only one ON KEY specification can be active at a given time. When you include LABEL, multiple ON KEY specifications for multiple keys can be active at once.

ON KEY without arguments removes the effect of all previously-entered ON KEY <command> commands.

SET KEY is identical in function to ON KEY LABEL; only the syntax differs. If you use ON KEY LABEL and SET KEY to set the same key, dBASE executes the program or procedure specified by the most recently issued command.

ON KEY is similar to ON ESCAPE ON ESCAPE specifies a command for dBASE to execute when SET ESCAPE is ON and the Esc key is pressed. If SET ESCAPE is ON and both ON KEY and ON ESCAPE are in effect, ON ESCAPE takes precedence when Esc is pressed. The following table summarizes the relationship between SET ESCAPE, ON ESCAPE, and ON KEY when Esc is pressed:

SET ESCAPE	ON ESCAPE	ON KEY	When you press Esc
ON		DO prog1	dBASE displays Program Interrupted window
OFF		DO prog1	Prog1 executes
ON	DO prog2	DO prog1	Prog2 executes
OFF	DO prog2	DO prog1	Prog1 executes
ON KEY LABEL

Use the following key label names to assign key or key combinations with ON KEY LABEL <key label>.

Key identification	<key label>
Alphabetic characters	A or a, B or b, ...
Numbers	0, 1, 2 ...
Backspace	Backspace
Back Tab	Backtab
Delete	Del
End	End
Home	Home
Insert	Ins
Page Up	PgUp
Page Down	PgDn
Tab	Tab
Left arrow	Leftarrow
Right arrow	Rightarrow
Up arrow	Uparrow
Down arrow	Dnarrow
F1 to F10	F1, F2, F3, ...
Ctrl+<key>	Ctrl-<key> or Ctrl+<key>
Shift+<key>	Shift-<key> or Shift+<key>
Alt+<key>	Alt-<key> or Alt+<Key>
Enter	Enter
Escape	Esc
Space bar	Spacebar


ON KEY Example

The following example displays selected fields from 10 records, pauses for 3 seconds and adds more records to the screen. ON KEY LABEL command is used to branch the program to procedures that either reverse the record pointer, enter a browse window, or exit scolling:

CLEAR
SET TALK OFF
PUBLIC mExit
mExit=.F.
ON KEY LABEL F8 DO BackUp
ON KEY LABEL F9 DO Details
ON KEY LABEL F10 DO GetOut
USE Clients Order Company
? CENTER("INSTRUCTIONS")
? CENTER("Press F8 to go back X records")
? CENTER("Press F9 to Browse all fields")
? CENTER("Press F10 to exit")
?
WAIT "Slow Browse - Press any key when ready"
Cnt=1
DO WHILE .NOT. EOF() .AND. .NOT. mExit
  DISPLAY NEXT 10 Company, Contact
  Pause=INKEY(3)
ENDDO
SET TALK ON
ON KEY
RETURN

PROCEDURE BackUp
CLEAR
SKIP -9
RETURN

PROCEDURE Details
SKIP -9
BROWSE
RETURN

PROCEDURE GetOut
mExit=.T.
RETURN


Portability

The LABEL <key label> option is not supported in dBASE III PLUS.


See Also

CLEAR TYPEAHEAD

INKEY( )

KEYBOARD

ON ERROR

ON ESCAPE

SET ESCAPE

SET FUNCTION


ON MENU

See Also	Example	Portability	dBASE IV Menus

Executes a command when the user selects (highlights) any pad in a dBASE IV menu bar if the pad is not assigned a command with ON PAD. This command is supported primarily for compatibility with dBASE IV. In dBASE for Windows, use DEFINE, OPEN FORM, and READMODAL( ) to create and activate menus associated with forms.

Syntax

ON MENU <menu name>
[<command>]

<command>

The command that is executed when you select the pad. If you omit <command>, the command previously assigned by ON MENU is disabled.

Description

Use ON MENU when you want a default command to execute when a pad that is not assigned an ON PAD command is selected. If you assign a command to a menu pad with ON PAD, any command previously assigned with ON MENU is disabled for that pad.


ON MENU Example

The following example uses ON MENU to initiate an action each time the user moves from one pad to another. That action is determined by procedure ChgPad, which can branch to pop-up menus (ON PAD... ACTIVATE POPUP...) or procedures:

DEFINE MENU Files
* Define pads
DEFINE PAD Pad1 OF Files AT 3,2 PROMPT "Review Data"
DEFINE PAD Pad2 OF Files AT 3,25;
    PROMPT "File Maintenance"
DEFINE PAD Pad3 OF Files AT 3,45 PROMPT "Exit"
* Define pad actions
ON MENU Files DO ChgPad
CLEAR
ACTIVATE MENU Files
RETURN

* Procedure ChgPad
PROCEDURE ChgPad
DEFINE WINDOW Results FROM 15,20 TO 18,60
ACTIVATE WINDOW Results
DO CASE
    CASE PAD()="PAD1"
        ? "Branch to a table/data related popup"
    CASE PAD()="PAD2"
        ? "Branch to a file maintenance popup"
    CASE PAD()="PAD3"
        DEACTIVATE WINDOW Results
        DEACTIVATE MENU
ENDCASE
RETURN


Portability

Not supported in dBASE III PLUS.


See Also

DEFINE

ON PAD

OPEN FORM

READMODAL( )


ON MOUSE

See Also	Example	Portability	Keyboard and Mouse Events

Detects when the user clicks the left mouse button and executes a command when the button is released. This command is supported primarily for compatibility with dBASE IV. In dBASE for Windows, use properties such as OnLeftMouseDown to manage mouse actions in forms.

Syntax

ON MOUSE
[<command>]

<command>

The command that is executed when you release the mouse button. ON MOUSE without a <command> option disables any previous ON MOUSE <command>.

Description

Use ON MOUSE to execute a command when the user clicks the left mouse button during execution of a command such as EDIT or @...SAY...GET. ON MOUSE causes dBASE to stop executing the current command and execute <command>. The interrupted command resumes when <command> finishes executing.

ON MOUSE interrupts certain commands, but it does not interrupt commands that rely on uninterrupted processing to ensure data accuracy, such as SORT, INDEX, and PACK. ON MOUSE also does not affect the execution of some commands that require user input, such as ACCEPT and WAIT.

The action assigned with ON MOUSE is triggered under the following conditions:

An @...SAY...GET and READ combination is executing, and the user clicks outside the @...GET input area.

A BROWSE, CREATE/MODIFY COMMAND, or CREATE/MODIFY FILE window is open, and the user clicks outside it.

A dBASE IV menu is active and the user clicks outside it.

A dBASE IV popup menu is active and the user clicks outside it.

ON MOUSE without arguments removes the effect of all previously entered ON MOUSE <command> commands.


ON MOUSE Example

This example draws a box on the screen and sets up a READ. Inside the READ, if the user clicks the left mouse button, the procedure CheckMous displays a message saying where the user clicked:

ON MOUSE DO CheckMous
CLEAR
@ 2,5 TO 4,10  && draw a box
Ans=" "
@ 10,0 SAY ;
  "Click the mouse. Press any key when done" ;
   GET Ans
READ
ON MOUSE  && reset ON MOUSE

PROCEDURE CHECKMOUS
r=MROW()  && mouse row
c=MCOL()  && mouse col
IF (r>=2 .AND. r<=4) .AND. (c>=5 .AND. c<=10)
  @ 11,0 SAY "You clicked in the box     "
ELSE
  @ 11,0 SAY "You clicked outside the box"
ENDIF


Portability

Not supported in dBASE III PLUS.


See Also

ACCEPT

BROWSE

CLEAR TYPEAHEAD

EDIT

INDEX

ISMOUSE( )

MDOWN( )

MODIFY COMMAND

MODIFY FILE

ON ERROR

ON ESCAPE

ON KEY

PACK

READ

SET ESCAPE

SET FUNCTION

SORT

WAIT

@...SAY...GET


ON NETERROR

See Also	Example	Shared Data

Executes a specified command when a multiuser-specific error occurs.

Syntax

ON NETERROR [<command>]

<command>

The command to execute when a multiuser-specific error occurs. To execute more than one command when such an error occurs, issue ON NETERROR DO <filename>, where <filename> is a program or procedure file containing the sequence of commands to execute. ON NETERROR without a <command> option disables any previous ON NETERROR <command> statement.

Description

Use ON NETERROR to control a program's response to multiuser-specific errors. For example, in a multiuser environment on a local area network (LAN), an error can occur when two users attempt to alter the same record in a shared table at the same time, or when one user attempts to open a shared table that another user already has open for exclusive use.

ON NETERROR is similar to ON ERROR, except that ON ERROR responds to all run-time errors regardless of whether they are multiuser-specific. You can use ON ERROR to handle both single-user and multiuser errors, or you can use ON NETERROR to handle just multiuser errors. If you issue both ON ERROR and ON NETERROR, then ON ERROR responds to just single-user errors, leaving ON NETERROR to respond to multiuser errors.

While dBASE is executing an ON NETERROR command, that particular ON NETERROR <command> statement is disabled. Thus, if another multiuser-specific error occurs during the execution of <command>, dBASE responds with its default error messages. You can, however, set another ON NETERROR condition inside a subroutine called with ON NETERROR.

You should avoid using a dBASE command recursively with ON NETERROR.


ON NETERROR Example

The following example uses ON NETERROR in case the Clients table cannot be opened exclusively:

SET PROCEDURE TO PROGRAM(1) ADDITIVE
ON NETERROR Do NetErr
USE Clients EXCLUSIVE
* If Clients cannot be opened exclusively then
* the subroutine NetErr will be called.

PROCEDURE NETERR
WAIT "Multi-user problem"


See Also

DO

ERROR( )

MESSAGE( )

ON ERROR

RETRY

RETURN

SET EXCLUSIVE

SET REPROCESS

SQLERROR( )

SQLMESSAGE( )


ON PAD

See Also	Example	Portability	dBASE IV Menus

Executes a command or displays a pop-up menu when the user selects (highlights) a pad in a dBASE IV menu bar. This command is supported primarily for compatibility with dBASE IV. In dBASE for Windows, use DEFINE, OPEN FORM, and READMODAL( ) to create and activate menus associated with forms.

Syntax

ON PAD <pad name>
OF <menu name>
[<command>] | [ ACTIVATE POPUP <popup name> ]

<command>

The command that is executed when you select the pad.

ACTIVATE POPUP <popup name>

The pop-up menu to display when the user selects the pad <pad name>.

Description

ON PAD causes a command to execute or a pop-up menu to display when the user selects (highlights) a pad in a dBASE IV menu bar. Before using ON PAD, create the menu and the pad with DEFINE MENU and DEFINE PAD, respectively. The ON PAD command executes when the user highlights the pad or clicks on the pad.

If you omit both <command> and ACTIVATE POPUP <popup name>, any command previously assigned by ON PAD is disabled.


ON PAD Example

This program segment defines a menu and uses the ON PAD command to associate a pop-up with each of the first three pads. The fourth pad executes a procedure through an ON SELECTION PAD command:

DEFINE MENU Top MESSAGE "Press Esc to exit"
DEFINE PAD Pad1 OF Top PROMPT "Andrews" AT 3,3
DEFINE PAD Pad2 OF Top PROMPT "Marx" AT 3,22
DEFINE PAD Pad3 OF Top PROMPT "Stooges" AT 3,41
DEFINE PAD Pad4 OF Top PROMPT "Help" AT 3,60

DEFINE POPUP Pop1 FROM 5,3;
  MESSAGE "Press Esc to exit"
DEFINE BAR 1 OF Pop1 PROMPT "Patty"
DEFINE BAR 2 OF Pop1 PROMPT "Maxine"
DEFINE BAR 3 OF Pop1 PROMPT "Laverne"

DEFINE POPUP Pop2 FROM 5,22;
  MESSAGE "Press Esc to exit"
DEFINE BAR 1 OF Pop2 PROMPT "Groucho"
DEFINE BAR 2 OF Pop2 PROMPT "Harpo"
DEFINE BAR 3 OF Pop2 PROMPT "Chico"
DEFINE BAR 4 OF Pop2 PROMPT "Zeppo"

DEFINE POPUP Pop3 FROM 5,41;
  MESSAGE "Press Esc to exit"
DEFINE BAR 1 OF Pop3 PROMPT "Moe"
DEFINE BAR 2 OF Pop3 PROMPT "Curly"
DEFINE BAR 3 OF Pop3 PROMPT "Larry"

ON PAD Pad1 OF Top ACTIVATE POPUP Pop1
ON PAD Pad2 OF Top ACTIVATE POPUP Pop2
ON PAD Pad3 OF Top ACTIVATE POPUP Pop3

ON SELECTION PAD Pad4 OF Top DO Sorry
ON SELECTION POPUP Pop1 DO P1info    && Programs that;
                                        display text
ON SELECTION POPUP Pop2 DO P2info    && files;
                                        containing
ON SELECTION POPUP Pop3 DO P3info    && short ;
                                        biographies.

CLEAR
ACTIVATE MENU Top

PROCEDURE Sorry
DEFINE WINDOW Excuses FROM 12,20 TO 16,60 DOUBLE
ACTIVATE WINDOW Excuses
@ 1,1 SAY CENTER("There is no help!",40)
WAIT
DEACTIVATE WINDOW Excuses


Portability

Not supported in dBASE III PLUS.


See Also

DEFINE

DEFINE PAD

OPEN FORM

READMODAL( )


ON PAGE

See Also	Example	Portability	Printing

Executes a specified command when printed output reaches a specified line on the current page.

Syntax

ON PAGE
[AT LINE <expN> <command>]

AT LINE <expN>

Identifies the line number at which to execute the specified page-formatting command.

<command>

The command to execute when printed output reaches the specified line number, <expN>. To execute more than one command, issue ON PAGE DO <filename>, where <filename> is a program or procedure file containing the sequence of commands to execute.

Description

Use ON PAGE to specify a command to execute when printed output reaches a specific line number. ON PAGE with no options disables any previous ON PAGE statement.

The value of the _plineno system variable indicates the number of lines that have been printed on the current page. As soon as the _plineno value is equal to the value you specify for <expN>, dBASE executes the ON PAGE command.

Use the ON PAGE command to print headers and footers. For example, the ON PAGE command can call a procedure when the _plineno system memory variable reaches the line number that signifies the end of a page. In turn, that procedure can call two procedures, one to print the footer on the current page and one to print the header on the next page.

You can begin header routines with EJECT PAGE to ensure that the header text prints at the top of the following page. EJECT PAGE also sets the _plineno system memory variable to 0. Use the ? command at the beginning of a header procedure to skip several lines before printing the header information. You can also use the ? command at the end of the procedure to skip several lines before printing the text for the page.

Begin footer routines with the ? command to move several lines below the last line of text. You can use the ?? command with the _pageno system memory variable to print a page number for each page on the same line as the footer.

To calculate the appropriate footer position, add the number of lines for the bottom margin and the number of lines for the footer text to get the total lines for the bottom of the page. Subtract this total from the total number of lines per page. Use this result to specify a number for the AT LINE argument. If the footer text exceeds the number of lines per page, the remainder prints on the next page.


ON PAGE Example

This example uses EJECT PAGE in conjunction with ON PAGE to print a footer on each page. In this example, a page length of 5 is set up (lines 0 thru 4). Text is printed on four lines: 0,1,2,3, and the footer prints on line 4. Eight lines of text are printed on two pages:

SET TALK OFF
CLEAR
SET PRINTER ON
_padvance="LINEFEEDS"
_plength=5
_pageno=1
EJECT
ON PAGE AT LINE 3 do Page_Brk
PRINTJOB
i=1
DO WHILE  i<=8
  ?? "Line of text   ",_pageno,_plineno,i
  ?
  i=i+1
ENDDO
ON PAGE  && turn off ON PAGE
ENDPRINTJOB
CLOSE PRINTER

PROCEDURE Page_Brk
??  "   Page Footer",_pageno,_plineno
EJECT PAGE
RETURN
*                        Page       Line         i
* This prints out as:
*
* Line of text             1          0          1
* Line of text             1          1          2
* Line of text             1          2          3
* Line of text             1          3          4
*    Page Footing          1          4
* Line of text             2          0          5
* Line of text             2          1          6
* Line of text             2          2          7
* Line of text             2          3          8
*    Page Footer           2          4


Portability

Not supported in dBASE III PLUS.


See Also

?

??

_pageno

_plineno

EJECT PAGE

PRINTJOB...ENDPRINTJOB

SET PCOL

SET PRINTER

SET PROW


ON POPUP

See Also	Example	Portability	dBASE IV Menus

Executes a command when the user selects (highlights) a bar in a dBASE IV pop-up menu, if the bar is not assigned a command with ON BAR. This command is supported primarily for compatibility with dBASE IV. In dBASE for Windows, use DEFINE, OPEN FORM, and READMODAL( ) to create and activate menus associated with forms.

Syntax

ON POPUP <pop-up name>
[<command>]

<command>

The command that is executed when you select the pop-up menu item. If you omit <command>, the command previously assigned by ON POPUP is disabled.

Description

ON POPUP causes a specified command to execute when a pop-up menu bar is selected (highlighted). If you assign a command to a pop-up menu bar with ON BAR, any command previously assigned with ON POPUP is disabled for that bar.


ON POPUP Example

The following example uses ON POPUP to display a help message for each bar when the cursor is positioned at that bar:

DEFINE POPUP FileType FROM 5,12
DEFINE BAR 1 OF FileType PROMPT ".DBF"
DEFINE BAR 2 OF FileType PROMPT ".QBE"
DEFINE BAR 3 OF FileType PROMPT ".WFM"
DEFINE BAR 4 OF FileType PROMPT ".FRM"
DEFINE BAR 5 OF FileType PROMPT ".LBL"
ON POPUP FileType DO ShowHelp
ON EXIT POPUP FileType Do Cleanup
CLEAR
ACTIVATE POPUP FileType
RETURN

* Procedure ShowHelp
PROCEDURE ShowHelp
DO CASE
    CASE PROMPT() = ".DBF"
    @ 7,27 SAY "These files store database records"

    CASE PROMPT() = ".QBE"
    @ 7,27 SAY "These files store query files"

    CASE PROMPT() = ".WFM"
    @ 7,27 SAY "These files store form design files"

    CASE PROMPT() = ".FRM"
    @ 7,27 SAY "These files store report"

    CASE PROMPT() = ".LBL"
    @ 7,27 SAY "These files store labels"
ENDCASE
RETURN

* Procedure Cleanup
PROCEDURE Cleanup
@ 7,27 CLEAR TO 7,79
RETURN


Portability

Not supported in dBASE III PLUS.


See Also

DEFINE

ON BAR

OPEN FORM

READMODAL( )


ON READERROR

See Also	Example	Portability	Error Handling and Debugging

Executes a specified command when an error occurs during data-entry.

Syntax

ON READERROR
[<command>]

<command>

The command to execute when a user enters an invalid value into a field. ON READERROR without <command> disables any previously issued ON READERROR <command>.

Description

Use ON READERROR to trap the following data-entry errors:

Invalid dates

Input that is outside the boundaries specified by a RANGE option of @...SAY...GET

Input that does not meet the condition specified in a VALID option of @...SAY...GET

The command you specify with ON READERROR can be a call to a program, procedure, or user-defined function (UDF). For example, you could call a UDF that displays a message.

With or without ON READERROR, the user must enter valid dates and data that are within a VALID or RANGE clause. If the user makes a data-entry error when a RANGE clause is in effect but no ON READERROR condition is in effect, dBASE displays a message indicating acceptable input values.


ON READERROR Example

The following example brings up the Clients table in a Table Record window and uses ON READERROR to trap for incorrect date entries. To activate ON READERROR, enter an invalid date in BalDate and procedure ErrHndlr presents a window with appropriate messages:

ON READERROR DO ErrHndlr
USE Clients
BROWSE
RETURN

PROCEDURE ErrHndlr
DEFINE FORM HeadsUp FROM 10,25 TO 20,50
DEFINE TEXT Line1 OF HeadsUp AT 2,4;
  PROPERTY Text "An Error has occurred",;
  Width 22, ColorNormal "R/W"
DEFINE TEXT Line2 OF HeadsUp AT 4,4;
  PROPERTY Text "Error: Date out of range",;
  Width 22
DEFINE TEXT Line3 OF HeadsUp AT 6,4;
  PROPERTY Text "Enter a value within range",;
  Width 22
OPEN FORM HeadsUp


Portability

Not supported in dBASE III PLUS.


See Also

APPEND

CHANGE

EDIT

INSERT

ON ERROR

READ

@...SAY...GET


ON SELECTION BAR

See Also	Example	Portability	dBASE IV Menus

Executes a command when the user chooses a bar in a dBASE IV pop-up menu. This command is supported primarily for compatibility with dBASE IV. In dBASE for Windows, use DEFINE, OPEN FORM, and READMODAL( ) to create and activate menus associated with forms.

Syntax

ON SELECTION BAR <bar expN>
OF <pop-up name>
[<command>]

<command>

The command that is executed when you choose the pop-up menu item. If you omit <command>, the command previously assigned by ON SELECTION BAR is disabled.

Description

ON SELECTION BAR causes a specified command to execute when a particular pop-up menu bar is chosen, as when the user highlights the bar and presses Enter or double-clicks on the bar with the mouse. If you assign a command to a pop-up menu bar with ON SELECTION BAR, any command previously assigned with ON SELECTION POPUP is disabled for that bar.


ON SELECTION BAR Example

The following example initially presents a 3-bar popup menu and then uses ON SELECTION BAR to branch to the appropriate procedure. This command should be compared to ON SELECTION POPUP which would normally call a procedure that would evaluate PROMPT( ) or BAR( ) and then branch to another lower level procedure.

CLEAR
SET TALK OFF
USE Company ORDER Company IN SELECT() ALIAS Company
USE Company ORDER Company IN SELECT() ALIAS Sales AGAIN

DEFINE WINDOW BrowVw FROM 10,1 TO 24,75
DEFINE POPUP Pop1 FROM 1,1
DEFINE BAR 1 OF Pop1 PROMPT "Company Info";
    MESSAGE "CTRL-End to Exit Browse"
DEFINE BAR 2 OF Pop1 PROMPT "Sales Info";
    MESSAGE "CTRL-End to Exit Browse"
DEFINE BAR 3 OF Pop1 PROMPT "Exit"
ON SELECTION BAR 1 OF Pop1 DO ProcA
ON SELECTION BAR 2 OF Pop1 DO ProcB
ON SELECTION BAR 3 OF Pop1 DO ProcC
ACTIVATE POPUP Pop1
DEACTIVATE WINDOW BrowVw
SELECT Company
USE
SELECT Sales
USE
RETURN

* Procedure ProcA
PROCEDURE ProcA
SELECT Company
BROWSE FIELDS Company, Street1, Street2, City, State_Prov, Zip_P_Code,;
   Phone, Type, CompCode WINDOW BrowVw
RETURN

* Procedure ProcB
PROCEDURE ProcB
SELECT Sales
BROWSE FIELDS YTD_Sales WINDOW BrowVw
RETURN

* Procedure ProcC
PROCEDURE ProcC
DEACTIVATE POPUP


Portability

Not supported in dBASE III PLUS.


See Also

DEFINE

ON SELECTION POPUP

OPEN FORM

READMODAL( )


ON SELECTION FORM

See Also	Example	Portability	Forms

Executes a subroutine or a codeblock when the user submits a form.

Syntax

ON SELECTION FORM <form name>
[<expFP> | <expCB>]

<form name>

The name of the form to which <expFP> or <expCB> is assigned.

<expFP> | <expCB>

A subroutine or a codeblock to execute when the user submits the form. <expFP> is the name of a function or a procedure, and <expCB> is a codeblock.

If you omit <expFP> | <expCB>, the routine or codeblock previously assigned by ON SELECTION FORM is disabled.

Description

Use ON SELECTION FORM to execute a subroutine or codeblock automatically when the user submits a form.

A form is submitted when the user:

Presses Enter when the cursor is in the body of the form, but not in a browse object, an editor object, or on a drive letter or directory prompt in a list box or a combo box.

Presses Spacebar when the cursor is on a pushbutton.

Presses the pick character of a pushbutton, or Alt+<pick character>, when the cursor is in the form.

Clicks when the mouse pointer is on a pushbutton.

ON SELECTION FORM is equivalent to the OnSelection property of the form object.


ON SELECTION FORM Example

The following example defines a form and list box for selecting an aircraft model and uses ON SELECTION FORM to call procedure Photo when the user presses Enter. Procedure Photo displays a graphic from the binary field Image of the selected record:

CLOSE ALL
SET TALK OFF
SET PROCEDURE TO PROGRAM(1) ADDITIVE
USE Aircrdb ORDER Aircraft IN SELECT()
SELECT Aircrdb
DEFINE FORM AC               ;
   PROPERTY                  ;
      Top 5,                 ;
      Left 60,                ;
      Height 13,             ;
      Width 30,              ;
      Text "Aircraft",       ;
      Sizeable .T.
DEFINE LISTBOX Model OF AC             ;
   PROPERTY                            ;
      Top 2,                           ;
      Left 6,                         ;
      Height 7,                        ;
      Width 18,                        ;
      DataSource "FIELD Aircrdb->Aircraft"
ON SELECTION FORM AC Photo
OPEN FORM AC

FUNCTION Photo
RESTORE IMAGE FROM BINARY Image
RETURN .T.


Portability

Not supported in dBASE IV or dBASE III PLUS.


See Also

ActiveControl

_curobj

OnClick

OnSelection


ON SELECTION MENU

See Also	Example	Portability	dBASE IV Menus

Executes a command when the user chooses a pad from a dBASE IV menu bar if the pad is not already assigned a command with ON SELECTION PAD. This command is supported primarily for compatibility with dBASE IV. In dBASE for Windows, use DEFINE, OPEN FORM, and READMODAL( ) to create and activate menus associated with forms.

Syntax

ON SELECTION MENU <menu name>
[<command>]

<command>

The command that is executed when you choose the pad. If you omit <command>, the command previously assigned by ON SELECTION MENU is disabled.

Description

Use ON SELECTION MENU when you want to identify a default command to execute when a pad that is not assigned an ON SELECTION PAD command is selected. If you assign a command to a menu pad with ON SELECTION PAD, any command previously assigned with ON SELECTION MENU is disabled for that pad.


ON SELECTION MENU Example

In the following example, only Pad1 is assigned an ON SELECTION PAD command. The other pads use the ON SELECTION MENU command executing the Showfiles procedure when they are chosen. Pad1 uses ON SELECTION Pad with no <command> to disable the pad from using the ON SELECTION MENU command:

DEFINE MENU Files
* Define pads
DEFINE PAD Pad1 OF Files AT 0,0 PROMPT "Action"
DEFINE PAD Pad2 OF Files AT 0,15 PROMPT "Database"
DEFINE PAD Pad3 OF Files AT 0,30 PROMPT "Queries"
DEFINE PAD Pad4 OF Files AT 0,45 PROMPT "Forms"
DEFINE PAD Pad5 OF Files AT 0,60 PROMPT "Reports"
* Define pad actions
ON SELECTION MENU Files DO Showfiles
ON SELECTION PAD Pad1 OF Files
ON PAD Pad1 OF Files ACTIVATE POPUP Setact

DEFINE POPUP Setact FROM 3,0
DEFINE BAR 1 OF Setact PROMPT "Bar1"
DEFINE BAR 2 OF Setact PROMPT "Bar2"
ON SELECTION POPUP Setact KEYBOARD ""

CLEAR
ACTIVATE MENU Files
RETURN


Portability

Not supported in dBASE III PLUS.


See Also

ACTIVATE MENU

DEFINE

DEFINE PAD

ON MENU

ON PAD

ON SELECTION PAD

OPEN FORM

READMODAL( )


ON SELECTION PAD

See Also	Example	Portability	dBASE IV Menus

Specifies the command that executes when the user chooses a pad in a dBASE IV menu bar. This command is supported primarily for compatibility with dBASE IV. In dBASE for Windows, use DEFINE, OPEN FORM, and READMODAL( ) to create and activate menus associated with forms.

Syntax

ON SELECTION PAD <pad name>
OF <menu name>
[<command>]

<command>

The command that is executed when the user chooses the pad. If you omit <command>, the command previously assigned by ON SELECTION PAD is disabled.

Description

ON SELECTION PAD causes a command to execute when the user chooses a pad in a dBASE IV menu bar. The ON SELECTION PAD command executes when the user presses Enter while the pad is highlighted or when the user clicks on the pad. If you assign a command to a menu pad with ON SELECTION PAD, any command previously assigned with ON SELECTION MENU is disabled for that pad.


ON SELECTION PAD Example

The following example uses ON SELECTION PAD to branch to a procedure upon selection of a pad with the Enter key or a mouse click:

USE Clients
DEFINE MENU Mainmenu
DEFINE PAD Add OF Mainmenu AT 1,10 PROMPT "Add ;
Records"
DEFINE PAD Edit OF Mainmenu AT 1,30 PROMPT "Edit ;
Records"
DEFINE PAD Quit OF Mainmenu AT 1,50 PROMPT "Quit"
ON SELECTION PAD Add OF Mainmenu DO Addproc
ON SELECTION PAD Edit OF Mainmenu DO Editproc
ON SELECTION PAD Quit OF Mainmenu DO Cancel
CLEAR
ACTIVATE MENU Mainmenu

PROCEDURE Addproc
APPEND
RETURN

PROCEDURE Editproc
EDIT
RETURN

PROCEDURE Cancel
DEACTIVATE MENU
CLEAR ALL
CLOSE ALL
RETURN


Portability

Not supported in dBASE III PLUS.


See Also

DEFINE

ON PAD

OPEN FORM

READMODAL( )


ON SELECTION POPUP

See Also	Example	Portability	dBASE IV Menus

Executes a command when the user chooses a bar in a dBASE IV pop-up menu, if the bar is not assigned a command by ON SELECTION BAR. This command is supported primarily for compatibility with dBASE IV. In dBASE for Windows, use DEFINE, OPEN FORM, and READMODAL( ) to create and activate menus associated with forms.

Syntax

ON SELECTION POPUP <pop-up name> | ALL
[BLANK]
[<command>]

ALL

Specifies that <command> is executed when the user chooses any pop-up menu item that is not assigned a command by ON SELECTION BAR.

BLANK

Clears the pop-up menu from the screen before executing <command>.

<command>

The command that is executed when the user chooses the pop-up menu item. If you omit <command>, the command previously assigned by ON SELECTION POPUP is disabled.

Description

ON SELECTION POPUP causes a specified command to execute when a pop-up menu bar is chosen, as when the user highlights the bar and presses Enter, or double-clicks on the bar. If you assign a command to a pop-up menu bar with ON SELECTION BAR, any command previously assigned with ON SELECTION POPUP is disabled for that bar.


ON SELECTION POPUP Example

The following example initially presents a 3-bar popup menu and then uses ON SELECTION BAR to branch to the appropriate procedure. This command should be compared to ON SELECTION POPUP which would normally call a procedure that would evaluate PROMPT( ) or BAR( ) and then branch to another lower level procedure.

CLEAR
SET TALK OFF
USE Company ORDER Company IN SELECT() ALIAS Company
USE Company ORDER Company IN SELECT() ALIAS Sales AGAIN

DEFINE WINDOW BrowVw FROM 10,1 TO 24,75
DEFINE POPUP Pop1 FROM 1,1
DEFINE BAR 1 OF Pop1 PROMPT "Company Info";
    MESSAGE "CTRL-End to Exit Browse"
DEFINE BAR 2 OF Pop1 PROMPT "Sales Info";
    MESSAGE "CTRL-End to Exit Browse"
DEFINE BAR 3 OF Pop1 PROMPT "Exit"
ON SELECTION BAR 1 OF Pop1 DO ProcA
ON SELECTION BAR 2 OF Pop1 DO ProcB
ON SELECTION BAR 3 OF Pop1 DO ProcC
ACTIVATE POPUP Pop1
DEACTIVATE WINDOW BrowVw
SELECT Company
USE
SELECT Sales
USE
RETURN

* Procedure ProcA
PROCEDURE ProcA
SELECT Company
BROWSE FIELDS Company, Street1, Street2, City, State_Prov, Zip_P_Code,;
   Phone, Type, CompCode WINDOW BrowVw
RETURN

* Procedure ProcB
PROCEDURE ProcB
SELECT Sales
BROWSE FIELDS YTD_Sales WINDOW BrowVw
RETURN

* Procedure ProcC
PROCEDURE ProcC
DEACTIVATE POPUP


Portability

Not supported in dBASE III PLUS.


See Also

DEFINE

ON SELECTION BAR

OPEN FORM

READMODAL( )


OPEN DATABASE

See Also	Example	Portability	Table Basics

Establishes a connection to a database server or a database defined for a specific directory location.

Syntax

OPEN DATABASE <database name>
[LOGIN <username>/<password>]
[WITH <option expC>]

<database name>

The name of the database you want to open. Databases are created using the IDAPI Configuration Utility (see Getting Started for more information).

<user name>/<password>

Character string specifying the user name and password combination required to access the database.

WITH <option string>

Character string specifying server-specific information required to establish a database server connection. For information about establishing database server connections, refer to your Borland SQL Link documentation, and contact your network or database administrator for specific connection information.

Description

The OPEN DATABASE command is used to establish a connection with a database defined with the IDAPI Configuration Utility. When opening a database, you need to specify whatever login parameters and database-specific information that connection requires. Typically, your network or system administrator can provide you with the information necessary to establish connections to established databases and database servers at your site.


OPEN DATABASE Example

The following example uses OPEN DATABASE to establish a connection with a database server, opens a database previously created using the IDAPI Configuration Utility with SET DATABASE TO, and opens a server dBASE table and appends it to the client/server database:

CLEAR
SET DBTYPE TO DBASE
OPEN DATABASE CAClients      && Establish connection;
                                with database server
USE CAClients IN 1           && Opens server table
SELECT 1                     && Work area 1 active
APPEND FROM CLIENTS.DBF      && Append from local;
                                dBASE table
CLOSE ALL                    && Closes Clients;
                                server table
CLOSE DATABASE CAClients     && Disconnect from ;
                                database server


Portability

Not supported in dBASE IV or dBASE III PLUS.


See Also

CLOSE...

DATABASE( )

SET DATABASE

SET DBTYPE


OPEN FORM

See Also	Example	Portability	Forms

Opens forms as modeless windows.

Syntax

OPEN FORM <form name 1> [ON <object name 1>]
[, <form name 2> [ON <object name 2>] ...]

<form name 1> [, <form name 2>, ...]

The names of the forms to open.

ON <object name>

Specifies which object in a form gets initial focus.

Description

Use OPEN FORM to open forms and display their objects.

The form you open with OPEN FORM is modeless. A modeless form has the following characteristics:

While the form is open, focus can be transferred to other forms.

Execution of the routine that opened the form continues after the form is opened.

You open forms as modeless windows when you want more than one form open at once. For example, an application that performs several tasks might use a different form for each task.

Only one form can have focus at a given time; this form is said to be active, and is displayed on top of all other open forms. dBASE gives input focus to forms in the order in which you list them in the OPEN FORM command; the first form specified receives input focus first. When the last form is closed, execution of the application is finished.

Note:	To open a form as a modal window, use the ReadModal( ) method or the READMODAL( ) function. For example, forms that serve as dialog boxes are modal, since they halt program execution until the user inputs a response.

The OPEN FORM command is equivalent to the Open( ) method.


OPEN FORM Example

The following example defines four default sized forms and uses the OPEN FORM command syntax options to establish an initial focus order:

DEFINE FORM Opn1
DEFINE FORM Opn2 AT 4,4
DEFINE FORM Opn3 AT 8,8
DEFINE FORM Opn4 AT 12,12
OPEN FORM Opn4, Opn1, Opn3, Opn2


Portability

Not supported in dBASE IV or dBASE III PLUS.


See Also

Open( )

READMODAL( )

ReadModal( )


ORDER( )

See Also	Example	Portability	Table Organization

Returns the name of the master .NDX file or the master .MDX index tag in the current or a specified work area.

Syntax

ORDER( [<alias>] )

<alias>

A work area number (1 through 225), letter (A through J), or alias name. The work area letter or alias name must be enclosed in quotes.

Description

ORDER( ) returns the name of the master .NDX file or .MDX index tag in the current or specified work area. ORDER( ) returns an empty string ("") if no master index exists in the specified work area.

You can use ORDER( ) to determine the name of the master index and save the name of the index to a memory variable, and then use the SET ORDER command to later restore the master index.


ORDER( ) Example

The following example uses ORDER( ) to show the name of master index for the current table:

USE Company EXCLUSIVE
INDEX ON Company TAG Company
INDEX ON City    TAG City
SET ORDER TO Company
? "The master index file is " + ORDER() + ;
   " for the " + DBF() + " table"
SET ORDER TO       && no index
? "The master index file is " + ORDER() + ;
   " for the " + DBF() + " table"
SET ORDER TO City
? "The master index file is " + ORDER() + ;
   " for the " + DBF() + " table"


Portability

Not supported in dBASE III PLUS.


See Also

ALIAS( )

KEY( )

MDX( )

NDX( )

SELECT( )

SET INDEX

SET ORDER

TAG( )

USE


OS( )

See Also	Example	Portability	Disk and File Utilities

Returns the name and version number of the current operating system or the current version of Windows.

Syntax

OS([<expN>])

<expN>

Any number. OS( ) without <expN> returns the name and version number of the operating system. OS(expN) returns the version of Windows currently running.

Description

Use OS( ) to determine the operating system or version of Windows in which your programs are running. To determine which version of dBASE is running, use VERSION( ).

OS( ) lets you make your applications more portable from system to system. For example, if you plan to copy an application to more than one system, and if you suspect that some of these systems have DOS versions that are too old to accommodate certain sections of your code, make the execution of these sections contingent on the value returned by OS( ).


OS( ) Example

This example uses OS( ) to test whether the operating system in use is Windows version 3.10 or later. It finds the number of characters to the right of 'version', separates them out and converts them to a number. This number is compared to 3.10:

Os=OS(1) && Will return "Windows version ??.??"
L=Len(Os)
* Number of Chars
Os=UPPER(Os)
* convert to upper case
Pos=AT("VERSION",Os)
* locate 'version' in Os
* Pos points at the 'v' in 'version'
RightSide=L-Pos-6
* get # chars after 'version'
VersionStr=Right(Os,RightSide)
VersionNum=Val(VersionStr)
* convert to number
IF VersionNum<3.10
  ? "Your current operating system is",OS()
  ? "Your current windows system is  ",OS(1)
  WAIT ;
   "This program needs Windows version 3.10 or later"
ENDIF


Portability

The <expN> option is not supported in dBASE IV or dBASE III PLUS.


See Also

VERSION( )


PACK

See Also	Example	Fields and Records

Removes all records marked for deletion from the current table. This command has no effect when accessing Paradox or SQL tables, since records are removed immediately when they are deleted.

Syntax

PACK

Description

Use PACK to remove records from the current table that were previously marked for deletion by the DELETE command. You need to open a table for exclusive use before using PACK.

After you execute a PACK command, the disk space used by the deleted records is reclaimed when the table is closed. All open index files are automatically reindexed after PACK is executed. (Use REINDEX to update closed indexes.)

Space in .DBT memo files associated with deleted records is not reduced, however, when you use the PACK command. To reclaim space in a memo file, you need to use COPY to copy the original table.

Use PACK with caution. Records that have been marked for deletion but not yet eliminated with PACK can be undeleted and restored to a table using RECALL. Records eliminated with PACK are permanently lost and cannot be recovered.

SET DELETED ON provides many of the benefits of PACK without actually removing records from a table. With SET DELETED ON, most commands function as if records marked for deletion had been eliminated from a table.

To permanently remove all records of the current table in one step, use the ZAP command.


PACK Example

The following example creates a form with an entry field for entering a State_Prov code and a pushbutton that calls a procedure that uses PACK to permanently delete marked records from the file TEMP.DBF:

* Main Program
SET SAFETY OFF
USE Clients
COPY TO Temp
USE Temp EXCLUSIVE
PUBLIC mState
mState="   "                 && Three Spaces
DO Cleanup
* End Main Program

PROCEDURE Cleanup
SET PROCEDURE TO PROGRAM(1) ADDITIVE
DEFINE FORM Pack FROM 2,2 TO 10,40
DEFINE ENTRYFIELD State OF Pack AT 2, 15;
  PROPERTY Datalink "mState"
DEFINE TEXT State2 OF Pack AT 4, 6;
  PROPERTY Text "Enter State_Prov Code",;
  Width 40
DEFINE PUSHBUTTON Exit OF Pack AT 6, 13;
  PROPERTY;
    TEXT  "Pack",;
    OnClick GetRid,;
    Width 9
OPEN FORM Pack

* Procedure for Pushbutton
PROCEDURE GetRid
CLOSE FORMS Pack
DELETE FOR State_Prov = UPPER(mState)
PACK
COUNT FOR State_Prov= UPPER(mState) TO Check
IF Check = 0
  ? "Pack was successful."
ENDIF
RETURN


See Also

DELETE

RECALL

SET DELETED

ZAP


PAD( )

See Also	Example	Portability	dBASE IV Menus

Returns the name of the currently selected (highlighted) or most recently chosen pad in a dBASE IV menu bar. This command is supported primarily for compatibility with dBASE IV. In dBASE for Windows, use INSPECT( ) to return information associated with objects in forms.

Syntax

PAD( )

Description

Use PAD( ) to determine the name of the currently selected (highlighted) or most recently chosen pad in a dBASE IV menu bar; such pads are created with DEFINE PAD.


PAD( ) Example

For an example using PAD( ), see MENU( ).


Portability

Not supported in dBASE III PLUS.


See Also

DEFINE

DEFINE PAD

INSPECT( )


PADPROMPT( )

See Also	Example	Portability	dBASE IV Menus

Returns the prompt of the currently selected (highlighted) or most recently chosen pad in a dBASE IV menu bar. This command is supported primarily for compatibility with dBASE IV. In dBASE for Windows, use INSPECT( ) to return information associated with objects in forms.

Syntax

PADPROMPT(<pad name> [, <menu name>])

<pad name>

The menu name of the pad.

<menu name>

The menu bar in which the pad is displayed.

Description

PADPROMPT( ) returns the prompt the currently selected (highlighted) or most recently chosen pad; such pads are defined with DEFINE PAD.


PADPROMPT( ) Example

The following example uses PADPROMPT( ) to return the text that appears as the prompt when Pad1 is selected.

DEFINE MENU Mymen
DEFINE PAD Pad1 OF Mymen PROMPT "Print"
DEFINE PAD Pad2 OF Mymen PROMPT "Exit "
ON SELECTION PAD Pad1 OF Mymen DO Res
ON SELECTION PAD Pad2 OF Mymen DO Done
ACTIVATE MENU Mymen

*On selection of Pad1, this procedure is executed
PROCEDURE Res
  ? PADPROMPT("Pad1","Mymen")  && Returns "PRINT"
  WAIT ''                      && Pause
RETURN

*On selection of PAD2, this procedure is executed
PROCEDURE Done
  DEACTIVATE MENU              && Close the menu
  RELEASE MENU Mymen           && Release from memory
RETURN


Portability

Not supported in dBASE III PLUS.


See Also

DEFINE

DEFINE PAD

INSPECT( )


PARAMETERS

Programs

Assigns variable names to data passed from a calling program. This command is included primarily for compatibility with prior versions of dBASE, where using PARAMETERS was the only way to assign variable names in procedures. In dBASE for Windows, you should assign variable names by including them in parentheses after a PROCEDURE statement because this makes them local in scope. For more information, see PROCEDURE.


PAYMENT( )

See Also	Example	Portability	Numeric Data

Returns the periodic amount required to repay a debt.

Syntax

PAYMENT(<principal expN>, <interest expN>, <term expN>)

<principal expN>

The original amount to be repaid over time.

<interest expN>

The interest rate per period expressed as a positive decimal number. Specify the interest rate in the same time increment as the term.

<term expN>

The number of payments. Specify the term in the same time increment as the interest.

Description

Use PAYMENT( ) to calculate the periodic amount (payment) required to repay a loan or investment of <principal expN> amount in <term expN> payments. PAYMENT( ) returns a float based on a fixed interest rate compounding over a fixed length of time.

If <principal expN> is positive, PAYMENT( ) returns a positive number. If <principal expN> is negative, PAYMENT( ) returns a negative number.

Express the interest rate as a decimal. For example, if the annual interest rate is 9.5%, <interest expN> is .095 (9.5/100) for payments made annually.

Express <interest expN> and <term expN> in the same time increment. For example, if the payments are monthly, express the interest rate per month, and the number of payments in months. You would express an annual interest rate of 9.5%, for example, as .095/12, which is 9.5/100 divided by 12 months.

The formula dBASE uses to calculate PAYMENT( ) is as follows:

                           term
              int*(1 + int)^
pmt = princ * -------------------
                       term
              (1 + int)^    -  1

where int = rate / 100

For the monthly payment required to repay a principal amount of $16860.68 in five years, at 9% interest, the formula expressed as a dBASE expression looks like this:

? PAYMENT(16860.68,.09/12,60)       && Returns 350.00
nTemp = (1 + .09/12)^60
? 16860.68*(.09/12*nTemp)/(nTemp-1) && Returns 350.00

Use SET DECIMALS to set the number of decimal places PAYMENT( ) displays.


PAYMENT( ) Example

The following example creates a form for user entered mortgage loan information and uses PAYMENT( ) to calculate monthly loan payments:

LOCAL f
f=NEW Mortgage()
f.OPEN()
CLASS Mortgage OF FORM
  this.Top=5
  this.Left=50
  this.Width=55
  this.Height=13
  this.Text="Dewey's Loans"
  DEFINE TEXT Txt1 OF THIS AT 2, 5;
    PROPERTY Text "What is the principal?",;
    Width 26, ColorNormal "RB/W"
  DEFINE ENTRYFIELD Princ OF THIS AT 2,35;
    PROPERTY Value 0, ;
    Width 7
  DEFINE TEXT Txt2 OF THIS AT 4, 5;
    PROPERTY Text "What is the interest rate?",;
    Width 35, ColorNormal "RB/W"
  DEFINE ENTRYFIELD Int OF THIS AT 4,35 ;
    PROPERTY Value 0, Picture "99.99",;
    Width 8
  DEFINE TEXT Txt3 OF THIS AT 6,5;
    PROPERTY Text "What is the number of payments?",;
    Width 50, ColorNormal "RB/W"
  DEFINE ENTRYFIELD Pay OF THIS AT 6,45 ;
    PROPERTY Value 0, Picture "999",;
    Width 8
  DEFINE PUSHBUTTON Results OF THIS AT 10,18;
    PROPERTY Text "Payment",;
    OnClick {;myResult="Your payment will be: $" + ;
    LTRIM(STR(PAYMENT(Form.Princ.Value,;
    (Form.Int.Value/100)/12,Form.Pay.Value),13,2));
    ; Form.FV.Text = MyResult},;
    Height 2, ColorNormal "N/W", Width 15
  DEFINE TEXT FV OF THIS AT 8,8;
    PROPERTY Text "Your payment: ", Width 40,;
    ColorNormal "R+/W"
ENDCLASS


Portability

Not supported in dBASE III PLUS.


See Also

FV( )

PV( )

SET DECIMALS


PCOL( )

See Also	Example	Printing

Returns the printing column position of a printer. Column numbers begin at 0.

Syntax

PCOL( )

Description

Use PCOL( ) to determine the horizontal printing position of a printer--that is, the column at which the printer is set to begin printing. Use PCOL( ) in mathematical statements to direct the printer to begin printing at a position relative to its current column position. For example, PCOL( ) + 5 represents a position five columns to the right of the current position, and PCOL( ) - 5 represents a position five columns to the left of the current position.

When you direct output to the printer, dBASE maps each character according to the coordinate plane, a two-dimensional grid. The coordinate plane is divided into character cells whose widths depend on the value of _ppitch. See the table in the description of _ppitch, which lists _ppitch values. The height of each character cell is determined by the size of the font of the parent form window. For more information about the coordinate plane, see Chapter 16 in the Programmer's Guide.

PCOL( ) returns a column number that reflects the current value of _ppitch, regardless of whether you are printing with proportional or monospaced fonts. If you are printing with a proportional font, you can add and subtract fractional numbers to and from the PCOL( ) value to move the printing position accurately. If you issue ? without the STYLE option and use only integer coordinates, dBASE uses a monospaced font and all output should appear exactly the same as in dBASE IV.

SET PRINTER must be ON or SET DEVICE TO PRINTER must be in effect for PCOL( ) to return a column position; otherwise, it returns 0.


PCOL( ) Example

The following example writes "Jack & Jill" to the printer. It uses PCOL( ) to note the column position three times, at the beginning, after "Jack", and after "Jill":

SET TALK OFF
SET PRINTER ON
* now ?s are directed to printer
?          && sets printer at col 0 of next line
beginpos=pcol()  && note the current column
?? "Jack"
lastjackpos=pcol()
?? " & Jill"
lastjillpos=pcol()
SET PRINTER OFF
CLOSE PRINTER
? beginpos       &&  0.00
? lastjackpos    &&  4.00
? lastjillpos    && 11.00
SET TALK ON


See Also

COL( )

PROW( )

SET DEVICE

SET PCOL

SET PRINTER


PCOUNT( )

See Also	Example	Portability	Programs

Returns the number of parameters passed by a calling command to the called program, procedure, or user-defined function (UDF).

Syntax

PCOUNT( )

Description

Because you can pass a program, procedure, or UDF more or fewer parameters than the PARAMETERS <parameter list> statement specifies, you can use PCOUNT( ) to determine exactly how many parameters have been passed.

PCOUNT( ) returns 0 if no parameters are passed.


PCOUNT( ) Example

The following example uses PCOUNT( ) to determine the number of parameters passed to a procedure.

Param1 = 'Hello'
Param2 = 100
DO MyProg WITH Param1, Param2

PROCEDURE MyProg
PARAMETERS Par1, Pr2, Pr3, Pr4
? 'You passed ' + LTRIM(STR(PCOUNT())) + ;
" parameters to this procedure."
RETURN


Portability

PCOUNT( ) is not supported in dBASE III PLUS.


See Also

DO

FUNCTION

PARAMETERS

PROCEDURE

SET PROCEDURE


PI( )

See Also	Example	Portability	Numeric Data

Returns the approximate value of pi, the ratio of a circle's circumference to its diameter.

Syntax

PI( )

Description

PI( ) returns a float that is approximately 3.141592653589793. pi is a constant. Use it to measure the area and circumference of a circle or the volume of a cone or cylinder. For example, use it in the trigonometric functions SIN( ), COS( ), and TAN( ), which require the angle value in radians. pi radians is equivalent to 180 degrees.

Use SET DECIMALS to set the number of decimal places PI( ) displays.


PI( ) Example

The following example uses PI( ) in a program to determine geometric dimensions of a hot tub:

SET TALK OFF
CLEAR
width = 0
depth = 0
@ 12,12 SAY "Enter the width of your hottub " ;
   GET width PICTURE "99"
@ 13,12 SAY ;
   "What is the depth of the hottub" ;
   GET depth PICTURE "99"
READ
@ 15,12 SAY "The hottub has a circumference of " + ;
   LTRIM(STR((2 * PI() * width/2))) + " feet"
@ 16,12 SAY "The hottub has a volume of " + ;
   STR(PI() * ((width/2)^2) * depth,5,2) + ;
   " cubic feet"
@ 17,12 SAY "The hottub is " + ;
   STR(PI() * ((width/2)^2),5,2) + ;
   " feet in area"


Portability

Not supported in dBASE III PLUS. In dBASE IV, PI( ) returns a value accurate only to 14 decimal places, regardless of the value of SET DECIMALS.


See Also

COS( )

DTOR( )

RTOD( )

SET DECIMALS

SIN( )

TAN( )


PLAY SOUND

See Also	Example	Portability	Objects

Plays a sound stored in a .WAV file or a binary field.

Syntax

PLAY SOUND
FILENAME
<filename> | ? | <filename skeleton> |
BINARY <binary field>

FILENAME <filename> | ? | <filename skeleton> |
BINARY <binary field>

Specifies the sound file or binary field. PLAY SOUND FILENAME ? and PLAY SOUND FILENAME <filename skeleton> display a window that lets the user select a sound file. <filename> is the name of a sound file; PLAY SOUND assumes a .WAV extension unless you specify otherwise. If you specify a file without including its path, dBASE looks for the file in the current directory, then in the path you specify with SET PATH. PLAY SOUND BINARY <binary field> plays the sound stored in a binary field.

Description

Use PLAY SOUND to play sounds you record with the Windows Sound Recorder or other sound applications developed for Windows. These sounds may include music, speech, or any other sounds stored in binary fields or in .WAV files.

Note:	To play a sound, your system must have a sound driver or a sound adapter board.


PLAY SOUND Example

The following example uses PLAY SOUND in a codeblock of an OnClick property of pushbutton Sound to play a sound stored in a binary field:

LOCAL f
f = NEW BFORM()
f.Open()

CLASS BFORM OF FORM
   this.HelpFile = ""
   this.Width =         63.40
   this.Maximize = .F.
   this.Minimize = .F.
   this.Height =         12.76
   this.Left =         35.00
   this.Text = "Pictures Form"
   this.Top =          5.65
   this.ColorNormal = "BG/B"
   this.OnOpen = {;create session}
   this.View = "PICTURES.QBE"
   this.HelpId = ""

   DEFINE PUSHBUTTON SOUND OF THIS;
       PROPERTY;
         Width         18.00,;
         Default .T.,;
         OnClick {;PLAY SOUND Binary Pictures->Sound},;
         Height          3.00,;
         Left         22.00,;
         Text "Sound",;
         Top          4.00,;
         ColorNormal "N/W",;
         FontName "Courier",;
         FontSize         16.00

ENDCLASS


Portability

Not supported in dBASE IV or dBASE III PLUS.


See Also

SET PATH


POPUP( )

See Also	Example	Portability	dBASE IV Menus

Returns the name of the current dBASE IV pop-up menu. This command is supported primarily for compatibility with dBASE IV. In dBASE for Windows, use INSPECT( ) to return information associated with objects in forms.

Syntax

POPUP( )

Description

POPUP( ) returns the name of a pop-up menu created with DEFINE POPUP.


POPUP( ) Example

The following example uses POPUP( ) to determine which pop-up menu on a menu bar was selected for branching to the correct table or procedure:

DEFINE MENU Choices;
    MESSAGE "Choose a table;
    Press Esc to return to main menu"
DEFINE PAD CliPad OF Choices;
    PROMPT "Clients" AT 3,2
DEFINE PAD CompPad OF Choices;
    PROMPT "Company" AT 3,20
DEFINE PAD CtcPad OF Choices;
    PROMPT "Contacts" AT 3,40
DEFINE PAD Exit OF Choices;
    PROMPT "Exit Program" AT 3,60

DEFINE POPUP CliPop FROM 5,2
DEFINE BAR 1 OF CliPop PROMPT "Add Records"
DEFINE BAR 2 OF CliPop PROMPT "Browse"

DEFINE POPUP CompPop FROM 5,20
DEFINE BAR 1 OF CompPop PROMPT "Add Records"
DEFINE BAR 2 OF CompPop PROMPT "Browse"

DEFINE POPUP CtcPop FROM 5,40
DEFINE BAR 1 OF CtcPop PROMPT "Add Records"
DEFINE BAR 2 OF CtcPop PROMPT "Browse"

ON SELECTION PAD CliPad OF Choices;
    ACTIVATE POPUP CliPop
ON SELECTION PAD CompPad OF Choices;
    ACTIVATE POPUP CompPop
ON SELECTION PAD CtcPad OF Choices;
    ACTIVATE POPUP CtcPop
ON SELECTION PAD Exit OF Choices;
    DO Cleanup

CLEAR
ON SELECTION POPUP ALL DO Proceed
ACTIVATE MENU Choices

* Procedure Proceed
PROCEDURE Proceed
DO CASE
  CASE POPUP() = "CLIPOP"
    USE Clients ORDER Company
      IF BAR()=1
        APPEND
      ELSE
        BROWSE
      ENDIF
  CASE POPUP()="COMPPOP"
    USE Company ORDER Company
      IF BAR()=1
        APPEND
      ELSE
        BROWSE
      ENDIF
  CASE POPUP()="CTCPOP"
    USE Contact ORDER Contact
      IF BAR()=1
        APPEND
      ELSE
        BROWSE
      ENDIF
  ENDCASE
  RETURN

* Procedure Cleanup
PROCEDURE Cleanup
RELEASE POPUPS CliPop, CompPop, CtcPop
DEACTIVATE MENU
CLEAR MENUS
CLOSE DATABASES
RETURN


Portability

Not supported in dBASE III PLUS.


See Also

DEFINE

INSPECT( )


PRINTJOB...ENDPRINTJOB

See Also	Example	Portability	Printing

Uses the values stored in system memory variables to control a printing operation.

Syntax

PRINTJOB
<statements>
ENDPRINTJOB

<statements>

Any valid dBASE statements..

Description

Use PRINTJOB...ENDPRINTJOB to control a printing operation with the values of the system memory variables _pbpage, _pepage, _pcopies, _peject, and _plineno. When dBASE begins executing PRINTJOB, it does the following:

Closes the current print document (if any) and begins a new one, as if you had issued CLOSE PRINTER before issuing PRINTJOB

Ejects a page if _peject is set to "BEFORE" or "BOTH"

Sets _pcolno to 0

When dBASE reaches ENDPRINTJOB, it does the following:

Ejects a page if _peject is set to "AFTER" or "BOTH"

Resets _pcolno to 0

Before using PRINTJOB...ENDPRINTJOB, set the relevant system memory variables and issue SET PRINTER ON. After ENDPRINTJOB, use CLOSE PRINTER to close and print the document.


PRINTJOB...ENDPRINTJOB Example

The following example uses PRINTJOB to print one line of text making three copies:

_pcopies=3         && 3 copies
_peject="none"     && no page eject before or after
_plineno=0         && initialized to 0
SET PRINTER ON
PRINTJOB
? "A one line print job"
?
ENDPRINTJOB
CLOSE PRINTER      && initiate printing
* prints:
* A one line print job
*
* A one line print job
*
* A one line print job
*


Portability

Not supported in dBASE III PLUS.


See Also

_pbpage

_pcopies

_peject

_pepage

_plineno

EJECT

EJECT PAGE

ON PAGE

SET PRINTER


PRINTSTATUS( )

See Also	Example	Portability	Printing

Returns true (.T.) if the print device is ready to accept output.

Syntax

PRINTSTATUS([<port name expC>])

<port name expC>

A character expression such as "LPT1" that identifies the printer port to check. Valid port names include all designations that the Windows Control Panel recognizes.

Description

Use PRINTSTATUS( ) to determine whether you have designated a printer port as an output device with SET PRINTER TO <port name expC>. In dBASE, the Windows Print Manager spools print output to and manages the printer port. Therefore, the Print Manager informs you when a printer is not ready to receive output.

If you do not pass <port name expC> to PRINTSTATUS( ), it checks the default port you specified with SET PRINTER TO. PRINTSTATUS( ) returns only .F. if you haven't specified a printer port with SET PRINTER TO or if the port you specify has not been set with SET PRINTER TO.

Note:	dBASE automatically executes SET PRINTER TO on startup if the WIN.INI file contains a valid printer definition. See your Windows documentation for information on WIN.INI settings.


PRINTSTATUS( ) Example

This example reads the default PRINTSTATUS and then queries LPT1, LPT2 and LPT3:

? PRINTSTATUS()
? PRINTSTATUS("LPT1")
? PRINTSTATUS("LPT2")
? PRINTSTATUS("LPT3")


Portability

Not supported in dBASE III PLUS.


See Also

CLOSE...

SET DEVICE

SET PRINTER


PRIVATE

See Also	Example	Portability	Memory Variables

Declares memory variables that you can use in the program where they are declared and in all subroutines the program calls. PRIVATE is supported primarily for compatibility with dBASE IV. In dBASE for Windows, declaring variables LOCAL is recommended.

Syntax

PRIVATE <memvar list> |
ALL
[LIKE <memvar skeleton 1>]
[EXCEPT <memvar skeleton 2>]

<memvar list>

The list of memory variables you want to declare private, separated by commas.

ALL

Makes private all memory variables declared in the subroutine.

LIKE <memvar skeleton 1>

Makes private the memory variables whose names are like the memory variable skeleton you specify for <memvar skeleton 1>. Use characters of the variable names and the wildcards * and ? to create <memvar skeleton 1>.

EXCEPT <memvar skeleton 2>

Makes private all memory variables except those whose names are like the memory variable skeleton you specify for <memvar skeleton 2>. Use characters of the variable names and the wildcards * and ? to create <memvar skeleton 2>. You can use LIKE and EXCEPT in the same statement, for example, PRIVATE ALL LIKE mvar* EXCEPT mvarnum*.

Description

Use PRIVATE to declare a memory variable in a subroutine private to that subroutine and its subroutines, and therefore inaccessible to higher-level routines in the call chain. To declare a variable PRIVATE, do so before initializing it to a particular value. Declaring a variable PRIVATE, however, does not create it. After declaring a variable private, you can create and initialize it to a value with STORE, =, or DECLARE.

A private variable is inaccessible to routines above it in the calling chain. In this way, a private variable is protected from having its value changed by routines above it in the calling chain that have variables with the same name. A variable that is private to a subroutine is in effect a different variable from one with the same name in a higher-level or unrelated routine. Once a private variable is assigned a value, DISPLAY MEMORY and LIST MEMORY indicate a variable of the same name in a higher-level subroutine as hidden.

By default, variables you initialize in programs are private. However, if you initialize a variable that has the same name as a variable declared PUBLIC in an earlier subroutine or in the Command window, and don't declare the variable PRIVATE, it not created as a private variable. Instead, the subroutine uses and alters the value of the existing public variable.

A private variable is not protected from alteration by a lower-level subroutine that has a variable with the same name. If a lower-level subroutine stores to or alters a variable that has the same name as one to which data has been stored at a higher level, the higher-level variable is accessed, and its data overwritten.

To prevent this from happening--to have dBASE in effect consider the same-named variables to be two different variables--declare the variable PRIVATE in the lower-level subroutine (or define variables as LOCAL). If you want the lower-level subroutine to have access to the value of the variable but not be able to send back an altered value, include it in parentheses in the DO...WITH statement.

Private variables are erased from memory when the subroutine that creates them finishes executing.

For more information, see PUBLIC for a table that compares the scope and availability of public, private, local, and static variables.


PRIVATE Example

The following example branches from a main program to several lower-level procedures to demonstrate that a variable declared PRIVATE in Level_2 is available in all procedures below the level on which it is declared, but that it is not accessible once the program returns to the main program level:

* **Main.Prg***
CLOSE ALL
CLEAR ALL
CLEAR
SET TALK OFF
? "**Main.PRG**"
STATIC nTotal
PUBLIC cString
nTotal = 7109.50
cString= "Hello"
ON ERROR ? "Var not available";
                      && Displays message on error
? nTotal              && Returns 7109.50
? cString             && Returns "Hello"
DO Level_2            && Branch to Proc Level_2
?
? "**Back to Main.PRG**"
? Deadline          && "Var not available" above ;
                         Proc Level_2

PROCEDURE Level_2
?
? "**Proc Level_2**"  && Orientation only
PRIVATE Deadline      && Var declared Private in;
                         Procedure Level_2
? Deadline            && "Var not available"-not ;
                         yet initialized
Deadline = {12/31/99} && Initialize variable
? Deadline            && Now it has a value
DO Level_3            && Branch to Level3
?
? "**Back to Level_2**"
? Deadline            && 12/31/99 still available
RETURN                && Return to line after ;
                         DO Level_2 in Main

PROCEDURE Level_3
?
? "**Proc Level_3**"  && Orientation only
? cString             && "Hello" is Public
? nTotal              && "Var not available"-Static ;
                         in Main
? Deadline            && 12/31/99 available in;
                         Procs below Level_2
Do Level_4            && Branch to Level_4
?
? "**Back to Level_3**"
? Deadline            && 12/31/99 Still available
RETURN                && Return to line after ;
                         DO Level_3 in Level_2

PROCEDURE Level_4
?
? "**Proc Level_4**"  && Orientation only
? nTotal              && "Var not available-Static;
                         in Main
? cString             && "Hello" - Public variable
? Deadline            && 12/31/99 still available;
                         in Procs below Level_2
RETURN                && Return to line after ;
                         DO Level_4 in Level_3


Portability

dBASE IV and dBASE III PLUS do not support both LIKE and EXCEPT in the same PRIVATE statement.


See Also

CLEAR MEMORY

DECLARE

LOCAL

PUBLIC

STATIC

STORE


PROCEDURE

See Also	Example	Portability	Programs

Defines a procedure in a program file and optionally declares memory variables to represent parameters passed to the procedure.

Syntax

PROCEDURE <procedure name> [(<parameter list>)]
[<statements>]
[RETURN [<return exp>]]

<procedure name>

The name of the procedure. Although dBASE imposes no limit to the length of procedure names, it recognizes only the first 32 characters. Procedure names can contain letters, numbers, and underscores.

(<parameter list>)

Memory variable names to assign to data items (or parameters) passed to the procedure by the statement that called it. The variables in <parameter list> are local in scope, protecting them from modification in lower-level subroutines. For more information about the local scope, see LOCAL.

The number of variables assigned can be different from the number of parameters passed. You can use PCOUNT( ) to identify the number of parameters a procedure has received. You can include up to 255 variable names in <parameter list>.

Note:	Procedures written in prior versions of dBASE might contain variable names that were declared using the PARAMETERS statement. This use is supported in dBASE for Windows for backward compatibility, but is not recommended because it scopes the variables as private instead of local. Variables scoped as private may inadvertently be overwritten if a subroutine the procedure calls uses a variable with the same name. For more information about the private scope, see PRIVATE.

<statements>

Any valid program statements that you want the procedure to execute. This can include assignment statements, commands, procedure calls, dBASE function calls, and other procedure calls. You can call procedures recursively.

RETURN [<return exp>]

Returns program control and supplies the value defined by <return exp> to the calling statement. If you do not include RETURN, the procedure ends when it encounters another PROCEDURE statement, a CLASS statement, a FUNCTION statement, or the end of the file. If you plan to use the value returned by the procedure, as in ? MyProc( ), you must include RETURN <return exp>.

Description

Use PROCEDURE to define a program subroutine that carries out certain commands and optionally returns a value. With procedures, you can extend the dBASE language to perform a wide range of functions that meet particular needs in your applications. You also create more modular code, which is easier to debug and maintain.

For example, if there are several places in your application where you want to perform certain tasks, include them in a procedure, as shown in the following example. In this case, each time you want to skip a record and go to the top of the file on encountering EOF, you would issue DO NextRecOrTop.

PROCEDURE NextRecOrTop
SKIP&& go to the next record if possible
IF EOF()&& if reach end-of-file
   GO TOP&& go to first record in the table
ENDIF
RETURN

Issue PROCEDURE only in a program file (.PRG or .WFM).You cannot nest procedures, or begin a procedure within a processing loop defined with IF, SCAN, etc.

You call a procedure with DO or with the call operator (parentheses), as shown in the following example.

** Two ways to call the same procedure
x = 100
DO FirstProc WITH x
? x               && returns 200
x = 100
? Firstproc(x)    && returns 200

PROCEDURE FirstProc(mvar)
mvar = mvar * 2
RETURN mvar

Using parameters

Use parameters to exchange values or references between one subroutine and a subroutine it calls. For example, if you regularly need to return a date 30 days from another date, you can create a procedure to calculate and return this value using the first date as a parameter you send to the procedure. The called procedure creates a local variable name representing the value of the parameter you send, performs the calculation, and returns the value representing a date 30 days later.

This is shown in the following example. Each time you need to add 30 days to a date, call Thirty( ) with the date as a parameter. In the example, begindate is the name the called procedure assigns to the parameter.

SET DATE AMERICAN
dStartDate = {03/12/95}
? Thirty(dStartDate)  && returns the value in enddate

PROCEDURE Thirty(begindate)
*begindate is the variable name assigned to
* the value in dStartDate
enddate = begindate + 30
RETURN enddate

You can pass memory variables, properties, array names and array elements, fields, literals, or expressions as parameters to procedures.

Passing memory variables and properties

There are two ways to pass memory variables and properties, by reference or by value. This section uses the term "memory variable" to refer to both memory variables and properties.

If you pass memory variables by reference, the called procedure has direct access to the variable. Its actions can change (overwrite) the value in that variable. Pass variables by reference if you want the called procedure to manipulate the values stored in the memory variables it receives as parameters.

If you pass memory variables by value, the called procedure has access only to the value contained in the variable. Its actions cannot change the contents of the variable itself. Pass variables by value if you want to the called procedure to use the values in the variables in its calculations without changing their values in the calling subroutine. To pass a memory variable by value, enclose it in parentheses when you pass it.

The following example shows the differences between passing a memory variable by reference and by value.

X=10
? X                 && X = 10
Do MyProc WITH X    && pass 10 by reference
? X                 && X now = 11 (changed by MyProc)
DO MyProc WITH (X)  && pass 11 by value
? X                 && X still = 11
                    && (unchanged by MyProc)

PROCEDURE MyProc(N) && N represents the value in X
? N          && returns 10 first time called,
             && 11 second time called
N=N+1
? N          && returns 11 first time called,
             && 12 second time called
RETURN

Field names take precedence over variable names. If a field and a variable have the same name and you want to pass the variable as a parameter, use M><memvar name> to force use of the variable. For example, if you have a field named CustNo and a variable named CustNo, to pass the variable to the procedure ShowCust, use the following command:

DO ShowCust WITH M->CustNo

Passing arrays

If you use an array as a parameter, you can pass either the entire array, by passing only the array name, or individual elements of the array.

Passing an entire array or an element of an array works the same as passing a memory variable.

If you pass the array name without parentheses, you are making a pass by reference. The called subroutine can change values in the array.

If you enclose the array name in parentheses when you pass it, you are making a pass by value. The called subroutine cannot change values in the array.

When you pass an array element, it is always passed by reference, even if you enclose it in parentheses. The called subroutine can change values in the array.

Passing fields

In contrast to memory variables, fields passed as parameters cannot be changed by a subroutine. Fields are always passed by value, so the called procedure cannot change their contents.

If you want to alter a field, store its contents to a memory variable and then execute the subroutine with that variable (for example, DO Namechg WITH cNewname). When control returns to the calling program, replace the field contents with the memory variable contents (for example, REPLACE Fname WITH cNewname).

Making procedures available

You can include a procedure in the program file that uses it, or place it in a separate program file you access with SET PROCEDURE or SET LIBRARY. If you include a procedure in the program file that uses it, you should place it at the end of the file and group it with other procedures.

A single program file can contain a total of 193 procedures. To access more than 193 procedures, use SET PROCEDURE...ADDITIVE. The maximum size of a procedure is limited to the maximum size of a program file.

If you plan to call a procedure with the DO command, as in DO ThisProcedure, do not give the procedure the same name as the program file that contains it. If you do, dBASE tries to run the program instead of the procedure, leading to unpredictable results.

If you plan to call a procedure with the call operator (parentheses), as in ThisProcedure( ), do not give the procedure the same name as a built-in dBASE function. If you do, dBASE executes its built-in function instead of the procedure.

When you call a procedure, dBASE searches for it in the search path in search order. If there is more than one procedure available with the same name, dBASE runs the first one it finds. For this reason, avoid using the same name for more than one procedure. See the description of DO for an explanation of the search path and order dBASE uses.

When you create a procedure, you can use its name to determine its address (a value of type "function pointer"). Codeblocks associated with objects are anonymous procedures. For more information on working with procedures, codeblocks, and function pointers, see Chapter 4 in the Programmer's Guide.


PROCEDURE Example

The following example calls procedures from within the main program file:

*MAIN.PRG
SET TALK OFF
CLEAR
DO A
DO B
DO C
RETURN

PROCEDURE A
@ 10,2 SAY "PROCEDURE A at the end of MAIN.PRG"
RETURN

PROCEDURE B
@ 15,2 SAY "PROCEDURE B at the end of MAIN.PRG"
RETURN

PROCEDURE C
@ 20,2 SAY "PROCEDURE C at the end of MAIN.PRG"
RETURN

The following example calls procedures from a separate procedure file:

*MAIN.PRG
SET TALK OFF
CLEAR
SET PROCEDURE TO PROCFILE
DO A
DO B
DO C
RETURN

*PROCFILE.PRG
PROCEDURE A
@ 10,2 SAY "PROCEDURE A in PROCFILE.PRG"
RETURN

PROCEDURE B
@ 15,2 SAY "PROCEDURE B in PROCFILE.PRG"
RETURN

PROCEDURE C
@ 20,2 SAY "PROCEDURE C in PROCFILE.PRG"
RETURN


Portability

In dBASE IV, you could have a procedure and a UDF (declared with FUNCTION) with the same name available at the same time, because they were called differently. In dBASE for Windows, if a procedure and a UDF of the same name are declared, the first one declared is the only one recognized.

The following table summarizes other differences in the use of PROCEDURE in dBASE III PLUS, dBASE IV, and dBASE for Windows.

	dBASE III PLUS	dBASE IV	dBASE for Windows
Maximum length of procedure name	8 characters	Unlimited, but only first 9 characters are recognized	Unlimited, but only the first 32 characters are recognized
Characters allowed in procedure name	Letters, numbers, and underscores; first character must be a letter	Letters, numbers, and underscores; first character must be either a letter or a number	Letters, numbers, and underscores
Maximum number of procedures per program file	32 (33 and above are not recognized)	963	193; use SET PROCEDURE... ADDITIVE to access more than 193
Maximum procedure size	Unlimited	65520 bytes of compiled code	same as maximum file size
Treatment of unnamed procedures	Not listed as one of the procedures in the procedure list	Listed as one of the procedures in the procedure list; by default, given the name of the program file	same as dBASE IV
Line continuation character (;)	Cannot be used to separate the PROCEDURE command and the procedure name	Can be used to separate the PROCEDURE command and the procedure name	same as dBASE IV


See Also

CLASS...ENDCLASS

CLOSE...

COMPILE

DEBUG

DO

FUNCTION

LOCAL

PCOUNT( )

PRIVATE

RETRY

RETURN

SET LIBRARY

SET PROCEDURE


PROGRAM( )

See Also	Example	Portability	Error Handling and Debugging

Returns the name of the currently executing program, procedure, or user-defined function (UDF).

Syntax

PROGRAM( [<expN>] )

<expN>

Any number.

Description

PROGRAM( ) returns the name of the lowest level executing subroutine--program, procedure, or UDF. PROGRAM( ) returns an empty string ("") when no program or subroutine is executing.

PROGRAM(expN) returns the full path name of the program that is currently running, which may be different from the name of the lowest level executing subroutine. This is shown in the following example.

SET PROCEDURE TO program1
** Inside PROGRAM1.PRG is PROCEDUREprocedure1
** If procedure1 is running, note the following:
? PROGRAM() returns PROCEDURE1
? PROGRAM(expN) returns C:\DBASEWIN\PROGRAM1.PRG.

You can issue PROGRAM( ) in the Command window if a program is suspended with SUSPEND. For example, if Program A calls Procedure B, and Procedure B is suspended, issuing PROGRAM( ) in the Command window returns the name of Procedure B; issuing PROGRAM(expN) in the Command window returns the full path name of the file containing Procedure B.

You can also use PROGRAM( ) with ON ERROR and LINENO( ) to identify the subroutine that was executing and the exact program line number at which the error occurred.

PROGRAM( ) returns the name of the subroutine in uppercase letters. PROGRAM( ) does not include a file-name extension even if the subroutine is a separate file, while PROGRAM(expN) always includes a file-name extension.


PROGRAM( ) Example

See the example of ON ERROR for an example of PROGRAM( ).


Portability

Not supported in dBASE III PLUS.


See Also

DEBUG

LINENO( )

ON ERROR

PROCEDURE

RESUME

SET PROCEDURE

SUSPEND


PROMPT( )

See Also	Example	Portability	dBASE IV Menus

Returns the prompt of the currently selected (highlighted) or most recently chosen menu item. This command is supported primarily for compatibility with dBASE IV. In dBASE for Windows, use INSPECT( ) to return information associated with objects in forms.

Syntax

PROMPT( )

Description

PROMPT( ) returns the prompt of a menu, a menu item, or a dBASE IV menu bar. It returns the currently selected item, if one is selected, or the most recently chosen item, if none is currently selected.


PROMPT( ) Example

The following example uses PROMPT( ) to return the string displayed in each bar so that it can be concatenated with another pre-defined string tailored for each bar and displayed as a message:

DEFINE POPUP Mypop FROM 2,2
DEFINE BAR 1 OF Mypop PROMPT " John "
DEFINE BAR 2 OF Mypop PROMPT " Mary "
ON BAR 1 OF Mypop SET MESSAGE TO PROMPT()+"is male"
ON BAR 2 OF Mypop SET MESSAGE TO PROMPT()+"is female"
ON SELECTION POPUP Mypop DEACTIVATE POPUP
ACTIVATE POPUP Mypop


Portability

Not supported in dBASE III PLUS.


See Also

DEFINE

INSPECT( )


PROPER( )

See Also	Example	Portability	String Data

Converts a character string to proper-noun format and returns the resulting string.

Syntax

PROPER(<expC> | <memo field>)

<expC> | <memo field>

The character string or memo field to convert to proper-noun format.

Description

PROPER( ) returns a string where the first character of each word in a character expression or memo field is capitalized and the remaining letters are lowercase. PROPER( ) changes the first character of a word only if it is a lowercase alphabetic character. PROPER( ) returns a maximum of 32766 characters, the maximum length of a string.

The current language driver defines the character values that are lowercase and uppercase alphabetic. In a U.S. language driver, a lowercase alphabetic character is from a to z, and an uppercase alphabetic character is from A to Z. See Appendix C in the Programmer's Guide for more information about language drivers.


PROPER( ) Example

The following example uses PROPER( ) to create consistent capitalization of text strings:

? PROPER("e. b. white")    && Returns "E. B. White"
? PROPER("e.b. white")     && Returns "E.b. White"
? PROPER("4-WINDS MUSIC")  && Returns "4-winds Music"
? PROPER("")               && Returns ""

When character field data is entered in all uppercase, you might want to permanently convert the field contents to upper- and lowercase. The following example replaces all uppercase company names in the Company table with the first letter of each word in uppercase and the remainder of each word in lowercase:

USE COMPANY
REPLACE ALL Company with PROPER(Company)

PROPER( ) also works with memo fields. The next example displays the contents of all memo fields in the Contact table and uses PROPER( ) to convert all first letters of strings to uppercase:

USE Contact
SCAN
? PROPER(Notes)
?
ENDSCAN
RETURN


Portability

Not supported in dBASE IV or dBASE III PLUS.


See Also

LDRIVER( )

LOWER( )

SET LDCHECK

UPPER( )


PROW( )

See Also	Example	Printing

Returns the printing row position of a printer. Row numbers begin at 0.

Syntax

PROW( )

Description

Use PROW( ) to determine the vertical printing position of a printer--that is, the row at which the printer is set to begin printing. Use PROW( ) in mathematical statements to direct the printer to begin printing at a position relative to its current row position. For example, PROW( ) + 5 represents a position five rows below the current position and PROW( ) - 5 represents a position five rows above the current position.

When you direct output to the printer, dBASE maps each character according to the coordinate plane, a two-dimensional grid. The coordinate plane is divided into character cells whose widths depend on the value of _ppitch. See the table in the description of _ppitch, which lists _ppitch values. The height of each character cell is determined by the size of the font of the parent form window. For more information about the coordinate plane, see Chapter 16 in the Programmer's Guide.

If you are printing with a proportional font, you can add and subtract fractional numbers to and from the PROW( ) value to move the printing position accurately. If you issue ? without the STYLE option and use only integer coordinates, dBASE uses a monospaced font, and all output appears exactly the same as in dBASE IV.

SET PRINTER must be ON or SET DEVICE TO PRINTER must be in effect for PROW( ) to return a row position; otherwise, it returns 0.


PROW( ) Example

This example reads the current row from PROW( ) and writes "hello" two rows down and some results on the line below it:

SET TALK OFF
SET DEVICE TO PRINTER
EJECT   && prow() is now zero
Beginrow=prow()
@ prow()+2,0 SAY "Hello"
* prow() is now beginrow+2
*   because of the @SAY command
Hellorow=prow()
@ prow()+1,0 SAY "Begin row="    && move to next row
@ prow(),pcol() SAY Beginrow     && 0.00
@ prow(),pcol() SAY " Hello row="
@ prow(),pcol() SAY Hellorow     && 2.00
@ prow(),pcol() SAY " Prow()="
@ prow(),pcol() SAY prow()       && 3.00
SET DEVICE TO SCREEN  && reset device
CLOSE PRINTER         && Initiates the printout


See Also

PCOL( )

ROW( )

SET PROW


PUBLIC

See Also	Example	Portability	Memory Variables

Declares global memory variables or arrays that you can use and change in any dBASE program or subroutine, or in the Command window.

Syntax

PUBLIC <memvar list> |
ARRAY <array name 1>"["<expN list 1>"]"
[, <array name 2>"["<expN list 2>"]"...]

Brackets ([ ]) in double quotation marks are required syntax components.

<memvar list>

The memory variables to make public.

ARRAY <array name 1>[<expN list 1>], <array name 2>[<expN list 2>] ...

The array variable(s)--<array name 1>, <array name 2>, and so on--and array element(s) of each array--<expN list 1>, <expN list 2>, and so on--to make public.

Description

Use PUBLIC to declare a memory variable, including array variables, in a subroutine accessible to higher-level and lower-level routines in a program and to the Command window.

When control passes from a subroutine--a program, procedure, or user-defined function (UDF)--to the higher-level calling routine--a program, procedure, UDF, or the Command window--dBASE normally clears from memory any variables the subroutine initialized. Declaring a variable PUBLIC prevents that variable from being cleared when control passes to the higher-level routine.

To declare a variable PUBLIC, do so before initializing it to a particular value. Declaring a variable PUBLIC creates it and initializes it to .F.

By default, variables you initialize in the Command window are public, and those you initialize in programs are private. The following table compares the characteristics of variables declared PUBLIC, PRIVATE, LOCAL and STATIC in a subroutine called CreateVar.

	PUBLIC	PRIVATE	LOCAL	STATIC
Created when it is declared and initialized to a value of .F.	Y	N	N	Y
Can be used and changed in CreateVar	Y	Y	Y	Y
Can be used and changed in lower-level subroutines called by CreateVar	Y	Y	N	N
Can be used and changed in higher-level subroutines that call CreateVar	Y	N	N	N
Automatically released when CreateVar ends	N	Y	Y	N
By default, when you have a program suspended, dBASE assigns private status to memory variables, including arrays, that you initialize in other programs and in the Command window. When you do not have a program suspended, dBASE assigns public status to variables that you initialize in the Command window.

Declaring an array variable with PUBLIC ARRAY achieves the same result as issuing PUBLIC <array name> followed by DECLARE <array>. For example, the following first line of code achieves the same result as the following second two lines of code:

PUBLIC ARRAY Row[5]

PUBLIC Row
DECLARE row[5]


PUBLIC Example

The following example uses PUBLIC to make the variables Val,Val1,Val2 accessible throughout all called programs and procedures:

RELEASE Val,Val1,Val2
PUBLIC  Val,Val1,Val2
? Val,Val1,Val2  &&  .F.  .F.  .F.
Val=10
? Val,Val1,Val2  &&  10   .F.  .F.
DO Proc1
? Val,Val1,Val2  &&   1   11   .F.
DO Proc2
? Val,Val1,Val2  &&   2   11   22

PROCEDURE Proc1
Val = 1
Val1 = 11
RETURN

PROC Proc2
Val =  2
Val2 = 22
RETURN

If the PUBLIC statement is omitted then Val1 and Val2 will not be available in the main program because they are first used in Proc1 and Proc2. Val would be available to Proc1 and Proc2 because it is first used in the main program.


Portability

The array name argument is not supported in dBASE III PLUS.


See Also

CLEAR MEMORY

DECLARE

LOCAL

PARAMETERS

PRIVATE

RELEASE

RESTORE

SAVE

STATIC

STORE


PUTFILE( )

See Also	Example	Portability	Disk and File Utilities

Displays a dialog box within which the user can create a new file name. Returns the file name the user enters, or returns an empty string if the user chooses the Cancel button or presses Esc.

Syntax

PUTFILE([<title expC>
[, <filename expC>
[, <extension expC >
[, <filetype expL>
[, <change filetype expL>]]]]])

<title expC >

A title that is displayed at the top of the dialog box.

<filename expC >

The default file name that is displayed in the dialog box's entryfield. Without <filename expC >, PUTFILE( ) displays an empty entryfield.

<extension expC >

A default extension for the file name that PUTFILE( ) returns.

<filetype expL>

A logical value that determines whether the dialog box opens with a list of all file types (.T.) or with a list of tables in a database (.F.). The default is .T. If you want to specify a value for <filetype expL>, you must also specify a value or empty string ("") for <filename skeleton>, <title expC>, and <extension expC>.

<change filetype expL>

A logical value that determines whether the user can switch between database tables and all file types while in the dialog box (.T.) or cannot switch between file types (.F.). The default is .F. If you want to specify a value for <change filetype expL>, you must also specify a value or empty string ("") for <filename skeleton>, <title expC>, and <extension expC>, and you must specify a value for <filetype expL>.

Description

Use PUTFILE( ) to generate a new file name. Once the file name is generated, you can use it in other commands and function calls. For example, you can use PUTFILE( ) to generate a table file name, then give another file that file name with RENAME.

By default, the dialog box opened with PUTFILE( ) displays file names from the directory that was last accessed through the dialog box. Each time you use the dialog box to access a different directory, that directory serves as the default the next time the dialog box is opened.


PUTFILE( ) Example

The following examples use PUTFILE( ):

F1=PUTFILE()  && Simply opens the dialog box
F2=PUTFILE("Select a file name for this report")
* Adds a title to the dialog box
F3=PUTFILE("Enter report name","Report.txt")
* User OKs the default name or enters another name
F4=PUTFILE("Enter a table name","Temp",".dbf")
* Default name: temp and default extension: .dbf
? "F1",F1
? "F2",F2
? "F3",F3
? "F4",F4


Portability

Not supported in dBASE IV or dBASE III PLUS.


See Also

FILE( )

GETFILE( )

RENAME


PV( )

See Also	Example	Portability	Numeric Data

Returns a float that is the present value of an investment.

Syntax

PV(<payment expN>, <interest expN>, <term expN>)

<payment expN>

The amount of the periodic payment. Specify the payment in the same time increment as the interest and term. The payment can be negative or positive.

<interest expN>

The interest rate per period expressed as a positive decimal number. Specify the interest rate in the same time increment as the payment and term.

<term expN>

The number of payments. Specify the term in the same time increment as the payment and interest.

Description

PV( ) is a financial function that calculates the original principal balance (present value) of an investment. PV( ) returns a float that is the amount to be repaid with equal periodic payments at a fixed interest rate compounding over a fixed length of time. For example, use PV( ) if you want to know how much you need to invest now to receive regular payments for a specified length of time.

Express the interest rate as a decimal. For example, if the annual interest rate is 9.5%, <interest expN> is .095 (9.5 / 100) for payments made annually.

Express <payment expN>, <interest expN>, and <term expN> in the same time increment. For example, if the payment is monthly, express the interest rate per month, and the number of payments in months. Express an annual interest rate of 9.5%, for example, as .095/12, which is 9.5/100 divided by 12 months.

The formula dBASE uses to calculate PV( ) is as follows:

                     term
            (1 + int)^    -  1
pv = pmt * -------------------
                         term
            int*(1 + int)^

where int = rate / 100

For the present value of an investment earning 9% interest, to be paid at $350 monthly for five years, the formula expressed as a dBASE expression looks like this:

? PV(350,.09/12,60)            && Returns 16860.68
nTemp = (1 + .09/12)^60
? 350*(nTemp-1)/(.09/12*nTemp) && Returns 16860.68

In other words, you have to invest $16,860.68 now into an account paying an interest rate of 9% annually to receive $350/month for the next five years.

Use SET DECIMALS to set the number of decimal places PV( ) displays.


PV( ) Example

The following example uses PV( ) to calculate the size of a mortgage loan that the user could afford, given the monthly payment the user desires, current interest rates and the number of payments (360 for 30 year mortgage):

LOCAL f
f=NEW PV()
f.OPEN()
CLASS PV OF FORM
  this.Width=50
  this.Height=15
  this.Text= "What can I afford?"
  this.ColorNormal="BG+/BG"
  DEFINE TEXT Txt1 OF THIS AT 3,5;
    PROPERTY Text "Desired monthly payment?",;
    Width 35
  DEFINE ENTRYFIELD Amnt OF THIS AT 3,38 ;
    PROPERTY Value 0, Picture "9999",;
    Width 8
  DEFINE TEXT Txt2 OF THIS AT 5,5;
    PROPERTY Text "Current interest rate?",;
    Width 26
  DEFINE ENTRYFIELD Int OF THIS AT 5,33 ;
    PROPERTY Value 0, Picture "99.99",;
    Width 8
  DEFINE TEXT Txt3 OF THIS AT 7,5;
    PROPERTY Text "How many monthly payments?",;
    Width 45
  DEFINE ENTRYFIELD Pymts OF THIS AT 7,40 ;
    PROPERTY Value 0, Picture "999",;
    Width 8
  DEFINE PUSHBUTTON Results OF THIS AT 11,15;
    PROPERTY Text "Loan Amount", Width 20,;
    OnClick {;myResult="You can afford to borrow $"+;
    LTRIM(STR(PV(Form.Amnt.Value,;
    (Form.Int.Value/100)/12,Form.Pymts.Value),13,2));
    ; Form.PV.Text=myResult},;
    Height 2, ColorNormal "N/W"
  DEFINE TEXT PV OF THIS AT 9,5;
    PROPERTY Text "How much to borrow? ", Width 40
ENDCLASS


Portability

Not supported in dBASE III PLUS.


See Also

FV( )

PAYMENT( )

SET DECIMALS


QUIT

See Also	Example	Portability	Programs

Closes all open files, clears all memory variables, exits dBASE, and returns control to the operating system.

Syntax

QUIT [WITH <expN>]

WITH <expN>

Passes a return code, <expN>, to the operating system when you exit dBASE.

Description

Use QUIT to end your dBASE work. If you include QUIT in a program file, dBASE halts the program's execution and exits dBASE. To end a program's execution without leaving dBASE, use CANCEL or RETURN.

Use QUIT WITH <expN> to pass a return code to Windows or to another application.


QUIT Example

The following example shows how to create pushbuttons on a form that present the user with the option to terminate dBASE by issuing the QUIT command. In this example, clicking on the Exit pushbutton issues a code block containing the QUIT command:

DEFINE FORM QuitTest FROM 2,2 TO 15,40;
  PROPERTY Text "Testing Quit"
DEFINE PUSHBUTTON PB1 OF QuitTest AT 8,11;
  PROPERTY Text "Exit dBASE", Width 15,;
    OnClick {;QUIT}
OPEN FORM QuitTest


Portability

The WITH <expN> option is not supported in dBASE III PLUS.


See Also

CANCEL

CLEAR

CLOSE...

RELEASE

RETURN

RUN

RUN( )


RANDOM( )

See Also	Example	Portability	Numeric Data

Returns a decimal value between 0 and 1.

Syntax

RANDOM([<expN>])

<expN>

The numeric or float number with which to seed RANDOM( ).

Description

Use RANDOM( ) to generate a series of random numbers. If you specify a positive <expN> value, RANDOM( ) uses <expN> as a seed value. A seed value is the value that a function operates on to return a result. Thus, RANDOM( ) always returns the same number when you specify the same positive <expN>. For example, RANDOM(199) always returns 0.11, RANDOM(399) always returns 0.23, and RANDOM(599) always returns 0.35.

If you do not specify <expN>, or use zero, RANDOM( ) uses as a seed value the number that the previous RANDOM( ) returned or, if there is no previous RANDOM( ), a fixed internal seed value of 0.

Use RANDOM( ) with a negative <expN> value when you want RANDOM( ) to return a more truly random series of numbers. If you specify a negative <expN> value, RANDOM( ) uses a seed value based on the number of seconds on your computer system clock. As a result, using RANDOM( ) with negative <expN> values makes it likely that RANDOM( ) will return different numbers each time your program executes.

You can use RANDOM( ) to generate a seemingly random series of numbers while maintaining control over what those numbers are. For example, using RANDOM(5), and then RANDOM( ) three times without the <expN> option always returns 0.03, 0.49, 0.56, 0.68. In the first use of RANDOM( ), 5 is the seed value; in the second use of RANDOM( ), 0.03 is the seed value, since the previous RANDOM( ) returned 0.03.

Use SET DECIMALS to set the number of decimal places RANDOM( ) displays.


RANDOM( ) Example

The following program generates a random list of 20 flights from the Flights table for making random inspections:

USE FLIGHTS
SET TALK OFF
CLEAR
Count=1
DO WHILE COUNT <=20
  Flt=INT(RANDOM()*RECCOUNT()+1)
  GOTO Flt
  ? Flight_No AT 10, Origin, Dest
  Count=Count+1
ENDDO
X=INKEY(5)      && Delays display 5 seconds
CLOSE ALL

The following example uses RANDOM( ) to generate a random number to be used as part of a unique table name:

CLEAR
Tmp_file = "TMP" + LTRIM(STR(RANDOM()*10000,5,0))+".DBF"
USE Clients
COPY STRUCTURE TO &Tmp_file
USE &tmp_file IN 2
SELECT 2
? "The current table is: " + Tmp_file
X=INKEY(5)      && Delays display 5 seconds
CLOSE ALL
ERASE &tmp_file

The next example uses RANDOM( ) to generate three sets of six randomly picked numbers from a possible range of 151:

CLEAR
SET TALK OFF
Play=1
Pick=1
DO WHILE Play<=3
  DO WHILE Pick<=6
    lotto = RANDOM()*51
    ? "Pick"+LTRIM(STR(Pick))+"  " AT 10, ;
      LTRIM(STR(lotto,5,0))
    Pick=Pick+1
  ENDDO
  ?
  Pick=1
  Play=Play+1
ENDDO
SET TALK ON
RETURN


Portability

Not supported in dBASE III PLUS. In dBASE IV, the function is RAND( ); RANDOM( ) is not recognized.

In dBASE IV, you can reset to the default seed value by issuing RAND(100001). dBASE for Windows does not support resetting to the default seed value. Also in dBASE IV, RAND(0) always returns the same value. In dBASE for Windows, RANDOM(0) is identical to RANDOM( ), and uses as a seed value the number that the previous RANDOM( ) returned.


See Also

GENERATE

SET DECIMALS


RAT( )

See Also	Example	Portability	String Data

Returns a number that represents the starting position of a string within another string or memo field. RAT( ) searches back from the right end of the target string or memo field, and returns a value counting from the beginning of the target.

Syntax

RAT(<search expC>, <target expC> | <target memo field>
[, <nth occurrence expN>])

<search expC>

The string to search for in <target expC> or <target memo field>.

<target expC> | <target memo field>

The string or memo field , or target, in which to search for <search expC>.

<nth occurrence expN>

Which occurrence of <search expC> to find. If you do not specify <nth occurrence expN>, dBASE searches for the first occurrence from the end. You can search for other occurrences by specifying the number (based on starting from the end), which must be greater than zero.

Description

Use RAT( ) to search for the first or <nth occurrence expN> occurrence of <search expC> in a target string or memo field, searching right to left, end to beginning. The search is case-sensitive. Use UPPER( ) or LOWER( ) to make the search case-insensitive.

Even though the search starts from the end of the target string or memo field, the result RAT( ) returns represents the numeric position of <search expC> counting from the beginning of the target. This is shown in the following example.

? RAT("abc","abcdefabc")  && returns 7
**                 |
** The bar above shows the first occurrence of 'abc'
**    searching from the end of the target
** That character is in position 7 counting from the
**    beginning of the target

If <search expC> occurs only once in the target, RAT( ) and AT( ) return the same value. For example, RAT("abc","abcdef") and AT("abc","abcdef") both return 1.

RAT( ) returns 0 when:

The search string is not found

The search string is an empty string

The search string is longer than the target string

The nth occurrence you specify with <nth occurrence expN> does not exist

To find the starting position of <search expC>, searching from left to right, beginning to end, use AT( ). To learn if one string exists within another, use the substring operator ($). See Language Definition for information about operators.


RAT( ) Example

The following example uses RAT( ) to locate the starting point of a passed string, starting at the right end of a second string:

? RAT("B","ABC")             && Returns 2
? RAT("ss","Mississippi")    && Returns 6
? RAT("ss","Mississippi",2)  && Returns 3
? RAT("Z","ABC")             && Returns 0
? RAT("a","ABC")             && Returns 0
? RAT("ABC","AB")            && Returns 0
? RAT("","ABC")              && Returns 0
? RAT("a","abc",2)           && Returns 0

The next example uses RAT( ) when displaying the contents of a field:

USE Clients
LIST FIELDS Company, Contact ;
   FOR RAT("COMPUTER",UPPER(Company)) > 0
CLOSE DATABASES


Portability

Not supported in dBASE III PLUS. dBASE IV limits a memo field search to approximately 64K of data.


See Also

AT( )

LOWER( )

STUFF( )

SUBSTR( )

UPPER( )


READ

See Also	Example	Portability	Input/Output

Activates all @...GET fields and memory variables in the results pane of the Command window or the current dBASE IV window. This command is supported primarily for compatibility with dBASE IV. In dBASE for Windows, use DEFINE, OPEN FORM, and READMODAL( ) to create and activate forms.

Syntax

READ
[SAVE]

SAVE

Stores the contents of each @...GET in an internal buffer. Without the SAVE option, dBASE clears @...GETs from the buffer when READ finishes executing. With the SAVE option, the next READ repeats all @...GETs stored in the buffer, allowing input and editing.

Description

Use READ to activate @...SAY...GETs in the results pane of the Command window or the current dBASE IV window you have opened with ACTIVATE WINDOW. READ allows the @...GET fields and memory variables to be edited.

If the @...SAY...GETs are in an open format file, you can issue APPEND, BROWSE [FORMAT], CHANGE, EDIT, or INSERT, as well as READ, to activate them in a window you have opened with ACTIVATE WINDOW. READ activates the @...SAY...GET commands stored in a format file, if that file is opened (with SET FORMAT TO). If a format file is open and you issue one or more @...SAY...GETs and a READ, READ ignores the @...SAY...GETs and instead reads the format file.

READs can also be within a format file. READ within a format file activates the @...GET statements after the READ and before either the next READ or the end of the format file. You can thus create a multi-window format file by inserting READ commands to start new displays in the current window and numbering subsequent @...SAY...GETs from row 0.

You can nest READs. For example, you can issue ON KEY LABEL and specify a procedure or user-defined function (UDF) that includes more @...SAY...GETs and READ commands. Or, you can include nested READs in a UDF that is an argument of @...GET...VALID or @...GET...HELP. With nested READ commands, more than one READ can be active at one time. When one READ finishes executing, control returns to the previous READ.

All open index files are automatically updated when READ is used to store values to the current table.


READ Example

In this example, the user is asked to enter a name and an address. The READ statement passes control over to the user to enter data:

CLEAR
SET TALK OFF
Name=space(20)
Address=space(20)
@ 5,5 SAY "Name" GET Name
@ 6,6 SAY "Address" GET Address
READ

With READ SAVE the GETs are still available. If they are not needed then CLEAR GETS will remove them:

@ 5,5 SAY "Name" GET Name
@ 6,6 SAY "Address" GET Address
READ SAVE
WAIT "Do you wish to make any changes? ";
  TO Answer
IF UPPER(Answer)="Y"
  READ
ELSE
  CLEAR GETS
ENDIF

CLEAR will perform a CLEAR GETS if a READ was issued but will not clear a READ SAVE.

Control does not pass to the user until READ is issued. The READ might happen in a different .PRG file. It need not happen at all.


Portability

In dBASE III PLUS, @...GET fields just occur on the screen. In dBASE IV, @...GET fields can appear onscreen outside of windows and can occur in the context of a window opened with ACTIVATE WINDOW.


See Also

@...SAY...GET

ACCEPT

ACTIVATE WINDOW

CHANGE

CLEAR GETS

DEFINE

INPUT

SET CARRY

SET FORMAT


READKEY( )

See Also	Example	Keyboard and Mouse Events

Returns an integer that identifies the key or key combination that was pressed to terminate execution of a full-screen editing command. This command is supported primarily for compatibility with dBASE IV. In dBASE for Windows, use properties such as OnClick to initiate actions based on how a user exits a form.

Syntax

READKEY( )

Description

READKEY( ) returns an integer to indicate the key pressed when a full-screen data-editing command is terminated.

Full-screen editing commands for which READKEY( ) returns meaningful values are APPEND, BROWSE, EDIT, INSERT, and READ.

READKEY( ) returns a relevant value only when it is invoked from inside a program, procedure, or user-defined-function (UDF).

READKEY( ) returns a value from 0 to 36 if a command is terminated from an unchanged record, unless the user terminates the command with Ctrl+W or Ctrl+End. READKEY( ) returns a value from 256 to 291 if the command is terminated from a changed record, unless the user terminates the command with Ctrl+Q or Esc. See INKEY( ) Values and READKEY( ) Values for a complete list of the values READKEY( ) returns.

For example, pressing Enter to terminate a READ operation always returns either 15 or 271, depending on whether you exit with or without modifications. The user cannot exit from the beginning of a file in APPEND mode.

You can use READKEY( ) as the argument of an @…GET…VALID command. In this case, READKEY( ) only returns a value from 0 to 36, and although you can determine which key is used to exit the input area, you cannot determine whether changes were made.


READKEY( ) Example

The following example uses READKEY( ) to determine if the contents of a record was altered during the previous EDIT, and if so, issue the FLUSH command to save all changes before continuing. ? commands merely furnish feedback to the Command window results pane:

USE Clients
EDIT
IF READKEY() >= 256     && Data has changed
  FLUSH
  ? "Record changes saved to disk"
ELSE
  ? "Record not changed"
ENDIF


See Also

APPEND

BROWSE

EDIT

INKEY( )

INSERT

LASTKEY( )

OnClick

READ

@...SAY...GET


READMODAL( )

See Also	Example	Portability	Forms

Opens a form as a modal window and returns the name of the object that has input focus when the user submits the form.

Syntax

READMODAL(<object reference> [, <expL>])

<object reference>

References the object that receives initial input focus when the form is opened.

<expL>

A logical condition that determines if pressing Esc closes the form. The default is true (.T.).

Description

Use READMODAL( ) to open a form as a modal window.

A form that you open as a modal window has the following characteristics:

While the form is open, focus cannot be transferred to other forms.

Execution of the routine that opened the form stops until the form is closed. When the form is closed, control transfers to the command line after the one that opened the form.

Many applications use modal forms as dialog boxes, which typically require users to take an action before the dialog box can be closed.

By default, READMODAL( ) returns the name of the object that has focus when the user submits the form; however, you can specify your own return value for READMODAL( ) using the WITH option of CLOSE FORMS.

READMODAL( ) is similar to the ReadModal( ) method, which also opens a form as a modal window.

To open a form as a modeless window, use the Open( ) method or the OPEN FORM command.


READMODAL( ) Example

The following example uses READMODAL( ) to display and enable a previously defined form:

SET CUAENTER OFF
DEFINE FORM Mortgage FROM 2,2 TO 15,60;
  PROPERTY Text "Dewey's Loans",MDI .F.,;
    OnClose {;SET CUAENTER ON}
  DEFINE TEXT Txt1 OF Mortgage AT 2,5;
    PROPERTY Text "What is the principal?",;
    Width 26, ColorNormal "RB/W"
  DEFINE ENTRYFIELD Princ OF Mortgage AT 2,45;
    PROPERTY Picture "999,999",;
    Width 7, Value 0
  DEFINE TEXT Txt2 OF Mortgage AT 4,5;
    PROPERTY Text "What is the interest rate?",;
    Width 30, ColorNormal "RB/W"
  DEFINE ENTRYFIELD Int OF Mortgage AT 4,45 ;
    PROPERTY Picture "99.99",;
    Width 5, Value 0
  DEFINE TEXT Txt3 OF Mortgage AT 6,5;
    PROPERTY Text "What is the number of;
  payments?",Width 39,ColorNormal "RB/W"
  DEFINE ENTRYFIELD Pay OF Mortgage AT 6,45 ;
    PROPERTY Picture "999",;
    Width 4, Value 0
  DEFINE TEXT Txt4 OF Mortgage AT 8,8;
    PROPERTY Text "Your payment will be:",;
    Width 30, ColorNormal "R+/W"
  DEFINE ENTRYFIELD Pymnt OF Mortgage AT 8,45;
    PROPERTY Width 10, Value 0, Picture "$9999.99",;
    OnGotFocus {;this.Value=;
      PAYMENT(Form.Princ.Value,;
      (Form.Int.Value/100)/12,Form.Pay.Value)}
  DEFINE PUSHBUTTON Exit OF Mortgage AT 11,18;
    PROPERTY Text "Exit", OnClick {;Form.Close()}
READMODAL(Mortgage.Princ)


Portability

Not supported in dBASE IV or dBASE III PLUS.


See Also

ACTIVATE WINDOW

CLEAR WINDOWS

CLOSE...

DEACTIVATE WINDOW

DEFINE WINDOW

Open( )

OPEN FORM

ReadModal( )

RELEASE WINDOWS


RECALL

See Also	Example	Fields and Records

Unmarks records that were previously marked for deletion in the current table. This command has no effect when accessing Paradox or SQL tables, since records are removed immediately when they are deleted.

Syntax

RECALL
[<scope>]
[FOR <condition 1>]
[WHILE <condition 2>]

<scope>

The number of records to recall. RECORD <n> identifies a single record by its record number. NEXT <n> identifies n records, beginning with the current record. ALL specifies all records. REST specifies all records from the current record to the end of the file.

FOR <condition 1>
WHILE <condition 2>

Determines which records are affected by RECALL. FOR restricts RECALL to records that meet <condition 1>. WHILE starts processing with the current record and continues with each subsequent record as long as <condition 2> is true.

Description

Use RECALL to undelete records that have been marked for deletion in the current table with DELETE but have not yet been removed with PACK. Executing DELETE does not erase records but identifies them as to be deleted. RECALL reverses this process, unmarking the records and fully restoring them to the table. RECALL with no options unmarks the current record only.

Records eliminated with PACK or ZAP are permanently removed and cannot be recovered using RECALL.

When SET DELETED is ON, the <scope> and FOR options have no effect, and the WHILE option affects only the current record. RECALL with no options is not affected by SET DELETED; the current record is recalled.

In most cases, SET DELETED ON filters out all deleted records of the active table. It is possible to access a deleted record, though, if you refer to the record by record number. For example, if record number 4 is deleted and SET DELETED is ON, GO 4 positions the record pointer at the deleted record.


RECALL Example

See DELETE for an example of RECALL.


See Also

DELETE

PACK

SET DELETED

ZAP


RECCOUNT( )

See Also	Example	Fields and Records

Returns the number of records in the current or a specified table.

Syntax

RECCOUNT( [<alias>] )

<alias>

A work area number (1 through 225), letter (A through J), or alias name. The work area letter or alias name must be enclosed in quotes.

Description

RECCOUNT( ) retrieves a count of a table's records from the table header, which holds information about the table structure. In contrast, COUNT with no argument yields a record count by actually counting the table's records.

If no table is active, RECCOUNT( ) returns zero. RECCOUNT( ) includes all records, even if SET DELETED is ON or SET FILTER is in effect.

You can use RECSIZE( ) in combination with RECCOUNT( ) to determine the approximate size, in bytes, of a table. The DIR command displays the number of bytes DOS allocates to a table. DOS might not allocate the same number of bytes as the actual size of the file.


RECCOUNT( ) Example

The following example uses RECCOUNT( ) to return the number of records in each specified table:

USE Company IN SELECT()
USE Contact IN SELECT()
? "The table - Company - has " + ;
  LTRIM(STR(RECCOUNT("Company"),4,0)) + " records."
? "The table - Contact - has " + ;
  LTRIM(STR(RECCOUNT("Contact"),4,0)) + " records."
CLOSE ALL

The following example uses RECCOUNT( ) to initialize an array to the dimensions of Clients table and copies the contents of the table to the array:

SET TALK OFF
USE Clients
DECLARE Clnt2[RECCOUNT(),FLDCOUNT()]
COPY TO ARRAY Clnt2
Cnt = 1
DO WHILE Cnt <= RECCOUNT()
  ? Clnt2[Cnt,2]       && Displays company name
  Cnt=Cnt+1
ENDDO
CLOSE ALL
CLEAR ALL
SET TALK ON


See Also

DIR

DBF( )

DISKSPACE( )

DISPLAY STRUCTURE

RECNO( )

RECSIZE( )


RECNO( )

See Also	Example	Fields and Records

Returns the current record number of the current or a specified table. For Paradox and SQL tables, this function returns a bookmark of the current position in a table.

Syntax

RECNO( [<alias>] )

<alias>

A work area number (1 through 225), letter (A through J), or alias name. The work area letter or alias name must be enclosed in quotes.

Description

RECNO( ) returns the current record number of the table in the current or a specified work area. RECNO( ) considers all records, even if SET DELETED is ON or SET FILTER is in effect. If no table is open in the specified work area, RECNO( ) returns a value of 0.

If the record pointer moves past the last record (EOF) in the table, RECNO( ) returns a value that is one more than the total number of records in the table. If the record pointer moves before the first record (BOF) in the table, RECNO( ) returns a value of 1. RECNO( ) also returns a value of 1 if there are no records in the table.


RECNO( ) Example

The following example uses RECNO( ) to display the record number in a SCAN loop and after the record pointer is moved from EOF( ) to BOF( ):

SET TALK OFF
CLEAR
USE Company IN SELECT() EXCLUSIVE
? "Record Num" AT 4, "Company" AT 18
?
SCAN
   ? LTRIM(STR(RECNO())) AT 4, Company AT 18
ENDSCAN
IF EOF()
? "The End of File has been reached ;
at Record #" +  LTRIM(STR(RECNO(),3,0))
ENDIF
GO TOP
SKIP -1
IF BOF()
? "The Beginning of File has been reached ;
at Record # " +  LTRIM(STR(RECNO(),3,0))
ENDIF
CLOSE ALL
SET TALK ON


See Also

BOF( )

EOF( )

RECCOUNT( )


RECSIZE( )

See Also	Example	Fields and Records

Returns the number of bytes in a record of the current or specified table.

Syntax

RECSIZE( [<alias>] )

<alias>

A work area number (1 through 225), letter (A through J), or alias name. The work area letter or alias name must be enclosed in quotes.

Description

RECSIZE( ) returns the number of bytes in a record of a table in the current or specified work area. If no table is open in the specified work area, RECSIZE( ) returns a value of zero.

LIST STRUCTURE and DISPLAY STRUCTURE also show the size of a table's records.


RECSIZE( ) Example

The following example uses RECSIZE( ) to return the record length within the table structure in bytes for each specified table:

USE Company IN SELECT()
USE Contact IN SELECT()
? "The table - Company - has a record size of " + ;
   LTRIM(STR(RECSIZE("Company"),4,0)) + " bytes"
? "The table - Contact - has a record size of " + ;
   LTRIM(STR(RECSIZE("Contact"),4,0)) + " bytes"
CLOSE ALL


See Also

DBF( )

DIR

DISPLAY STRUCTURE

LIST STRUCTURE

RECCOUNT( )

RECNO( )


REDEFINE

See Also	Example	Portability	Objects

Changes an object definition in memory.

Syntax

REDEFINE <class name> <object name>
[OF <container object>]
[FROM <row, col> TO <row, col> > | <AT <row, col>]
[PROPERTY <stock property list>]
[CUSTOM <custom property list>]
[WITH <parameter list>]

<class name>

The class of the object you want to redefine. See DEFINE for a list of objects from the standard classes.

<object name>

The object reference to the object you want to redefine.

OF <container object>

Identifies the object that contains the object you want to redefine. (For most UI objects this container object is a form.)

FROM <row>, <col> TO <row>, <col> | AT <row>, <col>

Specifies the initial location and size of the object within its parent form or window. FROM and TO specify the upper left and lower right coordinates of the object, respectively. AT specifies the position of the upper left corner.

PROPERTY <stock property list>

Specifies values you assign to the built-in properties of the object.

CUSTOM <custom property list>

Specifies new properties you create for the object and the values you assign to them. For information on custom properties, see Chapter 10 in the Programmer's Guide.

WITH <parameter list>

Specifies the parameters you pass to the object. Declare these parameters with the PARAMETERS clause of the CLASS...ENDCLASS command.

Description

Use REDEFINE to change an existing object.

You control object characteristics with properties, which are memory variables contained in the object. For example, a form has height and width, so form objects have properties named Height and Width. The REDEFINE command lets you assign new values to these and other properties after you create the object with the DEFINE command or the NEW operator.

Each REDEFINE command has the same options as its associated DEFINE command, and they both give control over the same properties.

You can also change properties using the dot operator. For information on the dot operator and the syntax required to use it, see Chapter 10 in the Programmer's Guide.


REDEFINE Example

The following example creates four forms on the screen with a pushbutton in form Fourth that enables the user to REDEFINE forms First, Second and Third to screen positions that present a vertical form orientation:

SET PROCEDURE TO PROGRAM(1) ADDITIVE
PUBLIC FIRST, SECOND, THIRD, FOURTH
DEFINE FORM First FROM 0,0 TO 10,29
DEFINE FORM Second FROM 0,31 TO 10,58
DEFINE FORM Third FROM 13,0 TO 28,58
DEFINE FORM Fourth FROM 0,60 TO 28,74
  DEFINE PUSHBUTTON Remodel OF Fourth AT 20,1;
    PROPERTY;
      TEXT "Change Layout", Width 13,;
      OnClick Rotate
  DEFINE PUSHBUTTON Exit OF Fourth AT 23,1;
    PROPERTY;
      TEXT "Revert To", Width 13,;
      OnClick RevertTo
OPEN FORM First, Second, Third, Fourth
SET FOCUS TO Fourth

PROCEDURE RevertTo
CLOSE FORMS Third, Fourth
RETURN

PROCEDURE Rotate
CLOSE FORMS First, Second, Third
REDEFINE FORM First FROM 0,0 TO 28,17
REDEFINE FORM Second FROM 0,19 TO 28,37
REDEFINE FORM Third FROM 0,39 TO 28,58
OPEN FORM First, Second, Third
SET FOCUS TO FOURTH
RETURN


Portability

Not supported in dBASE III PLUS or dBASE IV.


See Also

CLASS...ENDCLASS

DEFINE


REFRESH

See Also	Example	Portability	Table Basics

Updates the current or specified work area data buffers to reflect the latest changes to data.

Syntax

REFRESH [<alias>]

<alias>

A work area number (1 through 225), letter (A through J), or alias name. The work area letter or alias name must be enclosed in quotes.

Description

Use REFRESH to update specified work area data buffers so that data you display reflects the latest changes made to tables by other users on a network. This command is most often used when accessing data from tables stored on a database server; however, you can also use it to update the data buffers for open Paradox and dBASE tables.


REFRESH Example

This example opens Company.DBF and Orders.DBF. Because they are not exclusively opened, another user could change a record in Company or Orders after this user has read it from the server. REFRESH rereads the records to ensure that the latest data is displayed:

CLOSE ALL
SET EXCLUSIVE ON
USE S:\Dbasewin\Samples\Orders
INDEX ON Customer_N TAG Customer_N
* build the index
CLOSE ALL
SET EXCLUSIVE OFF
USE S:\Dbasewin\Samples\Company
SELECT 2
USE S:\Dbasewin\Samples\Orders
SET RELATION TO Customer_N INTO Company
* Now anyone can access company
SCAN
  REFRESH("Company")
  REFRESH("Orders")
  EDIT
ENDSCAN


Portability

Not supported in dBASE IV or dBASE III PLUS.


See Also

SET REFRESH


REINDEX

See Also	Example	Table Organization

Updates all open index files in the selected work area to reflect changes in the current table.

Syntax

REINDEX

Description

Use REINDEX to incorporate all changes made to the current table into the open index files if they were not open when the table was updated. Reindexing updates all open .NDX and .MDX files opened with USE or SET INDEX.

If an index file is created using the UNIQUE option of the INDEX command, or while SET UNIQUE is ON, REINDEX rebuilds the index as a unique index. Similarly, if you created a descending order index using the DESCENDING option of the INDEX command, the REINDEX command rebuilds the index in descending order.


REINDEX Example

The following example uses REINDEX to reindex an open index file after a new record has been added with the index file open but inactive:

USE Company EXCLUSIVE
INDEX ON Ytd_sales TAG Ytd OF Company1
* this creates Company1.mdx with tag Ytd
USE COMPANY EXCLUSIVE
* now Company1.mdx will not be updated
APPEND BLANK
REPLACE Company WITH "Missing From Index"
* Company1.mdx is out of date
USE COMPANY INDEX Company1 EXCLUSIVE
SET ORDER TO TAG Ytd OF Company1
*
BROWSE TITLE "Record "+ltrim(str(reccount()))+" not in YTD"
* Ytd is now the index but it is out of date
* the last record cannot be found
REINDEX
* Ytd is now updated
BROWSE TITLE "Reindex includes last record"


See Also

INDEX

SET INDEX

SET ORDER

SET UNIQUE

USE


RELATION( )

See Also	Example	Portability	Table Organization

Returns the key expression defined with the SET RELATION command for the current or specified work area.

Syntax

RELATION(<expN> [,<alias>] )

<expN>

The number of a relation that you want to return.

<alias>

A work area number (1 through 225), letter (A through J), or alias name. The work area letter or alias name must be enclosed in quotes.

Description

RELATION( ) returns the expression linking tables defined from the current or specified work area with the SET RELATION command. If the table is linked to more than one table, you can specify the number of the relation you want to return. RELATION( ) returns an empty string ("") if no relation is set in the <expN> position.

Use RELATION( ) to save the key expressions of all SET RELATION settings for later use when restoring relations. To save the target table (the table into which you SET a RELATION), use the TARGET( ) function.


RELATION( ) Example

The following example uses RELATION( ) to determine the key expression used to establish a relationship between two child tables, Contact and Summary, and the parent table, Company:

CLOSE ALL
CLEAR
SELECT 1
USE Customer
INDEX ON Customer_N TAG Customer_N
SELECT 2
USE Orders
SELECT 3
USE LineItem
INDEX ON Order_no TAG Order_no
SELECT 2
SET RELATION TO Order_no INTO LineItem
SET RELATION TO Customer_N INTO Customer ADDITIVE
IF LEN(RELATION(1)) > 0
   @ 9,0 SAY "Orders.dbf is related to " + ;
      TARGET(1)+ " key expression: "+RELATION(1)
   IF LEN(RELATION(2)) > 0
      @ 11,0 SAY "Orders.dbf is also related to " + ;
      TARGET(2)+ " key expression: "+RELATION(2)
   ENDIF
ENDIF


Portability

Not supported in dBASE IV or dBASE III PLUS.


See Also

ALIAS( )

CREATE QUERY

CREATE VIEW

CREATE VIEW...FROM ENVIRONMENT

SELECT( )

SET RELATION

SET VIEW

SET( )

TARGET( )


RELEASE

See Also	Example	Portability	Memory Variables

Deletes specified memory variables and arrays, freeing memory space for additional variables.

Syntax

RELEASE <memvar list> |
ALL
[LIKE <memvar skeleton 1>]
[EXCEPT <memvar skeleton 2>]

<memvar list>

The specific memory variables to release from memory, separated by commas.

ALL

Removes from memory all stored memory variables.

LIKE <memvar skeleton 1>

Removes from memory all memory variables whose names are like the memory variable skeleton you specify for <memvar skeleton 1>. Use characters of the variable names and the wildcards * and ? to create <memvar skeleton 1>.

EXCEPT <memvar skeleton 2>

Removes from memory all memory variables except those whose names are like the memory variable skeleton you specify for <memvar skeleton 2>. Use characters of the variable names and the wildcards * and ? to create <memvar skeleton 2>. You can use LIKE and EXCEPT in the same statement, for example, RELEASE ALL LIKE mvar* EXCEPT mvarnum*.

Description

Use RELEASE to clear memory variables, thus making additional space available for new ones. To remove large groups of variables, use the option ALL [LIKE <memvar skeleton 1>] [EXCEPT <memvar skeleton 2>].

If you issue RELEASE ALL [LIKE <memvar skeleton 1>] [EXCEPT <memvar skeleton 2>] in a subroutine--a program, procedure, or user-defined function (UDF)--dBASE releases only the private memory variables defined in that subroutine. It doesn't release memory variables declared in higher-level routines.

When control returns from a subroutine to its calling routine, dBASE clears from memory all variables initialized in the subroutine that were not declared PUBLIC or STATIC. Thus, you do not have to release a subroutine's private variables explicitly with RELEASE in the calling routine.


RELEASE Example

The following example initializes a series of memory variables with names that are a concatenation of a string and a natural order record number. After processing, Client_ID and Company field values are held in variables IDx and Compx respectively. DISPLAY MEMORY merely confirms the presence of these memory variables. RELEASE ALL LIKE demonstrates how groups of memory variables can be released from memory, as evidenced by subsequent DISPLAY MEMORY commands:

SET TALK OFF
SET SAFETY OFF
USE Clients EXCLUSIVE
INDEX ON Client_ID TAG Client_ID
DO WHILE .NOT. EOF()
  VAR1="ID"+LTRIM(STR(RECNO()))
  VAR2="Comp"+LTRIM(STR(RECNO()))
  STORE Client_ID TO &VAR1
  STORE Company TO &VAR2
  SKIP
ENDDO
CLEAR
DISPLAY MEMORY         && IDx and COMPx memvars
CLEAR
RELEASE ALL LIKE COMP*
DISPLAY MEMORY         && IDx only remaining
CLEAR
RELEASE ALL LIKE ID*
DISPLAY MEMORY         && all gone
CLEAR
SET TALK ON
SET SAFETY ON


Portability

dBASE IV and dBASE III PLUS do not support both LIKE and EXCEPT in the same RELEASE statement.


See Also

CLEAR

LOCAL

PRIVATE

PUBLIC

QUIT

RESTORE

RETURN

SAVE

STATIC


RELEASE AUTOMEM

See Also	Example	Portability	Fields and Records

Clears all stored automem variables from memory.

Syntax

RELEASE AUTOMEM

Description

When you create a set of automem variables for a table using STORE AUTOMEM, CLEAR AUTOMEM, or USE...AUTOMEM, dBASE for Windows initializes one variable for each field, assigning each variable the same name and data type as the corresponding field. When you no longer need the automem variables, you can use RELEASE AUTOMEM to remove them from memory, making space available for other variables. RELEASE AUTOMEM releases all memory variables with the same name as fields in the current table, even variables that were not created with an AUTOMEM command.

Closing a table or moving to another work area does not automatically release a table's associated automem variables. dBASE for Windows does not recognize a variable as an automem variable, even if it was created as an automem variable, if it does not have the same name as a field in the current table. Thus, when you close a table or select another work area, the associated automem variables remain in memory. After you close a table or select another work area, RELEASE AUTOMEM does not remove these variables from memory so you must remove them with either RELEASE or CLEAR ALL.


RELEASE AUTOMEM Example

The following sample uses CLEAR AUTOMEM to enable the user to edit AUTOMEM variables for a new record. However, a new record will only be added if the user confirms that the data is correct. RELEASE AUTOMEM is used with ON ESCAPE and READKEY( ) to release all automem variables from memory when the user discontinues data entry by pressing ESCAPE:

SET TALK OFF
CLEAR
USE Clients
ON ESCAPE RELEASE AUTOMEM
AddMoreData()
RETURN

FUNCTION AddMoreData
@0,0 to 8, 70
@10,20 to 12,45
CLEAR AUTOMEM
DO WHILE .T.
  lConfirm = .F.
  @11,22 CLEAR TO 11,39
  @1,1 SAY 'ID' GET m->CLIENT_ID
  @1,10 SAY 'COMPANY' GET m->COMPANY
  @3,1 SAY 'Contact' GET m->CONTACT
  @4,1 SAY 'Address' GET m->ADDRESS
  @6,1 SAY 'City' GET m->CITY
  @6,23 SAY 'State/Province' GET STATE_PROV
  @6,54 SAY 'Zip' GET ZIP_P_CODE
  READ
    IF READKEY() = 12
      RELEASE AUTOMEM
      EXIT
    ELSE
      @11,22 SAY "Data Correct, Y-N?";
      GET lConfirm PICTURE 'Y'
      READ
        IF lConfirm
          APPEND AUTOMEM
          CLEAR AUTOMEM
        ENDIF
    ENDIF
ENDDO
RETURN .T.


Portability

Not supported in dBASE IV or dBASE III PLUS.


See Also

CLEAR AUTOMEM

RELEASE

STORE AUTOMEM

USE


RELEASE DLL

See Also	Example	Portability	Windows Programming

Deactivates DLL files.

Syntax

RELEASE DLL <DLL filename list>

Description

Use RELEASE DLL when you debug a DLL file or a dBASE application. For example, you must deactivate a DLL file and activate it again each time you change one of its routines.

A DLL file is a precompiled library of external routines written in non-dBASE languages such as C and Pascal. A DLL file can have any extension, although most have extensions of .DLL. You activate a DLL file with the LOAD DLL command.


RELEASE DLL Example

The following example demonstrates the command sequence for using RELEASE DLL as a trouble shooting tool:

LOAD DLL myDLL.DLL
* ... test DLL operation
RELEASE DLL myDLL.DLL
* ... change .DLL or C program
LOAD DLL myDLL.DLL
* ... test again
RELEASE DLL myDLL.DLL


Portability

Not supported in dBASE IV or dBASE III PLUS.


See Also

EXTERN

LOAD DLL


RELEASE MENUS

See Also	Example	Portability	dBASE IV Menus

Removes deactivated menus from memory. This command is supported primarily for compatibility with dBASE IV. In dBASE for Windows, use RELEASE OBJECT to clear an object from a form.

Syntax

RELEASE MENUS
[<menu name list>]

<menu name list>

The menus to remove from memory.

Description

RELEASE MENUS removes from memory specified menu bar names established with DEFINE MENU, and all associated menu pad definitions established with DEFINE PAD.

RELEASE MENUS works like CLEAR MENUS, except that RELEASE MENUS lets you designate specific menu bar definitions, while CLEAR MENUS releases the definitions of all currently defined menu bars.

If you do not include <menu name list>, RELEASE MENUS removes all menu bar definitions from memory.


RELEASE MENUS Example

The following example defines a menu, and then uses RELEASE MENU TO remove it from memory followed by ACTIVATE MENU to cause an error message, which demonstrates that the menu definition is no longer present:

DEFINE MENU Main
DEFINE PAD pDo OF Main PROMPT "Pad 1"
DEFINE PAD pRfm OF Main PROMPT "Pad 2"
ON SELECTION MENU Main DEACTIVATE MENU
CLEAR
ACTIVATE MENU Main
WAIT 'You are about to get an error -;
 "No such menu: MAIN"'
RELEASE MENU Main
ACTIVATE MENU Main     && Error message - Main;
                          no longer in memory


Portability

Not supported in dBASE III PLUS.


See Also

CLEAR MENUS

DEACTIVATE MENU

DEFINE

RELEASE OBJECT


RELEASE OBJECT

See Also	Example	Portability	Objects

Removes object definitions from memory.

Syntax

RELEASE OBJECT <container reference>.<object reference>

<container reference>.<object reference>

<container reference> is an object reference variable pointing to the object (usually a form) that contains the object. <object reference> is an object reference variable pointing to the object itself.

Description

Use RELEASE OBJECT to:

remove an object when you no longer need it.

conserve memory resources.

Releasing a form from memory also releases the objects it contains. Likewise, releasing a menu from memory also releases the menus it contains.

RELEASE OBJECT is identical to the Release( ) method.


RELEASE OBJECT Example

The following example defines three check boxes on form Check_It and uses RELEASE OBJECT to remove "Choice 3" check box from the form upon selection of Choice 1:

PUBLIC Check_It
SET PROCEDURE TO PROGRAM(1) ADDITIVE
DEFINE FORM Check_It FROM 0,0 TO 10,18
DEFINE CHECKBOX Ck1 OF Check_It AT 2,4;
  PROPERTY Text "Choice 1",;
  OnChange Exclude, Value .F.
DEFINE CHECKBOX Ck2 OF Check_It AT 4,4;
  PROPERTY Text "Choice 2", Value .F.
DEFINE CHECKBOX Ck3 OF Check_It AT 6,4;
  PROPERTY Text "Choice 3", Value .F.
OPEN FORM Check_It

PROCEDURE Exclude
IF TYPE("Check_It.Ck3")<>"U"
  RELEASE OBJECT Check_It.Ck3
ENDIF
RETURN


Portability

Not supported in dBASE IV or dBASE III PLUS.


See Also

CLEAR ALL

CLOSE...

Release( )


RELEASE POPUPS

See Also	Example	Portability	dBASE IV Menus

Erases dBASE IV popup menus from the screen and releases them from memory. This command is supported primarily for compatibility with dBASE IV. In dBASE for Windows, use RELEASE OBJECT to clear an object from a form.

Syntax

RELEASE POPUPS
[<popup name list>]

<popup name list>

The popup menu definitions to remove from memory.

Description

RELEASE POPUPS removes from memory popup menu definitions established with DEFINE POPUP, and all associated bar definitions established with DEFINE BAR.

RELEASE POPUPS works like CLEAR POPUPS, except that CLEAR POPUPS releases the definitions of all currently defined popup menus, while RELEASE POPUPS lets you designate specific popup menu definitions.

To erase the current popup from the screen while maintaining its definition in memory, use DEACTIVATE POPUP instead of RELEASE POPUPS. The popup menu is erased and disabled, but you can display and enable it again with ACTIVATE POPUP.


RELEASE POPUPS Example

Sample syntax is as follows:

RELEASE POPUPS Pop1, Pop2, Pop3

See POPUP( ) for an example of how to use RELEASE POPUPS in the context of a program that includes menu bars and popup menus.


Portability

Not supported in dBASE III PLUS.


See Also

ACTIVATE POPUP

CLEAR POPUPS

DEACTIVATE POPUP

DEFINE

DEFINE POPUP

RELEASE OBJECT


RELEASE SCREENS

See Also	Example	Portability	Input/Output

Removes from memory all or specified variables created by SAVE SCREEN, and clears the Command window buffer. This command is supported primarily for compatibility with dBASE IV.

Syntax

RELEASE SCREENS
[<memvar list>]

<memvar list>

The memory variables to remove from memory.

Description

Use RELEASE SCREENS to release from memory variables that contain the saved contents of the results pane of the Command window. Each memory variable should contain the contents of the results pane of the Command window as the result of a previous SAVE SCREEN TO <memvar> command. RELEASE SCREENS has no effect on screens saved with the SAVE SCREEN TO FILE option.

If any of the variables on <memvar list> were not created as the result of a SAVE SCREEN command, dBASE does not release them. To clear such variables from memory, use RELEASE.

If you use RELEASE SCREENS without <memvar list>, its action is identical to CLEAR SCREENS.


Portability

Not supported in dBASE III PLUS.


RELEASE SCREENS Example

See SAVE SCREEN for an example of RELEASE SCREEN.


See Also

CLEAR SCREENS

RELEASE

SAVE SCREEN


RELEASE WINDOWS

See Also	Example	Portability	dBASE IV Windows

Releases specified dBASE IV-style window definitions from memory. This command is supported primarily for compatibility with dBASE IV. In dBASE for Windows, use CLOSE FORMS or RELEASE OBJECT to close or release a form.

Syntax

RELEASE WINDOWS
[<window name list>]

<window name list>

The names of windows to release from memory.

Description

Use RELEASE WINDOWS to conserve memory by removing window definitions when they are no longer needed.

Both RELEASE WINDOWS and CLEAR WINDOWS remove window definitions from memory. However, RELEASE WINDOWS removes specified window definitions, while CLEAR WINDOWS removes all window definitions. When no argument is specified, RELEASE WINDOWS is identical to CLEAR WINDOWS.

RELEASE WINDOWS is different from DEACTIVATE WINDOW; RELEASE WINDOWS removes windows from the screen and from memory, while DEACTIVATE WINDOW clears windows from the screen but maintains their definitions in memory.


RELEASE WINDOWS Example

The following example opens three tiled windows, browses two fields of the Contact table in Window C, uses DEACTIVATE WINDOWS to remove windows from the screen and RELEASE WINDOWS to remove a window from memory.

SELECT A
USE COMPANY
SELECT B
USE CONTACT
CLEAR
DEFINE WINDOW A FROM 1,1 TO 15,40 DOUBLE
DEFINE WINDOW B FROM 5,5 TO 18,60 DOUBLE
DEFINE WINDOW C FROM 10,10 TO 23,50 DOUBLE
ACTIVATE WINDOW A, B, C
BROWSE FIELDS COMPCODE, CONTACT
DEACTIVATE WINDOW C
SELECT A
BROWSE FIELDS COMPANY, YTD_SALES
DEACTIVATE WINDOW B
WAIT "Window A remains open"
DEACTIVATE WINDOW ALL  && Windows still in memory
WAIT "No windows are open"
RELEASE WINDOWS C      &&  A & B still in memory
CLEAR
ACTIVATE WINDOW A,B    && A & B back from memory
WAIT "Still Going...."
CLEAR WINDOWS          && Windows cleared from memory
CLEAR                  && Clear screen
RETURN


Portability

Not supported in dBASE III PLUS.


See Also

CLEAR WINDOWS

CLOSE FORMS

DEACTIVATE WINDOW

DEFINE

RELEASE OBJECT


RENAME

See Also	Example	Disk and File Utilities

Renames a file on disk.

Syntax

RENAME <filename 1> | ? | <filename skeleton 1>
TO <filename 2> | ? | <filename skeleton 2>

<filename 1> | ? | <filename skeleton 1>

Identifies the original file (also known as the source file). RENAME ? and RENAME <filename skeleton> display a dialog box from which you can select a file to rename. If you specify a source file without including its path, dBASE looks for the file in the current directory, then in the path you specify with SET PATH. If you specify a source file without including its extension, dBASE assumes no extension.

TO <filename 2> | ? | <filename skeleton 2>

Identifies the new name for the source file (also known as the target file). The ? and <filename skeleton> options display a dialog box in which you specify the name of a target file and its directory.

Description

RENAME is a utility command that lets you change the name of a file at the operating system level.

If the source file has a file-name extension, it must be specified in the command line. If the source file is not in the current directory or the path you specify with SET PATH, a path must also be included.

RENAME differs from its DOS counterpart in that wildcards do not let you rename more than one file at a time. To rename more than one file at a time using wildcards, use !, RUN, or DOS, and execute the DOS RENAME command.

If SET SAFETY is ON and a file exists with the same name as the target file, dBASE displays a dialog box asking if you want to overwrite the existing file. If SET SAFETY is OFF and a file exists with the same name as the target file, dBASE returns an error, and the target file is not overwritten.

If you specify a new directory for the target file, dBASE copies the source file to this directory. If you specify a new drive for the target file, dBASE returns an error message and the source file is not copied or renamed.

RENAME does not automatically rename a .DBT or .MDX file associated with a .DBF file. If, for example, you rename a table file that has memo fields and you do not rename the associated .DBT file, an error message displays when you try to use the file. In such cases, it is best to create a new copy of the file with COPY TO.


RENAME Example

The following examples use RENAME:

CLOSE DATABASES
RENAME Temp.dbf TO Savit.dbf
* Temp.dbf cannot be open
RENAME Temp.dbt TO Savit.dbt
RENAME ?
* Opens dialog box
RENAME *.qbe
* Opens dialog box showing only query files


See Also

!

COPY FILE

DOS

RUN

SET DEFAULT

SET DIRECTORY

SET PATH

SET SAFETY


RENAME TABLE

See Also	Example	Portability	Table Basics

Changes the name of a specified table.

Syntax

RENAME TABLE <old table name> | ? | <filename skeleton 1>
TO <new table name> | ? | <filename skeleton 2>
[ [TYPE] PARADOX | DBASE]

<old table name> | ? | <filename skeleton>

Table you want to rename. RENAME TABLE ? and RENAME TABLE <filename skeleton> display a dialog box, from which you can select a table file. If you specify a file without including its path, dBASE for Windows looks for the file in the current directory, then in the path you specify with SET PATH. If you specify a file without including an extension or specifying its type, dBASE for Windows assumes the file type specified with the SET DBTYPE command.

You can also rename a table in a database (defined using the IDAPI Configuration Utility) by specifying the database as a prefix (enclosed in colons) to the name of the table, that is, :database name:table name. If the database is not already open, dBASE for Windows displays a dialog box in which you specify the parameters, such as a login name and password, necessary to establish a connection to that database.

<new table name> | ? | <filename skeleton 2>

New name of the table. If you rename a table in a database, you must specify the same database as the destination of the new table. Also, the new table name must be the same type as the old table. The ? and <filename skeleton> options display a dialog box, in which you specify the name of the target table and the directory to save it in.

[TYPE] PARADOX | DBASE

Specifies the type of table you want to rename, which can be a Paradox or dBASE table.

Description

Use the RENAME TABLE command to change the name of a table without exiting to the operating system. You cannot rename an open table, and the new table name cannot already exist in the same directory or database.

If you rename a table that has associated files (such as memo or index files), those files are also automatically renamed to match the new table name.


RENAME TABLE Example

The following example uses RENAME TABLE to change the name of a closed table:

dbf_file = "FLIGHTS.DBF"
IF SELECT() > 1
   area = 1
   go_on = .T.
   DO WHILE area < SELECT() .AND. go_on
      SELECT (area)
      IF dbf_file = DBF()
         go_on = .F.
      ENDIF
      area = area + 1
   ENDDO
ENDIF
IF go_on
   RENAME TABLE &dbf_file TO AllFlts.DBF
ENDIF


Portability

Not supported in dBASE IV or dBASE III PLUS.


See Also

CLOSE...

COPY

COPY FILE

USE


REPLACE

See Also	Example	Fields and Records

Replaces the contents of specified fields in the current table with data from specified expressions.

Syntax

REPLACE
<field 1> WITH <exp 1> [ADDITIVE]
[, <field 2> WITH <exp 2> [ADDITIVE] ...]
[<scope>]
[FOR <condition 1>]
[WHILE <condition 2>]
[REINDEX]

<field 1> WITH <exp 1>

Designates fields to be replaced by data in specified expressions. Multiple fields of a record may be changed by including additional <field n> WITH <exp n> expressions, separated by commas.

ADDITIVE

Adds text to the end of memo field text instead of replacing existing text. You can use ADDITIVE only when the specified field is a memo field in a dBASE table.

<scope>

The number of records to replace. RECORD <n> identifies a single record by its record number. NEXT <n> identifies n records, beginning with the current record. ALL specifies all records. REST specifies all records from the current record to the end of the file.

FOR <condition 1>
WHILE <condition 2>

Determines which records are affected by the REPLACE command. A FOR clause restricts REPLACE to records that meet <condition 1>. WHILE starts processing with the current record and continues with each subsequent record as long as <condition 2> is true.

REINDEX

Specifies that all affected indexes are rebuilt once the REPLACE operation finishes.

Description

The REPLACE command overwrites a specified field with new data. The field you select can be any type, including memo fields. (To replace binary or OLE fields, use REPLACE BINARY and REPLACE OLE, respectively.) The field and the expression specified by the WITH clause must have the same data type. In numeric fields, the WITH expression can be larger than the field width, in which case, the number is displayed in scientific notation. In converting memo fields to character fields, REPLACE truncates the data to fit in the assigned field width.

To change multiple fields, include additional <field n> WITH <exp n> expressions, one for each field. When <scope>, WHILE, or FOR options are used, data is replaced in all records within the scope and all records that match specified conditions.

Use the ADDITIVE option to add a character string to the end of existing memo field text. You can leave a blank space at the beginning of the string to provide proper spacing.

Be careful when replacing data in a table with a master index open when you are also using the <scope>, WHILE, or FOR options. dBASE for Windows automatically updates all open index files after a REPLACE operation finishes. After replacing data that changes the value in the key field in the master index, the record and the record pointer immediately move to the position in the index based on the new value of a key. If replacement in the key field causes a record (and the the pointer) to move down past other records that fall within the scope or meet the specified conditions, those records are not replaced. To make replacements to an indexed table's key field, first close the index and update the data, and then reopen the index using SET INDEX, and update the index using REINDEX.

Replacements in fields other than the key field of the master index do not affect the order of the index and can be made with <scope>, WHILE, or FOR without complications.

When replacing a numeric or float value, the new value length cannot exceed the field width; otherwise, dBASE returns a numeric overflow message. The field contents are replaced with an approximation to the new value in scientific notation, if it will fit; otherwise the field contents are replaced with asterisks, destroying stored data.

REPLACE alters data in fields of the current table unless you use alias->field to specify a field in an alias table.

If no relation has been set from the current table, you can replace only the current record in the alias table. If a relation has been set, you can use <scope>, FOR <condition 1>, or WHILE <condition 2> to replace multiple records in the alias table.

REPLACE with no options substitutes <exp 1> for the contents of <field 1> in the current record only.

An entered expression must be of the same data type as the contents of the field it is replacing, except in the case of a memo field, which can be replaced by a character expression.


REPLACE Example

The following example uses REPLACE to change or enter data in TEMP.DBF, which is a copy of Clients table:

SET SAFETY OFF
USE Clients EXCLUSIVE
INDEX ON Client_ID TAG Client_ID
COPY TO Temp.DBF
USE Temp
REPLACE ALL Company with PROPER(Company)
* If entered in all uppercase, changes to upper/lower
* case.
REPLACE ALL State_Prov with UPPER(State_Prov)
* Makes two-letter state codes all  uppercase if
* entered in upper/lower case.
REPLACE ALL Phone with STUFF(Phone,AT("-",Phone),1,;
    "*")
* Substitutes an asterisk for the hyphen in the Phone
* field.
REPLACE ALL NOTES with "Georgia state tax applies";
    ADDITIVE  FOR State_Prov="GA"
* Places the text sting in the Notes memo field of
* each Georgia record.
GO TOP
BROWSE
CLOSE ALL
SET SAFETY ON


See Also

APPEND

BLANK

BROWSE

CHANGE

EDIT

REINDEX

REPLACE AUTOMEM

REPLACE BINARY

REPLACE MEMO

REPLACE OLE

SET RELATION

UPDATE


REPLACE AUTOMEM

See Also	Example	Portability	Fields and Records

Transfers contents of memory variables into corresponding fields of the current record in the current table.

Syntax

REPLACE AUTOMEM

Description

Automem variables are memory variables that have the same name, data type, and length as the corresponding fields of the current table. Automem variables are used to hold data that will be stored in the fields of records. You can manipulate data stored in automem variables as memory variables rather than as field values, and you can validate the data before storing the data to a table.

Create a set of automem variables for the fields in a table with USE...AUTOMEM, CLEAR AUTOMEM, or STORE AUTOMEM. To add new records to a table and fill the fields with values from corresponding automem variables, use APPEND AUTOMEM or INSERT AUTOMEM. To update the fields of existing records with values from corresponding automem variables, use REPLACE AUTOMEM.

Use REPLACE AUTOMEM to update all the fields of a record without having to name the fields. By contrast, with the REPLACE command, you need to name every field you want updated.

Remember that an automem variable and its corresponding field have the same name. When a command allows an argument that could be either a memory variable or a field, dBASE for Windows assumes the argument refers to a field. To distinguish the memory variable from the field, prefix the names of automem variables with m->.

REPLACE AUTOMEM updates the current record. It cannot update all records within a specified scope or all records matching a condition, as the REPLACE command can with the options <scope>, FOR <condition>, and WHILE <condition>.

REPLACE AUTOMEM does not replace field data with data from a memory variable with the same name but of a different data type. If you try to make such a replacement, dBASE for Windows displays an error message.


REPLACE AUTOMEM Example

The first portion of this example creates a copy of Clients table that is then given to a branch office or different department for changes:

USE Clients EXCLUSIVE
INDEX ON SUBSTR(Client_ID,1,1)+ ;
  SUBSTR(Client_ID,2,4) TAG Client_ID
COPY TO Branch1 FOR State_Prov = "CA"
! COPY Branch1.DBF B:   && Copies to diskette

After Branch1.DBF has been updated or changed and you wish to have these changes reflected in the master Clients table, the following program uses REPLACE AUTOMEM to transfer current field values in Branch1.DBF to the Clients table:

SET TALK OFF
SET EXACT OFF
USE Clients EXCLUSIVE
INDEX ON SUBSTR(Client_ID,1,1)+ ;
  SUBSTR(Client_ID,2,4) TAG Client_ID
USE Branch1 IN 2
SELECT 2
GO TOP
DO WHILE .NOT. EOF()
  CLEAR AUTOMEM
  STORE AUTOMEM
* Field values in current (Branch1) record stored
* to AUTOMEM variables
  Look = SUBSTR(Client_ID,1,1)+;
    SUBSTR(Client_ID,2,4)
  SELECT 1              && switch to Clients table
  SEEK Look             && locate matching Client_ID
  IF FOUND()
    REPLACE AUTOMEM     && update Clients to Branch1
  ENDIF
  SELECT 2              && back to Branch1.DBF
  SKIP                  && increment record pointer
ENDDO
SELECT 1                && Check results by Browsing
GO TOP                  && Clients table
BROWSE
CLOSE ALL
RETURN


Portability

Not supported in dBASE IV or dBASE III PLUS.


See Also

APPEND AUTOMEM

CLEAR AUTOMEM

INSERT AUTOMEM

REPLACE

STORE AUTOMEM

USE


REPLACE BINARY

See Also	Example	Portability	Fields and Records

Replaces the contents of a binary field with the contents of another binary file.

Syntax

REPLACE BINARY <binary field name>
FROM <filename> | ? | <filename skeleton>
[TYPE <binary type user number>]

<binary field name>

The binary field of the current table that is replaced by the contents of <filename>.

FROM <filename> | ? | <filename skeleton>

Specifies the file to copy to the binary field in the current record. If you specify a file without including its path, dBASE for Windows looks for the file in the current directory, then in the path you specify with SET PATH. If you specify a file without including its extension, dBASE for Windows assumes a .BMP extension; however, the file may also include types such as .BMP, .PCX, and .WAV files. The ? and <filename skeleton> options display a dialog box, in which you specify the file to copy.

TYPE <binary type user number>

Specifies a number that can be used to identify the type of binary data being stored. Use the BINTYPE( ) function to retrieve the type number. The range is from 1 to 32K-1 for user-defined file types and 32K to 64K -1 for predefined types (although any number may be specified within the allowable range).

Predefined binary type numbers	Description
1 to 32K -1 (32,767)	User-defined file types
32K (32,768)	.WAV files
32K + 1 (32,769)	.BMP and .PCX files
Description

Use REPLACE BINARY to copy a binary file to the current record's binary field. You can copy one binary file to each binary field of each record in a table.

While dBASE memo fields may contain types of information other than text, binary fields are recommended for storing images, sound, or any other binary or BLOB type data.


REPLACE BINARY Example

The following example uses COPY BINARY to copy the Boa bitmap from ANIMALS.DBF to a file named BOA.BMP. COPY STRUCTURE creates a new table with an identical structure but no records. APPEND BLANK adds a new, blank record and REPLACE BINARY copies the contents of BOA.BMP into the field Bmp of record number one of ANIM2.DBF:

CLOSE ALL
USE Animals
GOTO 2
COPY BINARY Bmp TO Boa.BMP
COPY STRUCTURE TO Anim2
USE Anim2
b=2**15+1   && 32k+1 for type .BMP
APPEND BLANK
REPLACE BINARY Bmp FROM "Boa.BMP" TYPE b
EDIT
* In edit, User can now click on Bmp and see the Boa


Portability

Not supported in dBASE IV or dBASE III PLUS.


See Also

APPEND MEMO

BINTYPE( )

COPY BINARY

REPLACE MEMO

REPLACE MEMO...FROM

REPLACE OLE

RESTORE IMAGE


REPLACE FROM ARRAY

See Also	Example	Portability	Fields and Records

Transfers data stored in an array to the fields of the current record of a table.

Syntax

REPLACE FROM ARRAY <array name>
[<scope>]
[FOR <condition 1>]
[WHILE <condition 2>]
[FIELDS <field list>]
[REINDEX]

<array name>

The name of the array that you want to transfer data from.

<scope>

The number of records to replace with the data stored in the specified array. RECORD <n> identifies a single record by its record number. NEXT <n> identifies n records, beginning with the current record. ALL specifies all records. REST specifies all records from the current record to the end of the file.

FOR <condition 1>
WHILE <condition 2>

Determines which records are affected by REPLACE FROM ARRAY. FOR restricts REPLACE FROM ARRAY to records that meet <condition 1>. WHILE starts processing with the current record and continues with each subsequent record as long as <condition 2> is true.

FIELDS <field list>

Restricts data replacement to the fields specified by <field list>.

REINDEX

Specifies that all non-master indexes are rebuilt once the REPLACE FROM ARRAY operation finishes.

Description

Use REPLACE FROM ARRAY to transfer values from an array into fields of the current table. The number specified by the last array subscript corresponds to the number of fields you can replace. The number specified by the next-to-last subscript of the array corresponds to the number of records you can replace.

When you use REPLACE FROM ARRAY with no options or just the FIELDS option, dBASE for Windows replaces field values starting at the current record. With a multidimensional array, if there are more records than specified by the next-to-last array subscript, dBASE for Windows replaces record data until it runs out of array values.

Use a one-dimensional array to replace field values in one record. For example, if you use DECLARE sample[3], a one-dimensional array, the command line REPLACE FROM ARRAY sample replaces up to three fields in one record.

Use a two-dimensional array to replace the field values in more than one record. A two-dimensional array is like a table with rows corresponding to records and columns corresponding to fields. For instance, if you use DECLARE sample[2,3], the command line REPLACE FROM ARRAY sample replaces up to three fields in two records.

The data types of the array must match those of corresponding fields in the table you are replacing. If the data type of an array element and a corresponding field do not match, dBASE for Windows returns an error.


REPLACE FROM ARRAY Example

The following example creates an array with 3 elements and copies 3 field values to the array for display and possible editing. If the user chooses to edit the array values, REPLACE FROM ARRAY is used to copy the altered field values back to the same record in the table.

DECLARE CompArray[3]
* Create an array with three elements
CLOSE DATABASES
ON ESCAPE RETURN
USE Company
SET FIELDS TO Company, Phone, CompCode
DO WHILE .NOT. EOF()
  COPY TO ARRAY CompArray FIELDS Company, Phone,;
    CompCode NEXT 1
  CLEAR
  ? "Company", "Phone" AT 30, "CompCode" AT 50
  ? "*******", "*****" AT 30, "********" AT 50
  ? CompArray[1], CompArray[2] AT 30, CompArray[3];
    AT 50
  ?
  ?
  ACCEPT "Entry Correct? (Y/N) " TO Chc
  IF UPPER(Chc)="N"
    @ 10,5 SAY "Enter Company " GET CompArray[1]
    @ 11,5 SAY "Enter Phone   " GET CompArray[2]
    @ 12,5 SAY "Enter CompCode" GET CompArray[3]
    READ
    REPLACE FROM ARRAY CompArray
  ENDIF
  SKIP
ENDDO
CLOSE DATABASES


Portability

Not supported in dBASE III PLUS.


See Also

APPEND FROM ARRAY

COPY TO ARRAY

DECLARE


REPLACE MEMO

See Also	Example	Portability	Fields and Records

Replaces the text of a memo field with the contents of an array.

Syntax

REPLACE MEMO <memo field> WITH ARRAY <array name>
[ADDITIVE]

<memo field>

The memo field where text from an array is stored.

WITH ARRAY <array name>

The array whose contents replace the text in a memo field.

ADDITIVE

Causes the new text to be appended to existing text. REPLACE MEMO without the ADDITIVE option causes dBASE for Windows to overwrite any text currently in the memo field.

Description

Use the REPLACE MEMO command to replace the text of a memo field with the contents of an array. Each element of <array name> contains the data to add one line to the specified memo field. After you store text in the elements of the array, use REPLACE MEMO to store that data in a memo field.

REPLACE MEMO, when used with STORE MEMO, lets you include the text of a memo field on a data-entry screen displaying the text from automem variables and then stores the changes back into the memo field when you have finished editing.

To add text to existing text or to an empty memo field, store empty character values to an array instead of using STORE MEMO. Add text to the array and then use REPLACE MEMO, including ADDITIVE if you do not want to overwrite existing text.


REPLACE MEMO Example

The following example declares an array with an element for each field in Clients table, copies the contents of record number 4 to the array, and then uses REPLACE MEMO to place the contents of array Move into the memo field of record number 10:

SET TALK OFF
USE Clients
DECLARE Move[FLDCOUNT()]
GOTO 4
COPY TO ARRAY Move
GOTO 10
REPLACE Notes WITH CHR(13) + ;
  "Cross Reference: " && Overwrites prior entries
REPLACE MEMO Notes WITH ARRAY Move ADDITIVE
? Notes               && Displays Notes contents


Portability

Not supported in dBASE IV or dBASE III PLUS.


See Also

APPEND MEMO

DECLARE

REPLACE

REPLACE FROM ARRAY

REPLACE MEMO...FROM

STORE MEMO


REPLACE MEMO...FROM

See Also	Example	Portability	Fields and Records

Inserts a text file in a memo field.

Syntax

REPLACE MEMO <memo field>  FROM <filename> | ? | <filename skeleton>
[ADDITIVE]

<memo field>

The memo field where a text file is inserted.

FROM <filename> | ? | <filename skeleton>

The file that identifies a text file. The ? and <filename skeleton> options display a dialog box where you can specify the file whose content you want to copy to the memo field.

ADDITIVE

Causes the new text to be appended to existing text. REPLACE MEMO without the ADDITIVE option causes dBASE for Windows to overwrite any text currently in the memo field.

Description

Use the REPLACE MEMO...FROM command to insert a text file into a memo field. You can insert one text file to each memo field of each record in a table.

While dBASE memo fields may contain types of information other than text, binary fields are recommended for storing images, sound, and other user-defined binary type information. Use OLE fields for linking to OLE documents from other Windows applications.


REPLACE MEMO...FROM Example

In this example, the Customer file is scanned. If there is a file of the form CUST????.DOC, where ???? is the 4 character company code, then REPLACE MEMO...FROM copies the file into the Notes memo field:

CLOSE ALL
USE Customer
SCAN
  FN="Cust"+Compcode+".Doc"
  IF FILE("&FN")
    REPLACE MEMO Notes FROM &FN
  ELSE
    BLANK FIELD Notes
  ENDIF
ENDSCAN


Portability

Not supported in dBASE IV or dBASE III PLUS.


See Also

COPY MEMO

REPLACE BINARY

REPLACE MEMO

REPLACE OLE


REPLACE OLE

See Also	Example	Portability	Fields and Records

Inserts an OLE document into an OLE field.

Syntax

REPLACE OLE <OLE field name>
FROM <filename>  | ? | <filename skeleton>
[LINK]

<OLE field name>

The field where an OLE document is inserted.

FROM <filename> | ? | <filename skeleton>

The file that identifies an OLE document, including its extension. If you specify a file without including its path, dBASE looks for the file in the current directory, then in the path you specify with SET PATH. The ? and <filename skeleton> options display a dialog box where you can specify the file whose content you want to copy to the OLE field.

LINK

LINK provides a pointer to the OLE document. By default, dBASE embeds the OLE document in the specified OLE field.

Description

Use REPLACE OLE to insert the contents of an OLE document into an OLE field. You can either embed the actual OLE document in an OLE field (the default) or access the OLE document by linking it to the OLE field.

If you link the OLE document, the OLE field contains only a reference to the OLE document. As long as the OLE document remains in the same location, the OLE field displays the most current version of the document.

If you embed the OLE document, the OLE field contains a copy of the document. There are no links between the field and the OLE document; therefore, any changes to the original version of the OLE document are not reflected in the embedded document.


REPLACE OLE Example

The following example demonstrates REPLACE OLE. It adds a new record to the Pictures table. The Name field is replaced with "AirBrlnd" and the bitmap file AIRBRLND.BMP is placed in the BitMapOle field:

USE Pictures
APPEND BLANK
REPLACE Name WITH "AirBrlnd"
REPLACE OLE BitMapOle FROM "AirBrlnd.BMP"

If you have AIRBRLND.BMP you can examine this record with EDIT or BROWSE and click on the BitMapOle field.


Portability

Not supported in dBASE IV or dBASE III PLUS.


See Also

CLASS OLE

DEFINE


REPLICATE( )

See Also	Example	Portability	String Data

Returns a string repeated a specified number of times.

Syntax

REPLICATE(<expC> | <memo field>, <expN>)

<expC> | <memo field>

The string or memo field to repeat.

<expN>

The number of times to repeat the string or memo field.

Description

REPLICATE( ) returns a character string composed of a character expression or memo field repeated a specified number of times. dBASE displays an error if the resulting string exceeds 32766 characters. Therefore, the number of repeats you specify must be less than 32766 divided by the number of characters in the character expression or memo field.

If the character expression is an empty string or the memo field is empty, REPLICATE( ) returns an empty string. If the number of repeats you specify for <expN> is 0, REPLICATE( ) returns an empty string. If <expN> is less than 0, dBASE displays an error.

To repeat space characters, use SPACE( ).


REPLICATE( ) Example

The following example uses REPLICATE( ) to create different strings of characters:

? REPLICATE("+",10)           && Returns "++++++++++"
? REPLICATE("",10)            && Returns ""
? REPLICATE("-",10)           && Returns "----------"
? REPLICATE("dBASE",2)        && Returns "dBASEdBASE"
a_s = REPLICATE("A",32766)
? LEN(a_s)                    && Returns 32766
? REPLICATE("dBASE for Windows!",1820)
* 32766/18 characters in the string = 1820 times


Portability

The <memo field> argument is not supported in dBASE IV or dBASE III PLUS. Both dBASE IV and dBASE III PLUS limit the return value of REPLICATE( ) to 254 characters.


See Also

SPACE( )


REPORT FORM

See Also	Example	Portability	Input/Output

Generates and displays or prints a report, using the report format stored in a specified report file and information derived from records in the current table.

Syntax

REPORT FORM <filename 1> | ? | <filename skeleton 1>
[<scope>] [FOR <condition 1>] [WHILE <condition 2>]
[CROSSTAB]
[HEADING <expC>]
[NOEJECT]
[PLAIN]
[SUMMARY]
[TO FILE <filename 2> | ? | <filename skeleton 2>] | [TO PRINTER]

<filename 1> | ? | <filename skeleton>

The report format file to use. The ? and <filename skeleton> options display a dialog box from which you can select a file. If you specify a file without including its path, dBASE looks for the file in the current directory, then in the path you specify with SET PATH. If you specify a file without including its extension, dBASE looks for .RPT, .FRG, or .FRM, in that order. If you specify CROSSTAB, dBASE looks for .RPC, .FRG, or .FRM in that order.

<scope>

The number of records to derive the report from. RECORD <n> identifies a single record by its record number. NEXT <n> identifies n records, beginning with the current record. ALL specifies all records. REST specifies all records from the current record to the end of the file.

FOR <condition 1>
WHILE <condition 2>

Determines which records are affected by REPORT FORM. FOR restricts REPORT FORM to records that meet <condition 1>. WHILE starts processing with the current record and continues with each subsequent record as long as <condition 2> is true.

CROSSTAB

Specifies that the report was created with the Cross-Tab dialog box.

HEADING <expC>

Adds a character expression, <expC>, as the heading of each page. HEADING has no effect if used with PLAIN.

NOEJECT

Prevents a page feed before printing begins.

PLAIN

Suppresses page numbers and dates on the pages of the report. Any title appears only on the first page.

SUMMARY

Includes only the totals of groups and subtotals of subgroups, excluding the individual contents of records within each group and subgroup. The report format defines groups and subgroups.

TO FILE <filename 2> | ? | <filename skeleton>

Directs output to the text file <filename 2>. By default, dBASE assigns a .TXT extension to <filename 2> and saves the file in the current directory. The ? and  <filename skeleton> options display a dialog box in which you specify the name of the target file and the directory to save it in.

TO PRINTER

Directs output to the printer.

Description

Use REPORT FORM to print or display reports in a format that you have defined in the Report Designer using CREATE REPORT or MODIFY REPORT. For information about using the Report Designer, see Designing Reports and Labels or the Crystal Reports documentation. If you do not specify a <scope>, WHILE <condition 1>, or FOR <condition 2> option, REPORT FORM prints the report specifications for each record in record number or index order.

When printing or displaying a report that includes groups of data or group subtotals, the current table must either be in sorted order or its master index must be in use. The sorted file or index must be arranged according to the value of the field on which the data is grouped.

REPORT FORM without the TO FILE or TO PRINTER options displays the report in the Command window or current user-defined window.


REPORT FORM Example

This example opens the Company database and then generates a report using the Comprep1 report definition:

CLOSE DATABASE
USE Company
REPORT FORM Comprep1 TO PRINT


Portability

The <filename skeleton> option is not supported in dBASE IV or dBASE III PLUS.


See Also

CREATE REPORT


RESOURCE( )

See Also	Example	Portability	Windows Programming

Returns a character string from a DLL file.

Syntax

RESOURCE(<resource id>, <DLL filename expC>)

<resource id>

A numeric value that identifies the character string resource.

<DLL filename>

The name of the DLL file.

Description

Use RESOURCE( ) to generate a character string from a resource in a DLL file. The character string must be less than 32K; a character string longer than this is truncated.

RESOURCE( ) is often useful for internationalizing applications without changing program code. For example, you can store in a DLL file all character strings that might need translation from one language to another, and your application can retrieve them at run time with the RESOURCE( ) function. To modify the application for another language, translate the strings and store them in a new DLL file, in the same order and with the same resource IDs as their counterparts in the original DLL file. Then substitute the new DLL for the original one. For more information on DLL files, see EXTERN, LOAD DLL, and Chapter 25 in the Programmer's Guide.


Portability

Not supported in dBASE IV or in dBASE III PLUS.


RESOURCE( ) Example

This example shows how RESOURCE( ) can be used to change languages for international development:

#define ENGLISH 1
#define SPANISH 2
ApLanguage = SPANISH
MyGreeting = RESOURCE(SPANISH,"greeting.dll")
CLEAR
? MyGreeting


See Also

EXTERN

LOAD DLL

RELEASE DLL


RESTORE

See Also	Example	Portability	Memory Variables

Copies the memory variables stored in the specified disk file to active memory.

Syntax

RESTORE FROM <filename> | ? | <filename skeleton>
[ADDITIVE]

<filename> | ? | <filename skeleton>

The file of memory variables to restore. RESTORE FROM ? and RESTORE FROM <filename skeleton> display a dialog box, from which you can select a file. If you specify a file without including its path, dBASE looks for the file in the current directory, then in the path you specify with SET PATH. If you specify a file without including its extension, dBASE assumes .MEM.

ADDITIVE

Preserves existing memory variables when RESTORE is executed.

Description

Use RESTORE with SAVE to retrieve and store important memory variables. By default, all private variables are cleared at the end of execution of the program file that created them, while all public variables are cleared when you exit dBASE. To preserve these values for future use, store them in a memory file by using SAVE. You can then retrieve these values later by using RESTORE.

Without the ADDITIVE option, RESTORE clears all existing user memory variables before returning to active memory the variables stored in a memory file. Use ADDITIVE when you want to restore a set of variables while retaining those already in memory.

Note:	If you use ADDITIVE and a restored variable has the same name as an existing variable, the restored variable will replace the existing one.

If you issue RESTORE in the Command window, dBASE makes all restored variables public. When dBASE encounters RESTORE in a program file, it makes all restored variables private to that program.


RESTORE Example

The following example stores Company name to the variable Start when the user exits a BROWSE. The value in Start is then saved to an external .MEM file with the SAVE command. The next time the program is run, RESTORE FROM is used to recover the variable Start, and SEEK positions the record pointer to the appropriate Company so BROWSE can be resumed at the former location:

SET TALK OFF
SET SAFETY OFF
USE Clients EXCLUSIVE
INDEX ON Company TAG Company
IF FILE("Lst_Look.MEM")
  RESTORE FROM Lst_Look       && Recover Start
  SEEK Start
  BROWSE
ELSE
  GO TOP
  BROWSE
ENDIF
STORE Company TO Start
SAVE TO Lst_Look.MEM
CLOSE ALL
SET TALK ON
SET SAFETY OFF


Portability

The ? and <filename skeleton> arguments are not supported in dBASE IV or dBASE III PLUS.


See Also

CLEAR MEMORY

RELEASE

SAVE

SET PATH

STORE


RESTORE IMAGE

See Also	Example	Portability	Objects

Displays an image stored in a file or a binary field.

Syntax

RESTORE IMAGE FROM
<filename> | ? | <filename skeleton> | BINARY <binary field>
[TIMEOUT <expN>]
[TO PRINTER]
[[TYPE] PCX]

FROM <filename> | ? | <filename skeleton> | BINARY <binary field>

Identifies the file or binary field to restore the image from. RESTORE IMAGE FROM ? and RESTORE IMAGE FROM <filename skeleton> display the Open Source File dialog box, which lets the user select a file. <filename> is the name of an image file; RESTORE IMAGE assumes a .BMP extension and file type unless you specify otherwise. If you specify a file without including its path, dBASE looks for the file in the current directory, then in the path you specify with SET PATH. RESTORE IMAGE FROM BINARY <binary field> displays the image stored in a binary field. You store an image in a binary field with the REPLACE BINARY command.

TIMEOUT <expN>

Specifies the number of seconds the image is displayed onscreen.

TO PRINTER

Sends the image to the printer as well as to the screen.

[TYPE] PCX

Specifies an image stored in PCX format, and assumes a .PCX file-name extension if none is given. The word TYPE is optional.

Description

Use RESTORE IMAGE to display a graphic image that was generated and saved in bitmap or PCX format. The image is displayed in a window.

Note:	Your computer must have a graphics adapter to display an image.

To print an image with the TO PRINTER option, you must have a printer that can process and print graphic data.


RESTORE IMAGE Example

The following example defines a form and list box for selection of an aircraft model and uses RESTORE IMAGE to display a graphic from the memo field Image of the selected record:

CLOSE ALL
SET TALK OFF
USE Aircrdb ORDER Aircraft IN SELECT()
SELECT Aircrdb
DEFINE FORM AC               ;
   PROPERTY                  ;
      Top 5,                 ;
      Left 2,                ;
      Height 13,             ;
      Width 30,              ;
      Text "Aircraft",       ;
      Sizeable .T.,          ;
      OnSelection Photo
DEFINE LISTBOX Model OF AC             ;
   PROPERTY                            ;
      Top 2,                           ;
      Left 10,                         ;
      Height 7,                        ;
      Width 18,                        ;
      DataSource "FIELD Aircrdb->Aircraft"
OPEN FORM AC

FUNCTION Photo
RESTORE IMAGE FROM BINARY Image
RETURN .T.


Portability

Not supported in dBASE IV or dBASE III PLUS.


See Also

DEFINE

REPLACE BINARY


RESTORE SCREEN

See Also	Example	Portability	Input/Output

Redisplays in the results pane of the Command window its previous contents saved with SAVE SCREEN. This command is supported primarily for compatibility with dBASE IV.

Syntax

RESTORE SCREEN
[FROM <memvar> |
FROM FILE <filename> | ? | <filename skeleton>]

FROM <memvar>

Displays the Command window contents saved to the memory variable <memvar> with SAVE SCREEN TO <memvar>.

FROM FILE <filename> | ? | <filename skeleton>

Displays the Command window contents saved to the file <filename> with SAVE SCREEN TO FILE. The ? and <filename skeleton> options display a dialog box, from which you can select a file. If you specify a file without including its path, dBASE looks for the file in the current directory, then in the path you specify with SET PATH. If you specify a file without including its extension, dBASE assumes .SCN.

Description

RESTORE SCREEN is a companion command to SAVE SCREEN. Use SAVE SCREEN to save the contents of the results pane of the Command window and RESTORE SCREEN to restore these saved contents back to the results pane of the Command window. RESTORE SCREEN overwrites the current contents of the results pane of the Command window with the saved Command window contents you specify.

Use RESTORE SCREEN without any arguments to restore the contents of the results pane of the Command window saved in the Command window buffer. See the description of SAVE SCREEN for information on how to save the Command window contents to its buffer in memory.


RESTORE SCREEN Example

See SAVE SCREEN for an example of RESTORE SCREEN.


Portability

Not supported in dBASE III PLUS. In dBASE IV, RESTORE SCREEN applies to the entire screen; FROM <memvar> is a required option; and the FROM FILE option isn't supported.


See Also

CLEAR SCREENS

RELEASE SCREENS

SAVE SCREEN

SET PATH


RESTORE WINDOW

See Also	Example	Portability	dBASE IV Windows

Extracts window definitions from a window file and loads them in memory. This command is supported primarily for compatibility with dBASE IV. In dBASE for Windows, run the program, procedure, or library file that contains stored form definitions.

Syntax

RESTORE WINDOW <window name list> | ALL
FROM <filename> | ? | <filename skeleton>

<window name list> | ALL

Identifies which windows are restored from the window file. <window name list> identifies one or more windows by name. ALL specifies all windows stored in the file.

FROM <filename> | ? | <filename skeleton>

Identifies the file you want to restore the window from. RESTORE WINDOW ? and RESTORE WINDOW <filename skeleton> display the Open Source File dialog box, from which you can select a file. <filename> is the name of a window file; dBASE assumes a .WIN extension unless you specify otherwise. If you specify a file without including its path, dBASE looks for the file in the current directory, then in the path you specify with SET PATH.

Description

Use RESTORE WINDOW to load window definitions from a window file into memory. The windows can then be displayed and enabled with ACTIVATE WINDOW. To save window definitions in a window file, use SAVE WINDOW.

Since saving an open window with SAVE WINDOW also saves window contents, you can extract and redisplay a window containing static information, such as a menu or a message, without having to recreate the window each time. If the window contained active GETs or other UI objects, however, RESTORE WINDOW does not reactivate them; only the image is restored.

RESTORE WINDOW overwrites an existing window definition in memory when the existing window has the same name as a restored window.


RESTORE WINDOW Example

See SAVE WINDOW for an example of RESTORE WINDOW.


Portability

Not supported in dBASE III PLUS. The ? and <filename skeleton> options are not supported in dBASE IV.


See Also

ACTIVATE WINDOW

CLEAR WINDOWS

DEFINE

OPEN FORM

READMODAL( )

SAVE WINDOW


RESUME

See Also	Example	Error Handling and Debugging

Restarts program execution at the command line following the one at which program execution was suspended.

Syntax

RESUME

Description

RESUME causes dBASE to resume execution of a program that is suspended. You can suspend program execution by issuing SUSPEND. If you have not assigned a value to ON ERROR, you can also choose to suspend a program when an error occurs.

To restart program execution, enter RESUME in the Command window. The program file resumes execution at the line immediately following the line that caused it to become suspended. If you want to re-execute the line that caused an error, perhaps because you fixed the condition that caused the error, retype the program line at the command line before issuing RESUME.


RESUME Example

See SUSPEND for and example of how to use RESUME after a SUSPEND command has been executed in a program.


See Also

CANCEL

ON ERROR

RETRY

RUN

SUSPEND


RETRY

See Also	Example	Error Handling and Debugging

Returns control from a subroutine to the command line of the calling routine or Command window that called the subroutine.

Syntax

RETRY

Description

Use RETRY to re-execute a command--for example, one that resulted in an error. RETRY returns program control to the calling command. RETRY clears the memory variables created by the subroutine.

RETRY is valid only in program files.

You can use RETRY with ON ERROR to give the user more chances to resolve an error condition. Using RETRY with ON ERROR resets ERROR( ) to zero.


RETRY Example

The following example uses the Recover procedure when an error is detected with ON ERROR. If the Clients table is already open in another work area when the USE command is executed, an error is returned. The Recover procedure uses CLOSE DATABASES to insure that all tables are closed and RETRY returns program flow to the USE command:

ON ERROR DO Recover
USE Clients EXCLUSIVE
BROWSE
ON ERROR
CLOSE DATABASES

PROCEDURE Recover
WAIT "An error has occurred.;
  Press any key to retry.."
CLOSE DATABASES
RETRY


See Also

ERROR( )

MESSAGE( )

ON ERROR

RESUME

RETURN


RETURN

See Also	Example	Portability	Programs

Ends execution of a program, procedure, or user-defined function (UDF), returning control to a calling routine--program, procedure, or UDF--or to the Command window.

Syntax

RETURN
[<return exp> | TO MASTER | TO <routine name>]

<return exp>

The value a procedure UDF returns to the calling routine or the Command window. RETURN <return exp> must be the last line in a procedure or UDF definition; <return exp> is required for UDFs.

TO MASTER

Returns control to the highest-level calling routine or to the Command window. As one routine calls another, each goes onto the call stack, a list of pending routines and subroutines. TO MASTER returns to the bottom routine in the stack (the master procedure), terminates all subroutines in the call stack, and releases all nonpublic variables at each level.

If RETURN TO MASTER executes in the master procedure, control returns to the Command window. If the call stack started from a suspended prompt in the Command window, control returns to the suspended prompt.

TO <routine name>

Returns control to the specified calling routine, terminating all intervening subroutines on the call stack and releasing those subroutines' non-public variables. (See the previous description of TO MASTER for an explanation of call stack.)

dBASE handles special cases as follows:

If <routine name> is the name of the current routine, a regular RETURN occurs.

If <routine name> occurs more than once in the call stack, control passes to the routine by that name that is closest in the stack (the one that made the most recent call).

If <routine name> is master, the TO MASTER option takes precedence and returns control to the highest-level calling routine.

If <routine name> is not in the call stack, RETURN causes a run-time error.

Description

When a procedure ends, dBASE automatically returns to the calling routine. You can use RETURN in procedures to return from a point in the procedure other than its end. You must use RETURN at the end of UDFs to return the result (the return value) of the UDF.

Use RETURN in programs to restore control to calling routines or to the Command window. Command processing generally resumes as follows:

If the routine is called with a DO statement, command processing continues at the line following the DO statement.

If the routine is a UDF called directly as a command or as part of an expression (not with DO), command processing continues in the statement containing the call.

If you use the TO MASTER or TO <routine name> options of the RETURN command, command processing continues with the next command line after the last one executed in MASTER or <routine name>.

RETURN does all of the following:

Releases all non-public memory variables defined in the routine returned from (and in any intervening routines on the call stack), but does not affect public variables or the values of static variables in that routine

Sets the ERROR( ) function to 0

Changes scope--cognition of which private, local, and static system variables are in effect and what their values are--to that of the routine returned to, restoring previous values of private, local, and static system variables for that routine

You can also use CANCEL to end execution of a routine, but CANCEL always returns control to the Command window.


RETURN Example

The following examples show various uses RETURN. In GetOut you can RETURN to the main program or to an open procedure. The RETURN in IsReady( ) shows a value being returned.

DO PrintTo With "LPT1:"
DO GetOut With .t.
DO GetOut With .f.
Answer= IsReady()

PROCEDURE PrintTo
PARAMETER OutPutDev
* ...
RETURN

PROCEDURE GetOut
Parameter Done
IF Done
   RETURN TO MASTER
ELSE
   RETURN TO ReportMenu
ENDIF

FUNCTION IsReady
RETURN .T.


Portability

The <return exp> and TO <routine name> options are not supported in dBASE III PLUS.


See Also

CANCEL

DO

ERROR( )

FUNCTION

LOCAL

PRIVATE

PROCEDURE

PUBLIC

QUIT

RETRY

STATIC


RIGHT( )

See Also	Example	Portability	String Data

Returns characters from the end of a character string or memo field.

Syntax

RIGHT(<expC> | <memo field>, <expN>)

<expC> | <memo field>

The string or memo field to extract characters from.

<expN>

The number of characters to extract from the string or memo field.

Description

Starting with the last character of a character expression or memo field, RIGHT( ) returns a specified number of characters. RIGHT( ) returns a maximum of 32766 characters, the maximum length of a string.

If the number of characters you specify for <expN> is greater than the number of characters in the specified string or memo field, RIGHT( ) returns the string as is, without adding space characters to achieve the specified length. If <expN> is less than or equal to zero, RIGHT( ) returns an empty string.

When RIGHT( ) returns characters from a memo field, it counts two characters for each carriage-return and linefeed combination (CR/LF).


RIGHT( ) Example

The following example uses RIGHT( ) to return a portion of a text string, starting from the right end of the string:

? RIGHT("dBASE",1)                 && Returns "E"
? RIGHT("dBASE",3)                 && Returns "ASE"
? RIGHT("dBASE",9)                 && Returns "dBASE"
? RIGHT("dBASE",0)                 && Returns ""

The next example uses RIGHT( ) to order a file by the last three characters of the Zip_P_Code field.

USE Clients EXCLUSIVE
INDEX ON RIGHT(Zip_P_Code,3) TAG Zipdex
LIST FIELDS Company, Zip
CLOSE ALL


Portability

The <memo field> argument is not supported in dBASE IV or dBASE III PLUS. Both dBASE IV and dBASE III PLUS limit the return value of RIGHT( ) to 254 characters.


See Also

AT( )

LEFT( )

RAT( )

SUBSTR( )


RLOCK( )

See Also	Example	Portability	Shared Data

Locks the current record or a specified list of records in the current or specified alias table, and returns .T. if successful.

Syntax

RLOCK([<list expC>] | [<bookmark list expC>]
[,<alias>])

<list expC>

The list of record numbers to lock, separated by commas.

<bookmark list expC>

The list of bookmarks (record indicators) returned by BOOKMARK( ) specifying a record in a non-dBASE table, such as a Paradox table, that does not have natural record-order record numbers. Separate bookmarks with commas.

<alias>

A work area number (1 through 225), letter (A through J), or alias name. The work area letter or alias name must be enclosed in quotes. If you don't include <alias>, RLOCK( ) acts on the current table.

You don't have to specify record numbers or bookmarks if you want to specify a value for <alias>. However, if you have specified record numbers or bookmarks, you must precede <alias> with a comma (,).

Description

Use RLOCK( ) to lock the current record or a list of records in the current or an alias table. If you do not pass RLOCK( ) any arguments, it locks the current record in the current table. If you pass only <alias> to RLOCK( ), it locks the current record in the alias table. If RLOCK( ) is successful in locking all the records you specify, it returns .T. You can lock up to 100 records in each table open at your workstation with RLOCK( ).

You can view and update a record you lock with RLOCK( ). Other users can view this record but can't update it. When you lock a record with RLOCK( ), it remains locked until you do one of the following:

Issue UNLOCK.

Press Ctrl+L (the lock/unlock toggle command) in a Browse or Edit window when the record pointer is on a record you locked with RLOCK( ).

Close the table.

RLOCK( ) is similar to FLOCK( ), except FLOCK( ) locks an entire table. Use FLOCK( ), therefore, when you need to have sole access to an entire table or related tables--for example, when you need to update multiple tables related by a common key--or when you want to update more than 100 records at a time.

All commands that change table data cause dBASE to attempt to execute an automatic record or file lock. If dBASE fails to execute an automatic record or file lock, it returns an error. You might want to use RLOCK( ) for event trapping, testing for its return value rather than for an error condition.

RLOCK( ) cannot lock the records you specify when any of the following conditions exist:

Another user has locked, explicitly or automatically, the current record or one of the records in <list expC> or <bookmark list expC>.

Another user has locked, explicitly or automatically, the current table or the specified alias table.

By default, when RLOCK( ) cannot immediately lock the records you specify, dBASE prompts you to retry locking the records or to cancel further retries. Use SET REPROCESS to specify the number of retries. If you choose to cancel, RLOCK( ) returns .F.

When you set a relation to a parent table with SET RELATION and then lock a record in the table with RLOCK( ), dBASE attempts to lock all child records in child tables. For more information on relating tables, see SET RELATION.

RLOCK( ) is equivalent to LOCK( ).


RLOCK( ) Example

This example loops until it can lock the 10th record with RLOCK( ) or until the user decides to stop trying. If successful, a subroutine, CompMod, is called to update the record:

RecordWasRead = .t.
SET REPROCESS TO 20  && Try to lock 20 times
USE Company
GO 10
Again = .t.
DO WHILE Again
  IF RLOCK()      && Can dBASE Lock the file?
    DO CompMod    && Update this record
    Again = .f.
    UNLOCK        && Allow other users to change
                  && the file.
  ELSE            && RLOCK() returns .F.
    CLEAR
    Wait "Record lock failed. Try again? (Y/N) ";
      to mRetry
    IF UPPER(mRetry)="N"
      Again = .f.
    ENDIF
    RecordWasRead = .f.
  ENDIF
ENDDO
USE
SET REPROCESS TO 0  && The default

LOCK( ) can lock more than one record:

USE Games ALIAS Fun
* ...
Pythagoras= LOCK("8,15,17","Fun")


Portability

Not supported in dBASE III PLUS. The <bookmark list expC> option is not supported in dBASE IV.


See Also

FLOCK( )

SET LOCK

SET RELATION

SET REPROCESS

UNLOCK


ROLLBACK( )

See Also	Example	Portability	Shared Data

Ends a transaction initiated by BEGINTRANS( ) without saving any changes to the open files. Returns .T. if the data was rolled back successfully.

Syntax

ROLLBACK( [<database name expC>] )

<database name expC>

The name of the database in which to cancel the transaction.

If you began the transaction with BEGINTRANS( <database name expC>), you must issue ROLLBACK(<database name expC>). If instead you issue ROLLBACK( ), dBASE ignores the ROLLBACK( ) statement.

If you began the transaction with BEGINTRANS( ), <database name expC> is an optional ROLLBACK( ) argument. If you include it, it must refer to the same database as the SET DATABASE TO statement that preceded BEGINTRANS( ).

Description

Use ROLLBACK( ) to end the open transaction and restore any open files to the state they were in when BEGINTRANS( ) was issued. To end a transaction and write changes to the files, use COMMIT( ).For more information on transactions, see BEGINTRANS( ).


ROLLBACK( ) Example

The following example begins a transaction with BEGINTRANS( ). It opens a multi-user version of Company.dbf and attempts to set values in the Ytd_Sales field to 0. ON ERROR detects any error which might occur. In particular, it will detect if another user has locked any record in Company.dbf. If an error occurs, ROLLBACK( ) resets all values. Otherwise COMMIT( ) writes the changes to disk:

CLOSE ALL
SET PROCEDURE TO PROGRAM(1) ADDITIVE
SET EXCLUSIVE OFF

BEGINTRANS()

TransErr=.f.
ON ERROR DO TransErr    && Activates ON ERROR trap

USE L:\MultiUse\Company
REPLACE ALL Ytd_Sales WITH 0
ON ERROR                && Disables ON ERROR

IF TransErr
  ? "Rollback"
  ROLLBACK()            && restore data
ELSE
  ? "Commit"
  COMMIT()              && save changes
ENDIF

PROC TransErr
WAIT "Warning: Transaction Fails"
TransErr=.t.


Portability

Not supported in dBASE IV or dBASE III PLUS. ROLLBACK( ) replaces the ROLLBACK command in dBASE IV.


See Also

BEGINTRANS( )

COMMIT( )

SET EXCLUSIVE


ROUND( )

See Also	Example	Numeric Data

Returns a specified number rounded to a specified number of decimal places.

Syntax

ROUND(<expN 1>, <expN 2>)

<expN 1>

The numeric or float number to round.

<expN 2>

If <expN 2> is positive, the number of decimal places to round <expN 1> to. If <expN 2> is negative, whether to round <expN 1> to the nearest tenth, hundredth, thousandth, and so on.

Description

Use ROUND( ) to round a number to a specified number of decimal places or to a specified tenth, hundredth, thousandth value, and so forth. Use ROUND( ) with SET DECIMALS to round a number and remove trailing zeros.

If the digit in position <expN 2> + 1 is between 0 and 4 inclusive, <expN 1> (with <expN 2> decimal places) remains the same; if the digit in position <expN 2> + 1 is between 5 and 9 inclusive, the digit in position <expN 2> is increased by 1.

Use 0 as <expN 2>to round a number to the nearest whole number. Using -1 rounds a number to the nearest tenth; rounding to a -2 rounds a number to the nearest hundredth; and so on. For example, ROUND(14932,-2) returns 14900 and ROUND(14932,-3) returns 15000.

See the table in the description of INT( ) that compares INT( ), FLOOR( ), CEILING( ), and ROUND( ).


ROUND( ) Example

The following example demonstrates the use of ROUND( ) as the decimal place parameter of the function is incremented:

SET DECIMALS TO 6
SET TALK OFF
x = 14.746321
? "   x = 14.746321"
FOR y = -5 TO 5 STEP 1
   ? "If y = " + STR(y,2,0)
   ?? "   ROUND(x,y) returns "
   ?? ROUND(x,y)
NEXT
SET TALK ON


See Also

ABS( )

CEILING( )

FLOOR( )

INT( )


ROW( )

See Also	Example	Input/Output

Returns the number of the current row position in the Results pane of the Command window or the current dBASE IV window. This command is supported primarily for compatibility with dBASE IV. In dBASE for Windows, use the Top property of a class to determine its vertical position on a form.

Syntax

ROW( )

Description

ROW( ) returns the number of the current row position in the Results pane of the Command window or the current dBASE IV window opened with ACTIVATE WINDOW. ROW( ) returns the column position of the cursor as a numeric type number.


ROW( ) Example

This example uses the ROW( ) and COL( ) functions to position output relative to the current row and column:

CLEAR                && screen cursor is at 0,0
@ 0,0 SAY "A rose "
* row() is now 0
* col() is now 7
@ ROW()+1,COL() SAY "is a rose "
* row() is now 1
* col() is now 17
@ ROW()+1,COL() SAY "is a rose "
* row() is now 2
* col() is now 27
* Screen shows:
* A rose
*        is a rose
*                  is a rose


See Also

ACTIVATE WINDOW

COL( )

DEFINE


RTOD( )

See Also	Example	Portability	Numeric Data

Returns the degree value of an angle measured in radians.

Syntax

RTOD(<expN>)

<expN>

A negative or positive integer or float that is the size of the angle in radians.

Description

RTOD( ) converts the measurement of an angle from radians to degrees. RTOD( ) returns a float.

To convert radians to degrees, dBASE

Multiplies the number of radians by 180

Divides the result by PI( )

Returns the quotient

An angle of pi radians is equivalent to 180 degrees.

Use RTOD( ) with the trigonometric functions ACOS( ), ASIN( ), ATAN( ), and ATN2( ) to convert the radian return values of these functions to degrees. For example, if the default number of decimal places is 2, ATAN(1) returns the value of the angle in radians, 0.79, while RTOD(ATAN(1)) returns the value of the angle in degrees, 45.00.

Use SET DECIMALS to set the number of decimal places RTOD( ) displays.


RTOD( ) Example

The following example uses RTOD( ) to convert radians to degrees and returns degrees. One pi radian is equal to 180 degrees:

? RTOD(pi())            && Returns 180


Portability

Not supported in dBASE III PLUS.


See Also

ACOS( )

ASIN( )

ATAN( )

ATN2( )

COS( )

DTOR( )

PI( )

SET DECIMALS

SIN( )

TAN( )


RTRIM( )

See Also	Example	Portability	String Data

Returns a string with no trailing space characters.

Syntax

RTRIM(<expC> | <memo field>)

<expC> | <memo field>

The string or memo field to remove the trailing space characters from.

Description

RTRIM( ) is identical to TRIM( ). See the description of TRIM( ) for more information.


RTRIM( ) Example

See the example of TRIM( ); substitute RTRIM( ) for TRIM( ).


Portability

The <memo field> argument is not supported in dBASE IV or dBASE III PLUS. Both dBASE IV and dBASE III PLUS limit the return value of RTRIM( ) to 254 characters.


See Also

LEFT( )

LTRIM( )

RIGHT( )

TRIM( )


RUN( )

See Also	Example	Portability	Disk and File Utilities

Executes a single DOS command, a DOS application, or a Windows application from within dBASE, and returns an exit code from the DOS command interpreter or the Windows application.

Syntax

RUN([<expL1>,] <DOS command expC> [,<expL2>])

<expL1>

Determines whether RUN( ) runs a Windows program (value of .T.) or a DOS program (value of .F.). If you do not include <expL 1>, dBASE assumes a value of .F.

<DOS command expC>

A command recognized by your DOS operating system. Unlike the RUN command, this command must be <expC>.

<expL2>

dBASE for Windows ignores this parameter; it is included for backward compatibility with dBASE IV.

Description

Use RUN( ) to execute a single DOS command or an external (DOS or Windows) application without exiting dBASE. To execute multiple DOS commands interactively without exiting dBASE, use the DOS command.

When execution of the command or program file is completed, control returns to the Command window or to the program, procedure, or user-defined function (UDF) that called RUN( ), and an exit code is returned.

For RUN( ) to access DOS (as when <expL1> = .F. or when <expL1> is omitted), dBASE loads COMMAND.COM using the DBASEWIN.PIF in the directory where DBASEWIN.EXE is located. (To determine that directory, use HOME( ).). You can use the Windows PIF Editor to customize the settings in DBASEWIN.PIF. For example, if you don't want the DOS window to close automatically after the command is completed, you can clear the Close Window on Exit checkbox in DBASEWIN.PIF. For information about .PIF files, see your Windows documentation.

If a DOS command or application is executed, the exit code returned by RUN( ) is 0 if the command or the application executes successfully.When RUN( ) executes Windows applications, the value returned is the instance handle of the application (if execution was successful) or an error number (if execution was unsuccessful). Each instance handle is a 16-bit integer that identifies an active Windows application, and each error number identifies a Windows error condition.


RUN( ) Example

This command attempts to run the Brief Editor in DOS. If it succeeds then Result =0; if not, Result will be nonzero.

Result=RUN(.f.,"B")

These commands attempt to run Windows programs:

Result=RUN(.t.,"winfile.exe")
* e.g. returns  10798
Result=RUN(.t.,"nosuch.exe")
* e.g. returns 2


Portability

Not supported in dBASE III PLUS. In dBASE IV, <expL1> determines whether the operating system's command interpreter is loaded, and <expL2> determines whether all available extended memory is released prior to running <DOS command>.


See Also

DOS

HOME( )

RUN


RUN

See Also	Example	Disk and File Utilities

Executes a single DOS command or program from within dBASE.

Syntax

RUN <DOS command>

<DOS command>

A command recognized by your DOS operating system.

Description

Use RUN to execute a single DOS command or program file without exiting dBASE. Enter commands and file names exactly as you would when working in DOS; do not enclose them in quotes. ! is equivalent to RUN.

When execution of the command or program file is completed, control returns to the Command window or to the program, procedure, or user-defined function (UDF) that executed RUN.

When you issue commands that run in a DOS window, you can use the Windows PIF Editor to customize the settings in DBASEWIN.PIF. For example, if you don't want the DOS window to close automatically after the command is completed, you can clear the Close Window on Exit checkbox in DBASEWIN.PIF. For more information about .PIF files, see your Windows documentation.

To execute multiple DOS commands interactively without exiting dBASE, use the DOS command. To execute a Windows application without exiting dBASE, use RUN( ).

If you want to change the current directory being used by dBASE, use CD instead of RUN. Issuing RUN CD will change the directory only in the DOS window; the directory change will not be reflected in the dBASE system.


RUN Example

RUN must have an argument:

RUN dir
* Performs the DOS directory command
RUN  && gives a syntax error


See Also

CD

DOS

HOME( )

RUN( )

SET DIRECTORY

SET PATH


SAVE

See Also	Example	Portability	Memory Variables

Stores all or specified memory variables to a designated memory file.

Syntax

SAVE TO <filename> | ? | <filename skeleton>
[ALL]
[LIKE <memvar skeleton 1>]
[EXCEPT <memvar skeleton 2>]

TO <filename> | ? | <filename skeleton>

Directs the memory variable output to be saved to the target file <filename>. By default, dBASE assigns a .MEM extension to <filename> and saves the file in the current directory. The ? and <filename skeleton> options display a dialog box in which you specify the name of the target file and the directory to save it in.

ALL

Stores all memory variables to the memory file. If you issue SAVE TO <filename> with no options, dBASE also saves all memory variables to the memory file.

LIKE <memvar skeleton 1>

Stores in the target file the memory variables whose names are like the memory variable skeleton you specify for <memvar skeleton 1>. Use characters of the variable names and the wildcards * and ? to create <memvar skeleton 1>.

EXCEPT <memvar skeleton 2>]

Stores in the target file all memory variables except those whose names are like the memory variable skeleton you specify for <memvar skeleton 2>. Use characters of the variable names and the wildcards * and ? to create <memvar skeleton 2>.

Description

Use SAVE with RESTORE to store and retrieve important memory variables. Private variables are cleared at the end of the program file that created them, while public variables are cleared when you exit dBASE. To preserve these values for future use, store them in a memory file with SAVE. Use RESTORE to retrieve them.

If SET SAFETY is ON and a file exists with the same name as the target file, dBASE displays a dialog box asking if you want to overwrite the file. If SET SAFETY is OFF, any existing file with the same name is overwritten without warning.

Note:	SAVE does not save object reference, function pointer, or system memory variables.


SAVE Example

See RESTORE for an example of using SAVE.


Portability

The ? and | <filename skeleton> options are not supported in dBASE IV or dBASE III PLUS. dBASE IV and dBASE III PLUS do not support both LIKE and EXCEPT in the same SAVE statement.

In dBASE IV and dBASE III PLUS, you must specify ALL if you want to specify LIKE or EXCEPT. In dBASE for Windows, a statement such as SAVE TO memfile LIKE mvar* is acceptable; the ALL option is assumed.


See Also

RELEASE

RESTORE

SET SAFETY

STORE


SAVE SCREEN

See Also	Example	Portability	Input/Output

Saves the contents of the results pane of the Command window. This command is supported primarily for compatibility with dBASE IV. In dBASE for Windows, form definitions are saved in program, procedure, or library files.

Syntax

SAVE SCREEN
[TO <memvar> |
TO FILE <filename> | ? | <filename skeleton>]

TO <memvar>

Saves the contents of the results pane of the Command window to the memory variable you specify for <memvar>. You must assign a unique name for the memory variable. By default, the memory variable is public, even when SAVE SCREEN is run within a subroutine. The variable is of type screen (S).

TO FILE <filename> | ? | <filename skeleton>

Directs output to the target file <filename>. By default, dBASE assigns an .SCN extension to <filename> and saves the file in the current directory. The ? and <filename skeleton> options display a dialog box in which you specify the name of the target file and the directory to save it in.

Description

Use SAVE SCREEN to save the contents of the results pane of the Command window to a variable, a text file, or the Command window buffer. (SAVE SCREEN does not save user-defined form windows.) SAVE SCREEN without options saves the contents of the results pane of the Command window to the Command window buffer in memory. Every time you issue a SAVE SCREEN without options, dBASE overwrites the contents of this buffer.

Use SAVE SCREEN to simulate a pop-up dialog box by saving the contents of the results pane of the Command window, displaying something else in the results pane of the Command window, then restoring the saved Command window. This series of actions is not necessary if you create forms with DEFINE FORM. You can use SAVE SCREEN to save dBASE IV windows, because these windows appear only in the results pane of the Command window.

To redisplay the contents of the results pane of the Command window that you saved with SAVE SCREEN, use RESTORE SCREEN. If you used SAVE SCREEN without options to save to the Command window buffer, use RESTORE SCREEN without options to restore the contents of the buffer.

Remove saved Command window buffer contents from memory with RELEASE SCREENS or CLEAR SCREENS.


SAVE SCREEN Example

This example uses SAVE SCREEN, RESTORE SCREEN, and RELEASE SCREEN. It displays the current time in the Command results pane, saves the contents of the Command results pane to a variable, clears the pane and then redisplays from the saved screen variable:

CLEAR
? "Now is the time "+time()
? "Screen 1"
SAVE SCREEN TO Timescreen
WAIT
CLEAR
? "Screen 2"
WAIT
RESTORE SCREEN FROM Timescreen
* Redisplays the first screen
? "Screen 1 again"
WAIT

Timescreen is a public variable of type "S".

RELEASE SCREEN Timescreen

RELEASE SCREENS releases all Screen types. RELEASE Timescreen can also be used.

SAVE SCREEN does not require arguments:

SAVE SCREEN

With no arguments, SAVE SCREEN saves to the memory variable used to store the Command results pane in memory.


Portability

Not supported in dBASE III PLUS. In dBASE IV, SAVE SCREEN applies to the entire screen; the TO FILE option is not supported; and TO <memvar> is a required option. In dBASE IV, you can save to a memory variable that already exists; in dBASE for Windows, the memory variable name must be unique.


See Also

CLEAR SCREENS

PUBLIC

RELEASE SCREENS

RESTORE SCREEN


SAVE WINDOW

See Also	Example	Portability	dBASE IV Windows

Saves window definitions to a window file. This command is supported primarily for compatibility with dBASE IV. In dBASE for Windows, form definitions are saved in program, procedure, or library files.

Syntax

SAVE WINDOW <window name list> | ALL
TO <filename> | ? | <filename skeleton>

<window name list> | ALL

Identifies which window definitions are saved to the window file. <window name list> identifies one or more windows by name. ALL specifies all currently defined windows.

TO <filename> | ? | <filename skeleton>

Identifies the window file. By default, dBASE assigns a .WIN extension to <filename> and saves the file in the current directory. The ? and <filename skeleton> options display the Save Target File dialog box, which lets you specify the name of the target file and the directory to save it in.

Description

SAVE WINDOW stores a window definition in a window file. Once saved, it can be restored to memory with RESTORE WINDOW. While SAVE WINDOW can save multiple windows to one file, you cannot add new window definitions to an existing window definition file.


SAVE WINDOW Example

The following example uses SAVE WINDOW to save the window design of Window C to a file for later recovery with the RESTORE WINDOW command:

SELECT A
USE COMPANY
SELECT B
USE CONTACT
CLEAR
DEFINE WINDOW A FROM 1,1 TO 15,40 DOUBLE
DEFINE WINDOW B FROM 5,5 TO 18,60 DOUBLE
DEFINE WINDOW C FROM 10,10 TO 23,50 DOUBLE
ACTIVATE WINDOW A, B, C
BROWSE FIELDS COMPCODE, CONTACT
DEACTIVATE WINDOW C        && Cleared from screen
SAVE WINDOW C TO WIN_C_BU.WIN
SELECT A
BROWSE FIELDS COMPANY, YTD_SALES
DEACTIVATE WINDOW B        && Cleared from screen
WAIT "Window A still open - press any key"
DEACTIVATE WINDOW ALL      && Windows still in memory
WAIT "No windows are open-press any key"
CLEAR WINDOWS              && Cleared from memory
CLEAR                      && Clear screen
RESTORE WINDOW C FROM WIN_C_BU
ACTIVATE WINDOW C
WAIT  "Still Going...Press any key"
CLEAR WINDOWS              && Cleared from memory
RETURN


Portability

Not supported in dBASE III PLUS.


See Also

ACTIVATE WINDOW

CLEAR WINDOWS

DEFINE

DEFINE WINDOW

OPEN FORM

RESTORE WINDOW


SCAN

See Also	Example	Portability	Programs

Steps through each record in the current table, executing specified statements on each record that meets specified conditions.

Syntax

SCAN
[<scope>] [FOR <condition 1>] [WHILE <condition 2>]
[<statements ]
[LOOP]
[EXIT]

ENDSCAN

<scope>

The number of records to scan. RECORD <n> identifies a single record by its record number. NEXT <n> identifies n records, beginning with the current record. ALL specifies all records. REST specifies all records from the current record to the end of the table.

FOR <condition 1>
WHILE <condition 2>

Determines which records are affected by SCAN. FOR restricts SCAN to records that meet <condition 1>. WHILE starts processing with the current record and continues with each subsequent record as long as <condition 2> is true.

<statements>

Program lines consisting of any combination of commands, functions, user-defined functions (UDFs), and LOOP and EXIT options. Because SCAN processes a table record by record, these statements are likely to include table commands and functions such as ISBLANK( ) and REPLACE.

LOOP

Moves the record pointer ahead one record and returns program control to the beginning of the loop without performing the statements that follow LOOP and precede ENDSCAN.

EXIT

Transfers program control out of the SCAN loop to the statement following ENDSCAN without executing the statements that follow EXIT and precede ENDSCAN and without processing any more records.

ENDSCAN

A required command that marks the end of the SCAN loop. When dBASE encounters ENDSCAN, it moves the record pointer ahead one record and returns program control to the beginning of the loop.

Description

Use SCAN to process the current table record by record, starting with the first record in the table or master index or the first record that meets a FOR condition. For each record that falls within <scope> or meets a FOR condition or a WHILE condition or any combination of the three, dBASE executes all the statements after SCAN until it encounters LOOP, EXIT, or ENDSCAN. The SCAN loop continues to the end of the table (or the last record in the index) unless the <scope>, the FOR or WHILE condition, or the EXIT option ends the processing earlier. The record pointer remains where it is when processing ends.

At the end of each loop, dBASE automatically moves the record pointer forward one record in the table before returning to the beginning of the loop; therefore, do not include a SKIP command.

You can nest loops and other structures, including other SCAN loops, in a SCAN loop. Each ENDSCAN in a nested group of SCANs moves the record pointer one record. The nested code must account for this record pointer movement, or code might execute on records you did not intend it to.

SCAN works like a DO WHILE .NOT. EOF( )...SKIP...ENDDO construct; however, with SCAN you can specify conditions with FOR, WHILE, and <scope>. SCAN also requires fewer lines of code than DO WHILE.

When using SCAN with an indexed table, do not change the value of a field that is (or is part of) the master index key. When you change the value of such a field, dBASE repositions the record in the index file, which might cause unintended results. For example, if you change a key field that causes its record to move to the end of the index, that record might have the SCAN...ENDSCAN statements executed on it a second time.

If you change work areas within a SCAN loop, select the work area containing the table being scanned before control passes back to the first statement in the SCAN loop.


SCAN Example

The following example uses SCAN to step through a table and calls an invoicing procedure for those records that have a positive value in field Startbal:

CLEAR
USE Clients
SCAN FOR Startbal > 0
  DO Invoice WITH Company, Startbal, Baldate
ENDSCAN

PROCEDURE Invoice
PARAMETERS Company, Startbal, Baldate
? Company, Startbal, Baldate
RETURN

The following code is equivalent to the SCAN loop used in the previous example but uses the DO WHILE and IF/ENDIF commands:

SET TALK OFF
USE Clients
DO WHILE .NOT. EOF()
  If Startbal > 0
    DO Invoice WITH Company, Startbal, Baldate
  ENDIF
  SKIP
ENDDO

PROCEDURE Invoice
PARAMETERS Company, Startbal, Baldate
? Company, Startbal, Baldate
RETURN


Portability

Not supported in dBASE III PLUS. Nested SCAN loops are not supported in dBASE IV.


See Also

DO WHILE

DO...UNTIL

FOR...NEXT

INDEX

LOCATE

SEEK

SKIP


SECONDS( )

See Also	Example	Date and Time Data

Returns the number of seconds that have elapsed on your computer's system clock since 12 a.m. (midnight).

Syntax

SECONDS( )

Description

SECONDS( ) returns the number of seconds to the hundredth of a second that have elapsed on your system clock since 12 a.m. (midnight). The number is in the format SS.hh, where SS are the seconds, and hh are the hundredths of a second.

Use SECONDS( ) to calculate the amount of time that portions of your program take to run. SECONDS( ) is more convenient for this purpose than TIME( ) because SECONDS( ) returns a number rather than a character string.

You can also use SECONDS( ) instead of ELAPSED( ) to determine elapsed time for the current day to within hundredths of a second.


SECONDS( ) Example

The first line of the following example parses the hour, minute and second characters of the string returned by TIME( ) to calculate the number of seconds elapsed between midnight and the current time. The second command line is meant to illustrate that SECONDS( ) returns the same value as calculated by the first command line:

? TIME(),(VAL(SUBSTR(TIME(),1,2))*3600) + ;
   (VAL(SUBSTR(TIME(),4,2))*60) + ;
   VAL(SUBSTR(TIME(),7,2))
? SECONDS()


See Also

ELAPSED( )

SET TIME

TIME( )


SEEK

See Also	Example	Table Organization

Searches for the first record in an indexed table whose key fields matches the specified expression.

Syntax

SEEK <expC list> | <expN list>

<expC list> | <expN list>

The character string or number to find in the master index key fields. For dBASE tables, you can specify a dBASE expression that matches the index key expression. For Paradox and SQL tables, you can specify values (separated by commas) that match single or composite index key fields.

Description

dBASE for Windows can search a table for specific information either by a sequential search of a table or by an indexed search of the table's master index. A sequential search is similar to looking for information in a book by reading the first page, then the second, and so on, until the information is found or all pages have been read. LOCATE uses this method, checking each record until the information is found or the last record has been inspected.

An indexed search is similar to looking up a topic in a book index and turning directly to the appropriate page. Once a table index is created, SEEK, or the similar command FIND, can use this index to quickly identify the appropriate record.

SEEK begins searching at the top of an index and halts when either a match is found or the end of the index is reached. If a match is found (FOUND( ) returns .T.), the record pointer of the associated table is positioned at the record containing the match.

Use SKIP to access other records whose key fields match the index key fields or expression. SKIP advances the record pointer one record; because of the indexed order, other matches immediately follow the first. However, SKIP after SEEK (unlike CONTINUE after LOCATE) does not search for a match; it moves the record pointer one record whether or not it finds a match.

The SET NEAR setting determines whether dBASE for Windows, after an unsuccessful SEEK, positions the record pointer at the end-of-file or at the record in the indexed table immediately after the position at which the value searched for would have been found. If SET NEAR is OFF (the default) and SEEK is unsuccessful, EOF( ) returns .T. and FOUND( ) returns .F. If SET NEAR is ON and SEEK is unsuccessful, EOF( ) returns .F. (unless the position at which the sought value would have been found is the last record in the index), and FOUND( ) returns .F.

SEEK can locate any valid key fields or expressions of data type character, numeric, float, or date. Character input must be delimited with single or double quotation marks or brackets. Date expressions must be delimited with braces ({ }) or converted using the CTOD( ) function.

The expression you look for with SEEK must match the key expression or fields of the master index. For example, if the master index key is SUBSTR(Custno, 2, 5), use SEEK SUBSTR(Custno, 2, 5).

When you seek a key expression of type character, the rules established by SET EXACT determine if a match exists. If SET EXACT is OFF, the default condition, only the beginning characters of the key field need to be entered for SEEK to determine a match. If SET EXACT is ON, the entered expression must be identical to the key field for a match to exist.

The SEEK( ) function works like SEEK followed by FOUND( ), except that SEEK searches in the current work area, while SEEK( ) can search in a current or a specified work area. SEEK( ) returns .T. or .F. depending on whether the search is successful.

FIND, SEEK, and LOCATE each have their own advantages. FIND and SEEK conduct the most rapid searches; however, both require an indexed file and can search only for values of the key expression. SEEK offers greater flexibility than FIND by accepting dBASE expressions as well as character and numeric input. Searches for memory variable values using FIND require use of the & macro-substitution operator, while character input to SEEK must be delimited.

If the information for which you are searching is in an unindexed file or is not contained in the key field of an indexed file, you can use LOCATE. LOCATE accepts an expression of any data type as input and can search any field of a table for that value. For large tables, however, a sequential search using LOCATE can be slow. In such cases, you might want to use INDEX to create a new index and then use SEEK, SEEK( ), or FIND.


SEEK Example

The following example uses SEEK to locate the first occurrence of a company in Illinois:

USE Company EXCLUSIVE
INDEX ON State_Prov TAG State
Keyvalue="IL"
SEEK Keyvalue     && SEEK the contents of a variable
IF FOUND()
   ? "All Companies in Illinois"
   LIST FIELDS Company, State_Prov;
     WHILE State_Prov=Keyvalue
ELSE
   ? "Illinois was not found"
ENDIF


See Also

DTOS( )

EOF( )

FIND

FOUND( )

INDEX

LOCATE

SEEK( )

SET EXACT

SET NEAR


SEEK( )

See Also	Example	Portability	Table Organization

Searches for the first record in an indexed table whose key field matches the specified expression.

Syntax

SEEK(<expC> | <expN> [,<alias>] )

<expC> | <expN>

The character string or number to look for in the key field of the indexed table in the current or <alias> work area. Character input must be delimited with single or double quotation marks or brackets. Date expressions must be delimited with braces ({ }) or converted using the CTOD( ) function.

<alias>

A work area number (1 through 225), letter (A through J), or alias name. The work area letter or alias name must be enclosed in quotes.

Description

SEEK( ) evaluates the expression specified by <expC> or <expN> and attempts to find its value in the master index of the table open in the current or specified work area. SEEK( ) returns .T. if it finds a match of the key expression in the master index, and .F. if no match is found.

SEEK( ) can search only for an expression that is contained in the master index key field. When you specify <expC>, a character expression, and SET EXACT is ON, <expC> must match every character in the key field. If SET EXACT is OFF, dBASE for Windows compares <expC> only to the first characters in the key field.

SEEK( ) begins searching at the top of an indexed table and moves the record pointer to the first record whose key field matches <expC> or <expN>. If dBASE for Windows does not find <expC> or <expN>, SEEK( ) moves the record pointer to the end of the file. SEEK( ) can locate any valid key expression of data type character, numeric, float, or date. If SET NEAR is ON, the record pointer moves to the record immediately following the expression searched for whenever an exact match cannot be found.

Use SKIP to access other records whose key field value matches the search expression. SKIP advances the record pointer one record. Because of the indexed order, other matches immediately follow the first. However, SKIP after SEEK( ) (unlike CONTINUE after LOCATE) does not search for a match; it moves the record pointer one record whether or not it finds a match.

You can use SEEK( ) to produce the same effect as performing SEEK followed by FOUND( ). The value that FOUND( ) returns matches that returned by SEEK( ).


SEEK( ) Example

The following example uses SEEK( ) to find the first occurrence of a matching record in an indexed table:

CLOSE DATABASE
USE Company EXCLUSIVE        && work area 1
INDEX ON State_Prov TAG State
SELECT 2
Gotit=SEEK("CA","Company")

dBASE is pointing to work area 2 and performing a SEEK( ) in work area 1.


Portability

Not supported in dBASE III PLUS.


See Also

EOF( )

FIND

FOUND( )

INDEX

LOOKUP( )

SEEK

SET EXACT

SET NEAR

SET RELATION

SET SKIP


SELECT

See Also	Example	Table Basics

Sets the current work area in which to open or perform operations on a table.

Syntax

SELECT <alias>

<alias>

Specifies a work area. You can enter a work area number (1 through 225), letter (A through J), or alias name. The work area letter or alias name can also be enclosed in quotes.

Description

Use SELECT to choose a work area in which to open a table, or to specify a work area in which a table is already open. Use SELECT to open a table and other files associated with a table, such as index, query, and format files, in each work area.

Each work area supports its own value of FOUND( ) and an independent record pointer. Changes in the record pointer of the active work area have no effect on the record pointers of any other work areas, unless you set a relation between the work areas with the SET RELATION command.

Use the macro (&) operator to select a work area by a variable, or simply enclose the variable containing the work area in parentheses. For example, if N=1, use SELECT (N) to select work area 1.


SELECT Example

The following example uses the SELECT command to change the current table to a different previously opened table:

PUBLIC table1, table2
USE Contact EXCLUSIVE IN SELECT()
INDEX ON CompCode TAG CompCode
table1 = ALIAS()

USE Company IN SELECT()
table2 = ALIAS()

SELECT Company
COPY STRUCTURE TO CntctLst;
   FIELDS Contact->CompCode, ;
   Company->Company, Contact->Contact, ;
   Company->Street1, Company->Street2, ;
   Company->City, Company->State_Prov,;
   Company->Zip_P_Code
USE CntctLst IN SELECT()
table3 = ALIAS()
APPEND
SELECT &table1
? ALIAS(),DBF(),WORKAREA()
SELECT &table3
? ALIAS(),DBF(),WORKAREA()
SELECT &table2
? ALIAS(),DBF(),WORKAREA()
SELECT 3
? ALIAS(),DBF(),WORKAREA()
SELECT 1
? ALIAS(),DBF(),WORKAREA()
SELECT 2
? ALIAS(),DBF(),WORKAREA()
CLOSE ALL


See Also

SELECT( )

SET RELATION

USE

WORKAREA( )


SELECT( )

See Also	Example	Portability	Table Basics

Returns the number of an available work area or the work area number associated with a specified alias.

Syntax

SELECT( [<alias>] )

<alias>

A work area number (1 through 225), letter (A through J), or alias name. The work area letter or alias name must be enclosed in quotes.

Description

If you do not specify an alias, SELECT( ) returns the number of the next available work area, a number between 1 and 225. If you specify an alias, SELECT( ) determines whether the specified alias name is already in use.

Use SELECT( ) to locate an available work area in which to open a table without closing an open table. SELECT( ) returns a value of 0 when there are no more work areas available or a specified <alias> is not already in use.


SELECT( ) Example

The following example demonstrates how SELECT( ) is used to return the next available work area or the work area of an alias:

CLOSE DATABASES
USE Clients IN SELECT()
USE Company IN SELECT()
? SELECT()   && Returns 3, meaning work area 3 is;
             next available
? ALIAS(1)   && Returns CLIENTS
? ALIAS(2)   && Returns COMPANY
? DBF(1)     && Returns C:CLIENTS.DBF
? SELECT()   && Returns 3, Work Area 3 still current;
             work area
SELECT 2     && Work area 2 active
? ALIAS()    && Returns COMPANY
? WORKAREA() && Returns 2
? SELECT()   && Returns 3
? SELECT("Clients");
             && Returns 1 - work area 1


Portability

Not supported in dBASE III PLUS.


See Also

ALIAS( )

DBF( )

SELECT

WORKAREA( )


SET

See Also	Portability	Environment

Displays a dialog box for viewing and changing the values of many SET commands. The changed values are stored in the DBASEWIN.INI file.

Syntax

SET

Description

Use SET to view and change settings interactively, instead of typing individual SET commands such as SET TALK ON in the Command window.

Note:	Any changes you make to settings by using SET are automatically saved to DBASEWIN.INI. This means that the settings will be in effect each time you start dBASE. If you want to change the value of SET commands only temporarily, issue individual SET commands in the Command window or in a program. For more information about DBASEWIN.INI, see Appendix C in the User's Guide.

Issuing SET is the same as choosing the Properties | Desktop menu option.


Portability

In dBASE IV and dBASE III PLUS, changes you make by using SET are valid only until you exit dBASE; they are not saved in the CONFIG.DB file.


See Also

DISPLAY STATUS

SET( )

SETTO( )

individual SET commands


SET( )

See Also	Example	Portability	Environment

Returns the current setting of a SET command or function key.

Syntax

SET(<expC>)

<expC>

A character expression that is the SET command or function key whose setting value to return.

Description

Use SET( ) to learn a SET or function key setting so that you can change it or save it. For example, you can issue SET( ) at the beginning of a program to learn current settings. You can then save these settings in memory variables, change the settings, and restore the original settings from the memory variables at the end of the program.

When dBASE supports a SET and a SET…TO command that use the same keyword, SET( ) returns the on|off setting and SETTO( ) returns the SET…TO setting. For example, you can issue SET CARRY ON, SET CARRY OFF, or SET CARRY TO <field list>. SET("CARRY") returns "ON" or "OFF" and SETTO("CARRY") returns the field list as a character expression.

If dBASE supports a SET…TO command but not a corresponding SET command, SET( ) and SETTO( ) both return the SET…TO value. For example, SET("BLOCKSIZE") and SETTO("BLOCKSIZE") both return the same value.

When <expC> is a function key name, such as "F4", SET( ) returns the function key setting. To return the value of a Ctrl+function key setting, add 10 to the function key number; to return the value of a Shift+function key setting, add 20 to the function key number. That is, to return the value of Ctrl+F4, use SET("F14"), and to return the value of Shift+F4, use SET("F24").

If a procedure file is open, SET("PROCEDURE") returns the name of the procedure file. If more than one procedure file is open, SET("PROCEDURE") returns only the name of the first one loaded. To return the name of another open procedure file, enter a number as the second argument; for example, SET("PROCEDURE", 2) returns the name of the second procedure file that was loaded. If no procedure files are open, SET("PROCEDURE") returns an empty string ("").

The command you specify for <expC> can be abbreviated to four letters in most cases, following the same rules as those for abbreviating keywords. For example, SET("DECI") and SET("DECIMALS") have the same meaning. The <expC> argument is not case-sensitive.


SET( ) Example

In this example, you see a typical use of SET( ). The current color settings are obtained using SET( ) and saved. The colors are changed, some work is performed (in this case, simply clearing the screen) and the original setting is then restored:

Oldcolors=SET("ATTRIBUTE")
SET COLOR TO G/B,R/B
CLEAR
SET COLOR TO &Oldcolors
* Old colors restored

The following example shows most of the SET( ) arguments along with the kind of response obtained:

? SET("F1")        && help;
? SET("ALTERNATE") && ON
? SET("ATTRIBUTE") && RGB+/B,N/W,N/G && N/G,W/B,RGB+/B,B/W,N/W
? SET("AUTO")      && OFF
? SET("BELL")      && ON
? SET("CARRY")     && OFF
? SET("CATALOG")   && OFF
? SET("CENTURY")   && OFF
? SET("CONFIRM")   && OFF
? SET("CONSOLE")   && ON
? SET("COVER")     && OFF
? SET("CUAENTER")  && ON
? SET("CURRENCY")  && LEFT
? SET("DELIMITER") && OFF
? SET("DELETED")   && OFF
? SET("DESIGN")    && ON
? SET("ECHO")      && OFF
? SET("ENCRYPTION")&& OFF
? SET("ESCAPE")    && ON
? SET("EXACT")     && OFF
? SET("EXCLUSIVE") && OFF
? SET("FIELDS")    && OFF
? SET("FORMAT")    && ""
? SET("FULLPATH")  && OFF
? SET("HEADING")   && ON
? SET("HELP")      && ON
? SET("INTENSITY") && ON
? SET("LIBRARY")   && ""
? SET("LOCK")      && ON
? SET("MARGIN")    &&          0
? SET("MARK")      && /
? SET("MEMOWIDTH") &&         50
? SET("MESSAGE")   && ""
? SET("NEAR")      && OFF
? SET("ODOMETER")  &&        100
? SET("ORDER")     && ""
? SET("PATH")      && ""
? SET("PCOL")      &&          0
? SET("POINT")     && .
? SET("PRECISION") &&         16
? SET("PRINTER")   && OFF
? SET("RELATION")  && ""
? SET("REPROCESS") &&          0
? SET("SAFETY")    && OFF
? SET("SEPARATOR") && ,
? SET("SKIP")      && ""
? SET("SPACE")     && ON
? SET("STEP")      && OFF
? SET("TALK")      && ON
? SET("TOPIC")     && ""
? SET("TYPE")      &&         50
? SET("UNIQUE")    && OFF


Portability

Not supported in dBASE III PLUS.


See Also

DISPLAY STATUS

SET

SETTO( )


SETTO( )

See Also	Example	Portability	Environment

Returns the current setting of a SET...TO command or function key.

Syntax

SETTO(<expC>)

<expC>

A character expression that is the SET...TO command whose setting value to return.

Description

Use SETTO( ) to learn a SET or function key setting so that you can change it or save it. For example, you can issue SETTO( ) at the beginning of a program to learn current settings. You can then save these settings in memory variables, change the settings, and restore the original settings from the memory variables at the end of the program.

When dBASE supports a SET and a SET…TO command that use the same keyword, SET( ) returns the SET setting and SETTO( ) returns the SET…TO setting. For example, you can issue SET CARRY ON, SET CARRY OFF, or SET CARRY TO <field list>. SET("CARRY") returns the ON or OFF setting and SETTO("CARRY") returns the field list as a character expression.

SETTO( ) is almost identical to SET( ). For more information, see SET( ).


SETTO( ) Example

In this example, you see a typical use of SETTO( ) when printing a special report to a particular printer. The current setting of SET PRINTER TO is stored. SET PRINTER TO is set to LPT2 and a report is printed. The original setting is then restored:

Oldprintto=SETTO("PRINTER")  && e.g. LPT1
SET PRINTER TO LPT2
REPORT FORM Myreport TO PRINTER
SET PRINTER TO &Oldprintto

The following example shows most of the SETTO( ) arguments along with the kind of response obtained:

? SETTO("ALTERNATE")  && D:\DBASEWIN\EXAMPLES\SETTO().RES
? SETTO("BORDER")     && SINGLE
? SETTO("BELL")       && 512,2
? SETTO("BLOCK")      &&          1
? SETTO("CATALOG")    &&
? SETTO("CURRENCY")   && $
? SETTO("DATE")       && MDY
? SETTO("DECIMALS")   &&          2
? SETTO("DELIMITER")  && ::
? SETTO("DEVICE")     && SCREEN
? SETTO("DIRECTORY")  && D:\DBASEWIN\EXAMPLES
? SETTO("DISPLAY")    && EGA25
? SETTO("EDITOR")     &&
? SETTO("FILTER")     &&
? SETTO("FIELDS")     &&
? SETTO("FORMAT")     &&
? SETTO("HELP")       && DBASEWIN.HLP
? SETTO("IBLOCK")     &&          1
? SETTO("LIBRARY")    &&
? SETTO("MARGIN")     &&          0
? SETTO("MARK")       && /
? SETTO("MEMOWIDTH")  &&         50
? SETTO("MESSAGE")    &&
? SETTO("ORDER")      &&
? SETTO("PATH")       &&
? SETTO("PCOL")       &&          0
? SETTO("POINT")      && .
? SETTO("PRECISION")  &&         16
? SETTO("PROCEDURE")  &&
? SETTO("PROW")       &&          0
? SETTO("PRINTER")    && LPT1
? SETTO("RELATION")   &&
? SETTO("REFRESH")    &&          0
? SETTO("RETRACE")    && OFF
? SETTO("SEPARATOR")  && ,
? SETTO("SKIP")       &&
? SETTO("TOPIC")      &&


Portability

Not supported in dBASE IV or dBASE III PLUS.


See Also

DISPLAY STATUS

SET

SET( )


SET ALTERNATE

See Also	Example	Portability	Input/Output

Controls the recording of input and output in an alternate text file.

Syntax

SET ALTERNATE on | OFF

SET ALTERNATE TO
[<filename> | ? | <filename skeleton>
[ADDITIVE]]

<filename> | ? | <filename skeleton>

The alternate text file, or target file, to create or open. The ? and <filename skeleton> options display a dialog box in which you can specify a new file or select an existing file. If you specify a file without including its path, dBASE looks for the file in the current directory, then in the path you specify with SET PATH. If you specify a file without including its extension, dBASE assumes .TXT.

ADDITIVE

Appends dBASE output that appears in the results pane of the Command window to the specified existing alternate file. If the file doesn't exist, dBASE returns an error message.

Default

The default for SET ALTERNATE is OFF. To change the default, set the ALTERNATE parameter in the [OnOffCommandSettings] section of DBASEWIN.INI. To set a default file name for use with SET ALTERNATE, specify an ALTERNATE parameter in the [CommandSettings] section of DBASEWIN.INI.

Description

Use SET ALTERNATE TO to create a record of dBASE output and commands. You can edit the contents of this file with the Text Editor for use in documents, or store it on disk for future reference. You can record, edit, and incorporate command sequences into new programs. (To send the results of @...SAY commands to a text file, use SET DEVICE TO FILE.)

SET ALTERNATE TO <filename> only opens an alternate file, while SET ALTERNATE ON | OFF controls the storage of input and output to that file. Only one alternate file can be open at a time. When you issue SET ALTERNATE TO <filename> to open a new file, dBASE closes the previously open alternate file.

When SET ALTERNATE is ON, dBASE stores output to the results pane of the Command window in the text file you have opened by previously issuing SET ALTERNATE TO <filename>. An alternate file must be open for SET ALTERNATE ON to have an effect. SET ALTERNATE does not affect a program's output; it only determines when that output is saved in the alternate file. (Keyboard entries in the Command window are not stored to the alternate file.)

To prevent your text file from beginning with a blank line, use two question marks (??) before the first word that you send to the alternate file.

Issuing SET ALTERNATE OFF does not close the alternate file. Before accessing the contents of an alternate file, formally close it with CLOSE ALTERNATE or SET ALTERNATE TO (with no file name). This ensures that all data recorded by dBASE for storage in the alternate file is transferred to disk, and automatically turns SET ALTERNATE to OFF.

If SET SAFETY is ON, you don't use the ADDITIVE option, and a file exists with the same name as the target file, dBASE displays a dialog box asking if you want to overwrite the file. If SET SAFETY is OFF and you don't use the ADDITIVE option, any existing file with the same name as the target file is overwritten without warning.


SET ALTERNATE Example

This example uses the SET ALTERNATE commands to write text to the screen and an ASCII file:

SET ALTERNATE TO Rose
* Open Rose.txt for text output
? "Opening alternate file" && to screen only
SET ALTERNATE ON
* ?,?? commands now go to Rose.txt
? "A rose "
SET ALTERNATE OFF  && Stop storing to Rose.txt.
?? "tended carefully in your garden "
SET ALTERNATE ON	&& Add to Rose.txt.
?? "is a rose "
?? "is a rose "
? "You will be proud of"
CLOSE ALTERNATE    && Close Rose.txt
* Rose.txt contains:
* A rose is a rose is a rose
* You will be proud of


Portability

The ADDITIVE option is not supported in dBASE III PLUS. The ? and <filename skeleton> options are not supported in dBASE III PLUS or dBASE IV.


See Also

CLOSE...

SET DEVICE


SET AUTOSAVE

See Also	Example	Portability	Fields and Records

Determines if dBASE writes data to disk each time a record is changed or added.

Syntax

SET AUTOSAVE on | OFF

Default

The default for SET AUTOSAVE is OFF. To change the default, update the AUTOSAVE setting in DBASEWIN.INI. To do so, either use the SET command to specify the setting interactively, or enter the AUTOSAVE parameter directly in DBASEWIN.INI.

Description

Use SET AUTOSAVE ON to reduce the chances of data loss. When SET AUTOSAVE is ON and you alter or add a record, dBASE for Windows updates tables and index files on disk when you move the record pointer. When SET AUTOSAVE is OFF, changes are saved to disk as the record buffer is filled.

Since dBASE for Windows periodically saves table changes to disk, in most situations you do not need to SET AUTOSAVE ON. SET AUTOSAVE OFF lets you process data faster, since dBASE for Windows writes your changes to disk less often.


SET AUTOSAVE Example

The following example uses SET AUTOSAVE ON to save newly entered data to disk each time the record pointer changes:

SET TALK OFF
CLOSE DATABASES
USE Company
a_save = SET("AUTOSAVE")
carry = SET("CARRY")
SET AUTOSAVE ON
SET CARRY ON
APPEND
SET CARRY &carry
SET AUTOSAVE &a_save
FLUSH
CLOSE ALL
CLEAR
SET TALK ON


Portability

Not supported in dBASE III PLUS.


See Also

CLOSE...

FLUSH


SET BELL

See Also	Example	Portability	Environment

Sets the bell frequency and duration.

Syntax

SET BELL ON | off

SET BELL TO
[<frequency expN>, <duration expN>]

<frequency expN>

The frequency of the bell tone in cycles per second, which must be an integer from 19 to 10,000, inclusive.

<duration expN>

The duration of the bell tone in ticks (18ths of a second), which must be an integer from 1 to 19, inclusive.

Default

The default for SET BELL is ON. The default bell frequency is 512 Hertz (cycles per second), and the default bell duration is 2 ticks. (A tick is 1/18 of a second.)

To change the default on|off setting, update the BELL parameter in the [OnOffCommandSettings] section of DBASEWIN.INI. To change the frequency and duration defaults, update the BELL parameters in the [CommandSettings] section of DBASEWIN.INI. To do so, either use the SET command to specify the setting interactively, or enter the parameters directly in DBASEWIN.INI.

Description

When SET BELL is ON, dBASE produces a tone when you fill a data entry field or enter invalid data. SET BELL TO determines the frequency and duration of this tone.

CHR(7) sounds a tone whether SET BELL is ON or OFF.

SET BELL TO with no arguments sets the frequency and duration to the default values of 512 and 2. SET BELL has an effect only on machines that have an internal speaker or other sound system.


SET BELL Example

The following examples set the bell to high and low pitch and short and long durations:

SET BELL ON
SET BELL TO 50,19
* BROWSE, APPEND etc will now ring the bell
* A long, very low bell
? CHR(7)  && ring the bell
SET BELL TO 10000,1
* Short, very high pitched
? CHR(7)  && ring the bell
SET BELL OFF
? CHR(7)  && the bell still rings
* BROWSE, APPEND etc will not ring the bell


Portability

SET BELL TO <frequency expN>, <duration expN> not supported in dBASE III PLUS.


See Also

CHR( )

SET CONFIRM


SET BLOCKSIZE

See Also	Example	Portability	Fields and Records

Changes the default block size of memo field and .MDX index files.

Syntax

SET BLOCKSIZE TO <expN>

<expN>

A number from 1 to 63 that sets the size of blocks used in memo and .MDX index files. (The actual size in bytes is the number you specify multiplied by 512.)

Default

The default for SET BLOCKSIZE is 1 (for compatibility with dBASE III PLUS). To change the default, update the BLOCKSIZE setting in DBASEWIN.INI.

Description

Use SET BLOCKSIZE to change the size of blocks in which dBASE for Windows stores memo field files and .MDX index files on disk. The actual number of bytes used in blocks is <expN> multiplied by 512. Instead of using SET BLOCKSIZE, you can set the block size used for memo and .MDX index files individually, by using SET MBLOCK and SET IBLOCK commands.

After the block size is changed, memo fields created with the COPY, CREATE, and MODIFY STRUCTURE commands have the new block size. To change the block size of an existing memo field file, use the SET BLOCKSIZE command to change the block size and then copy the table containing the associated memo field to a new file. The new file then has the new block size.


SET BLOCKSIZE Example

The following example uses SET BLOCKSIZE to create another table that is a copy of Clients but has a memo blocksize of 1024 bytes embedded in its structure instead of the default of 512 bytes:

USE Clients
? SET("Blocksize")          && Returns default of 1;
                               meaning each memo;
                               block = 512 bytes
SET BLOCKSIZE TO 2
COPY  TO Clients2
USE Clients2
? SET("Blocksize")          && Returns 2
LIST FILES LIKE *.DBT       && Note file size larger;
                               than Clients.DBT
CLOSE DATABASES


Portability

Not supported in dBASE III PLUS.


See Also

COPY

COPY INDEXES

CREATE

MODIFY STRUCTURE

INDEX

REINDEX

REPLACE

SET( )

SET IBLOCK

SET MBLOCK


SET BORDER

See Also	Example	Environment

Defines the default border of subsequently defined dBASE IV windows, dBASE IV pop-up menus, and @...TO boxes. This command is supported primarily for compatibility with dBASE IV. In dBASE for Window, use DEFINE to create forms instead of windows.

Syntax

SET BORDER TO
[SINGLE | DOUBLE | PANEL | NONE |
<border definition list>]

SINGLE

Sets the default border to a single line.

DOUBLE

Sets the default border to a double line.

PANEL

Sets the default border to a solid border one row high on the top and bottom and one column wide on the left and right sides.

NONE

Sets the default border to no border at all.

<border definition list>

A list of characters that make up the border. The syntax of a border definition list is as follows:

[<1>] [,[<2>] [,[<3>] [,[<4>] [,[<5>]

[,[<6>] [,[<7>] [,[<8>]]]]]]]]

Each number 1 through 8 can be

A decimal value for any character in the currently installed character set

A character string

A memory variable

A CHR( ) function

Separate entries with a comma and specify them in the following order:

Figure: Order of border characters

If you specify only one character, dBASE draws the entire border with that character. You can omit a character by using a comma in its place if other entries follow it, or by omitting it if it comes at the end of the list of entries. Omitting a character leaves it unchanged from its previous setting (unless you specify only one character and omit the rest).

Default

The default for SET BORDER is SINGLE.

Description

To change the default border, use SET BORDER before you define the border appearance for dBASE IV-style pop-up menus and windows and boxes drawn with the @...TO command.

SET BORDER TO without an option sets the default border to the default of SINGLE.

SET BORDER establishes the border display of the following objects:

 A box defined with @...TO. An @...TO border definition overwrites a SET BORDER definition.

A pop-up menu defined with DEFINE POPUP.

A window defined with DEFINE WINDOW and opened with ACTIVATE WINDOW. A DEFINE WINDOW border definition overwrites a SET BORDER definition.

SET BORDER affects the display of only those objects you define after you use SET BORDER. The border setting then becomes part of the definition.


SET BORDER Example

The following example creates three windows, each with SET BORDER set to a different option. Note that they all appear as they were created, despite the fact that SET BORDER is DOUBLE when the ACTIVATE WINDOW command is issued. INKEY(3) is a delay before issuing DEACTIVATE WINDOW:

SET BORDER TO PANEL
DEFINE WINDOW A FROM 2,2 TO 20,22
SET BORDER TO DOUBLE
DEFINE WINDOW B FROM 2,25 TO 20,45
SET BORDER TO SINGLE
DEFINE WINDOW C FROM 2,48 TO 20,68
SET BORDER TO DOUBLE
ACTIVATE WINDOW A, B, C
? INKEY(3)
DEACTIVATE WINDOW C
? INKEY(3)
DEACTIVATE WINDOW B
? INKEY(3)
CLEAR ALL
RETURN


See Also

@...TO

DEFINE

DEFINE POPUP

DEFINE WINDOW


SET CARRY

See Also	Example	Portability	Fields and Records

Specifies the fields from which data is copied to new records created with APPEND, BROWSE, EDIT, or INSERT commands.

Syntax

SET CARRY on | OFF

SET CARRY TO [<field list> [ADDITIVE]]

<field list>

The list of fields whose values are carried forward to new records.

ADDITIVE

Adds fields in <field list> to the list of fields previously defined with SET CARRY TO. Without ADDITIVE, <field list> overrides any previously specified list of fields.

Default

The default for SET CARRY is OFF.

Description

When SET CARRY is ON, records added using APPEND, BROWSE, EDIT, or INSERT are filled with the contents of the record immediately preceding the new record at the logical end of the table. (You can also supply default record contents for INSERT and APPEND using the DEFAULT argument of @...SAY...GET.)

When SET CARRY is OFF, new records are initially blank. SET CARRY does not affect INSERT AUTOMEM, APPEND AUTOMEM, INSERT BLANK, or APPEND BLANK. These commands always add a record containing automem variables or a blank record.

Specifying a field list with the SET CARRY TO command limits the fields carried to the new record. Using the SET CARRY TO command automatically sets CARRY ON. Specifying the ADDITIVE keyword adds fields to an already defined field list.

SET CARRY TO with no field list restores the default condition where all fields are carried to new records.

You can also limit the fields by specifying a field list with SET FIELDS TO. The SET CARRY TO field list applies only to SET CARRY, while the SET FIELDS TO fields list applies to all commands operating on tables. A SET FIELDS TO field list overrides a SET CARRY TO field list.


SET CARRY Example

The following example uses SET CARRY TO to carry field data forward from the previous record. In the example, the user wants to enter new records for companies that are all in the same local area so they have the same State and Zip, plus report to the same corporate office:

USE Company
SET CARRY TO State_Prov, Zip_P_Code, Corp_Off
APPEND
* Edit window appears with data already entered in
* the 3 designated fields.
SET CARRY OFF
CLOSE ALL


Portability

Not supported in dBASE III PLUS.


See Also

APPEND

INSERT

SET FIELDS

@...SAY...GET


SET CATALOG

See Also	Example	Table Basics

Opens a catalog file.

Syntax

SET CATALOG on | OFF

SET CATALOG TO [<filename> | ?]

TO <filename> | ?

Specifies the name of the catalog you want to open. SET CATALOG TO ? displays a dialog box, in which you can select an existing catalog file.

Default

The default for SET CATALOG is OFF. To change the default, update the CATALOG setting in DBASEWIN.INI. To do so, either use the SET command to specify the setting interactively, or enter the CATALOG parameter directly in DBASEWIN.INI.

Description

Use SET CATALOG TO <filename> to open an existing catalog.

SET CATALOG on|OFF determines if new files are added to the open catalog file. After setting CATALOG ON, all tables and associated files such as index, query, format, report, and label files you use or new files you create are added to the catalog.

To stop adding files to an open catalog, use SET CATALOG OFF. Then, when you want to resume adding files to the catalog, use SET CATALOG ON again. To close a catalog, use the SET CATALOG TO command without a filename.

A master catalog, CATALOG.CAT, stores catalog file names along with catalog title descriptions. The description you enter for each catalog entry is displayed later in the catalog window when you use the SET CATALOG TO ? command to select a catalog name.

When you select a catalog file, it is automatically opened in its own work area buffer. If you want to manipulate the catalog table, first open it in a user-accessible work area:

Catname=CATALOG()
USE(Catname) IN SELECT() AGAIN ALIAS Catalog

To update the catalog from within a program, temporarily disable the catalog:

Catname = CATALOG()
SaveCat = SET("CATALOG")
SET CATALOG OFF
USE (Catname) IN SELECT() ALIAS Catalog
* <update catalog>
USE IN Catalog
SET CATALOG TO (SaveCat)

Whenever you open a catalog, dBASE checks the catalog contents against the disk. If you have previously deleted any files with SET CATALOG OFF, dBASE deletes the corresponding entries in the catalog for the files that have been deleted.

Adding entries

When SET CATALOG is ON, a new entry is added automatically to the active catalog when you use any of the following commands:

COPY STRUCTURE	INDEX
COPY STRUCTURE EXTENDED	JOIN
CREATE	SET FILTER
CREATE FROM	SET FORMAT
CREATE|MODIFY FORM	SET VIEW
CREATE|MODIFY LABEL	SORT
CREATE|MODIFY REPORT	TOTAL
CREATE|MODIFY VIEW	USE
IMPORT FROM

If the file name already exists in the catalog, you are prompted for a file title (if SET TITLE is ON). Use the SET TITLE OFF command to suppress the file title prompt if you do not want to enter file titles.


SET CATALOG Example

The following example first CREATEs a CATALOG that contains only the Company and Orders tables. It later opens the catalog with SET CATALOG TO so that a user does not need to deal with any other tables. They can use the Catalog viewer in place of the file viewer:

CLOSE ALL
CREATE CATALOG CompOrd
USE Company
USE Orders IN Select()
SET CATALOG TO
* Now CompOrd is created

SET CATALOG TO CompOrd

Now user can use Catalog Viewer and need not deal with other tables in the subdirectory.


See Also

CATALOG( )

CREATE CATALOG

SELECT( )

SET( )

SET TITLE

USE


SET CENTURY

See Also	Example	Date and Time Data

Controls the format in which dBASE displays the year portion of dates.

Syntax

SET CENTURY on | off

Default

The default for SET CENTURY is set by the International option of the Windows Control Panel. To change the default, set the CENTURY parameter in DBASEWIN.INI. To do so, either use the SET command to specify the setting interactively, or enter the CENTURY parameter directly in DBASEWIN.INI.

Description

When SET CENTURY is ON, dBASE displays dates in the current format with 4-digit years; when SET CENTURY is OFF, dBASE displays dates in the current format with 2-digit years.

You can enter a date with a 2-, 3-, or 4-digit year whether SET CENTURY is ON or OFF. dBASE assumes that 2-digit years are in the 20th century. If SET CENTURY is OFF, dBASE truncates any digits to the left of the last two when displaying the date. However, dBASE stores the correct value of the date internally.

The following table shows the how dBASE displays and stores dates depending on the setting of SET CENTURY. (The table assumes SET DATE is AMERICAN.)

You enter date as	dBASE stores date as	With  SET CENTURY ON,  dBASE displays	With  SET CENTURY OFF,  dBASE displays
{10/13/94}	10/13/1994	10/13/1994	10/13/94
{10/13/994}	10/13/0994	10/13/0994	10/13/94
{10/13/1994}	10/13/1994	10/13/1994	10/13/94
{10/13/2094}	10/13/2094	10/13/2094	10/13/94
As the table shows, SET CENTURY does not affect the relationship between how you enter a date and how dBASE evaluates and stores it. SET CENTURY affects only how dBASE displays the year portion of the date.


SET CENTURY Example

See SET DATE for an example of SET CENTURY.


See Also

DATE( )

SET DATE


SET COLOR TO

See Also	Example	Colors and Fonts

Defines color display characteristics for dBASE IV windows and for text that appears in the results pane of the Command window. This command is supported primarily for compatibility with dBASE IV. In dBASE for Windows, use the ColorNormal or ColorHighlight properties to define colors for objects.

Syntax

SET COLOR TO
[<standard text>]
[, [<enhanced text>]
[, [<perimeter>]
[, [<background>]]]]

[<standard text>]
[, [<enhanced text>]
[, [<perimeter>]
[, [<background>]]]]

Identifies the display elements affected by SET COLOR, as described in the following table:

Argument	Screen element(s) affected
<standard text>	Color attributes of command messages and screen output. For example, the output of the ? and @ ... SAY commands appear in standard text.
<enhanced text>	Color attributes of enhanced text areas, such as @...GET fields and highlighted browse data cells.
<perimeter>	Color attributes of the perimeter bordering the area displaying text on the screen. This argument is included for backward compatibility with dBASE IV; it is ignored under dBASE for Windows.
<background>	Color attributes of the background for display systems with uniform backgrounds, such as monochrome. <background> includes two parameters: a background color and an attribute. This argument is included primarily for backward compatibility with dBASE IV.
Default

dBASE uses the colors set in the Windows desktop as default colors.

Description

Use SET COLOR to select screen colors and attributes. You can also specify colors with the SET COLOR OF command, and with the COLOR option of commands like @...SAY...GET. If you use both SET COLOR and SET COLOR OF to establish a color setting for the same screen element, dBASE uses the color setting of the most recently issued command.

SET COLOR TO with no arguments resets the display to the dBASE default color setting.

Use SET COLOR in programs to customize the appearance of dBASE IV items and to produce graphic effects. When SET COLOR is used while a window is active, it sets color attributes only for the contents of the active window. SET COLOR does not affect the colors in windows you create with DEFINE FORM.

dBASE recognizes <standard text>, <enhanced text>, <perimeter>, and <background> color settings. If a setting is omitted from the list, its place must be marked by a comma. If options are omitted from the end of the list, the comma is not required. For example, if you want to specify a value only for enhanced text, you can issue the following command. The first comma indicates that you don't want to specify a value for standard text.

SET COLOR TO , <enhanced text>

The color and attribute codes recognized by color monitors are shown in the following lists. The attribute codes can be used in combination. You can also specify custom colors using DEFINE COLOR.

Colors recognized by color monitors

Black	N	Magenta	RB
Blue	B	Brown	RG
Green	G	White	W
Cyan	GB	Blank	X
Red	R

Attributes

* or +	High Intensity

The display on some VGA monitors, particularly laptops, is clearest when monochrome color codes are used. In dBASE, monochrome monitors recognize the following color codes and attributes:

Color codes recognized by monochrome monitors

Black	N	White	W
Blank	X

Attributes

* or +	High Intensity

Inverse I Underline	U

Each color argument for the standard and enhanced text areas includes two settings: a foreground color and a background color. Separate the settings with a forward slash (/). For example, the following command sets standard text to blue on a bright white background, and enhanced text to bright white on a red background.

SET COLOR TO B/W+, W+/R

If you omit either of the first two colors in a color setting, dBASE designates it as black. For example, SET COLOR TO W sets standard text to white on a black background.

For more information about the use of the <perimeter> and <background> arguments, see the Syntax section. These arguments are not generally used in Windows applications.


SET COLOR TO Example

See DEFINE COLOR for an example of SET COLOR TO.


See Also

ColorHighlight

ColorNormal

DEFINE

DEFINE COLOR

GETCOLOR( )

ISCOLOR( )

SET COLOR OF


SET COLOR OF

See Also	Example	Portability	Colors and Fonts

Defines the color settings for specified screen areas. This command is supported primarily for compatibility with dBASE IV. In dBASE for Windows, use the ColorNormal or ColorHighlight properties to define colors for objects. SET COLOR OF does not affect forms.

Syntax

SET COLOR OF
NORMAL | HIGHLIGHT | MESSAGES |
BOX | INFORMATION | FIELDS
TO [<color>]

NORMAL | HIGHLIGHT | MESSAGES | BOX | INFORMATION | FIELDS

Identifies the display elements affected by SET COLOR OF, as described in the following table:

Option	Screen element(s) affected
NORMAL	Standard text, such as text displayed by @...SAY statements
HIGHLIGHT	Highlighted bar menu and pop-up menu items, highlighted fields in the BROWSE screen, and all fields in the EDIT screen
MESSAGES	Unselected bar menu and pop-up options, and messages defined with DEFINE MENU, DEFINE PAD, or DEFINE POPUP
BOX	Pop-up borders
INFORMATION	Menu pick characters
FIELDS	Text displayed in @...GET input areas
TO [<color>]

Specifies the color settings.

Default

dBASE uses the colors set in the Windows desktop as default colors. Change the defaults by adding any of the following settings to DBASEWIN.INI: Color of Normal, Color of Highlight, Color of Message, Color of Box, Color of Information, Color of Fields.

Description

Use SET COLOR OF to control the color settings of specific portions of the screen. For information about the color codes to use with SET COLOR OF, and for details on how to specify colors, see SET COLOR TO. SET COLOR OF with no color argument sets the color display for the specified screen area to its default setting.

When dBASE IV windows are open, SET COLOR OF sets colors for the contents of the active window. When you deactivate the window, the SET COLOR OF settings are stored as part of the window definition.


SET COLOR OF Example

The following example sets the color of the normal and field screen areas:

Oldcolors=SET("ATTRIBUTE")
DEFINE COLOR Col_Yellow  255, 255, 0
* define yellow
DEFINE COLOR Col_green     0, 255, 0
* Equivalent to G
SET COLOR OF NORMAL TO Col_Yellow/B
SET COLOR OF FIELDS TO B/Col_green
CLEAR
Today=date()
@ 5,10 say "Hello, today is " get Today
READ
SET COLOR TO &Oldcolors


Portability

Not supported in dBASE III PLUS. The TITLES option has no effect.


See Also

ColorHighlight

ColorNormal

DEFINE

DEFINE COLOR

GETCOLOR( )

ISCOLOR( )

SET COLOR TO


SET CONFIRM

See Also	Example	Environment

Controls the cursor's movement from one entry field to the next during data entry in the results pane of the Command window and in dBASE IV windows.This command is supported primarily for compatibility with dBASE IV. It has no effect on dBASE for Windows forms.

Syntax

SET CONFIRM on | OFF

Default

The default for SET CONFIRM is OFF. To change the default, set the CONFIRM parameter in DBASEWIN.INI.

Description

 When SET CONFIRM is OFF, dBASE moves the cursor immediately to the next input area when the current one is full. When SET CONFIRM is ON, the cursor moves to the next input area only when you press Enter or a cursor-control key, or when you click another input area with the mouse.

Use SET CONFIRM ON to prevent moving the cursor from one input area to the next automatically, thus avoiding data-entry errors such as the overflow of contents from one input area into the next. Use SET CONFIRM OFF when input speed is more important.


SET CONFIRM Example

There are two settings for SET CONFIRM:

SET CONFIRM OFF
SET CONFIRM ON

SET CONFIRM ON automatically moves to the next input area after a keystroke completes the current area.

If the following code is run with SET CONFIRM ON, then the user must press the Enter key to move from cMyVar to nMyVar. If CONFIRM is OFF, the user who enters three characters in cMyVar passes immediately to nMyVar.

SET CONFIRM ON                    && or SET CONFIRM OFF
cMyVar = space(3)
nMyVar = 0
CLEAR
@ 3,5 SAY "CONFIRM IS: "+SET("CONFIRM")
@5,5 SAY "Enter 3 letters: "GET cMyVar PICTURE "AAA"
@6,5 SAY "Enter 3 numbers: "GET nMyVar PICTURE "999"
READ


See Also

SET BELL

SET CUAENTER


SET CONSOLE

See Also	Example	Environment

Controls the display of input and output in the results pane of the Command window during program execution.

Syntax

SET CONSOLE ON | off

Default

The default for SET CONSOLE is ON.

Description

When SET CONSOLE is ON, dBASE displays all standard input and command output in the results pane of the Command window. Use SET CONSOLE OFF to prevent dBASE from displaying this input and output.

You can issue SET CONSOLE only in a program, not in the input pane of the Command window. SET CONSOLE does not affect the display of error messages or safety prompts, nor does it affect the display of input entered in the input pane of the Command window.

A user can enter input requested by a program (such as by WAIT or ACCEPT) while SET CONSOLE is OFF; however, dBASE displays neither the prompt for the input nor the input itself.

@...SAY...GETs override the SET CONSOLE setting and are visible regardless of the SET CONSOLE status.


SET CONSOLE Example

This example uses SET CONSOLE OFF to turn off the screen display while a report is sent to the printer. It then sets the console back on:

SET CONSOLE OFF
REPORT FORM Report1 TO PRINTER
SET CONSOLE ON

Turn CONSOLE OFF only for a specific reason.


See Also

ACCEPT

ON ERROR

SET TALK

WAIT


SET COVERAGE

See Also	Example	Portability	Error Handling and Debugging

Determines whether dBASE creates/updates a coverage file (.COV).

Syntax

SET COVERAGE on | OFF

Default

The default for SET COVERAGE is OFF. To change the default, set the COVERAGE parameter in DBASEWIN.INI. To do so, either use the SET command to specify the setting interactively, or enter the COVERAGE parameter directly in DBASEWIN.INI.

Description

A coverage file is a binary file containing cumulative information on how many times, if any, dBASE enters and exits (and thus fully executes) each logical block of a program. Use SET COVERAGE as a program development tool to determine which program lines dBASE executes and does not execute each time you run a program.

When SET COVERAGE is ON, and you call a program, procedure, or user-defined function (UDF) in a separate program file, dBASE creates a new coverage file or updates an existing one. When dBASE creates a coverage file, it assigns the file the root name of the program or procedure file and a .COV extension.

To view the contents of a coverage file, use DISPLAY COVERAGE or LIST COVERAGE. If the coverage file reveals that some lines are not executing, you can respond by changing the program or the input to the program to make the lines execute. In this way, you can make sure that you test all lines of code in the program.

You can issue SET COVERAGE ON in a program file or in the Command window. If you issue SET COVERAGE ON in a program file, dBASE will create coverage files for that program and for each subroutine that exists in separate programs or procedure files that the main program calls. You can also issue #pragma COVERAGE(ON) in a program file to create a coverage file for it and all program files it calls.

If you issue SET COVERAGE ON in the Command window, dBASE will create coverage files for any programs, or procedures or user-defined functions (UDFs) in open procedure files, that you call from the Command window until you issue SET COVERAGE OFF.

A logical block does not include commented lines or programming construct command lines such as IF and ENDIF. It does, however, include command lines within programming construct command lines. If your program does not contain any programming constructs (IF, DO WHILE, FOR...NEXT, SCAN...ENDSCAN, LOOP, DO CASE, DO...UNTIL), the program has only one logical block consisting of all uncommented command lines.

The coverage file identifies a logical block by its corresponding program line number(s):

Line 1   * UPDATES.PRG
Line 2   SET TALK OFF	Block 1 (Lines 2-3)
Line 3   USE Customer INDEX Salespers
Line 4   SCAN
Line 5      DO CASE
Line 6      CASE Salesper = "S-12"
Line 7         SELECT 2      Block 2 (Lines 7-8)
Line 8         USE S12
Line 9      CASE Salesper = "L-5"
Line 10        SELECT 2      Block 3 (Lines 10-11)
Line 11        USE L5
Line 12     CASE Salesper = "J-25"
Line 13        SELECT 2      Block 4 (Lines 13-14)
Line 14        USE J25
Line 15     ENDCASE
Line 16     DO Changes       Block 5 (Lines 16-17)
Line 17     SELECT 1
Line 18  ENDSCAN
Line 19  CLOSE ALL           Block 6 (Lines 19-20)
Line 20  SET TALK ON

Before dBASE can create coverage files, you must compile the program file and all called files you want to analyze while SET COVERAGE is ON. If you COMPILE a program while SET COVERAGE is OFF, then turn SET COVERAGE ON and DO the program, dBASE does not produce a coverage file.

dBASE writes the coverage file to disk when the program is unloaded from memory or when you issue LIST COVERAGE or DISPLAY COVERAGE. To unload a program from memory, use CLEAR PROGRAM.

The preprocessor command #pragma COVERAGE(ON) can only be used in a program file. When you use #pragma COVERAGE(ON), you do not have to issue SET COVERAGE ON before compiling the program; instead of recreating the coverage file, dBASE updates the existing one when you make changes to the program and recompile.


SET COVERAGE Example

The following example is a batch program that updates records from a central file:

* Update.PRG
USE Clients
SET COVERAGE ON
SCAN
  IF DELETED()
    DO Deletes
  ELSE
    DO Updates
  ENDIF
ENDSCAN
DISPLAY COVERAGE Update
CLOSE ALL

PROCEDURE Updates
    * update code here

PROCEDURE Deletes
    * delete code here

DISPLAY COVERAGE opens a .COV file that shows which lines of the program dBASE executed when the program was run. If no records were marked for deletion, the coverage file would reveal that dBASE had not executed one logical block, the line DO DELETES. To test whether the call to procedure Deletes works, the programmer could delete a test record and run the program again so that dBASE executes line 5.

When SET COVERAGE is ON and dBASE executes every line of a program, procedure, or UDF file, the coverage file states that test coverage was 100%.


Portability

Not supported in dBASE IV or dBASE III PLUS.


See Also

#pragma

COMPILE

DEBUG

DISPLAY COVERAGE

SET DEVELOPMENT


SET CUAENTER

See Also	Example	Portability	Forms

Determines whether Enter works in Windows mode or dBASE DOS mode.

Syntax

SET CUAENTER ON | off

Default

The default for SET CUAENTER is ON. To change the default, update the CUAENTER setting in dBASEWIN.INI. To do so, either use the SET command to specify the setting interactively, or enter the CUAENTER parameter directly in DBASEWIN.INI.

Description

Use SET CUAENTER to control Enter.

In dBASE for Windows, pressing Enter submits the current form; this is typical of Windows applications. However, in dBASE DOS, pressing Enter moves the cursor from one GET field to the next. In dBASE for Windows, you move focus from object to object with the mouse or by pressing Tab and Shift+Tab instead of Enter.

To move focus in the dBASE DOS manner, execute SET CUAENTER OFF. You typically do this when you need to maintain consistency with your DOS applications.


SET CUAENTER Example

The following example creates a basic form with three entry fields from the Contact table and two pushbuttons to advance or retard the record pointer. SET CUAENTER OFF is used to make the cursor behave as it would in a DOS application, that is, advance between fields or to the pushbuttons when the user presses Enter. Changing the command to SET CUAENTER ON causes the cursor to respond only to the TAB key and mouse clicks:

LOCAL f
f = NEW BFORM()
f.Open()

CLASS BFORM OF FORM
   this.HelpFile = ""
   this.Width =         53.60
   this.Height =         13.00
   this.Left =         47.00
   this.Text = "Edit as Required"
   this.Top =          4.88
   this.OnClose = {;SET CUAENTER ON}
   this.HelpId = ""

   DEFINE ENTRYFIELD ENTRYFIELD1 OF THIS;
       PROPERTY;
         Width          9.00,;
         Height          1.50,;
         Left          1.00,;
         DataLink "COMPANY->COMPCODE",;
         Top          5.00,;
         Border .T.

   DEFINE ENTRYFIELD TYPE OF THIS;
       PROPERTY;
         Width          9.00,;
         Height          1.50,;
         Left         11.00,;
         DataLink "COMPANY->TYPE",;
         Top          5.00,;
         Border .T.

   DEFINE ENTRYFIELD COMPANY OF THIS;
       PROPERTY;
         Width         30.00,;
         Height          1.50,;
         Left         22.00,;
         DataLink "COMPANY->COMPANY",;
         Top          5.00,;
         Border .T.

   DEFINE TEXT TEXT1 OF THIS;
       PROPERTY;
         Width         40.00,;
         Alignment          7,;
         Height          2.41,;
         Left          6.00,;
         Text "Company Information",;
         Top          1.00,;
         ColorNormal "N/W",;
         Border .T.,;
         FontSize         12.00

   DEFINE PUSHBUTTON BACK OF THIS;
       PROPERTY;
         Width         15.40,;
         Default .T.,;
         OnClick {;SKIP-1},;
         Height          2.00,;
         Left          3.00,;
         Text "Back",;
         Top          8.00,;
         ColorNormal "N/W"

   DEFINE PUSHBUTTON NEXT OF THIS;
       PROPERTY;
         Width         15.40,;
         OnClick {;SKIP},;
         Height          2.00,;
         Left         25.00,;
         Text "Next",;
         Top          8.00,;
         ColorNormal "N/W"

ENDCLASS


Portability

Not supported in dBASE IV or dBASE III PLUS.


See Also

READ

@...SAY...GET


SET CURRENCY

See Also	Example	Portability	Numeric Data

SET CURRENCY left | right positions currency symbol(s) to the left or right of a monetary value when you use the "$" PICTURE or FUNCTION symbol or the function TRANSFORM( ). SET CURRENCY TO determines the characters dBASE uses for the currency symbol in PICTURE or FUNCTION clauses.

Syntax

SET CURRENCY left | right

SET CURRENCY TO
[<expC>]

LEFT

Places currency symbol(s) to the left of currency numbers.

RIGHT

Places currency symbol(s) to the right of currency numbers.

<expC>

The characters that appear as a currency symbol. Although dBASE imposes no limit to the length of <expC>, it recognizes only the first nine characters. You cannot include numbers in <expC>.

Default

The defaults for SET CURRENCY are set by the International option of the Windows Control Panel. You can change the defaults interactively by using the SET command, or by specifying parameters directly in DBASEWIN.INI.

To change the default location of the currency symbol, set the CURRENCY parameter to LEFT or RIGHT in the [OnOffCommandSettings] section in DBASEWIN.INI.

To change the default characters that appear as a currency symbol, set the CURRENCY parameter in the [CommandSettings] section in DBASEWIN.INI.

Description

Use SET CURRENCY left | right to specify the position of currency symbol(s) in monetary numeric values. Use SET CURRENCY TO to establish a currency symbol other than the default.

When SET CURRENCY is LEFT, dBASE displays only as many currency symbols as fit, together with the digits to the left of any decimal point, within ten character spaces.

SET CURRENCY TO without the <expC> option resets the currency symbol to the default set with the International option of the Windows Control Panel.


SET CURRENCY Example

An example of SET CURRENCY LEFT | RIGHT is shown in the example for INT( ).


Portability

SET CURRENCY left | right is not supported in dBASE III PLUS. SET CURRENCY TO <expC > is not supported in dBASE III PLUS or dBASE IV.


See Also

SET POINT

SET SEPARATOR

TRANSFORM( )


SET CURSOR

Example	Portability	Keyboard and Mouse Events

Determines whether the cursor is visible or hidden.

Syntax

SET CURSOR ON | off

Default

The default for SET CURSOR is ON. To change the default, set the CURSOR parameter in DBASEWIN.INI.

Description

Use SET CURSOR to control whether a cursor appears on the screen. When SET CURSOR is OFF, the cursor is hidden. Issue SET CURSOR ON to redisplay the cursor.


SET CURSOR Example

The following program ensures that the cursor is on during the program and resets the cursor when leaving:

OldCursor=SET("CURSOR")    && save current setting
SET CURSOR ON              && set cursor on
* ...
SET CURSOR &OldCursor      && reset cursor


Portability

Not supported in dBASE III PLUS.


SET DATABASE

See Also	Example	Portability	Table Basics

Sets the default database from which tables are accessed.

Syntax

SET DATABASE TO [<database name>]

<database name>

Specifies the name of the database you want to make the current database.

Description

SET DATABASE sets the current database, which defines the default location for tables accessed by dBASE commands. Using this command, you can select from any databases previously opened with the OPEN DATABASE command. Databases are defined using the IDAPI Configuration Utility. (For more information on using this program, see Getting Started.)

When you issue the SET DATABASE TO command without a database, dBASE for Windows restores operation to accessing tables in the current directory (or in the directory specified by SET PATH).


SET DATABASE Example

See OPEN DATABASE and DATABASE( ) for examples of using SET DATABASE.


Portability

Not supported in dBASE IV or dBASE III PLUS.


See Also

CLOSE...

DATABASE( )

OPEN DATABASE

SET DBTYPE


SET DATE

See Also	Example	Portability	Date and Time Data

Specifies the format dBASE uses for the display and entry of dates. For information on changing the system date, see SET DATE TO.

Syntax

SET DATE [TO] AMERICAN | ANSI | BRITISH | FRENCH | GERMAN |
ITALIAN | JAPAN | USA | MDY | DMY | YMD

TO

Include for readability only; TO has no affect on the operation of the command.

AMERICAN | ANSI | BRITISH | FRENCH | GERMAN | ITALIAN |
JAPAN | USA | MDY | DMY | YMD

The options correspond to the following formats:

Option	Format
AMERICAN	MM/DD/YY
ANSI	YY.MM.DD
BRITISH	DD/MM/YY
FRENCH	DD/MM/YY
GERMAN	DD.MM.YY
ITALIAN	DD-MM-YY
JAPAN	YY/MM/DD
USA	MM-DD-YY
MDY	MM/DD/YY
DMY	DD/MM/YY
YMD	YY/MM/DD
Default

The default for SET DATE is set by the International option of the Windows Control Panel. To change the default, set the DATE parameter in DBASEWIN.INI. To do so, either use the SET command to specify the setting interactively, or enter the DATE parameter directly in DBASEWIN.INI.

Description

SET DATE determines how dBASE displays fields and memory variables of date type. If SET CENTURY is ON, dBASE displays all formats with a 4-digit year.

SET DATE overrides any prior SET MARK setting. However, you can use SET MARK after SET DATE to change the date separator character.


SET DATE Example

The following examples use SET DATE and SET CENTURY to control the display of date data.

date = {04/01/94}            && or date = {4/1/94}
SET CENTURY OFF
SET DATE AMERICAN
? date                       && Returns 04/01/94
SET CENTURY ON
? date                       && Returns 04/01/1994
SET DATE JAPAN
? date                       && Returns 1994/04/01
SET DATE GERMAN
? date                       && Returns 01.04.1994
SET DATE BRITISH
? date                       && Returns 01/04/1994
SET DATE ITALIAN
? date                       && Returns 01-04-1994
SET DATE FRENCH
? date                       && Returns 01/04/1994
SET DATE USA
? date                       && Returns 04-01-1994


Portability

The format options JAPAN, USA, MDY, DMY, and YMD are not supported in dBASE III PLUS.


See Also

DATE( )

DMY( )

MDY( )

SET CENTURY

SET DATE TO

SET MARK


SET DATE TO

See Also	Example	Portability	Date and Time Data

Sets the system date. See SET DATE for information on changing how dBASE displays dates.

Syntax

SET DATE TO <expC>

<expC>

The character expression, in the current date format, to set as the current system date.

Default

The default for the value of the system date is set by the Date/Time option of the Windows Control Panel.

Description

Use SET DATE TO to reset the date on your system clock. Subsequent values of DATE( ) and the date stamp of files you save reflect the new date.

Enter <expC> in the current date format as determined by SET DATE, DBASEWIN.INI, or the International option of the Windows Control Panel (in that order). That is, SET DATE settings override those in DBASEWIN.INI, and settings in DBASEWIN.INI override those in the Windows Control Panel. Be sure <expC> matches the date format in use when your program runs.

The date must be in the range from January 1, 1980, to December 31, 2099. Because dBASE assumes 2digit years refer to twentieth-century dates, you must type all 4 digits for the year of dates beyond the twentieth century.


SET DATE TO Example

The following example uses SET DATE TO and SET TIME TO to update system time after getting input from the user:

SET PROCEDURE TO PROGRAM(1) ADDITIVE

DEFINE FORM Main FROM 0,0 to 13,55;

   PROPERTY ColorNormal "BG+/BG",;

   Text "System Update"

DEFINE TEXT T1 OF Main AT 3,5 ;

   PROPERTY TEXT "Enter Current Time (24 hour):",;

   Width 39

DEFINE ENTRYFIELD F1 OF Main AT 3,40 ;

   PROPERTY Value SPACE(8), Picture "99:99:99",;

   Width 12

DEFINE TEXT T2 OF Main AT 5,5 ;

   PROPERTY TEXT "Enter Current Date",;

   Width 25

DEFINE ENTRYFIELD F2 OF Main AT 5,40 ;

   PROPERTY Value {}, Picture "99/99/99",;

   Width 12

DEFINE PUSHBUTTON Update OF Main AT 9,7;

  PROPERTY TEXT "Update System Time and Date",;

  Height 2, Width 38, OnClick Update

OPEN FORM Main

PROCEDURE Update

SET DATE TO DTOC(Form.F2.Value)

SET TIME TO Form.F1.Value

? "Update complete"

CLOSE FORM Main

RETURN


Portability

Not supported in dBASE III PLUS or dBASE IV.


See Also

DATE( )

SET CENTURY

SET DATE

SET TIME


SET DBTYPE

See Also	Example	Portability	Table Basics

Sets the default table type to either Paradox or dBASE.

Syntax

SET DBTYPE TO [PARADOX | DBASE]

PARADOX | DBASE

Sets the default table type to a Paradox or dBASE table.

Default

The default for SET DBTYPE TO is DBASE. To change the default, update the DBTYPE setting in DBASEWIN.INI. To do so, either use the SET command to specify the setting interactively, or enter the DBTYPE parameter directly in DBASEWIN.INI.

Description

SET DBTYPE sets the default type of table used by commands that open or create a table. You can override this selection by specifying a specific extension, that is, .DBF for a dBASE table or .DB for a Paradox table.

SET DBTYPE TO specified without a DBASE or PARADOX argument returns DBTYPE to its default (dBASE).


SET DBTYPE Example

The following example uses SET DBTYPE to set the environment for a relation between two .DBF files. Selected fields are copied to a Paradox table. SET DBTYPE then sets the table type environmental variable to Paradox, and the newly created table is used and browsed. SET DBTYPE finally sets the environment back to the default of DBASE:

CLOSE DATABASES
SET SAFETY OFF
SET DBTYPE TO DBASE
USE Company ORDER Compcode IN SELECT()
USE Contact IN SELECT()
SELECT Contact
SET RELATION TO CompCode INTO Company
SELECT Contact
COPY TO CntctLst TYPE PARADOX;
   FIELDS Company->Company, ;
   Contact->CompCode, Contact->Contact, ;
   Company->Street1, Company->Street2, ;
   Company->City, Company->State_Prov, ;
   Company->Zip_P_Code
CLOSE DATABASES
SET DBTYPE TO PARADOX
USE CntctLst
BROWSE
CLOSE DATABASES
SET DBTYPE TO


Portability

Not supported in dBASE IV or dBASE III PLUS.


See Also

CLOSE...

COPY TABLE

CREATE

DATABASE( )

DELETE TABLE

MODIFY STRUCTURE

OPEN DATABASE

RENAME TABLE

SET DATABASE

USE


SET DECIMALS

See Also	Example	Numeric Data

Determines the number of decimal places of numbers to display.

Syntax

SET DECIMALS TO
[<expN>]

<expN>

The number of decimals places, from 0 to 18.

Default

The default for SET DECIMALS is 2. To change the default, set the DECIMALS parameter in DBASEWIN.INI. To do so, either use the SET command to specify the setting interactively, or enter the DECIMALS parameter directly in DBASEWIN.INI.

Description

Use SET DECIMALS to specify the number of decimal places of numbers you want dBASE to display. SET DECIMALS affects the display of most mathematical calculations, but not the way numbers are stored on disk or maintained internally.

SET DECIMALS TO without <expN> resets the number of decimal places back to the default of 2.


SET DECIMALS Example

The following example uses SET DECIMALS to control how many decimal places are displayed:

SET DECIMALS TO 2
? 2.22 * 3.3333              && Returns 7.40
SET DECIMALS TO 0
? 2.22 * 3.3333              && Returns 7
SET DECIMALS TO 7
? 2.22 * 3.3333              && Returns 7.3999260

Additional examples of using SET DECIMALS are included in the examples for INT( ) and RANDOM( ).


See Also

INT( )

RANDOM( )

ROUND( )

SET PRECISION

VAL( )


SET DEFAULT

See Also	Example	Disk and File Utilities

Determines the default drive dBASE uses when searching for and storing files. SET DEFAULT is supported primarily for backward compatibility with dBASE III PLUS. In dBASE for Windows, you can use SET DIRECTORY to specify a default drive and/or directory in a single statement.

Syntax

SET DEFAULT TO
[<drive>]

<drive>[:]

A single letter indicating the default drive. You can type a colon following the drive letter, but it does not affect the operation of SET DEFAULT.

Default

The default for SET DEFAULT is the drive to which DOS is currently logged.

Description

Use SET DEFAULT to inform dBASE which drive holds input data and should receive new files. SET DEFAULT TO without the option <drive> sets the default drive to the original default drive.

Use SET PATH to designate additional directories for dBASE to search for files.


SET DEFAULT Example

In this example, a programmer has set the data files on the B drive and the program files in a hard disk subdirectory. The default is set to the data drive and a path is made to the program subdirectory:

SET PATH TO C:\PROJECT\PRG
SET DEFAULT TO B:\

Now all DO statements will find their programs in the path and all table statements, USE etc, will be found in the default drive.


See Also

RUN

SET DIRECTORY

SET PATH

VALIDDRIVE( )


SET DELETED

See Also	Example	Portability	Fields and Records

Controls whether dBASE for Windows processes records marked for deletion.

Syntax

SET DELETED ON | off

Default

The default for SET DELETED is ON. To change the default, update the DELETED setting in DBASEWIN.INI. To do so, either use the SET command to specify the setting interactively, or enter the DELETED parameter directly in DBASEWIN.INI.

Description

Use SET DELETED to include or exclude records marked for deletion in a table. When SET DELETED is OFF, all records appear in a table. When SET DELETED is ON, dBASE for Windows excludes records that have been marked for deletion from processing by subsequent commands such as LOCATE and LIST. Records marked for deletion, however, do remain in the table.

GO <expN>, INDEX, REINDEX, RECCOUNT( ) and any command executed with the RECORD <expN> scope option are not affected by SET DELETED. If, however, SET DELETED is ON and the records are displayed, GO <expN> does not place the record pointer on a record marked for deletion.

If two tables are related with SET RELATION, SET DELETED ON suppresses the display of deleted records in the child table. The related record in the parent table still appears, however, unless the parent record is also deleted.


SET DELETED Example

The following example uses SET DELETED to exclude records that are marked for deletion from being copied to another table:

SET SAFETY OFF
USE Contact EXCLUSIVE IN SELECT()
INDEX ON CompCode TAG CompCode
USE Company IN SELECT()
SELECT Company
SET RELATION TO CompCode INTO Contact
DELETE FOR Company->State_Prov = "CA"
SET DELETED ON
COPY FIELDS Company->Company, Contact->Contact, ;
   Company->Street1, Company->Street2, ;
   Company->City, Company->State_Prov,;
   Company->Zip_P_Code TO CntctLst TYPE PARADOX
SET DBTYPE TO PARADOX
USE CntctLst
BROWSE
CLOSE ALL
SET DBTYPE TO
SET SAFETY ON


Portability

In dBASE IV, the default for SET DELETED is OFF. In addition, regardless of the SET DELETED setting, if you position the record pointer on a specific record with the GO command, dBASE IV displays the record whether or not it is marked for deletion. dBASE for Windows does not display records marked for deletion when SET DELETED is ON.


See Also

DELETE

DELETED( )

PACK

RECALL

SET( )

SET FILTER

SET RELATION


SET DELIMITERS

See Also	Example	Input/Output

Controls whether specified delimiter characters mark the beginning and end of data-entry fields. This command is supported primarily for compatibility with dBASE IV, and has no effect in dBASE for Windows forms.

Syntax

SET DELIMITERS on | OFF

SET DELIMITERS TO
[<expC> | DEFAULT]

Default

The default for SET DELIMITERS is OFF. To change the default, set the DELIMITERS parameter in the [OnOffCommandSettings] section in DBASEWIN.INI. The default delimiter character is a colon (:). To change the default, set the DELIMITERS parameter in the [CommandSettings] section in DBASEWIN.INI.

To make changes to DBASEWIN.INI, either use the SET command to specify the settings interactively, or enter the DELIMITERS parameters directly in DBASEWIN.INI.

Description

When SET DELIMITERS is ON, data-entry fields begin and end with the delimiters specified with SET DELIMITERS TO. The default delimiter is a colon if no delimiters have been specified with SET DELIMITERS TO.

<expC>

A character expression indicating the single character or the pair of characters to be used as delimiters. If you specify a single character, it marks both the beginning and the end of a data-entry field. If you specify two characters, the first marks the beginning of a data-entry field, and the second marks the end. If you specify more than two characters, dBASE uses only the first two.

DEFAULT

Sets the delimiters to the default character, a colon ( : ). DEFAULT has the same effect as using SET DELIMITERS TO with no options.

Note:	SET DELIMITERS does not affect the DELIMITED WITH character in APPEND FROM and COPY TO.

In most cases, you do not need to use SET DELIMITERS, because dBASE IV entry fields and variables are already emphasized. However, if you have issued SET INTENSITY OFF, you might want to use SET DELIMITERS ON to show the beginning and end of each field.


SET DELIMITERS Example

The following example uses delimiters to emphasize a GET statement:

SET DELIMITERS ON
SET DELIMITERS TO "="
Examplevar="Test Delim  "
@ 5,5 SAY "Show delimiters" get Examplevar
* row 5 appears as
*     Show delimiters =Test Dilim  =
* The GET field has an equal sign immediately to
* the left and right.
SET DELIMITERS OFF  && reset SET DELIMITER


See Also

APPEND

COPY

DEFINE

SET INTENSITY


SET DESIGN

See Also	Example	Portability	Environment

Determines whether CREATE and MODIFY commands can be executed.

Syntax

SET DESIGN ON | off

Default

The default for SET DESIGN is ON. To change the default, set the DESIGN parameter in DBASEWIN.INI. To do so, either use the SET command to specify the setting interactively, or enter the DESIGN parameter directly in DBASEWIN.INI.

Description

When SET DESIGN is ON, dBASE lets you use CREATE and MODIFY commands to create and modify tables, forms, labels, reports, text, and queries. To prevent users of your applications from creating and modifying these types of files, issue SET DESIGN OFF in your programs.

If you issue SET DESIGN ON or OFF in a subroutine, the setting is effective only during execution of that subroutine.


SET DESIGN Example

The default setting of SET DESIGN is usually ON. In this example the default setting in dBASEWIN.INI is OFF so that a user cannot use CREATE and MODIFY:

* In dBASEWIN.INI
[OnOffCommandSettings]
design =OFF


Portability

Not supported in dBASE III PLUS.


See Also

CREATE

CREATE FORM

CREATE LABEL

CREATE REPORT

MODIFY COMMAND

MODIFY FILE

MODIFY STRUCTURE


SET DEVELOPMENT

See Also	Portability	Programs

Determines whether dBASE automatically compiles a program, procedure, or format file when you change the file and then execute it or open it for execution.

Syntax

SET DEVELOPMENT ON | off

Default

The default for SET DEVELOPMENT is ON. To change the default, set the DEVELOPMENT parameter in DBASEWIN.INI. To do so, either use the SET command to specify the "Ensure Compilation" setting interactively, or enter the DEVELOPMENT parameter directly in DBASEWIN.INI.

Description

When SET DEVELOPMENT is ON and you execute a program file with DO, or open a procedure or format file, dBASE compares the time and date stamp of the source file and the compiled file. If the source file has a later time and date stamp than the compiled file, dBASE recompiles the file.

When SET DEVELOPMENT is ON and you change a source program, procedure, or format file with MODIFY COMMAND, dBASE erases the corresponding compiled file. When you then execute the program or open the procedure or format file, dBASE recompiles it.

When SET DEVELOPMENT is OFF, dBASE does not compare time and date stamps, and executes or opens existing compiled program, procedure, or format files. When you modify a source file and then open or execute it, dBASE first looks for a compiled file in memory and executes it if found. If no compiled file is in memory, dBASE looks for a compiled disk file and executes it if found. If no compiled file is found, dBASE compiles the file.

When you DO a program, open a procedure file with SET PROCEDURE, or open a format file with SET FORMAT, dBASE always looks for, opens, and executes a compiled file. Therefore, if dBASE cannot find a compiled version of a source file when you execute or open the source, dBASE compiles the file regardless of the SET DEVELOPMENT setting.

During program development, when you are editing files often, you should turn SET DEVELOPMENT ON. This ensures that you are always executing an up-to-date compiled file.

Turn SET DEVELOPMENT OFF when you no longer plan to change any source code. Turning SET DEVELOPMENT OFF speeds up program execution because dBASE does not have to check time and date stamps. You might want to set the DEVELOPMENT parameter to OFF in the DBASEWIN.INI file you distribute with your compiled code.


Portability

Not supported in dBASE III PLUS.


See Also

CLEAR PROGRAM

COMPILE

DO

SET PROCEDURE


SET DEVICE

See Also	Example	Portability	Input/Output

Directs the output of @...SAY...GET commands, or non-streaming output, to the results pane of the Command window or current dBASE IV window, the printer, or a file. This command is supported primarily for compatibility with dBASE IV. In dBASE for Windows, use SET PRINTER to direct streaming output to the printer or a file.

Syntax

SET DEVICE
TO SCREEN |
TO PRINTER |
TO FILE <filename> | ? | <filename skeleton>

TO SCREEN

Directs the output of @...SAY commands to the current window. By default, the current window is the results pane of the Command window.

TO PRINTER

Directs the output of @...SAY commands to the printer. If you have issued SET PRINTER TO and specified a file instead of a printer, issuing SET DEVICE TO PRINTER directs @...SAY command output to the SET PRINTER file.

TO FILE <filename> | ? | <filename skeleton>

Directs the SAY output of @...SAY...GET commands to the text file <filename>. By default, dBASE assigns a .TXT extension to <filename> and saves the file in the current directory. The ? and <filename skeleton> options display a dialog box in which you specify the name of the target file and the directory to save it in.

If SET SAFETY is ON and a file exists with the same name as the target file, dBASE displays a dialog box asking if you want to overwrite the file. If SET SAFETY is OFF, any existing file with the same name is overwritten without warning.

Default

The default for SET DEVICE is TO SCREEN. To change the default, set the DEVICE parameter in DBASEWIN.INI.

Description

Use SET DEVICE to direct the output of @...SAY commands. For standard viewing of displays in windows, specify the default SCREEN. With SCREEN set, @...SAY...GET output overwrites anything at the same window location.

For printing displays as reports, specify PRINTER. The printer, in this case, is the one defined by the last SET PRINTER command, or the default print spooler if no SET PRINTER command has been issued. @...GET commands are ignored. An @ command that specifies coordinates of lower values than previous @ commands results in a page eject. On some printers, @...SAYs might not appear until the print buffer is emptied. To empty the buffer, issue an EJECT command or print a blank line.

SET DEVICE TO PRINTER and SET PRINTER ON perform different tasks. SET DEVICE TO PRINTER sends only @...SAY output to the device (printer or file) you have specified with SET PRINTER TO. SET PRINTER ON sends keyboard entries, @...SAY output, and other dBASE output to the device (printer or file) you have specified with SET PRINTER TO. Because SET PRINTER ON sends streaming output to the printer, you have more control over output format by using system memory variables and font styles. For more information, see Chapter 24 in the Programmer's Guide.

To create text files that can be edited with the Text Editor for use in documents or special reports, specify FILE <filename>. As with printer output, SET DEVICE TO FILE <filename> stores only the SAY output of @...SAY...GET commands, not the GET output. To create a record of dBASE output and commands other than @...SAY commands, such as the results of ? and ?? commands, use SET ALTERNATE.


SET DEVICE Example

This example uses the SET DEVICE TO FILE, TO PRINTER and TO SCREEN to write text to an ASCII file, to a printer file and, just to the screen:

SET DEVICE TO FILE Rose
* Open Rose.txt for text output
? "Opening alternate file" && to screen only
@ 5,10 SAY "A file rose "
@ 7,10 SAY "is a rose "
@ 9,10 SAY "is a rose "
SET DEVICE TO PRINTER
* Rose.txt is now closed
@ 5,10 SAY "A printed rose "
@ 7,10 SAY "is a rose "
@ 9,10 SAY "is a rose "
EJECT
CLOSE PRINTER         && initiates printing
SET DEVICE TO SCREEN  && closes printer output
@ 5,10 SAY "A screen rose "
@ 7,10 SAY "is a rose "
@ 9,10 SAY "is a rose "


Portability

In dBASE III PLUS, the PRINTER option is called PRINT, and the TO FILE options are not supported. The ? and <filename skeleton>options aren't supported in dBASE IV.


See Also

?

??

@...SAY...GET

CHOOSEPRINTER( )

EJECT

SET ALTERNATE

SET FORMAT

SET PRINTER

SET SAFETY


SET DIRECTORY

See Also	Example	Portability	Disk and File Utilities

Changes the current working drive or directory.

Syntax

SET DIRECTORY TO
[<path>]

<path>

A character expression indicating the default path. To specify a root path, start <path> with a backslash (\) or the root directory (as with C:\). If <path> does not begin with \ or the root directory, dBASE begins the path with the current directory.

Default

The default working directory is the same as the directory returned by HOME( ); that is, the directory containing the dBASE program files. You can change the default in Windows or in dBASE. In Windows, if you specify a Working Directory when you create or modify the dBASE icon properties, dBASE uses that directory as its default.

You can also update the DIRECTORY setting in dBASEWIN.INI. To do so, either use the SET command to specify the setting interactively, or enter the DIRECTORY parameter directly in DBASEWIN.INI.

A directory in the DBASEWIN.INI file overrides any in the dBASE icon's Working Directory field.

Description

SET DIRECTORY lets you change the current working drive and directory. Use SET DIRECTORY to change the current working directory to any valid drive and path. The current directory appears in the File Viewer window.

dBASE returns an error message if you try to SET DIRECTORY to a drive that doesn't exist or isn't ready. If you are unsure whether a drive is valid and ready for use, issue VALIDDRIVE( ) before using SET DIRECTORY.

SET DIRECTORY TO .. (two periods) changes the directory to the directory one level above the current directory. SET DIRECTORY TO without the option <path> sets the directory to the dBASE icon's Working Directory, if there is one specified, or else to the HOME( ) directory.

Another way to access files on different directories is with the command SET PATH. You can specify one or more search paths, and dBASE uses these paths to locate files not on the current directory. Use SET PATH when an application's files are in several directories. You can also use SET DEFAULT to specify the drive on which dBASE searches for and stores files.

If you change the drive with SET DIRECTORY, the default drive (SET DEFAULT) is also set to the new drive.

SET DIRECTORY works like CD, except CD with no argument causes dBASE to display the current drive and directory. See CD for details on path statements.


SET DIRECTORY Example

The following example saves the current directory, then uses SET DIRECTORY to change directories several times and examine the files in these subdirectories. Finally, the example returns to the original directory:

* This example assumes that
* directories were created by:
* MD D:\Project
* MD D:\Project\Programs
* MD D:\Project\Data
* MD C:\Editor

Olddir=SET("DIRECTORY") && Original Directory
SET DIRECTORY TO D:\Project\Data
DIR                     && displays DBFs
SET DIRECTORY TO D:\Project\Programs
DIR *.prg               && display the programs
SET DIRECTORY TO ..
* moves from D:\Project\Programs to D:\Project
DIR *.*
SET DIRECTORY TO C:\Editor && C:\Editor
DIR *.doc
SET DIRECTORY TO &Olddir && return


Portability

Not supported in dBASE III PLUS.


See Also

CD

HOME( )

MKDIR

SET( )

SET PATH

VALIDDRIVE( )


SET DISPLAY

See Also	Example	Portability	Environment

Makes the results pane of the Command window correspond to the specified DOS display mode. This command is supported primarily for compatibility with dBASE IV. You don't need to issue this command for new applications running only in Windows.

Syntax

SET DISPLAY TO
MONO | COLOR | EGA25 | EGA43 | MONO43 | VGA25 |
VGA43 | VGA50

MONO | COLOR |EGA25 | EGA43 | MONO43 | VGA25 |
VGA43 | VGA50

The monitor display mode to set:

Display mode	Effect
MONO	Monochrome
COLOR	COlor
EGA25	25-line enhanced color display
EGA43	43-line enhanced color display
MONO43	43-line monochrome
VGA25	25-line VGA display
VGA43	43-line VGA display
VGA50	50-line VGA display
Description

Use SET DISPLAY to change screen display modes and resize the results pane of the Command window for use with dBASE IV applications. You don't need to issue this command for new applications running only in Windows.


SET DISPLAY Example

This example saves the current setting of SET DISPLAY and then tries each possible setting in turn:

Old_display=SET("DISPLAY")
Old_color=SET("Attribute")
SET COLOR TO G/B

SET DISPLAY TO MONO
CLEAR
WAIT "Mono"
SET DISPLAY TO COLOR
CLEAR
WAIT "COLOR"
SET DISPLAY TO EGA25
CLEAR
WAIT "EGA25"
SET DISPLAY TO EGA43
CLEAR
WAIT "EGA43"
SET DISPLAY TO MONO43
CLEAR
WAIT "MONO43"
SET DISPLAY TO VGA50
CLEAR
WAIT "VGA50"

SET DISPLAY TO &Old_display
SET COLOR TO &Old_color


Portability

Not supported in dBASE III PLUS.


See Also

OS( )

VERSION( )


SET ECHO

See Also	Portability	Error Handling and Debugging

Opens the dBASE Debugger. This command is supported primarily for compatibility with dBASE IV. In dBASE for Windows, use DEBUG to open the debugger.

Syntax

SET ECHO on | OFF

Default

The default for SET ECHO is OFF.

Description

Use SET ECHO to turn on the Debugger and view or control program execution interactively. SET ECHO is identical to DEBUG. For more information, see DEBUG.


Portability

In dBASE IV and dBASE III PLUS, SET ECHO ON does not open the Debugger when dBASE encounters the command but rather displays command lines as they execute (on the screen, to a file, or to the printer), thus providing a history of command line execution.


See Also

DEBUG

SET STEP


SET EDITOR

See Also	Example	Portability	Environment

Specifies the text editor to use when creating and editing programs and text files.

Syntax

SET EDITOR TO
[<expC>]

<expC>

The expression you would enter at the DOS prompt or as the Windows command line to start the editor, usually the name of the editor's executable file (.EXE) or a Windows .PIF file. If <expC> does not include the file's full path name, dBASE looks for the file in the current directory, then in the DOS path.

Default

The default for SET EDITOR is the dBASE for Windows internal Text Editor. To specify a different default editor, set the EDITOR parameter in DBASEWIN.INI. To do so, either use the SET command to specify the setting interactively, or enter the EDITOR parameter directly in DBASEWIN.INI.

Description

Use SET EDITOR to specify an editor other than the default dBASE Text Editor to use when creating or editing text files. The file name you specify can be any text editor that produces standard ASCII text files. The specified editor opens when you issue CREATE/MODIFY FILE or CREATE/MODIFY COMMAND. If you issue SET EDITOR TO without a file name for <expC>, dBASE returns to the default editor.

To choose an editor to use when viewing and editing memo fields, use SET WP.

You can use SET EDITOR to specify a .PIF file, which is a Windows file that controls the Windows environment for a DOS application, or a Windows .EXE file. Start the DOS editor by running the .PIF file rather than the .EXE. When you issue commands that run in a DOS window, dBASE loads COMMAND.COM using DBASEWIN.PIF in the _dbwinhome directory. You can use the Windows PIF Editor to customize the settings in DBASEWIN.PIF. For more information about .PIF files, see your Windows documentation. If there is not enough memory available to access an external editor, dBASE returns an "Unable to execute DOS" error message.

If the text editor you specify is already in use when you open a memo or file for editing, a second instance of the editor starts.


SET EDITOR Example

The following example changes the default editor to Brief, to Write, the Windows editor and back to the dBASE editor:

SET EDITOR TO "c:\brief\b"
* now c:\brief does not need to be in
* the path statements
* MODIFY COMMAND now accesses Brief.
MODIFY COMMAND TEMP.PRG
SET EDITOR TO
MODIFY COMMAND TEMP
* Reverts to dBASE editor

You might not have sufficent RAM to access an external editor in which case dBASE gives an "Unable to execute DOS" error message.


Portability

Not supported in dBASE IV or dBASE III PLUS.


See Also

_dbwinhome

MEMORY( )

MODIFY COMMAND

MODIFY FILE

SET WP


SET ERROR

See Also	Example	Portability	Error Handling and Debugging

Specifies one character expression to precede error messages and another one to follow them.

Syntax

SET ERROR TO
[<preceding expC> [, <following expC>]]

<preceding expC>

An expression of up to 33 characters to precede error messages. dBASE ignores any characters after 33.

<following expC>

An expression of up to 33 characters to follow error messages. dBASE ignores any characters after 33. If you want to specify a value for <following expC>, you must also specify a value or empty string ("") for <preceding expC>.

Default

The default for the message that precedes error messages is "Error: ". The default for the message that follows error messages is an empty string. To change the default, set the ERROR parameter in DBASEWIN.INI, using the following format:

ERROR = <precedingexpC> [, <followingexpC>]

Description

Use SET ERROR to customize the beginnings and endings of run-time error messages. SET ERROR TO without an argument resets the beginnings and endings to the default values.

SET ERROR is similar to ON ERROR; both can be used to customize error messages. SET ERROR, however, can only specify expressions to precede and follow a standard dBASE error message, while ON ERROR can specify the message itself. Also unlike ON ERROR, SET ERROR cannot call a procedure that carries out a series of commands.


SET ERROR Example

Use SET ERROR to customize error messages.

SET ERROR TO "Oops! - ", " - Please fix this."
? "a" = 1          && generate a runtime error
SET ERROR TO


Portability

Not supported in dBASE IV or dBASE III PLUS.


See Also

ERROR( )

MESSAGE( )

ON ERROR


SET ESCAPE

See Also	Example	Keyboard and Mouse Events

Specifies whether pressing Esc interrupts program execution.

Syntax

SET ESCAPE ON | off

Default

The default for SET ESCAPE is ON. To change the default, set the ESCAPE parameter in DBASEWIN.INI.

Description

When SET ESCAPE is ON, pressing Esc interrupts program execution. Use SET ESCAPE OFF in a program to prevent unexpected user interruptions and command file termination during the execution of commands such as INDEX, PACK, and COPY.

Note:	Use SET ESCAPE OFF only in tested programs. If SET ESCAPE is OFF and you have not used ON KEY or SET KEY to designate another key that interrupts programs, you can interrupt program execution only by rebooting your computer. Rebooting your computer to interrupt program execution, in turn, can cause data loss.

Regardless of whether SET ESCAPE is ON or OFF, pressing Esc always interrupts the processing of commands that pause for input from the keyboard, including ACCEPT, BROWSE, EDIT, INPUT, and READ.


SET ESCAPE Example

In the following example there is a bug in the subroutine WontWork. The instructions and the loop test do not correspond. With SET ESCAPE ON, you can press the Escape key to interrupt the program You can then choose SUSPEND to examine the variable MORE or to follow the program through the loop:

SET ESCAPE ON
DO WontWork

PROCEDURE WontWork
More = ""
DO WHILE More <> "X" && should be Upper(More)<>"X"
  ? "Beginning the loop"
  * ...
  WAIT "Enter E to exit the loop" TO More
ENDDO


See Also

CLEAR TYPEAHEAD

INKEY( )

ON ERROR

ON ESCAPE

ON KEY

READKEY( )

SET KEY


SET EXACT

See Also	Example	Portability	String Data

Establishes the rules dBASE uses to determine whether two character strings are equal.

Syntax

SET EXACT on | OFF

Default

The default for SET EXACT is OFF. To change the default, set the EXACT parameter in DBASEWIN.INI. To do so, either use the SET command to specify the setting interactively, or enter the EXACT parameter directly in DBASEWIN.INI.

Description

When comparing two strings, dBASE compares the first character of the string on the right of the equal sign with the first character of the string on the left, then the second character of the right string to the second of the left string, and so on until two characters do not match or all characters of the right string have been examined.

If there are more characters in the string on the right, dBASE always returns .F. when the strings are compared. Therefore, if you know one string is longer than the other, put the longer string on the left side of the comparison operator.

When SET EXACT is ON, dBASE recognizes two character strings as equal when they are identical. When SET EXACT is OFF, dBASE recognizes two character strings as equal if all the characters in the string to the right of the comparison operator (=) match the beginning characters in the string to the left.

For example, ? "abc"="abcdef" returns .F. whether SET EXACT is ON or OFF, because all the characters in the string on the right do not match the beginning characters in the string on the left. (There are more characters on the right than on the left.)

When SET EXACT is OFF, ? "abcdef"="abc" returns .T. because the characters in the string on the right do match the beginning characters in the string on the left. When SET EXACT is ON, ? "abcdef"="abc" returns .F., because the strings are not identical.

When SET EXACT is OFF and the right string is an empty string (""), dBASE returns .T. when any string is compared to the empty string. When SET EXACT is ON and the right string is an empty string, dBASE returns .T. only when another empty string is compared to it.

To force an exact comparison whether SET EXACT is ON or OFF, use == instead of =, as shown in the following example.

SET EXACT OFF
? "abcd" = "abc"	&& returns .T.
? "abcd" == "abc"   && returns .F.

In language drivers that have primary and secondary weights for characters (not U.S. language drivers but most others), dBASE compares characters by their primary weights when SET EXACT is OFF and by their secondary weights when SET EXACT is ON. For example, when SET EXACT is OFF, and the current language driver is German, "drücker" and "drucker" are equal.

SET EXACT affects all commands and functions that involve a string comparison, including FIND, SEEK, SEEK( ), LOCATE, LOOKUP( ), and any command executed with the FOR or WHILE option. For FIND and SEEK, dBASE treats the character string you specify as the right string of the comparison and the index file's key field as the left string.


SET EXACT Example

The following example uses SET EXACT to control how close to check for a match between two strings:

SET EXACT ON
? "Will" = "William"               && Returns .F.
? "William" = "Will"               && Returns .F.
SET EXACT OFF
? "Will" = "William"               && Returns .F.
? "William" = "Will"               && Returns .T.

The second example uses SET EXACT to demonstrate the difference between locating a memory variable with the SEEK command when EXACT is set OFF or ON:

SET TALK OFF
SET SAFETY OFF
SET EXACT OFF
USE Clients EXCLUSIVE
INDEX ON UPPER(Contact) TAG Contact
Lookup="Martin"
SEEK UPPER(Lookup)
IF FOUND()
   DISPLAY FIELDS Company,Contact
ELSE
   ? "With EXACT SET OFF, the record was not found"
ENDIF

SET EXACT ON
SEEK UPPER(Lookup)
IF FOUND()
   DISPLAY FIELDS Company,Contact
ELSE
   ? "With EXACT SET ON, the record was not found"
ENDIF
SET TALK ON
SET SAFETY ON
CLOSE DATABASES


Portability

In dBASE IV, constants are evaluated during compilation and not again during program execution. ? "abc"="a" returns .T. if SET EXACT is OFF when the program is compiled (and was not explicitly set in the program). If you later SET EXACT to ON in the Command window, ? "abc"="a" still returns .T. in the program.

In dBASE for Windows, constants are evaluated during program execution; ? "abc"="a" returns .T. or .F. depending on the setting of SET EXACT when the program is run.


See Also

CHARSET( )

FIND

LDRIVER( )

LOCATE

LOOKUP( )

SEEK

SEEK( )

SET LDCHECK


SET EXCLUSIVE

See Also	Example	Portability	Shared Data

Controls whether dBASE opens tables and their associated index and memo files in exclusive or shared mode.

Syntax

SET EXCLUSIVE on | OFF

Default

The default for SET EXCLUSIVE is OFF. To change the default, set the EXCLUSIVE parameter in DBASEWIN.INI. To do so, either use the SET command to specify the setting interactively, or enter the EXCLUSIVE parameter directly in DBASEWIN.INI.

Description

When you issue SET EXCLUSIVE ON, subsequent tables you open--and their associated indexes and memos--are in exclusive mode, unless you open them with USE...SHARED. When you open a table in exclusive mode, other users cannot open, view, or change the file or any of its associated index and memo files. If you try to open a table that another user has opened in exclusive mode, dBASE displays an error message.

SET EXCLUSIVE OFF causes subsequent tables you open--and their associated indexes and memos--to be in shared mode, unless you open them with USE...EXCLUSIVE. If a table in shared mode is in a shared network directory, other users on the network with access to the directory can open, view, and change the file and any of its associated index and memo files.

If you use SET INDEX and the table is open in exclusive mode, dBASE opens the index in exclusive mode. If the table is open in shared mode by way of an overriding USE...SHARED, dBASE opens the index in the mode specified by USE.

An index created with INDEX is opened in exclusive mode, regardless of whether the table is opened in shared or exclusive mode and regardless of the SET EXCLUSIVE setting. After creating an index, you can open the index in shared mode with USE...INDEX...SHARED or by issuing SET EXCLUSIVE OFF followed by SET INDEX TO.

The following commands require the exclusive use of a table with either SET EXCLUSIVE ON or USE...EXCLUSIVE:

CONVERT

COPY INDEXES

DELETE TAG

INDEX...TAG

INSERT

INSERT AUTOMEM

INSERT BLANK

MODIFY STRUCTURE

PACK

REINDEX

ZAP


SET EXCLUSIVE Example

The following example uses the Company table with SET EXCLUSIVE ON so that a new index can be created. Once the index is created Company is reopened with exclusive off:

CLOSE ALL
SET EXCLUSIVE ON
USE Company
INDEX ON CompCode+Company TAG CompComp
SET EXCLUSIVE OFF
* New USE commands will not be exclusive
* But Company is currently exclusive
USE Company ORDER CompComp
* This releases the exclusive lock on Company


Portability

Not supported in dBASE III PLUS.


See Also

FLOCK( )

INDEX

RLOCK( )

SET INDEX

SET LOCK

USE


SET FIELDS

See Also	Example	Fields and Records

Defines a group of fields to access in a table.

Syntax

SET FIELDS on | OFF

SET FIELDS TO
[<field list> | ALL [LIKE <skeleton 1>] [EXCEPT <skeleton 2>]]

<field list> | ALL [LIKE <skeleton1> | EXCEPT <skeleton 2> ]

The fields list accessible in subsequent table operations. The fields list may include fields from tables open in all work areas and may also include read-only calculated fields. The following table provides a description of SET FIELDS TO options:

Option	Description
ALL	Makes all fields accessible in all work areas
LIKE <skeleton 1>	Makes all fields whose names match <skeleton 1> accessible in all work areas
EXCEPT <skeleton 2>	Makes all fields except those whose names match <skeleton 2> accessible in all work areas
LIKE <skeleton 1> EXCEPT <skeleton 2>	Makes all fields whose names are like <skeleton 1> except those whose names match <skeleton 2> accessible in all work areas
Default

The default for SET FIELDS is OFF; however, specifying a fields list with SET FIELDS TO automatically sets FIELDS ON.

Description

The SET FIELDS command defines a list of fields that can be accessed in one or more tables. You can specify fields in other work areas by specifying fields prefixed by an alias name. The list of fields specified with the SET FIELDS command is not active unless you set FIELDS ON. When SET FIELDS is OFF, all fields in a table are accessible.

SET FIELDS is automatically set ON when you define a fields list with SET FIELDS TO <field list>. You might, however, want to use SET FIELDS OFF to have all fields available in certain circumstances and then switch back later to the restricted fields list you have specified with the SET FIELDS TO command. If you SET FIELDS ON without using the SET FIELDS TO <field list> command, no fields are accessible.

SET FIELDS TO with no parameters clears the fields list, makes all fields accessible, and sets FIELDS OFF. (The CLEAR FIELDS command also clears the fields list.)

SET FIELDS affects the following commands, allowing access to only the fields specified in <field list> when SET FIELDS is set ON:

APPEND	DISPLAY
AVERAGE	EDIT
BLANK	JOIN
BROWSE	LIST
CALCULATE	SUM
CHANGE	SET CARRY
CREATE/MODIFY VIEW	TOTAL
COPY
COPY STRUCTURE
COPY TO ARRAY

SET FIELDS TO does not affect the following commands:

INDEX	SET FILTER

LOCATE	SET RELATION

The fields list specified with SET FIELDS TO can include both table field names and calculated fields. The /R option provides a setting to specify read-only access to table fields, for example:

Salary/R, Hours/R

To specify a calculated field, you can specify any valid dBASE expression. For example,

Gross_pay = Salary * Hours

The skeleton uses the wildcard character * for any number of characters and ? for one character. ALL LIKE selects fields that match the skeleton. ALL EXCEPT selects the fields that do not match the skeleton. SET FIELDS TO ALL includes all fields of the current table.

To add to a previously specified fields list, use SET FIELDS TO again, with additional fields. For example, if you specify SET FIELDS TO Field1, and then SET FIELDS TO Field2, both Field1 and Field2 are in the fields list.


SET FIELDS Example

The following example uses SET FIELDS ON or OFF to alternate between a fields list declared with SET FIELDS TO and a table in the current work area:

SELECT 1
USE Contact Order CompCode
SELECT 2
USE Company
SET RELATION TO CompCode INTO Contact
SET FIELDS TO Contact->CompCode, Company->Company, ;
   Contact->Contact, Company->Phone
SET FIELDS OFF
BROWSE              && Company displayed in Browse
SET FIELDS ON
BROWSE              && Fields list displayed
CLEAR FIELDS


See Also

CLEAR FIELDS

SET( )

SET CARRY

SET RELATION


SET FILTER

See Also	Example	Table Organization

Sets a condition to limit records processed by dBASE commands.

Syntax

SET FILTER TO
[<condition>] | [FILE <filename> | ? | <filename skeleton>]

<condition>

The condition that records must meet to be processed by subsequent dBASE commands.

FILE <filename> | ? | <filename skeleton>

The query file that specifies the filter condition. SET FILTER FILE ? and SET FILTER FILE <filename skeleton> display a dialog box, in which you can select a file. If you specify a file without including its path, dBASE for Windows looks for the file in the current directory, then in the path you specify with SET PATH. If you specify a file without including its extension, dBASE for Windows assumes a .QRY extension.

Description

Use SET FILTER to view or work with only a portion of the records of a table. SET FILTER TO with no condition or file specified removes the current filter condition, causing dBASE for Windows to process all records in the table. You can set up a separate filter condition for each table you open in a different work area.

SET FILTER TO <condition> sets up a filter based on a valid dBASE expression. The condition can filter records in the current table based on an expression including all data types except memo. For example, you can specify SET FILTER TO Lastname = "Jones" to filter records in a character field, SET FILTER TO Departure > {01/01/94} to filter records based on a date field. You can also combine conditions, for example, specifying SET FILTER TO Lastname = "Jones" .AND. Departure > {01/01/94}.

SET FILTER TO FILE <filename> obtains a filter condition from a dBASE III PLUS query (.QRY) file. You cannot use a dBASE IV or dBASE for Windows .QBE file with this command.

Filters specified with the SET FILTER command are not activated until after the record pointer is moved within a table (for example, using the GO TOP or SKIP command). All commands that require a table in use, such as AVERAGE, BROWSE, EDIT, and REPORT, can use conditions specified by SET FILTER.

A filter condition does not affect commands that identify records directly by number, such as GOTO <expN>. GOTO <expN> can move the pointer to a record that does not meet the filter condition; however, you cannot display that record (for example, using the EDIT command).


SET FILTER Example

The following example uses SET FILTER to restrict the following BROWSE command to Clients in California:

USE Clients
SET FILTER TO State_Prov = "CA"
BROWSE FIELDS Company, Contact, City, ;
  State_Prov, Cuisine
SET FILTER TO          && release the filter

The following example uses SET FILTER to select from a RELATED table:

CLOSE DATA
USE Company EXCLUSIVE
INDEX ON Compcode TAG Compcode
SELE 2
USE Contact EXCLUSIVE
INDEX ON Contact TAG Compcode
SET RELATION TO Compcode INTO Company
SET FILTER TO Company->State_Prov="CA"
DISPLAY ALL ;
  Contact, Compcode,;
  Company->Company, Company->State_prov

Only contacts of companies in California are displayed.


See Also

CREATE QUERY

MODIFY QUERY

SET( )

SET DELETED

SET KEY


SET FORMAT

See Also	Example	Portability	Input/Output

Opens the specified format file in the selected work area, closing any currently open format file. Also compiles the format file if it has not already been compiled. This command is supported primarily for compatibility with dBASE IV. In dBASE for Windows, use DEFINE to create forms, which are used instead of dBASE IV windows or format files.

Syntax

SET FORMAT TO
[<filename> | ? | <filename skeleton>]

<filename> | ? | <filename skeleton>

The format file whose format to use. The ? and <filename skeleton> options display a dialog box from which you can select a file. If you specify a file without including its path, dBASE looks for the file in the current directory, then in the path you specify with SET PATH. If you specify a file without including its extension, dBASE assumes .FMO (a compiled format file). If dBASE cannot find a file with the extension .FMO, it looks for a file with the extension .FMT, which, if found, it compiles.

Description

Use a format file to specify custom formats to display in the Command Results window or the current window for data entry. Format files contain a series of commands, primarily @...SAY...GET commands, that define prompts and entry fields to appear within a window. SET FORMAT TO with no argument closes any format file that is open in the current work area. One format file can be open in each work area.

Create a format file using MODIFY COMMAND and give the file the extension .FMT. A format file can contain the following commands:

@...SAY...GET, READ

@...CLEAR, @...FILL, @...SCROLL, and @...TO

*, &&, and NOTE

Other commands in a format file have no effect.

SET FORMAT TO with no file name and CLOSE FORMAT achieve identical results. Issue CLOSE FORMAT <filename> when you are through with <filename> so that it does not interfere with subsequent READs.

To display and activate a format file's @...SAY...GET statements in the current window, first open the window with ACTIVATE WINDOW. After opening the window, activate the @...SAY...GETs in the open format file by issuing APPEND, BROWSE [FORMAT], CHANGE, EDIT, INSERT, or READ.

If you open a format file in conjunction with a CHANGE or EDIT command, the FIELDS option of CHANGE or EDIT has no effect. However, you can change or edit only those fields the format file displays.

READ within a format file activates the @...SAY...GET statements after the READ and before either the next READ or the end of the format file. You can thus create a multi-window format file by inserting READ statements to start new displays in the current window and numbering subsequent @...SAY...GETs from row 0. Pressing PgDn replaces the current display with the next, and PgUp replaces the current display with the previous.

Format files support colors defined with the SET COLOR and SET COLOR TO commands.


SET FORMAT Example

This example shows the use of SET FORMAT to create a two page READ:

Name=space(20)
Address=space(20)
SET FORMAT TO FORM1
READ
*
* FORM1.FMT contains:
*
* @ 0,0 SAY "PAGE 1"
* @ 5,5 SAY "Name" GET Name
* READ
* @ 0,0 SAY "PAGE 2"
* @ 5,5 SAY Name
* @ 6,6 SAY "Address" GET Address


Portability

In dBASE III PLUS, @...GET fields just occur onscreen. In dBASE IV, @...GET fields can appear onscreen outside of windows and can occur in the context of a window opened with ACTIVATE WINDOW.


See Also

@...SAY...GET

ACTIVATE WINDOW

APPEND

BROWSE

CHANGE

CLOSE...

DEFINE WINDOW

EDIT

INSERT

READ

SET COLOR TO

SET DEVELOPMENT


SET FULLPATH

See Also	Example	Portability	Environment

Specifies whether functions that return file names return the full path with the file name.

Syntax

SET FULLPATH on | OFF

Default

The default for SET FULLPATH is OFF. To change the default, set the FULLPATH parameter in DBASEWIN.INI. To do so, either use the SET command to specify the setting interactively, or enter the FULLPATH parameter directly in DBASEWIN.INI.

Description

Use SET FULLPATH ON when you need to have functions such as CATALOG( ), DBF( ), MDX( ), and NDX( ) return a file name with its full path. For example, if you are using tables in SQL databases, or tables located in different directories, issue SET FULLPATH ON to ensure that DBF( ) returns the full file name for use in subsequent commands.


SET FULLPATH Example

The following example obtains the name of the current table using both FULLPATH ON and FULLPATH OFF:

USE COMPANY
SET FULLPATH ON
? DBF()
* FULLPATH  ON returns
*   G:\DBASEWIN\EXAMPLES\COMPANY.DBF
SET FULLPATH OFF
? DBF()
* FULLPATH OFF returns
*   G:COMPANY.DBF


Portability

Not supported in dBASE III PLUS. If you want file names returned in the same format as they are in dBASE III PLUS, issue SET FULLPATH OFF.


See Also

CATALOG( )

DBF( )

MDX( )

NDX( )

SET( )


SET FUNCTION

See Also	Example	Keyboard and Mouse Events

Assigns a command or expression to a function key or to a combination of the Ctrl (control) key or the Shift key and a function key.

Syntax

SET FUNCTION <key> TO <expC>

<key>

A function key number, function key name, or character expression of a function key name--for example, 3, F3, or "F3". Specify a character expression for <key> to assign a key combination using the Ctrl or Shift key with a function key. Type "CTRL+" or "SHIFT+" in uppercase or lowercase and then a function key name--for example, "shift+F5" or "Ctrl+f3". You can use a hyphen in place of the plus sign. You cannot combine Ctrl and Shift, such as "Ctrl+Shift+F3".

<expC>

A dBASE command, function, user-defined function (UDF), or any character string. Follow a command with a semicolon (;) to execute the command immediately when you press <key>. You can execute more than one command by separating each command in the list with a semicolon.

Default

The following function key settings are in effect when dBASE starts:

Key	Command	Key	Command
F1	HELP;	F7	DISPLAY MEMORY;
F3	LIST;	F8	DISPLAY;
F4	DIR;	F9	APPEND;
F5	DISPLAY STRUCTURE;	F10	Activates the menu
F6	DISPLAY STATUS;
Description

Use SET FUNCTION to assign commands to a function key or a function key combination with Ctrl or Shift. You can also use SET FUNCTION to assign any character expression to a function key. When you are in the Command window and press the key or key combination, <expC> appears at the cursor. If <expC> ends with a semicolon, dBASE executes it immediately. If <expC> does not end with a semicolon (;), you can edit it.

Note:	F2 is reserved for toggling between views while in the Browse window. You can program it, but it will not be recognized when in the Browse window. You cannot program F10, or any combination using F11 or F12.

In forms, expressions assigned with SET FUNCTION are recognized only when you are in Entry Fields.

For more information on programming function keys, as well as on programming other keys, see ON KEY.


SET FUNCTION Example

The following example issues the SET command when the user presses a function key. This activates the PROPERTIES|ENVIRONMENT menu which lets the user change any SET command defaults:

SET FUNCTION F9 TO "SET;"

SET FUNCTION can also be used to issue multiple commands as follows:

SET FUNCTION F8 TO "CLOSE ALL;CLEAR;"+;
  "USE Clients;BROWSE;"


See Also

DISPLAY STATUS

FKLABEL( )

FKMAX( )

HELP

INKEY( )

ON KEY


SET HEADINGS

See Also	Example	Portability	Input/Output

Controls the display of field names in the output of AVERAGE, DISPLAY, LIST, and SUM.

Syntax

SET HEADINGS ON | off

Default

The default for SET HEADINGS is ON. To change the default, set the HEADINGS parameter in DBASEWIN.INI. To do so, either use the SET command to specify the setting interactively, or enter the HEADINGS parameter directly in DBASEWIN.INI.

Description

When SET HEADINGS is ON, the output of AVERAGE, DISPLAY, LIST, and SUM includes a heading identifying the fields of the table(s). Issue SET HEADINGS OFF before issuing AVERAGE, DISPLAY, LIST, or SUM to view output data without field-name headings.


SET HEADINGS Example

The following example uses DISPLAY with SET HEADING ON to show the field names and SET HEADING OFF to hide the field names:

USE Clients
SET HEADING OFF
? "Heading off"
DISPLAY Client_id, Company
SET HEADING ON
? "Heading on"
DISPLAY Client_id, Company
*
* Heading off
*       1  A8513 A Beck Pertamina
*
* Heading on
* Record#  Client_id Company
*       1  A8513     A Beck Pertamina


Portability

In dBASE III PLUS, the command is SET HEADING (no final s).

In dBASE IV, SET HEADINGS also affects the results of the TYPE command, determining whether the display of the typed file includes a heading specifying the file name and date. In dBASE for Windows, TYPE does not include this heading, regardless of the SET HEADINGS setting.


See Also

AVERAGE

DISPLAY

LIST

SUM

TYPE


SET HELP

See Also	Example	Portability	Windows Programming

Determines which Help file (.HLP) the dBASE Help system uses.

Syntax

SET HELP TO
[<help filename> | ? | <help filename skeleton>]

<help filename> | ? | <help filename skeleton>

Identifies the Help file to activate. ? and <filename skeleton> display a dialog box, from which you can select a file. If you specify a file without including its extension, dBASE assumes .HLP.

Description

Use SET HELP TO to specify which Help file to use when the dBASE Help system is activated.

The Help file is opened automatically when you start dBASE if you place the file in the dBASE home directory.

SET HELP TO closes any open Help file before it opens a new file.


SET HELP Example

To display a dialogue box to select from available Help files, issue the following command:

SET HELP TO ?    && or optionally
SET HELP TO *.HLP

To set Help to your own tailored help file:

SET HELP TO MyHlp.HLP

To set the Help file back to the dBASE for Windows default:

SET HELP TO \DBASEWIN\BIN\DBASEWIN.HLP


Portability

Not supported in dBASE IV or dBASE III PLUS.


See Also

HELP

HelpFile

HelpID

SET TOPIC


SET IBLOCK

See Also	Example	Portability	Table Organization

Changes the default block size used for new .MDX files.

Syntax

SET IBLOCK TO <expN>

<expN>

A number from 1 to 63 that sets the size of index blocks allocated to new .MDX files. The default value is 1. (The actual size in bytes is the number you specify multiplied by 512 bytes; however, the minimum size of a block is 1024 bytes.) To change the default, update the IBLOCK setting in DBASEWIN.INI. To do so, either use the SET command to specify the setting interactively, or enter the IBLOCK parameter directly in DBASEWIN.INI.

Description

Use SET IBLOCK to change the size of blocks in which dBASE for Windows stores .MDX files on disk to improve the performance and efficiency of indexes. You can specify a block size from 1024 bytes to approximately 32K. The IBLOCK setting overrides any previous block size defined by the SET BLOCKSIZE command or specified in the DBASEWIN.INI file. After the block size has been changed, new .MDX index files are created with the new block size.

Multiple index (.MDX) files are composed of individual index blocks (or nodes). Nodes contain the value of keys corresponding to individual records and provide the information to locate the appropriate record for each key value. Since the IBLOCK setting determines the size of nodes, the setting also determines the number of key values that can fit into each node. When a single node cannot contain all the key values in an index, dBASE for Windows creates one or more parent nodes. These intermediate nodes also contain key values. Instead of pointing to record numbers, however, intermediate nodes point to leaf nodes or other lower-level intermediate nodes. If you increase the size of index blocks and create a new .MDX file, the new and larger leaf nodes contain more key values.

Whether you can improve performance by storing key values in larger or smaller nodes depends on several factors: the distribution of data, if tables are linked together, the length of key values, the value of INDEXBYTES, and the type of operation requested. Typically, every .MDX file contains more than one index tag. Finding the best setting for a given .MDX file requires experimentation because the best size for one index tag might not be the best size for another.

The following is a list of basic principles governing index performance.

Since nodes might not be sequential, dBASE for Windows reads only one node at a time from the disk. Reading more than one node is usually inefficient, because typically the second node is not the next node in the sequential list.

Once a node is read into memory, dBASE for Windows attempts to store it there for later use. The amount of space devoted to caching the index nodes is determined by the setting of INDEXBYTES.

When users link several tables together, for example, with SET RELATION, performance is better if all the relevant nodes for the tables are in memory simultaneously. For example, if a large node for table B pushes out the previously read node for table A, dBASE for Windows must find and read the table A node again from disk when the node for table A needs to be used again. If both nodes remain in memory, performance can be improved.

When tables have many identical key values, dBASE for Windows might have to store them in many nodes. In this situation, performance might be improved by increasing the node size so that dBASE for Windows reads fewer nodes from disk to load the same number of key values into memory.

Small node sizes can cause performance degradation. This occurs because as nodes are read in and out, dBASE for Windows attempts to cache them all. When the small nodes are removed from memory by more recently read nodes, they leave unused spaces in memory that are too small to contain larger nodes. Over time, memory can become fragmented, resulting in slower performance.


SET IBLOCK Example

This example creates two .MDXs containing identical data but with different IBLOCK settings and consequently, different file sizes:

CLOSE DATA
DELETE FILE Co1.mdx
DELETE FILE Co2.mdx
* remove any previous .mdx
* CREATE THE MDXs
USE Company EXCLUSIVE
SET IBLOCK TO 2
INDEX ON CompCode TAG CompCode OF Co1
INDEX ON Company  TAG Company  OF Co1
INDEX ON City TAG City         OF Co1
SET IBLOCK TO 20
INDEX ON CompCode TAG CompCode OF Co2
INDEX ON Company  TAG Company  OF Co2
INDEX ON City TAG City         OF Co2
DIR CO?.MDX

Two .MDXs, Co1.MDX and Co2.MDX are created with different IBLOCK settings. CO1 and CO2 will have different file sizes because their block lengths are different.


Portability

Not supported in dBASE III PLUS.


See Also

COPY

COPY INDEXES

CREATE

MODIFY STRUCTURE

INDEX

REINDEX

REPLACE

SET( )

SET BLOCKSIZE

SET MBLOCK


SET INDEX

See Also	Example	Table Organization

Opens index files for the current table. Not applicable for Paradox and SQL tables.

Syntax

SET INDEX TO
[<filename list> | ? | <filename skeleton>]
[ORDER [TAG]
<filename 1> | <tag name> [OF
<filename 2> | ? | <filename skeleton>]]

<filename list> | <?> | <filename skeleton>

Specifies the index files to open, including both single and multiple indexes. SET INDEX TO ? and SET INDEX TO <filename skeleton> display a dialog box, in which you select an index file. If you specify a file without including its path, dBASE for Windows looks for the file in the current directory, then in the path you specify with SET PATH.

If you specify a file without including its extension, dBASE for Windows assumes an .NDX extension for single index files and an .MDX extension for multiple index files. If you have an .NDX file and an .MDX file with the same name, to open the .NDX file, specify the .NDX extension.

ORDER [TAG] <filename 1> | <tag name>

Specifies a master index that can be an .NDX file or a tag name contained within an .MDX index file.

OF <filename 2> | ? | <filename skeleton>

Specifies a multiple index file containing <tag name>. OF ? and OF <filename skeleton> display a dialog box, in which you select a multiple index file. If you specify a file without including its path, dBASE for Windows looks for the file in the current directory, then in the path you specify with SET PATH. If you specify a file without including its extension, dBASE for Windows assumes a .MDX extension.

Description

Use SET INDEX to open the specified .NDX and .MDX files in the current work area that will be updated when changes are made to the associated table. Including an index file list when issuing USE...INDEX is equivalent to following the USE command with the SET INDEX command.

If the first index opened with SET INDEX is an .NDX file, that index becomes the master index unless you specify another master index with the ORDER option or the SET ORDER command. If the first index opened with SET INDEX is an .MDX file and you do not specify the ORDER clause, no master index is defined, and records in the table appear in record number or natural order. To specify a master index for the current table, specify the ORDER option or use the SET ORDER command.

Before opening the indexes specified with the command, SET INDEX closes all open index files except those index files with tag names listed in the production .MDX file, the index file with the same name as the current table. Specifying SET INDEX TO without a list of indexes closes all open .NDX and .MDX files in the current work area, except for the production index file. You can also use the CLOSE INDEX command. All indexes, including the production .MDX file, are closed when you close the table.

The order in which you specify indexes with the SET INDEX command is not necessarily the same as the order dBASE for Windows uses. Open indexes for a specified work area are listed in the following order:

1.	Any single index files are in the order you list them in <filename list>.

2.	Indexes in the production .MDX file are in the order you list them in the .MDX file.

3.	Indexes in other .MDX files you specify with USE...INDEX or the SET INDEX command are in the order you list them in the individual .MDX files.

The order of the open indexes remains the same until you specify another index order with the USE...INDEX or SET INDEX commands, or you issue an INDEX command. Use the order number as an argument with NDX( ), TAG( ), and KEY( ) to determine an index file name, tag name, or key expression.


SET INDEX Example

The following example uses SET INDEX to open index tags and set the controlling index:

SET SAFETY OFF   && To avoid overwrite warning
USE Company EXCLUSIVE
INDEX ON Company TAG Company   && TAG Company in ;
                                   Company.mdx
INDEX ON Compcode  TAG Compcode
SET INDEX TO Company ORDER Company
BROWSE FIELDS Company, Compcode;
  TITLE "Indexed by Company"

The following example uses SET INDEX to open .NDX index files and set the controlling index:

USE Company EXCLUSIVE
INDEX ON Company TO Company    && Company.ndx
INDEX ON Compcode  TO Compcode && Compcode.ndx
SET INDEX TO Compcode.ndx, Company.ndx
* These are .NDX indexes, not .MDX tags
BROWSE FIELDS Compcode, Company;
  TITLE "Indexed by Compcode"


See Also

CLOSE...

INDEX

KEY( )

MDX( )

NDX( )

ORDER( )

REINDEX

SET ORDER

TAG( )

TAGNO( )

TAGCOUNT( )

USE


SET INTENSITY

See Also	Example	Environment

Determines whether dBASE displays variable and field data during data-entry operations in dBASE IV windows in reverse video (monochrome monitors) or in the colors specified for enhanced text with the SET COLOR or SET COLOR OF command (color monitors). SET INTENSITY is supported primarily for compatibility with dBASE IV. To define colors for Windows objects, use the ColorNormal and ColorHighlight properties.

Syntax

SET INTENSITY ON | off

Default

The default for SET INTENSITY is ON. To change the default, set the INTENSITY parameter in DBASEWIN.INI.

Description

When SET INTENSITY is ON, dBASE displays variable and field data in the enhanced text colors you specify with SET COLOR or SET COLOR OF. When SET INTENSITY is OFF, dBASE displays all data, including variable and field data and the status bar in the standard text colors you specify with SET COLOR or SET COLOR OF.

If you haven't used SET COLOR or SET COLOR OF to set an enhanced text color combination, SET INTENSITY ON causes dBASE to display enhanced text in reverse video.


SET INTENSITY Example

In this example, two GETs are issued. The first has intensity set on and the second has intensity off:

First="Amelia"
Last="Bloom"
SET INTENSITY ON && The default
@ 5,10 SAY "First name " GET First
SET INTENSITY OFF
@ row(),col()+2 Say "Last name :" GET Last
READ
SET INTENSITY ON && Reset

SET INTENSITY OFF makes GETs and SAYs visually indistinguishable.


See Also

ColorNormal

ColorHighlight

SET COLOR TO

SET COLOR OF

SET DELIMITERS


SET KEY

See Also	Example	Portability	Keyboard and Mouse Events

Assigns a program or a procedure to a specified key or key combination. (The dBASE IV command SET KEY, which limits the records processed in a table to those whose key field value falls within a range, is now called SET KEY TO.)

Syntax

SET KEY <expN> | <expC> TO
[<program name> | <procedure name>]

<expN> | <expC>

The key you assign the program or procedure to. <expN> is the INKEY( ) value of the key or key combination. <expC> is a function specified by F1 through F9, Shift+F1 through Shift+F10, or Ctrl+F1 through Ctrl+F10.

<program name> | <procedure name>

The program or procedure you assign to the key or key combination.

Description

Use SET KEY to assign a program or a procedure to a key or a key combination. When the user presses the specified key or key combination, SET KEY causes dBASE to stop execution of the current program and execute the specified program or procedure. The original program resumes execution when the program or procedure that SET KEY executes is completed.

SET KEY is identical in function to ON KEY LABEL; only the syntax differs. If you use ON KEY LABEL and SET KEY to set the same key, dBASE executes the program or procedure specified by the most recently issued command. For more information, see ON KEY.


SET KEY Example

The following example uses SET KEY to set a function key, an alt key, a control key and an alpha key as procedure calls:

SET PROCEDURE TO PROGRAM(1) ADDITIVE
SET KEY "F2" TO Open      && Do Open
SET KEY "ALT-F3" TO Close && Do Close
SET KEY "CTRL-F4" TO New  && Do New
SET KEY "x" TO Exit       && Do Exit

KEYBOARD "x{F2}{ALT-F3}{ctrl-F4}"
* This will call each function in turn

* Warning: the letter X will call
* the Exit procedure and cannot be used
* for ordinary typing.

Now reset the keys:

SET KEY "F2" TO
SET KEY "ALT-F3" TO
SET KEY "CTRL-F4" TO
SET KEY "x" TO

PROCEDURE Open
? "In open procedure"
RETURN

PROCEDURE Close
? "In Close Procedure"
RETURN

PROCEDURE Exit
? "In Exit Procedure"
RETURN

PROCEDURE New
? "In New Procedure"
RETURN


Portability

Not supported in dBASE IV or dBASE III PLUS. However, ON KEY is supported in both.


See Also

ON KEY

SET ESCAPE

SET FUNCTION

SET KEY TO


SET KEY TO

See Also	Example	Portability	Table Organization

Limits the records processed in the current or specified table to those whose key field value falls within a range.

Syntax

SET KEY TO
[<exp list 1> |
RANGE <exp 2> [,] |
, <exp 3> |
<exp 2>, <exp 3>
[LOW <exp list 2> [,] ]
[HIGH [,] <exp list 3>]
[EXCLUDE]
[IN <alias>]

<exp 1> | RANGE <exp2> [,] | ,<exp3> | <exp2>, <exp3>

Specifies a condition that filters records. For Paradox and SQL tables, you can specify values (separated by commas) that match single or composite index key fields. The following table summarizes how SET KEY filters records in the master index:

Option	Description
<exp list1>	Searches for records whose index key values match <exp list 1>
RANGE <exp2> [,]	Searches for records whose index values are greater than or equal to <exp 2>
RANGE ,<exp3>	Searches for records whose index values are less than or equal to <exp 3>
RANGE <exp2>, <exp3>	Searches for records whose index values are greater than or equal to <exp 2> and less than or equal to <exp3>
LOW <exp list 2> [,]

Specifies that records whose index key values are less than the specified low values are not included with qualified records.

HIGH [,] <exp list 2>

Specifies that records whose index key values are greater than the specified high values are not included with qualified records.

EXCLUDE

When a range is included, specifies that records where index values match either the high or low value of the range are not included with qualified records.

IN <alias>

Specifies a work area. You can enter a work area number (1 through 225), letter (A through J), or alias name. The work area letter or alias name must be enclosed in quotes.

Description

The SET KEY TO command limits the records that dBASE for Windows processes in the current or specified table to those whose key field values fall within the specified range. Unless you specify the EXCLUDE keyword, dBASE for Windows also includes key field values that match the high or low values of the specified range. SET KEY TO with no arguments removes any range of key values previously established for the current table with SET KEY.

The values specified in <exp 1>, <exp 2>, and <exp 3> must match the key expression of the master index. For example, if the index key is UPPER(Name), specify uppercase letters in the range expressions. In determining whether the specified range expressions match key field expressions, SET KEY TO follows the rules established by SET EXACT. The SET KEY TO range takes effect after you move the record pointer.

You cannot use SKIP or LOCATE to go to a record that falls outside the SET KEY range. However, you can use GO to move the record pointer to a record that is outside the SET KEY range. Also, commands such as REPLACE that process more than one record operate only on records that are within the SET KEY range. No records are processed when you specify a range that does not contain any records.

When you issue both SET KEY and SET FILTER for the same table, dBASE for Windows processes only records that are within the SET KEY index range and that also meet the SET FILTER condition.


SET KEY TO Example

The following example uses SET KEY four times to select records from the table:

USE Company EXCLUSIVE
INDEX ON State_Prov TAG State

SET KEY TO "CA"
LIST State_Prov
WAIT "only CA"

SET KEY TO RANGE ,"IL"
LIST State_Prov
WAIT "up to Illinois"

SET KEY TO RANGE  "GA",
LIST State_Prov
WAIT "Georgia and beyond"

SET KEY TO RANGE  "GA","IL"
LIST State_Prov
WAIT "From Georgia to Illinois only"


Portability

Not supported in dBASE III PLUS.


See Also

INDEX

KEY( )

MDX( )

NDX( )

TAG( )

SET FILTER


SET LDCHECK

See Also	Example	Portability	Environment

Enables or disables language driver ID checking.

Syntax

SET LDCHECK ON | off

Default

The default for SET LDCHECK is ON. To change the default, set the LDCHECK parameter in DBASEWIN.INI.

Description

Use SET LDCHECK to disable or enable dBASE's capability to check for language driver compatibility. This capability is important if you work with dBASE tables created with different dBASE configurations or different international versions of dBASE because it warns you of conflicting language drivers.

Language drivers determine the character set and sorting rules that dBASE uses, so if you create a dBASE table with one language driver and then use that file with a different language driver, some of the characters will appear incorrectly and you may get incorrect results when querying data.

For more information about working with language drivers, see Appendix C in the Programmer's Guide.


SET LDCHECK Example

See LDRIVER( ) for an alternative to SET LDCHECK ON.


Portability

Not supported in dBASE III PLUS.


See Also

CHARSET( )

LDRIVER( )


SET LIBRARY

See Also	Example	Portability	Programs

Opens a dBASE program file (.PRG), making all procedures and user-defined functions (UDFs) in the file available for execution.

Syntax

SET LIBRARY TO
[<filename> | ? | <filename skeleton>]

<filename> | ? | <filename skeleton>

The library file to open. The ? and <filename skeleton> options display a dialog box from which you can select a file. If you specify a file without including its path, dBASE looks for the file in the current directory, then in the path you specify with SET PATH. If you specify a file without including its extension, dBASE assumes .PRO (a compiled object file). If dBASE cannot find a .PRO file, it looks for a .PRG file (a source file). If dBASE finds a .PRG file, it compiles it.

Description

SET LIBRARY complements SET PROCEDURE. Both commands open a file, allowing access to the procedures and UDFs the file contains. You can use SET LIBRARY TO without a file name to close an open library file.

To execute a procedure or UDF, dBASE must have access to the file containing it. When dBASE encounters a call to a procedure or UDF, it looks for the procedure or UDF in specific places in a specific order. One of the places dBASE looks is in a file opened with SET LIBRARY. See the DO command for an explanation of the search path and order dBASE uses.

For more information about working with a library file, see Chapter 4 in the Programmer's Guide.


SET LIBRARY Example

The following example uses SET LIBRARY to make additional procedures and functions from another file available to the main program:

** Rpt_Proc.PRG **
PROCEDURE Rpt_Head
line_cnt=1
DEFINE FORM MainForm FROM 0,0 TO 20,40
DEFINE TEXT line01 OF MainForm AT  1, 0 ;
   PROPERTY TEXT CENTER("Clients Database Report")
DEFINE TEXT line02 OF MainForm AT  2,19 ;
   PROPERTY TEXT ;
   CENTER("Run on " + DTOC(DATE()),40,"-")
DEFINE TEXT rpt_line OF MainForm ;
   AT line_cnt + 3,0 ;
   PROPERTY TEXT CENTER("Company",40)
DEFINE TEXT rpt_line2 OF MainForm ;
   AT line_cnt + 3,40 ;
   PROPERTY TEXT CENTER("Contact",40)
DEFINE TEXT line03 OF MainForm AT  2,19 ;
   PROPERTY TEXT CENTER(Next_Rpt(7),40,"-")
OPEN FORM MainForm

FUNCTION Next_Rpt
PARAMETERS days
nextdate = "Next Report Due on " + ;
   DTOC(DATE() + days)
RETURN nextdate

The next part of the example is the master program file:

** Main.PRG **
SET PROCEDURE TO Main
SET LIBRARY TO Rpt_Proc
DO MainSetup
DO Rpt_Head
SET LIBRARY TO

PROCEDURE MainSetup
SET TALK OFF
SET ECHO OFF
CLEAR
SET DEVELOPMENT ON
RETURN


Portability

Not supported in dBASE III PLUS. The ? and <filename skeleton> options are not supported in dBASE IV.

In dBASE IV, a file opened with SET LIBRARY is always searched after a file opened with SET PROCEDURE. In dBASE for Windows, the first file opened is the first one searched.


See Also

DO

FUNCTION

PROCEDURE

SET( )

SET PROCEDURE


SET LOCK

See Also	Example	Portability	Shared Data

Determines whether dBASE attempts to lock a shared table during execution of certain commands that read the table but do not change its data.

Syntax

SET LOCK ON | off

Default

The default for SET LOCK is ON. To change the default, set the LOCK parameter in DBASEWIN.INI. To do so, either use the SET command to specify the setting interactively, or enter the LOCK parameter directly in DBASEWIN.INI.

Description

Issue SET LOCK OFF to disable automatic file locking for certain commands that only read a table. This lets other users change data in the file while you access it with read-only commands. For example, you might want to issue SET LOCK OFF before using AVERAGE if you do not expect other users to alter the data in the table you are using significantly. Or, you might want to issue SET LOCK OFF before processing a range of records that other users are not going to update.

The following commands automatically lock tables when SET LOCK is ON and do not lock tables when SET LOCK is OFF:

AVERAGE

CALCULATE

COPY (source file)

COPY MEMO

COPY STRUCTURE

COPY TO ARRAY

COPY TO...STRUCTURE [EXTENDED] (source file)

COUNT

JOIN (both source files)

LABEL FORM

REPORT FORM

SORT (source file)

SUM

TOTAL (source file)

dBASE continues to lock records and tables automatically for commands that let you change data whether SET LOCK is ON or OFF.


SET LOCK Example

This program demonstrates the use of SET LOCK in processing read-only data.

USE Company
SET LOCK OFF    && Do not lock records during COUNT
COUNT FOR Company->Type = "VAR"  TO nCount
CLEAR
? nCount
SET LOCK ON


Portability

Not supported in dBASE III PLUS.


See Also

FLOCK( )

RLOCK( )


SET MARGIN

See Also	Example	Printing

Sets the width of the left border of a printed page.

Syntax

SET MARGIN TO <expN>

<expN>

The column number at which to set the left margin. The valid range is 0 to 254, inclusive. You can specify a fractional number for <expN> to position output accurately with a proportional font.

Default

The default for SET MARGIN is 0. To change the default, set the MARGIN parameter in DBASEWIN.INI.

Description

Use SET MARGIN to adjust the printer offset for the left margin for all printed output. The margin established by SET MARGIN becomes the printer's column 0 position. SET MARGIN resets the value of the _ploffset system memory variable but does not affect the value of the _lmargin system memory variable.

Use SET MARGIN to adjust the position of text on the printed page according to the type of paper. For example, if you are printing to three-hole paper, you might need to increase the left border. You can also use SET MARGIN to compensate for the placement of paper in the printer. For example, if the paper is off-center in the printer, you can adjust the width of the left border to properly place the text.

When you direct output to the printer, dBASE maps each character according to the coordinate plane, a two-dimensional grid. The coordinate plane is divided into character cells whose widths depend on the value of _ppitch. See the table in the description of _ppitch, which lists _ppitch values. The height of each character cell is determined by the size of the font. For more information about the coordinate plane, see Chapter 16 in the Programmer's Guide.

If you change the value of SET MARGIN, dBASE takes the current value of _ppitch into consideration when calculating the cell width of the coordinate plane. This happens regardless of whether you are printing with proportional or monospaced fonts. If you issue ? without using the STYLE option and use only integer coordinates, dBASE uses a monospaced font, and all output appears exactly the same as in dBASE IV.


SET MARGIN Example

This example displays the 10 digits with the default margin and then sets the margin to column 10 and displays the 10 digits this time indented:

SET PRINTER ON
SET MARGIN TO 0   && The default
? "1234567890"
SET MARGIN TO 10
? "1234567890"
? _ploffset
SET MARGIN TO 0   && RESET MARGIN
SET PRINTER OFF
CLOSE PRINTER

Produces:

* this displays as:
* 1234567890
*           1234567890
*                   10
*
* _ploffset is set by SET MARGIN


See Also

_indent

_lmargin

_ploffset

_rmargin


SET MARK

See Also	Example	Portability	Date and Time Data

Determines the character dBASE uses to separate the month, day, and year when it displays dates.

Syntax

SET MARK TO
[<expC>]

<expC>

The single date separator character. You can specify more than one character for <expC>, but dBASE uses only the first one.

Default

The default for SET MARK is the separator character of the current date format in use by the system. dBASE uses the value set by SET DATE, DBASEWIN.INI, or the International option of the Windows Control Panel (in that order) to determine the current date format. That is, SET DATE settings override those in DBASEWIN.INI, and settings in DBASEWIN.INI override those in the Windows Control Panel.

To change the default separator character, set the MARK parameter in DBASEWIN.INI. To do so, either use the SET command to specify the setting interactively, or enter the MARK parameter directly in DBASEWIN.INI.

If you specify both DATE and MARK settings in DBASEWIN.INI, dBASE displays dates in the month/day/year format corresponding to the DATE setting, but uses the separator specified in the MARK setting. Once you've started dBASE, issuing SET DATE overrides any prior SET MARK setting, including one specified in DBASEWIN.INI.

Description

Use SET MARK to change the date separator from the default character. For example, if you issue SET DATE AMERICAN, the date separator character is a forward slash (/), and dBASE displays dates in MM/DD/YY format. However, if you specify SET MARK TO "." after issuing SET DATE AMERICAN, dBASE displays dates in the format MM.DD.YY. If you issue SET DATE AMERICAN again, the format returns to MM/DD/YY.

Issuing SET MARK TO without <expC> resets the date separator character to that of the current date format.


SET MARK Example

The following example uses SET MARK to change the date separator when displaying date data:

date = {04/01/94}
SET CENTURY OFF
SET DATE AMERICAN
ENDIF
? date	&& Returns 04/01/94
SET CENTURY ON
? date	&& Returns 04/01/1994
SET MARK TO ","
? date	&& Returns 04,01,1994
SET MARK TO "/"
? date	&& Returns 04/01/1994
SET MARK TO ":"? date	&& Returns 04:01:1994
SET MARK TO "-"
? date	&& Returns 04-01-1994
 SET DATE AMERICAN
? date	&& Returns 04/01/1994
SET DATE USA
? date	&& Returns 04-01-1994


Portability

Not supported in dBASE III PLUS.


See Also

DATE( )

DMY( )

MDY( )

SET CENTURY

SET DATE


SET MBLOCK

See Also	Example	Portability	Fields and Records

Changes the default block size of new memo field (.DBT) files.

Syntax

SET MBLOCK TO <expN>

<expN>

A number from 1 to 512 that sets the size of blocks used to store new memo (.DBT) files. (The actual size in bytes is the number you specify multiplied by 64.)

Default

The default value for SET MBLOCK is 8 (or 512 bytes). To change the default, update the MBLOCK setting in DBASEWIN.INI. To do so, either use the SET command to specify the setting interactively, or enter the MBLOCK parameter directly in DBASEWIN.INI.

Description

Use SET MBLOCK to change the size of blocks in which dBASE stores new memo field (.DBT) files on disk. You can specify a block size from 64 bytes to approximately 32K. The MBLOCK setting overrides any previous block size defined by the SET BLOCKSIZE command or specified in the DBASEWIN.INI file. After the block size has been changed, new memo .DBT files are created with the new block size. dBASE stores data in each memo field in a group made up of as many blocks as needed.

After the block size is changed, memo fields created with the COPY, CREATE, and MODIFY STRUCTURE commands have the new block size. To change the block size of an existing memo field file, use the SET BLOCKSIZE command to change the block size and then copy the table containing the associated memo field to a new file. The new file then has the new block size.

When the block sizes are large and the memo contents are small, memo (.DBT) files contain unused space and become larger than necessary. If you expect the contents of the memo fields to occupy less than 512 bytes (the default size allocated), set the block size to a smaller size to reduce wasted space. If you expect to store larger pieces of information in memo fields, increase the size of the block.

SET MBLOCK is similar to the older SET BLOCKSIZE command except for two advantages:

You can allocate different block sizes for memo field and index data, whereas SET BLOCKSIZE requires the same block size for both. To allocate block sizes for index data, use SET IBLOCK.

You can specify smaller blocks with SET MBLOCK than with SET BLOCKSIZE. SET BLOCKSIZE creates blocks in increments of 512 bytes, compared to 64 bytes with SET MBLOCK.


SET MBLOCK Example

The following example uses SET MBLOCK to create another table that is a copy of Clients but has a memo blocksize of 256 bytes embedded in its structure versus the default of 512 bytes. This technique applies if memo entries are normally less than 256 bytes and you want to minimize wasted space in the .DBT file:

USE Clients
? SET("MBLOCK")                && Returns default of 8;
                                meaning each memo;
                                block = 512 bytes
SET MBLOCK TO 4
COPY  TO Clients2
USE Clients2
? SET("MBLOCK")                && Returns 4
LIST FILES LIKE Clients*.DBT
* Note that Clients2.DBT is smaller than Clients.DBT
CLOSE DATABASES


Portability

Not supported in dBASE III PLUS.


See Also

CREATE

MODIFY STRUCTURE

REPLACE

SET( )

SET BLOCKSIZE

SET IBLOCK


SET MEMOWIDTH

See Also	Example	Fields and Records

Sets the width of memo field display or output.

Syntax

SET MEMOWIDTH TO
[<expN>]

<expN>

Specifies a number from 8 to 255 that sets the width of memo field display and output.

Default

The default memo width is set to 50.

Description

Use SET MEMOWIDTH to change the column width of memo fields during display and output. Memo fields can be displayed using the commands DISPLAY, LIST, ?, or ??. SET MEMOWIDTH does not affect the display of a memo field in the Text Editor. If the system memory variable variable_wrap is set to true (.T.), the system memory variables _lmargin and _rmargin determine the memo width.

The @V (vertical stretch) picture function causes memo fields to be displayed in a vertical column when _wrap is true. When @V is specified, the _pcolno system memory variable is incremented by the @V value. This lets you change the appearance of the printed output of ? or ?? commands by using the @V function. When @V is equal to zero, memo fields wrap within the SET MEMOWIDTH width.


SET MEMOWIDTH Example

The following example demonstrates the relationship between SET MEMOWIDTH and the value returned by MEMLINES( ). The REPLACE command places a string in memo field Notes and SET MEMOWIDTH is used to alter the memo field length for output purposes:

SET MEMOWIDTH TO 30
USE CLIENTS
REPLACE Notes WITH "Mr. Jackson contacted us "+;
  "this date, 04/15/94 regarding his accident of "+;
  "04/10/94 involving a truck and his 1994 Lexus."
CLEAR
? "MEMOWIDTH", "MEMLINES" AT 20
? "  30", LTRIM(STR(MEMLINES(Notes))) AT 22
?
? Notes
?
SET MEMOWIDTH to 45
? "MEMOWIDTH", "MEMLINES" AT 20
? "  45", LTRIM(STR(MEMLINES(Notes))) AT 22
?
? Notes

See MEMLINES( ) for another example of SET MEMOWIDTH.


See Also

?

??

DISPLAY

LIST

MEMLINES( )

MLINE( )

SET( )

_lmargin

_rmargin

_wrap


SET MESSAGE

See Also	Example	Portability	Environment

Displays a message in the status bar if it is enabled. This command is supported primarily for compatibility with dBASE IV. In dBASE for Windows, you generally use the StatusMessage property of an object to display a message on the status bar when an object receives focus.

Syntax

SET MESSAGE TO
[<message expC>]

<message expC>

A message up to 80 characters long.

Default

The default for SET MESSAGE is an empty string.

Description

Use SET MESSAGE to display a message in the status bar. If the status bar is not enabled, the message does not appear. Use SET to enable and disable the status bar.

SET MESSAGE TO without the option <message expC> sets the message to the default (an empty string), and removes any message from the status bar.

If you set a message as part of an object's definition, and the object is current, the object message overwrites any SET MESSAGE message.


SET MESSAGE Example

This example uses SET MESSAGE to write to the status bar, WAIT and then it clears the status bar with SET MESSAGE TO:

SET MESSAGE TO ;
  "All roads lead to Rome, "+;
  "all messages to the status bar"
WAIT "Press any key to clear the status bar"
* Wait writes to the command results pane,
* not the status bar so that the WAIT instruction
* does not overwrite the status bar.
SET MESSAGE TO
* Clear the status bar


Portability

In dBASE IV and dBASE III PLUS, the maximum message length is 79 characters, and when the status bar is disabled, the SET MESSAGE message still appears during full-screen editing commands and while menus are active.

In dBASE IV, you can position the message anywhere on the screen with the AT option. The AT option is not supported in dBASE for Windows.


See Also

DEFINE

SET TALK

StatusMessage


SET MOUSE

See Also	Keyboard and Mouse Events

Use SET MOUSE to enable or disable the mouse . This command is supported primarily for compatibility with dBASE IV. In dBASE for Windows applications, you would generally not disable mouse capabilities.

Syntax

SET MOUSE ON | off

Default

The default for SET MOUSE is ON.

Description

Use SET MOUSE OFF to remove the mouse pointer from the screen. Once the mouse pointer is removed, dBASE ignores all subsequent mouse actions. To enable the mouse again, use SET MOUSE ON.


See Also

ISMOUSE( )

MCOL( )

MROW( )

ON MOUSE


SET NEAR

See Also	Example	Portability	Table Organization

Specifies where to move the record pointer after a FIND, SEEK, or SEEK( ) operation fails to find an exact match.

Syntax

SET NEAR on | OFF

Default

The default for SET NEAR is OFF. To change the default, update the NEAR setting in DBASEWIN.INI. To do so, either use the SET command to specify the setting interactively, or enter the NEAR parameter directly in DBASEWIN.INI.

Description

Use SET NEAR to position the record pointer in an indexed table close to a particular key value when a search does not find an exact match. When SET NEAR is ON, the record pointer is set to the record closest to the key expression searched for but not found with FIND, SEEK, or SEEK( ). When SET NEAR is OFF and a search is unsuccessful, the record pointer is positioned at the end of the file.

If you unsuccessfully search for a character, date, numeric, or float value when SET NEAR is ON, and the index is in ascending order, dBASE for Windows positions the record pointer at the record whose key value follows the value searched for. When SET DELETED is ON or a filter is set with the SET FILTER command, SET NEAR disregards deleted or filtered records in determining the record nearest the key value expression.

With SET NEAR ON, FOUND( ) returns .T. for an exact match or .F. for a near match. With SET NEAR OFF, FOUND( ) returns .F. if no match occurs.


SET NEAR Example

The following example uses SET NEAR to control the placement of the record pointer if no matching record is found in an indexed table:

USE Company EXCLUSIVE
INDEX ON Zip_P_code TAG Zip
SET NEAR ON
SEEK "55555"
? EOF(),Zip_P_code
SET NEAR OFF
SEEK "55555"
? EOF(),Zip_P_code

There is no Zip_P_code 55555 in the table. With NEAR OFF, the record pointer is positioned at EOF( ). With NEAR ON, it is positioned at the nearest record, deleted or not.


Portability

Not supported in dBASE III PLUS.


See Also

EOF( )

FIND

FOUND( )

LOCATE

SEEK

SEEK( )

SET( )

SET DELETED

SET FILTER


SET ODOMETER

See Also	Example	Portability	Environment

Specifies how frequently dBASE updates and displays record counter information in the status bar if it is enabled. This command is supported primarily for compatibility with dBASE IV. dBASE for Windows displays a progress meter while certain commands are being carried out.

Syntax

SET ODOMETER TO
[<expN>]

<expN>

The interval at which dBASE updates the record counter. If <expN> is less than 1, dBASE returns an error.

Default

The default for SET ODOMETER is 100. To change the default, set the ODOMETER parameter in DBASEWIN.INI.

Description

Use SET ODOMETER to specify how frequently dBASE updates and displays record counter information during the execution of data-entry and calculation commands, such as AVERAGE, CALCULATE, COUNT, DELETE, GENERATE, INDEX, RECALL, SUM, and TOTAL. If the status bar is not enabled, SET ODOMETER has no effect. Use SET to enable and disable the status bar.

If SET TALK is OFF, dBASE does not display any record counter information in the status bar, regardless of the SET ODOMETER setting. If SET TALK is ON, use SET ODOMETER with a relatively high value to improve performance.

If you issue SET ODOMETER TO without the <expN> option, dBASE sets the odometer to the default value of 100.


SET ODOMETER Example

The following example demonstrates the use of two settings of SET ODOMETER as it generates records in a temporary database:

SET TALK ON  && Necessary
USE Clients
COPY STRUCTURE TO TEMP
USE TEMP EXCLUSIVE
SET ODOMETER TO 1
? "Odometer is set at " + ;
  LTRIM(STR(SET("ODOMETER")))
* Display odometer count setting;
* refresh count every record
GENERATE 100
* generates 100 random records
ZAP         && remove these records
SET ODOMETER TO 10
? "Odometer is set at " + ;
  LTRIM(STR(SET("ODOMETER")))
GENERATE 100
* refresh count every tenth record
USE
DELETE FILE TEMP.DBF
* Delete the temporary table


Portability

The following table lists differences between dBASE III PLUS, dBASE IV, and dBASE for Windows.

	dBASE III PLUS	dBASE IV	dBASE for Windows
<expN>	Required	Required	Optional
Initial default value of <expN>	1	1	100
<expN> minimum value	0	1	1
<expN> maximum value	None	200	32767
Value that resets record counter	4 million	None	None


See Also

SET TALK


SET ORDER

See Also	Example	Table Organization

Specifies an open index file or tag as the master index of a table.

Syntax

SET ORDER TO [<index position expN>]

or

SET ORDER TO [<.ndx filename 1>]
[NOSAVE]

or

SET ORDER TO
[TAG] <tag name>
[OF <filename 2> | ? ]
[NOSAVE]

<index position expN>

A number specifying the position of an index in the list of open .NDX files. This option is provided for compatibility with dBASE III PLUS and cannot be used if there are any .MDX files open. If <index position expN> evaluates to 0, the table appears unindexed, in record number or natural order.

<.ndx filename 1>

Specifies the name of an .NDX file created on a dBASE table.

[TAG] <tag name>

Specifies the name of an index tag open in an .MDX file (or a single or multiple field index created on a Paradox or SQL table). The TAG keyword is included for readability only; TAG has no affect on the operation of the command. For Paradox tables, if you specify SET ORDER TO without including an index tag name, the primary index is used as the master index, if it exists.

OF <filename 2> | ?

Specifies the multiple index file that contains the index tag you want to control the order of the current table. OF ? displays a dialog box, in which you select an index file. If you specify a file without including its path, dBASE for Windows looks for the file in the current directory, then in the path you specify with SET PATH. If you specify a file without including its extension, dBASE for Windows assumes an .MDX extension.

If you use the [TAG] <.ndx filename 1> | <tag name> option but do not specify the name of a .MDX index file, dBASE for Windows searches first for an .NDX index file, and then searches for the tag name in the production .MDX file.

NOSAVE

Used to delete a temporary index after the associated table is closed. If you decide after choosing this option that you want to keep the index, open the index again using SET ORDER without the NOSAVE option, before you close the table.

Description

Use SET ORDER to change the master index of a table without having to close and reopen indexes. You can choose the master index from the list of .NDX files or .MDX index tags opened with the SET INDEX or USE...INDEX commands.

If you specify the order with <index position expN>, use the index order defined with the SET INDEX command. You can use this option only if no .MDX files are open. If you specify SET ORDER without specifying an index, or if <index position expN> evaluates to 0, the table appears unindexed, in record number order.

When accessing a Paradox table, specifying SET ORDER TO without an argument resets the Paradox table to the primary index record order, if a primary index exists.


SET ORDER Example

The following example uses SET ORDER to specify which index file or tag is the active index:

USE Company EXCLUSIVE
INDEX ON CompCode TAG CompCode
INDEX ON Company  TAG Company
INDEX ON City TAG City
SET INDEX TO CompCode, Company, City
BROWSE FIELDS CompCode, Company, City ;
  TITLE "Compcode order"
SET ORDER TO City
BROWSE FIELDS CompCode, Company, City ;
  TITLE "City order"
SET ORDER TO Company
BROWSE FIELDS CompCode, Company, City ;
  TITLE "Company order"
SET ORDER TO         && Return to natural order


See Also

CLOSE...

INDEX

KEY( )

MDX( )

NDX( )

ORDER( )

REINDEX

SET INDEX

TAG( )

TAGCOUNT( )

TAGNO( )

USE


SET PATH

See Also	Example	Disk and File Utilities

Specifies the directory search route that dBASE follows to find files that are not in the current directory.

Syntax

SET PATH TO
[<path list>]

<path list>

A list of (optional) drives and directories indicating the search path--one or more drives and directories you want dBASE to search for files. Separate each directory path name with commas, semicolons, or spaces. The syntax for this command is similar to the PATH command available in DOS. Unlike DOS, however, you can use spaces or commas as well as semicolons to separate paths on the list; DOS accepts only semicolons.

Default

The default for SET PATH is empty (no path). To change the default, update the PATH setting in dBASEWIN.INI with as many valid drives and directories as you want. To do so, either use the SET command to specify the setting interactively, or enter the PATH parameter directly in DBASEWIN.INI.

Description

Use SET PATH to establish a search path to access files located on directories other than the current directory. When no SET PATH setting exists and you do not provide the full path name when you specify a file name, dBASE searches for that file only in the current directory.

The order in which you list drives and directories with SET PATH TO <path list> is the order dBASE searches for a file in that search path. Use SET PATH when an application's files are in several directories.

A path name without a drive letter or beginning backslash begins at the current directory on the current drive. Use two periods (..) to signify the parent directory of the current directory, and use a beginning backslash to signify the root directory of the current drive.

SET PATH TO without the option <path list> resets the search path to the default value (no path).


SET PATH Example

The following example uses SET PATH, opens a table in the path and uses SET FULLPATH to show the subdirectory used:

* Current directory is d:\example
SET PATH TO c:\temp prg, d:\example\pdox
* 'prg' refers to d:\example\prg
USE Lineitems
SET FULLPATH ON
? DBF()  && D:\EXAMPLE\PDOX\LINEITEMS.DBF
SET FULLPATH OFF


See Also

DISPLAY STATUS

LIST STATUS

SET DIRECTORY


SET PCOL

See Also	Example	Portability	Printing

Sets the printing column position of a printer, which is the value of PCOL( ).

Syntax

SET PCOL TO <expN>

<expN>

The column number to which to set PCOL( ). The valid range is 0 to 32,767, inclusive.

Description

Use SET PCOL to set the horizontal printing position of a printer, which is the value the PCOL( ) function returns. Subsequent @...SAY commands that specify a column position on the current line print in a column position relative to the new PCOL( ) value. Generally, you use the command SET PCOL TO 0 to reset the printer column to the left edge of the page.

SET PCOL does not affect the printing of @...SAY commands that use relative addressing with PCOL( ). For example, the following command line prints "Hello" beginning 10 spaces to the right of the current column, regardless of the value of PCOL( ).

@ 1,PCOL() + 10 SAY "Hello"

When you move the printing position to a new line, dBASE reinitializes PCOL( ) to 0, so SET PCOL affects the value of PCOL( ) for the current line only. When you send output to your printer, dBASE updates PCOL( ) by adding 1 to the current PCOL( ) value for each character it sends to the printer. The printing position moves 1 column for each character the printer prints.

When you send a printer control code or escape sequence to your printer, the printing position does not move. (Printer control codes and escape sequences are strings that give the printer instructions, such as to print underlining, boldface type, or different fonts.) Although control codes and escape sequences do not move the printing position, dBASE nonetheless increments the PCOL( ) value by the number of characters that you send to the printer. Each control code character increments the value of PCOL( ) by 1 just like any other character. As a result, the value of PCOL( ) might not reflect the actual printing position. Use SET PCOL to reset the value of PCOL( ) to the same value as the printing position.

To send a control code to the printer without changing the value of PCOL( ), save the current value of PCOL( ) to a memory variable, send the control code to the printer, then SET PCOL to the contents of the memory variable.


SET PCOL Example

The following example writes "Jack & Jill" to the printer. It uses PCOL( ) to note the column position three times, at the beginning, after "Jack", and after "Jill":

SET TALK OFF
SET PRINTER ON
* now ?s are directed to printer
?                && printer at col 0 of next line
beginpos=pcol()  && note the current column
?? "Jack"
lastjackpos=pcol()
?? " & Jill"
lastjillpos=pcol()
* prints:
* Jack & Jill
SET PRINTER OFF
CLOSE PRINTER
? beginpos       &&  0.00
? lastjackpos    &&  4.00
? lastjillpos    && 11.00
* Displays column positions for reference


Portability

Not supported in dBASE III PLUS or dBASE IV.


See Also

@...SAY...GET

PCOL( )

PROW( )

SET PROW


SET POINT

See Also	Example	Portability	Numeric Data

Specifies the character that separates decimal digits from integer digits in numeric display.

Syntax

SET POINT TO
[<expC>]

<expC>

The character representing the decimal point. You can specify more than one character, but dBASE uses only the first one. If you specify a number as a character for <expC> (for example, "3"), dBASE returns an error.

Default

The default for SET POINT is set by the International option of the Windows Control Panel. To change the default, set the POINT parameter in DBASEWIN.INI. To do so, either use the SET command to specify the setting interactively, or enter the POINT parameter directly in DBASEWIN.INI.

Description

SET POINT affects both numeric input and display with commands such as EDIT. SET POINT also affects numeric display with commands such as DISPLAY MEMORY, STORE, =, and the PICTURE "." template character. You must use the period in the PICTURE option, regardless of the setting of SET POINT. See Picture for more information on the PICTURE option.

SET POINT affects only the display of numeric expressions in dBASE syntax, not their input. Only a period is valid as a decimal point in numeric input. For example, if you SET POINT TO "," (comma) and issue the following command, dBASE returns an error:

?MAX(123,4, 123,5)

The correct syntax is

?MAX(123.4,123.5)

SET POINT TO without the <expC> option resets the decimal character to the default set with the International option of the Windows Control Panel.


SET POINT Example

The following example uses SET POINT to control the display of numeric data:

SET DECIMALS TO 2            && Default
SET CURRENCY LEFT            && Default
SET SEPARATOR TO "."
SET POINT TO ","
SET CURRENCY TO "FR"
? 23445.95 PICTURE "$999,999.99";
                             && Returns FR23.445,95
? 2345.95 PICTURE "$999,999.99";
                             && Returns FFR2.345,95
? 345.95 PICTURE "$999,999.99"
                             && Returns FFFFR345,95
? 345.95 PICTURE "@$999,999.99"
                             && Returns FR345,95

Another example of SET POINT is included in the INT( ) example.


Portability

Not supported in dBASE III PLUS.


See Also

SET DECIMALS

SET SEPARATOR

STORE


SET PRECISION

See Also	Example	Portability	Numeric Data

Determines the number of digits dBASE uses when comparing numbers.

Syntax

SET PRECISION TO
[<expN>]

<expN>

The number of digits, from 10 to 19.

Default

The default for SET PRECISION is 16. To change the default, set the PRECISION parameter in DBASEWIN.INI. To do so, either use the SET command to specify the setting interactively, or enter the PRECISION parameter directly in DBASEWIN.INI.

Description

Use SET PRECISION to change the accuracy, or precision, of numeric comparisons. You can set precision from 10 to 19 digits.

SET PRECISION affects data comparisons, but not mathematical computations or data display. In math computations, the precision is always 19 digits. To change the number of decimal places dBASE displays, use SET DECIMALS.


SET PRECISION Example

The following example demonstrates how the precision setting affects data comparisons and mathematical computations:

SET DECIMALS TO 18         && Max value
SET PRECISION TO 19        && Max value
x = 0.12345678901234567
y = 0.12345678901234568
? x = y            && Returns .F.
? x + y            && Returns 0.246913578024691350

SET PRECISION TO 16
? x = y            && Now returns .T.
? x + y            && Still returns 0.246913578024691350
SET DECIMALS TO 8
? x + y            && Returns 0.24691358


Portability

Not supported in dBASE III PLUS. In dBASE IV, SET PRECISION affects mathematical computations, but not comparisons of numbers.


See Also

SET DECIMALS


SET PRINTER

See Also	Example	Portability	Printing

The SET PRINTER TO setting specifies a file to receive streaming output, or uses a device code recognized by the Windows Print Manager to designate a printer. The On/Off setting controls whether dBASE also directs streaming output that appears in the Command window to the device or file specified by SET PRINTER TO.

Syntax

SET PRINTER on | OFF

SET PRINTER TO
[[FILE] <filename> | ? | <filename skeleton>] |
[<device>]

FILE

Use this keyword if you want to bypass the Windows print driver so that no printer control codes are written to the file. If you omit the keyword, the Windows print driver output is written to the file.

<filename> | ? | <filename skeleton>

The text file to send output to instead of the printer. By default, dBASE assigns a .PRT extension to <filename> and saves the file in the current directory. The ? and <filename skeleton> options display a dialog box in which you specify the name of the target file and the directory to save it in.

<device>

The printer port of the printer to send output to. Specify printers and their ports with the Windows Control Panel.

Default

The default for SET PRINTER is OFF. To change the default, set the PRINT parameter in the [OnOffCommandSettings] section in DBASEWIN.INI. The default for SET PRINTER TO is the default printer you specify with the Windows Control Panel.

Description

Use SET PRINTER TO to direct streaming output from commands such as ?, ??, and LIST to a printer or a text file. SET PRINTER TO with no option sends this output to the default printer. For more information about streaming and non-streaming output, see Chapter 24 in the Programmer's Guide.

Use SET PRINTER ON/OFF to enable or disable the printer you specify with SET PRINTER TO.

To send streaming output to a file rather than the printer, issue SET PRINTER TO FILE <filename>. When you issue SET PRINTER TO FILE <filename>, issuing SET PRINTER ON directs streaming output to the text file <filename> rather than to the printer. The file has the default extension of .PRT.

When SET PRINTER is OFF, dBASE directs streaming output only to the result pane of the Command window. SET PRINTER must be ON to output data to a text file unless you issue a command with its TO PRINTER option. The following example illustrates this behavior:

SET PRINTER OFF
SET PRINTER TO FILE test.prt
TYPE file.txt	&& Displays on screen only
TYPE file.txt TO PRINT && Output sent to screen and TEST.PRT

To send non-streaming output to the printer, use SET DEVICE TO PRINTER. To send non-streaming output to a text file, use SET DEVICE TO FILE.


SET PRINTER Example

The following example uses SET PRINTER ON and OFF:

SET PRINTER TO  && Set printer to default
SET PRINTER ON
? "Hello"       && to printer
SET PRINTER OFF
? prow(),pcol() && only displayed to  screen
CLOSE PRINTER   && intiate printing

SET PRINTER TO       && resets to default
SET PRINTER TO PRN   && sets to DOS output device
SET PRINTER TO LPT1
SET PRINTER TO NUL
SET PRINTER TO FILE Test
* Test.prt receives streaming output, including
* any control codes, that would have gone to the
* printer.


Portability

In dBASE III PLUS, use SET PRINT.


See Also

SET ALTERNATE

SET CONSOLE

SET DEVICE


SET PROCEDURE

See Also	Example	Portability	Programs

Opens a dBASE program file (.PRG), making all procedures and user-defined functions (UDFs) in the file available for execution.

Syntax

SET PROCEDURE TO
[<filename> | ? | <filename skeleton>]
[ADDITIVE]

<filename> | ? | <filename skeleton>

The procedure file to open. The ? and <filename skeleton> options display a dialog box, from which you can select a file. If you specify a file without including its path, dBASE looks for the file in the current directory, then in the path you specify with SET PATH. If you specify a file without including its extension, dBASE assumes .PRO (a compiled object file). If dBASE cannot find a .PRO file, it looks for a .PRG file (a source file). If dBASE finds a .PRG file, it compiles it.

ADDITIVE

Opens the procedure file(s) without closing any you have opened with previous SET PROCEDURE statements. SET PROCEDURE TO < filename> (without the ADDITIVE option) closes all procedure files you have opened with previous SET PROCEDURE statements.

Description

To execute a procedure or UDF, dBASE must have access to the file containing it. When dBASE encounters a call to a procedure or UDF, it looks for the procedure or UDF in specific places in a specific order. One of the places dBASE looks is in a file opened with SET PROCEDURE. See the DO command for an explanation of the search path and order dBASE uses.

To make the procedures or UDFs in a program available to other programs, place the following statement in the program:

SET PROCEDURE TO PROGRAM(1) ADDITIVE

If you issue SET PROCEDURE TO with no options, dBASE closes all procedure files you have opened with SET PROCEDURE. If you want to close only specific procedure files, use CLOSE PROCEDURE. The maximum number of open procedure files depends on available memory.

For more information about working with procedure files, see Chapter 4 in the Programmer's Guide.


SET PROCEDURE Example

The following program lines use SET PROCEDURE to set and add various procedure files so that all programs can access the procedures in the procedure files. Finally, all procedure files are released:

SET PROC TO SoundLib
* All programs can access all procedures
* in SoundLib.PRG
SET PROCEDURE TO PictLib ADDITIVE
* All programs can now access all procedures
* in SoundLib.PRG and PictLib.PRG
SET PROCEDURE TO PictLib
* Only PictLib can be accessed
SET PROCEDURE TO PROGRAM(1) ADDITIVE
* The current file, whatever its name,
* is now also a procedure file
SET PROCEDURE TO
* All procedure files are released
* and no longer available

The following example creates an entry form with three RadioButtons to select the desired conversion factor. SET PROCEDURE TO Cnvrt.PRG makes the function Metric in the procedure file Cnvrt available when the user clicks on entry field Answ:

** Metric Conversion Program **
SET PROCEDURE TO Cnvrt.PRG
f=NEW Convert()
f.OPEN()
CLASS Convert OF FORM
  this.Top=2
  this.Left=2
  this.Width=50
  this.Height=18
  this.Text= "Conversion Utility"
  DEFINE ENTRYFIELD Amt OF THIS AT 4,15;
    PROPERTY Value 0, Width 8
  DEFINE TEXT Ln1 OF THIS AT 2,6;
    PROPERTY;
    Text "Enter Amount; Select a RadioButton",;
    Width 45
  DEFINE RadioButton Inches OF THIS AT 6,8;
    PROPERTY Text "Inches to Centimeters",;
    Width 22, Value .F.
  DEFINE RadioButton Pounds OF THIS AT 8,8;
    PROPERTY Text "Pounds to Kilograms",;
    Width 21, Value .F.
  DEFINE RadioButton Degrees OF THIS AT 10,8;
    PROPERTY Text "Degrees F to C",;
    Width 21, Value .F.
  DEFINE TEXT Ln2 OF THIS AT 12,8;
    PROPERTY Text "Results:",;
    Width 15
  DEFINE ENTRYFIELD Answ OF THIS AT 12,19;
    PROPERTY Value 0, Width 17,;
    OnGotFocus Metric
  DEFINE PUSHBUTTON Exit OF THIS AT 15,15;
    PROPERTY TEXT "Exit", OnClick {;Form.Close()}
ENDCLASS

The following conversion function resides in a .PRG file named Cnvrt.PRG and is made available to the main program by the command line SET PROCEDURE TO Cnvrt.PRG

***Cnvrt.PRG***
FUNCTION Metric
DO CASE
   CASE Form.Inches.Value
      Form.Answ.Value = LTRIM(STR(Form.Amt.Value;
      * 2.54,10,2))+" Centimeters"
   CASE Form.Pounds.Value
      Form.Answ.Value = LTRIM(STR(Form.Amt.Value;
      * .454,10,2))+" Kilograms"
   CASE Form.Degrees.Value
      Form.Answ.Value = LTRIM(STR((Form.Amt.Value;
      -32)* (5/9),10,2))+" Degrees C"
ENDCASE
RETURN .T.


Portability

The ?, <filename skeleton>, and ADDITIVE options are not supported in dBASE III PLUS or dBASE IV. In dBASE IV, a file opened with SET PROCEDURE is always searched before a file opened with SET LIBRARY. In dBASE for Windows, the first file opened is the first one searched.


See Also

CLOSE...

COMPILE

DO

FUNCTION

PARAMETERS

PROCEDURE

RETURN

SET( )

SET LIBRARY


SET PROW

See Also	Example	Portability	Printing

Sets the current row position of a printer's print head, which is the value of PROW( ).

Syntax

SET PROW TO <expN>

<expN>

The row number to which to set PROW( ). The valid range is 0 to 32,767, inclusive.

Description

Use SET PROW to set the vertical printing position of a printer, which is the value the PROW( ) function returns. Subsequent @...SAY commands that specify a row position print relative to the new PROW( ) value. Generally, you use the command SET PROW TO 0 to reset the printer row to top-of-page.

SET PROW does not affect the printing of @...SAY commands that use relative addressing with PROW( ). For example, the following command line prints the word "Hello" two rows below the current row, regardless of the value of PROW( ).

 @ PROW() + 2,0 SAY "Hello"


SET PROW Example

The following example uses SET PROW to print relative to the current row:

SET DEVICE TO PRINTER
@ 10,0 say "Tenth row"
SET PROW TO 0
* reset prow, previous row 10 is now row 0
@ 2,0 say "2nd row relative to new setting"
SET DEVICE TO SCREEN
CLOSE PRINTER


Portability

Not supported in dBASE III PLUS or dBASE IV.


See Also

@...SAY...GET

PCOL( )

PROW( )

SET PCOL


SET REFRESH

See Also	Example	Shared Data

Determines how often dBASE refreshes the workstation screen with table information from the server.

Syntax

SET REFRESH TO <expN>

<expN>

A time interval expressed in seconds from 0 to 3,600 (1 hour), inclusive.

Default

The default for SET REFRESH is 0, meaning dBASE does not update the screen. To change the default, set the REFRESH parameter in DBASEWIN.INI. To do so, either use the SET command to specify the setting interactively, or enter the REFRESH parameter directly in DBASEWIN.INI.

Description

Use SET REFRESH to set a refresh interval when working with shared tables on a network. Then, when you use BROWSE, EDIT, or CHANGE to edit shared tables, your screen refreshes at the interval you set, showing you changes made by other users on the network to the same tables.

If another user has a lock on the file or records you are currently viewing, the file or records won't be refreshed until that user releases the lock.


SET REFRESH Example

USE Employee
CONVERT
SET REFRESH TO 5
BROWSE


See Also

BROWSE

CHANGE

EDIT

FLOCK( )

RLOCK( )


SET RELATION

See Also	Example	Table Organization

Links two or more open tables with common fields or expressions.

Syntax

SET RELATION TO
[<key exp list 1> | <expN 1>
INTO <child table alias 1>
[, <key exp list 2> | <expN 2>
INTO <child table alias 2>] ... ]
[ADDITIVE]]

For dBASE tables, you can also specify options to restrict processing of unlinked child table records and specify additional data integrity rules:

SET RELATION TO
[<key exp list 1> | <expN 1>
INTO <child table alias 1>
[CONSTRAIN]
[INTEGRITY
[CASCADE | RESTRICTED] ]
[, <key exp list 2> | <expN 2>
INTO <child table alias 2>]
[CONSTRAIN]
[INTEGRITY
[CASCADE | RESTRICTED] ] ... ]
[ADDITIVE]

<key exp list 1>

The key expression or field list that is common to both the current table and a child table and links both tables. When specifying the INTEGRITY option, you can specify a key field but not an expression. The child table must be indexed on the key field and that index must be the master index in use for the child table. An index based on the same key field must also be defined for the parent table but it does not need to be the master index for that table.

<expN 1> INTO <child table alias>

For dBASE tables only, you can specify <expN>to link records in a child table. When <expN> is RECNO( ), dBASE for Windows links the current table to a child table by corresponding record numbers, in which case, the child table does not have to be indexed.

INTO <child table alias>

<alias> specifies the child table linked to the current table. You can specify a work area number (1 through 225), letter (A through J), or alias name. The work area letter or alias name must be enclosed in quotes.

<key exp list 2> | <expN 2> INTO <alias 2> ...]

Specifies additional relationships from the current table into other tables.

CONSTRAIN

Limits records processed in the child table to those matching the key expression in the parent table.

INTEGRITY [CASCADE | RESTRICTED]

Specifies rules that control the addition or deletion of records in the child table. If INTEGRITY is specified, key fields of records added to child tables via APPEND, APPEND BLANK, BROWSE, EDIT, or INSERT commands are set to values matching those of the parent table. Also, when you delete records or change the value of key fields in the parent table, a dialog box appears, in which you can choose to delete all related child records (performing a cascade delete).

The CASCADE and RESTRICTED options specify rules to follow when adding or deleting records in a program (so the dialog box does not appear). The CASCADE option specifies that all child table records with matching key field values are deleted when you delete a record or change the key value of a record in the parent table. The RESTRICTED option prevents deletions or changes to records in the parent table if the child table contains records with matching key field values.

ADDITIVE

Adds the new relation to any existing ones. Without ADDITIVE, SET RELATION clears existing relations before establishing the new relation.

Description

Use SET RELATION to establish a link between open tables based on common fields or expressions. Remember that you can also define relations and link tables automatically by using the CREATE|MODIFY QUERY or VIEW commands, which let you save relations to a .QBE file.

Before setting a relation, open each table in a separate work area. When a relation is set, the table in the current work area is referred to as the parent table, and a table linked to the parent table by the specified key is called a child table. The child table must be indexed on the fields or expressions that link tables and that index must be the master index in use for the child table. An index with a key expression that matches <key exp list 1> must also be defined for the parent table but does not need to be the master index in use for that table.

A relation between tables is usually set through common keys specified by <key exp list>. The relating expression can be any expression derived from the parent table that matches the keys of the child table master index. The keys may be a single field or a set of concatenated fields contained in each table. The fields in each table can have different names but must contain the same type of data. For Paradox and SQL tables, you can specify single or composite index key fields.

For dBASE tables only, if you specify a numeric expression to link tables, the parent table is always linked to record numbers in a child table specified by the numeric expression (typically, the RECNO( ) function). This causes record 1 in the parent table to be linked to record 1 in the child table, record 2 in the parent table linked to record 2 in the child table, and so on.

SET RELATION clears existing relations before establishing a new one, unless you use the ADDITIVE option. SET RELATION TO without any arguments clears existing relations from the current table without establishing any new relations.

For dBASE tables, the CONSTRAIN and INTEGRITY options control processing of linked records. Using these options requires that the parent table not contain any records with duplicate key values. If a parent table has duplicate records, copy the table to a temporary table, index the temporary table using the UNIQUE option, and then use COPY to copy the table back to the original table name. After setting up a relation with either CONSTRAIN or INTEGRITY, the uniqueness of key values in the parent table is strictly enforced.

The CONSTRAIN option restricts access in the child table to only those records whose key values match records in a parent table. This is the same as using SET KEY TO on the key field of the child table. As a result, you cannot use SET KEY TO and CONSTRAIN at the same time. If a SET KEY TO operation is in effect on the child table when you specify CONSTRAIN with SET RELATION, dBASE for Windows returns a "SET KEY in use in alias" message. If the CONSTRAIN option is in effect when SET KEY TO is specified, dBASE for Windows returns the error "CONSTRAIN is active." You can use SET FILTER with the CONSTRAIN option, if you want to specify additional conditions to qualify records in a child table.

The INTEGRITY option specifies rules that control the addition or deletion of records in the child table. If INTEGRITY is specified, when you add records using APPEND, APPEND BLANK, BROWSE, EDIT, or INSERT commands, the key fields of records added to child tables are set to values matching those of the parent table. If you add new records to the parent table, values in the key field must be unique; otherwise, dBASE for Windows returns the error "Key already exists." When you edit records in the child table, key fields in the child table are read-only.

Integrity rules assume SET DELETED is ON. Setting DELETED OFF is not recommended when using the INTEGRITY option since it could show linked records already marked for deletion.

If you specify the INTEGRITY option without the CASCADE or RESTRICTED keywords, when you delete records or change the value of key fields in the parent table, a dialog box appears, in which you can choose to delete all related child records (performing a cascade delete).

If you specify INTEGRITY with the CASCADE option, dBASE for Windows automatically deletes all records in the child table that match the key value of records that are deleted or changed in the parent table. If a key value of a record in the parent table is changed to a value that already exists, dBASE for Windows returns the error "Key already exists."

If you specify INTEGRITY with the RESTRICTED option, dBASE for Windows prevents you from deleting records in the parent table with linked child table records. If you attempt to delete records or change the key value of records in the parent table while records with matching key values still exist in the child table, dBASE for Windows returns the error "Linked records still exist in alias" and the parent table record is not deleted or changed. You can delete records in a child table unless that table is itself a parent and an integrity rule is defined that restricts deletions to its child table records.

More than one relation can be defined from the same table. Also, more than one relation can be set from the same parent table if you use the ADDITIVE option or if you specify multiple relations with the same SET RELATION command. You can also establish additional relations from a child table, thus defining a chain of relations. Cyclic relations are not allowed; that is, dBASE for Windows returns an error if you attempt to define a relation from a child table back into its parent table.

When a relation is set from a parent table to a child table, the relation can be accessed only from the work area that contains the parent table. To access fields of the child table from the current work area, use the alias pointer (->) and prefix the name of fields in the child table by its alias name.

If a matching record cannot be found in a linked table, the linked table is positioned at the end-of-file, and EOF( ) returns .T. The setting of SET NEAR does not affect positioning of the record pointer in child tables. When the INTEGRITY option is used, if the parent table is positioned at the end of file, dBASE for Windows returns the error "No matching parent record."

When a SET SKIP list is active, the record pointer is advanced in each table, starting with the last work area in the relation chain and moving up the chain toward the parent table.


SET RELATION Example

The following example uses SET RELATION to create a relationship based on the key field, CompCode, between the parent table, Company, and the child table, Contact:

CLOSE ALL
USE Contact EXCLUSIVE
INDEX ON Compcode TAG Compcode
SELECT 2
USE Company EXCLUSIVE
INDEX ON Company TAG Company
SET RELATION TO CompCode INTO Contact

Now the contact and the company for which they are a contact are connected. Contact, the child table, must be indexed on Compcode. Company does not need to be indexed on Compcode.

If you want to add a second relationship for Company, use the ADDITIVE clause. In this example, a relationship to the TypeCo table is added. TypeCo is a code table that contains the TYPE field used in the company table (for example, "ISV") and a description in the TYPE_DESC field (for example, "Independent Software Vendor"):

SELECT SELECT()  && Select the next open work area
USE TypeCo EXCLUSIVE  && Contains a description of
                      && the type of company
INDEX ON TYPE TAG TYPE
SELECT Company
SET RELATION TO Type INTO TypeCo ADDITIVE

Now Company is simulaneously related to Contact via field Compcode and to TypeCo via the Type field.

DISPLAY ALL Company,Contact->Contact,;
  TypeCo->Type_desc
* All three tables are accessed


See Also

CREATE VIEW...FROM ENVIRONMENT

JOIN

SELECT

SET FIELDS

SET FILTER

SET SKIP

SET VIEW

SKIP


SET REPROCESS

See Also	Example	Portability	Shared Data

Specifies the number of times dBASE tries to lock a file or one or more records before generating an error or returning .F.

Syntax

SET REPROCESS TO <expN>

<expN>

A number from -1 to 32,000, inclusive, that is the number of times for dBASE to try to lock a file or one or more records.

Default

The default for SET REPROCESS is 0, meaning dBASE does not try to lock a file or one or more records after the original attempt. To change the default, set the REPROCESS parameter in DBASEWIN.INI. To do so, either use the SET command to specify the setting interactively, or enter the REPROCESS parameter directly in DBASEWIN.INI.

Description

Use SET REPROCESS to specify how many times dBASE should try to lock a file or one or more records before generating an error or returning .F. SET REPROCESS affects RLOCK( ), LOCK( ), and FLOCK( ), and all commands and functions that automatically attempt to lock a file or records.

SET REPROCESS TO 0 causes dBASE to prompt you to retry setting a lock or to cancel. If you cancel, RLOCK( ), LOCK( ), and FLOCK( ) return .F., and a command that automatically attempts to lock a file or record returns an error.

Setting SET REPROCESS to a number greater than 0 causes dBASE to retry setting a lock the specified number of times without prompting you to confirm each retry or to cancel.

SET REPROCESS TO -1 causes dBASE to retry setting a lock without prompting you to retry or cancel, and to continue retrying until the lock succeeds.


SET REPROCESS Example

See FLOCK( ) for an example for SET REPROCESS.


Portability

Not supported in dBASE III PLUS.


See Also

FLOCK( )

ON ERROR

ON NETERROR

RETRY

RLOCK( )

SET LOCK


SET SAFETY

See Also	Example	Environment

Determines whether dBASE asks for confirmation before overwriting a file or removing records from a table when you issue ZAP.

Syntax

SET SAFETY ON | off

Default

The default for SET SAFETY is ON. To change the default, set the SAFETY parameter in DBASEWIN.INI. To do so, either use the SET command to specify the setting interactively, or enter the SAFETY parameter directly in DBASEWIN.INI.

Description

When SET SAFETY is ON, dBASE prompts for confirmation before overwriting a file or removing records from a table when you issue ZAP. If you want your program to control the interaction between dBASE and the user with regard to overwriting files, issue SET SAFETY OFF in your program.

SET SAFETY affects the following commands:

Commands using a TO FILE option

COPY

COPY FILE

COPY TO...STRUCTURE EXTENDED

CREATE/MODIFY commands

INDEX

JOIN

SAVE

SET ALTERNATE TO

SORT

TOTAL

UPDATE

ZAP

Note:	SET TALK OFF does not suppress SET SAFETY warnings.


SET SAFETY Example

This example zaps a table when safety is on and when it is off:

USE COMPANY
COPY TO TEMP
* Make a temporary table
USE TEMP EXCLUSIVE
SET SAFETY ON
ZAP
* A window titled ZAP appears and a message
* "Remove all records from TEMP.DBF" is shown.
* The user will have to OK zapping the TEMP.DBF
SET SAFETY OFF
ZAP
* The table is zapped automatically
SET SAFETY ON
* Turn safety back on
USE
DELETE FILE TEMP.DBF
DELETE FILE TEMP.DBT
* Delete the temporary table


See Also

SET TALK


SET SEPARATOR

See Also	Example	Portability	Numeric Data

Specifies the character that separates each group of three digits (whole numbers) to the left of the decimal point in the display of numbers greater than or equal to 1000.

Syntax

SET SEPARATOR TO
[<expC>]

<expC>

The whole-number separator, which is the character that separates each group of three digits to the left of the decimal point in the display of numbers greater than or equal to 1000. You can specify more than one character, but dBASE uses only the first one. If you specify a number as a character for <expC> (for example, "3"), dBASE returns an error.

Default

The default for SET SEPARATOR is set by the International option of the Windows Control Panel. To change the default, set the SEPARATOR parameter in DBASEWIN.INI. To do so, either use the SET command to specify the setting interactively, or enter the SEPARATOR parameter directly in DBASEWIN.INI.

Description

SET SEPARATOR affects only the PICTURE "," template character and the numeric display of byte totals for the commands DIR, DISPLAY FILES, and LIST FILES. For example, if you SET SEPARATOR TO "."(period) and issue the following, dBASE returns 123456 displayed as 123.456:

? 123456 PICTURE"999,999"

You must use the comma in the PICTURE function, regardless of the setting of SET SEPARATOR. For more information on the PICTURE option, see Picture.

SET SEPARATOR TO without the <expC> option resets the separator to the default set with the International option of the Windows Control Panel.

Setting a whole-number separator with SET SEPARATOR does not affect the values of numbers, only their display.


SET SEPARATOR Example

See SET POINT and INT( ) for examples of SET SEPARATOR.


Portability

Not supported in dBASE III PLUS.


See Also

SET POINT


SET SKIP

See Also	Example	Portability	Table Organization

Specifies how to advance the record pointer through records of linked tables.

Syntax

SET SKIP TO
[<alias 1>[, <alias 2>] ... ]

[<alias1>[, <alias2>] ... ]

The alias tables defined in a relation. You can specify a work area number (1 through 225), letter (A through J), or alias name. The work area letter or alias name must be enclosed in quotes. SET SKIP TO without any options cancels previous SET SKIP settings.

Description

SET SKIP works only with tables that have been linked with the SET RELATION command. Used together, the SET RELATION and SET SKIP commands determine the way in which the record pointer moves through parent and child tables.

Use SET SKIP when you set a relation from a parent table containing unique key values to child tables that contain duplicate key values, that is, a one-to-many relationship. SET SKIP causes commands that move the record pointer to move the pointer to every record with matching key values in a child table before moving the record pointer in the parent table. If you define a chain of relations and use SET SKIP to move from one table to the next down the chain, the record pointer moves to every record in the last child table before the pointer moves in its parent table.


SET SKIP Example

The following example uses SET RELATION to create a relationship based on the key field, CompCode, between the parent table, Company, and the child table, Contact. It then uses SET SKIP in two different ways. First it accesses all contacts for each company, and second it accesses only one contact per company:

CLOSE DATABASE
USE Contact EXCLUSIVE
INDEX ON Compcode+Contact TAG Compcont
* Compcode+Contact is used rather than just
* Compcode because now, for each company, the
* Contacts are in alphabetical order
SELECT 2
USE Company EXCLUSIVE
INDEX ON Company TAG Company
SET RELATION TO CompCode INTO Contact
* now the tables and relationships are established
SET SKIP TO Contact
DISPLAY ALL Company,Contact->Contact
* All contacts for all companies are shown
SET SKIP TO
DISPLAY ALL Company,Contact->Contact
* Now only one contact per company is shown


Portability

Not supported in dBASE III PLUS.


See Also

SET RELATION

SKIP


SET SPACE

See Also	Example	Portability	Input/Output

Determines whether dBASE inserts a space between expressions displayed or printed with a single ? or ?? command.

Syntax

SET SPACE ON | off

Default

The default for SET SPACE is ON. To change the default, set the SPACE parameter in DBASEWIN.INI.

Description

Use SET SPACE OFF when you use a single ? or ?? command to print a list of expressions and you don't want spaces between the expressions. If you want the expressions printed with spaces between them, issue SET SPACE ON.

SET SPACE has no effect on multiple ? or ?? commands. For example, if you issue the command ?? <exp> twice, the second instance of <exp> will be printed adjacent to the first, even if SET SPACE is ON. However, if SET SPACE is ON and you issue ?? <exp>, <exp> as a single command, there will be a space between the two instances of <exp>.


SET SPACE Example

This example displays a first and a last name using SET SPACE ON and then SET SPACE OFF:

Firstname="Rachel"
Lastname ="Jayes"
SET SPACE ON  && the default
? Firstname,Lastname
* Rachel Jayes
SET SPACE OFF
? Firstname,Lastname
* RachelJayes
* The two variables are not separated


Portability

Not supported in dBASE III PLUS, which always adds a space between printed expressions (as if SET SPACE were ON).


See Also

?

??

LTRIM( )

RTRIM( )

TRIM( )


SET STEP

See Also	Portability	Error Handling and Debugging

SET STEP ON opens the dBASE Debugger. This command is supported primarily for compatibility with dBASE IV. In dBASE for Windows, use DEBUG to open the debugger.

Syntax

SET STEP on | OFF

Default

The default for SET STEP is OFF.

Description

Use SET STEP to turn on the Debugger and view or control program execution interactively. SET STEP is identical to DEBUG. For more information, see DEBUG.


Portability

In both dBASE IV and dBASE III PLUS, SET STEP ON does not open the Debugger but instead displays command lines on the screen, along with the screen output of the commands themselves.


See Also

DEBUG


SET TALK

See Also	Example	Environment

Determines whether dBASE displays messages in the status bar, or displays memory variable assignments in the results pane of the Command window.

Syntax

SET TALK ON | off

Default

The default for SET TALK is ON. To change the default, set the TALK parameter in DBASEWIN.INI. To do so, either use the SET command to specify the setting interactively, or enter the TALK parameter directly in DBASEWIN.INI.

Description

When SET TALK is ON, dBASE uses the current SET ODOMETER setting to indicate when operations such as COUNT and SORT are in progress in the status bar. It also displays the results of memory variable assignments (using STORE or =) in the results pane of the Command window.

Depending on the amount of memory your system has and the amount of memory particular operations require, issuing SET TALK OFF might improve the performance of some operations.

Use SET TALK with SET ALTERNATE or SET DEVICE to send SET TALK output to a file or printer rather than to the results pane of the Command window.


SET TALK Example

This example shows the effect of SET TALK ON and SET TALK OFF while creating a memory variable:

Oldtalk=SET("TALK")
SET TALK ON
First="Susan"    && Susan
Last="O'Shenko"  && O'Shenko
Name=Last+", "+First
SET TALK OFF
First="Tom"
Last="Frost"
Name=Last+", "+First
? Name
* Name will be set to "Frost, Tom"
* but this will not be displayed in the status bar
SET TALK &Oldtalk

When TALK is OFF, the assignment of "Tom" to First and "Frost" to Last and "Frost, Tom" to Name are not displayed.

In the following example Count displays to the status bar when TALK is ON:

CLOSE ALL
USE COMPANY
SET TALK ON       && Talk on
COUNT TO Recs     && Count displays in status bar
SET TALK OFF      && Talk off
COUNT TO Recs     && No display


See Also

SET ALTERNATE

SET CONSOLE

SET DEVICE

SET ODOMETER

STORE


SET TIME

See Also	Example	Portability	Date and Time Data

Sets the system time.

Syntax

SET TIME TO <expC>

<expC>

The time, which you must specify in one of the following formats:

HH

HH:MM or HH.MM

HH:MM:SS or HH.MM.SS

Default

The default for the value of the system time is set by the Date/Time option of the Windows Control Panel.

Description

Use SET TIME to reset your system's clock. Subsequent values of TIME( ) and the time stamp of any files you save reflect the new time.


SET TIME Example

See SET DATE TO for an example SET TIME.


Portability

Not supported in dBASE IV or dBASE III PLUS.


See Also

SET DATE TO

TIME( )


SET TITLE

See Also	Example	Table Basics

Turns the catalog file title prompt on or off.

Syntax

SET TITLE ON | off

Default

The default for SET TITLE is ON. To change the default, set the TITLE parameter in DBASEWIN.INI. To change the default, update the TITLE setting in DBASEWIN.INI. To do so, either use the SET command to specify the setting interactively, or enter the TITLE parameter directly in DBASEWIN.INI.

Description

When SET CATALOG is ON, files are automatically added to the catalog whenever they are created, used, or saved. If SET TITLE is ON, you are prompted to enter a file title or description to accompany the file entry in the catalog. Otherwise, this prompt does not appear.

When you create files from the Command window and a catalog is open, files are added to the catalog, but you are not prompted to enter a description.

To enter a title or modify other information in a catalog file, use commands such as BROWSE, EDIT, or REPLACE. You can open and modify a catalog file in any work area, but you cannot modify a catalog opened by SET CATALOG.


SET TITLE Example

The following example uses SET TITLE OFF to disable the prompt to enter a file title for the catalog record when a newly created file is added to the open catalog:

SET CATALOG ON
SET CATALOG TO Learn
SET TITLE OFF
CREATE NewNames TYPE DBASE FROM Customer TYPE PARADOX
USE NewNames TYPE DBASE
BROWSE


See Also

CATALOG( )

CREATE CATALOG

SELECT( )

SET CATALOG

USE


SET TOPIC

See Also	Example	Portability	Windows Programming

Specifies a Help topic to display initially.

Syntax

SET TOPIC TO [<expC>]

<expC>

The help topic keyword. If you omit <expC>, dBASE displays the Help Contents topic by default.

Default

The default for SET TOPIC is an empty string. To change the default, update the TOPIC setting in dBASEWIN.INI. To do so, either use the SET command to specify the setting interactively, or enter the TOPIC parameter directly in DBASEWIN.INI.

Description

Use SET TOPIC to display a specified topic each time:

The HELP command is executed.

The user presses F1 while the cursor is in the Command window.

You specify the topic with <expC>, the help topic keyword. If you specify the entire keyword, the Help system displays the topic immediately. If you specify only initial characters, the Help system displays the Search dialog box, a tool that lets users select topics from a list. The first topic whose Help keyword has <expC> in its leftmost position is highlighted automatically. For example, executing SET TOPIC TO "CA", then HELP displays the Search dialog box with CALCULATE highlighted.

When the user presses F1 while the cursor is not in the Command window, the Help system is context-sensitive and ignores the SET TOPIC TO setting. For example, if you execute SET TOPIC TO "CA", then execute BROWSE, pressing F1 displays information on the Table Editor rather than CALCULATE.


SET TOPIC Example

The following example would change the help topic based on a menu choice:

DO CASE
CASE MenuChoice = 1
    SET TOPIC TO "BROWSE"
    BROWSE          && dBASE BROWSE
CASE MenuChoice = 2
    SET TOPIC TO "EDIT"
    EDIT            && dBASE EDIT
CASE MenuChoice = 3
    SET TOPIC TO "SET"
    SetOptions      && User procedure to set various;
                       settings. Topic will bring up;
                       search window in help with;
                       SET... topics displayed
CASE MenuChoice = 4
    QUIT
ENDCASE


Portability

Not supported in dBASE IV or dBASE III PLUS.


See Also

HELP

HelpFile

HelpID

SET HELP


SET TYPEAHEAD

See Also	Example	Portability	Keyboard and Mouse Events

Sets the size of the typeahead buffer, where keystrokes are stored while dBASE is busy processing other data. This command is supported primarily for compatibility with dBASE IV. In dBASE for Windows, forms do not use the typeahead buffer.

Syntax

SET TYPEAHEAD TO <expN>

Default

The default size of the typeahead buffer is 50 characters. To change the default, set the TYPEAHEAD parameter in DBASEWIN.INI.

Description

SET TYPEAHEAD lets you to specify the size of the keyboard typeahead buffer. The size you specify with <expN> may be any number from 0 to 1600.

The keyboard typeahead buffer stores keystrokes the user enters while dBASE is busy processing other data. When the processing is complete and keyboard input is enabled again by a dBASE command such as BROWSE or EDIT, dBASE processes and deletes the values in the buffer in the order they were entered. dBASE continues to process and delete values in the buffer until the buffer is empty.

If the size of the typeahead buffer is set to 50, dBASE can store values for 50 keypresses, and rings the bell at the 51st press to warn that the buffer is full. A large typeahead buffer is useful if the user does not want to stop typing when dBASE is unavailable for processing direct keyboard input.

For some programs, you may want to disable the typeahead buffer with SET TYPEAHEAD TO 0. This ensures that user input comes directly from the keyboard, rather than from the typeahead buffer.

For example, if you want to be able to fill in multiple forms quickly, one after the other, you might SET TYPEAHEAD to a relatively high number during form processing. This would let you continue typing data while one form was being saved and the next (blank) one being displayed. The data you entered during processing would be entered onto the new form when it appeared. On the other hand, if you want to make sure that no data is entered until the form is displayed on the screen, you can issue SET TYPEAHEAD TO 0.

SET TYPEAHEAD limits the number of characters you can put into the typeahead buffer using KEYBOARD.

To flush the typeahead buffer, use CLEAR TYPEAHEAD.


SET TYPEAHEAD Example

For professional data entry persons, and typists who are sure of their typing, increase the size of the typeahead buffer by including the following command in your program:

SET TYPEAHEAD TO 100


Portability

In dBASE III PLUS and dBASE IV, the default size of the typeahead buffer is 20 characters. In dBASE IV, the maximum size of the typeahead buffer is 32000.


See Also

CLEAR TYPEAHEAD

INKEY( )

NEXTKEY( )

KEYBOARD


SET UNIQUE

See Also	Example	Table Organization

Determines if records with duplicate key values appear in an index file.

Syntax

SET UNIQUE on | OFF

Default

The default for SET UNIQUE is OFF. To change the default, update the UNIQUE setting in DBASEWIN.INI. To do so, either use the SET command to specify the setting interactively, or enter the UNIQUE parameter directly in DBASEWIN.INI.

Description

Use SET UNIQUE ON to include only the first record with the same key value in .MDX and .NDX indexes created with the INDEX command. When SET UNIQUE is OFF, indexes you create can include records with identical key values; records with identical keys are arranged by record number in the index.. Whenever you reindex an index file, dBASE for Windows maintains the index in the same way it was created.

dBASE for Windows processes unique indexes only once. Therefore, a previously hidden key value is not automatically updated when it is changed. Also, if you append a record that contains an index key that is already in the index file, the new record is not added to the index file, although the table is updated with the new record. REINDEX explicitly updates all key values in a unique index.

Following SET UNIQUE ON with an INDEX command is equivalent to issuing the single command INDEX...UNIQUE.


SET UNIQUE Example

The following example uses SET UNIQUE to make an index with just one record per state:

USE Clients EXCLUSIVE
INDEX ON State_Prov TAG State
SET UNIQUE ON
INDEX ON State_Prov TAG UnqState
SET UNIQUE OFF    && RESET UNIQUE
SET ORDER TO TAG State
BROWSE FIELDS State_Prov, Company ;
  TITLE "All records"
SET ORDER TO TAG Unqstate
BROWSE FIELDS State_Prov, Company  ;
  TITLE "One record per State"
COUNT TO numstates
WAIT "There are companies in ";
  +ltrim(str(numstates)) + " states"


See Also

INDEX

REINDEX

SET( )

SET INDEX

SET ORDER

UNIQUE( )

USE


SET VIEW

See Also	Example	Table Organization

Opens a previously defined query or view file.

Syntax

SET VIEW TO <filename> | ? | <filename skeleton>

<filename> | ? | <filename skeleton>

The query or view file containing the settings to define the current working environment or view. SET VIEW TO ? and SET VIEW TO <filename skeleton> display a dialog box, in which you select a view file. If you specify a file without including its path, dBASE for Windows looks for the file in the current directory, then in the path you specify with SET PATH. If you specify a file without including its file-name extension, dBASE for Windows looks for a .QBE, then a .VUE file.

Description

Use SET VIEW to change the working environment to one that was previously defined by CREATE QUERY, CREATE VIEW, or CREATE VIEW...FROM ENVIRONMENT. The working environment includes open tables and index files, all relations, the active fields list, and filter conditions.


SET VIEW Example

See CREATE VIEW...FROM ENVIRONMENT for an example of SET VIEW.


See Also

CREATE QUERY

CREATE VIEW

CREATE VIEW...FROM ENVIRONMENT


SET WINDOW OF MEMO

See Also	Example	Portability	Fields and Records

Specifies a window to use while editing the contents of a memo field.

Syntax

SET WINDOW OF MEMO TO [<window name>]

TO <window name>

Specifies the name of a previously defined window to be used for editing the contents of a memo field.

Description

Use the SET WINDOW OF MEMO command to use a previously defined window to edit memo fields when you are using commands such as APPEND, BROWSE, CHANGE, EDIT, or READ. The WINDOW clause that you specify with the @...SAY...GET command for editing memo fields overrides the window specified with this command.

If you specify SET WINDOW OF MEMO TO without specifying the name of a window, dBASE for Windows clears any previously defined window name.


SET WINDOW OF MEMO Example

The following example uses SET WINDOW OF MEMO to specify a window to use for editting a memo field:

DEFINE WINDOW MainWindow FROM  1, 1 TO 15,70
DEFINE WINDOW MemoEdit   FROM 6,30 TO 14,68
USE Company  EXCLUSIVE
ACTIVATE WINDOW MainWindow
SET WINDOW OF MEMO TO MemoEdit
@  2, 1 GET Notes OPEN WINDOW MemoEdit
READ
CLOSE DATABASES
DEACTIVATE WINDOW MainWindow


Portability

Not supported in dBASE III PLUS.


See Also

ACTIVATE WINDOW

CLEAR WINDOWS

DEFINE WINDOW

MOVE WINDOW


SET WP

See Also	Example	Portability	Environment

Specifies the text editor to use when viewing and editing memo fields.

Syntax

SET WP TO
[<expC>]

<expC>

The expression you enter at the DOS prompt or as the Windows command line to start the editor, usually the name of the editor's executable file (.EXE) or a Windows .PIF file. If <expC> does not include the file's full path name, dBASE looks for the file in the current directory, then in the DOS path..

Default

The default for SET WP is the dBASE for Windows internal Text Editor. To specify a different default editor, set the WP parameter in DBASEWIN.INI. To do so, either use the SET command to specify the setting interactively, or enter the WP parameter directly in DBASEWIN.INI.

Description

Use SET WP to specify an editor other than the default dBASE Text Editor to use when viewing or editing memo fields. The specified editor opens when you open a memo field for viewing or editing. If you issue SET WP TO without a file name for <expC>, dBASE returns to the default editor.

To choose an editor to use when viewing and editing programs and text files, use SET EDITOR.

You can use SET WP to specify a .PIF file, which is a Windows file that controls the Windows environment for a DOS application, or a Windows .EXE file. Start the DOS editor by running the .PIF file rather than the .EXE. When you issue commands that run in a DOS window, dBASE loads COMMAND.COM using DBASEWIN.PIF in the _dbwinhome directory. You can use the Windows PIF Editor to customize the settings in DBASEWIN.PIF. For more information about .PIF files, see your Windows documentation.

If the editor you specify is already in use when you open a memo for editing, a second instance of the editor starts.


SET WP Example

The following example shows two commands. The first sets the word processor to Word for Windows and the second resets the word processor to the default, dBASE text editor.

SET WP TO "C:\WORD2A\Winword.exe"
SET WP TO   && reset to default


Portability

Not supported in dBASE IV or dBASE III PLUS.


See Also

_dbwinhome

CREATE COMMAND

CREATE FILE

MODIFY COMMAND

MODIFY FILE

SET EDITOR


SHELL( )

See Also	Example	Portability	Environment

Removes or restores the dBASE interactive environment. Returns a logical value corresponding to the previous SHELL( ) state.

Syntax

SHELL([<expL>])

<expL>

The value that determines whether to hide or restore the dBASE environment.

Description

Use SHELL(.F.) in programs to temporarily hide the standard dBASE environment, allowing your application to take control of the user's working environment. To restore the dBASE interactive environment, issue SHELL(.T.). The environment is also restored when the user closes the form that SHELL( ) is activated for.

SHELL(.F.) operates differently when you are working in a form that is defined as a top-level MDI form (formname.MDI=.F.) or in a form that is not a top-level MDI form (formname.MDI=.T.).

When formname.MDI=.F. for the active form, SHELL(.F.) appears to remove dBASE from the user's system. The form name becomes the application name that appears in the Windows Task List in place of "dBASE for Windows." This makes your application look like a standalone application, and is the typical use for SHELL( ).

When formname.MDI=.T. for the active form, the menu system associated with the form appears as the menu at the top of the screen instead of at the top of the form. The user remains in dBASE, but the dBASE menu is replaced by the menu defined by the active form. However, the user can still access the SpeedBar if it is active. The user can click in the Command window to close the form.

Using SHELL( ) in a program has the same effect as changing the Visible property of the FrameWin object of _app, as shown in the following example. For more information, see _app.

SHELL(.F.)	&& same effect as next line
_app.FrameWin.Visible = .F.

If you issue SHELL(.F.) in the Command window, you exit to Windows momentarily and then return to dBASE.


SHELL( ) Example

This example shows the code generated by the form designer for a Shell Test form that simply sets the left double click button to SHELL(.t.) and the right double click button to SHELL(.f.).

LOCAL f
f = NEW SHELL ()
f.Open()

CLASS SHELL OF FORM
   this.OnRightDblClick = {shell(.t.)}
   this.OnLeftDblClick = {shell(.f.)}
   this.EscExit = .T.
   this.mdi = .f.
   * set mdi=.t. to see effect with mdi
   this.Text = "Shell Test .t."
   this.Width =         48.00
   this.Top =          2.00
   this.Left =          40.00
   this.Height =         15.00
   this.Minimize = .F.
   this.Maximize = .F.
ENDCLASS

When the form is activated e.g. with DO Shell.wfm, the Shell Test form appears on the screen (with mdi=.f.). Double clicking with the left mouse button makes other windows in the dBASE screen dissappear. Double clicking with the right button makes them reappear. * When you set mdi=.t., the Shell Test form can be accessed by pressing Ctrl Tab to show the Windows windows.


Portability

Not supported in dBASE IV or dBASE III PLUS.


See Also

_app

DEFINE

QUIT

SET DESIGN


SHOW MENU

See Also	Example	Portability	dBASE IV Menus

Displays, but does not enable, a previously-defined dBASE IV menu bar. This command is supported primarily for compatibility with dBASE IV. In dBASE for Windows, use DEFINE, OPEN FORM, and READMODAL( ) to create and activate menus associated with forms.

Syntax

SHOW MENU <menu name>
[PAD <pad name>]

PAD <pad name>

Identifies the pad that is highlighted by default when the menu is displayed. Without PAD <pad name>, the first pad defined with DEFINE PAD is highlighted.

Description

SHOW MENU displays a menu bar without enabling its options.

The DEFINE MENU command and all associated DEFINE PAD commands must be executed before you can use SHOW MENU. SHOW MENU overwrites the current screen display, then returns control to the command window or to the next command line.


SHOW MENU Example

The following example uses SHOW MENU to redisplay a previously active menu if the user answers "Y" when prompted after exiting the initial menu session. INKEY(5) pauses the SHOW MENU display for 5 seconds before proceeding with Procedure Exit2, which finally clears the screen and exits the program:

DEFINE WINDOW A FROM 5,10 TO 20,65;
    COLOR W+/B,RG+/RB+,R+/GB
DEFINE MENU Main;
    MESSAGE "Table Maintenance"
DEFINE PAD Add OF Main PROMPT "Add Records";
    AT 4,3 MESSAGE "Add new records"
DEFINE PAD Search OF Main PROMPT "Search File";
    AT 4,16 MESSAGE "Search for record"
DEFINE PAD Print OF Main PROMPT "Print";
    AT 4,29 MESSAGE "Print a report"
DEFINE PAD Exit OF Main PROMPT "Quit";
    AT 4,49 MESSAGE "Leave the program"
* KEYBOARD " " in the following lines is for
* demo purposes only - does nothing.  Replace
* with DO <proc name> to make functional.
ON SELECTION PAD Add OF Main KEYBOARD " "
ON SELECTION PAD Search OF Main KEYBOARD " "
ON SELECTION PAD Print OF Main KEYBOARD " "
ON SELECTION PAD Exit OF Main DO ExitMain
CLEAR
ACTIVATE WINDOW A
ACTIVATE MENU Main
WAIT "Want to view the menu again? - Y/N" TO Chc
ON ESCAPE DO Exit2
IF UPPER(Chc) = "Y"
  SHOW MENU Main
  INKEY(5)
  DO Exit2
ELSE
  CLEAR ALL
ENDIF

PROCEDURE ExitMain
DEACTIVATE MENU          && Clears menu from screen
CLEAR WINDOWS            && Clear window from memory
CLEAR MENUS              && Clears menu from memory
RETURN

PROCEDURE Exit2
DEACTIVATE WINDOW A
CLEAR WINDOWS
CLEAR MENUS
RETURN


Portability

Not supported in dBASE III PLUS.


See Also

ACTIVATE MENU

DEFINE

DEFINE MENU

OPEN FORM

READMODAL( )


SHOW OBJECT

See Also	Example	Portability	Objects

Updates the appearance of an object to reflect its most recent property settings.

Syntax

SHOW OBJECT <container reference>.<object reference>

<container reference>.<object reference>

<container reference> is an object reference variable pointing to the object (usually a form) that contains the object. <object reference> is an object reference variable pointing to the object itself.

Description

Use SHOW OBJECT to refresh an object on the screen. For example, when you change a bitmap image on a push button with the UpBitMap property, SHOW OBJECT makes the new image appear in the push button.


SHOW OBJECT Example

The following example defines a form with two pushbuttons that move the record pointer. An OnClick property calls a procedure that evaluates record pointer position with regard to EOF( ) or BOF( ). If the record pointer is located at EOF( ) or BOF( ), the procedure changes properties of the buttons and uses SHOW OBJECT to refresh the displayed button as per the new properties. The ELSE clause of the procedure refreshes the pushbutton to original property values and moves the record pointer:

USE ANIMALS
SET PROCEDURE TO PROGRAM(1) ADDITIVE
DEFINE FORM F1;
  PROPERTY Text "SHOW OBJECT Command Demo"
DEFINE PUSHBUTTON P1 OF F1 AT 9,15;
  PROPERTY Text "Previous",;
  Width 12, Height 2,;
  OnClick Prev
DEFINE PUSHBUTTON P2 OF F1 AT 12,15;
  PROPERTY Text "Next",;
  Width 12, Height 2,;
  OnClick Next
OPEN FORM F1

PROCEDURE Prev
  IF BOF()
    Form.P1.Text = "You are at BOF"
    Form.P1.Width = 16
    Form.P1.Left = 12
    SHOW OBJECT form.P1
  ELSE
    Form.P1.Text = "Previous"
    Form.P1.Width = 10
    Form.P1.Left = 15
    SHOW OBJECT form.P1
    SKIP-1
  ENDIF
RETURN

PROCEDURE Next
  IF EOF()
    Form.P2.Text = "You are at EOF"
    Form.P2.Width = 16
    Form.P2.Left = 12
    SHOW OBJECT form.P2
  ELSE
    Form.P2.Text = "Next"
    Form.P2.Width = 10
    Form.P2.Left = 15
    SHOW OBJECT form.P2
    SKIP
  ENDIF
RETURN


Portability

Not supported in dBASE IV or dBASE III PLUS.


See Also

UpBitMap


SHOW POPUP

See Also	Example	Portability	dBASE IV Menus

Displays, but does not enable, a previously-defined dBASE IV pop-up menu. This command is supported primarily for compatibility with dBASE IV. In dBASE for Windows, use DEFINE, OPEN FORM, and READMODAL( ) to create and activate menus associated with forms.

Syntax

SHOW POPUP <pop-up name>

Description

SHOW POPUP displays a pop-up menu without enabling its options. SHOW POPUP overwrites the current screen display, then returns control to the command window or to the next command line.

The DEFINE POPUP command with a PROMPT option, or the DEFINE POPUP command in combination with at least one DEFINE BAR command, must be executed before you can use SHOW POPUP.


SHOW POPUP Example

The following example uses SHOW POPUP to redisplay a previously active POPUP behind a currently active window:

USE Animals ORDER Name
DEFINE WINDOW wMss FROM 10,2 TO 20,76
DEFINE POPUP Main FROM 1,2 PROMPT FIELD Name
ON SELECTION POPUP Main DEACTIVATE POPUP
CLEAR
ACTIVATE POPUP Main
SHOW POPUP Main                && Redisplay the popup
ACTIVATE WINDOW wMss           && Open the window
@ 2,7 SAY "Note that this window IS active and;
 displaying this message."
@ 4,7 SAY "The POPUP is still visable in the;
 background but NOT active."
WAIT''                         && Wait for key press
RELEASE POPUP
CLEAR
CLEAR WINDOWS


Portability

Not supported in dBASE III PLUS.


See Also

DEFINE

DEFINE BAR

DEFINE POPUP

OPEN FORM

READMODAL( )


SIGN( )

See Also	Example	Portability	Numeric Data

Returns an integer that indicates if a specified number is positive, negative, or zero (0).

Syntax

SIGN(<expN>)

<expN>

The numeric or float number whose sign (positive, negative, or zero) to determine.

Description

Use SIGN( ) to determine if a numeric or float expression evaluates to a positive, negative, or zero (0) value. SIGN( ) returns 1 if a specified number is positive, 1 if that number is negative, and 0 if that number is 0.

SIGN( ) always returns an integer, regardless of the value of SET DECIMALS.


SIGN( ) Example

The following examples illustrate the three possible returned values of SIGN( ):

x = -1234.45
y = 1234.45
z = 0
? SIGN(x)                    && Returns -1
? SIGN(y)                    && Returns 1
? SIGN(z)                    && Returns 0

The following example uses SIGN( ) to display those records in the Clients table that have zero or positive balances in the StartBal field:

USE Clients
? "Companies with a starting balance of $00.00"
?
SCAN FOR SIGN(StartBal)=0
? Company, StartBal
ENDSCAN
?
? "Companies with a starting balance greater " + ;
   "than $00.00"
?
SCAN FOR SIGN(StartBal)=1
? Company, StartBal
ENDSCAN
CLOSE DATABASES


Portability

Not supported in dBASE III PLUS.


See Also

ABS( )

MAX( )

MIN( )

SET DECIMALS


SIN( )

See Also	Example	Portability	Numeric Data

Returns the trigonometric sine of an angle.

Syntax

SIN(<expN>)

<expN>

The size of the angle in radians. To convert an angle's degree value to radians, use DTOR( ). For example, to find the sine of a 30-degree angle, use SIN(DTOR(30)).

Description

SIN( ) calculates the ratio between the side opposite an angle and the hypotenuse in a right triangle. SIN( ) returns a float from -1 to +1. SIN( ) returns zero when <expN> is zero, pi, or 2pi radians.

Use SET DECIMALS to set the number of decimal places SIN( ) displays.

The cosecant of an angle is the reciprocal of the sine of the angle. To return the cosecant of an angle, use 1/SIN( ).


SIN( ) Example

Following are some ways to use SIN( ):

? SIN(PI())       && Returns 0
? SIN(PI()/2)     && Returns 1
? SIN(DTOR(30))   && Returns 0.5
? SIN(-3*PI()/2)  && Returns 1
? -SIN(3*PI()/2)  && Returns 1

The following program graphs a sine wave. It first draws the x- and y-axes, then plots the points SIN( ) returns:

* Sine.prg

SET TALK OFF
CLEAR
* Draw the x and y axes
@ 11,0 SAY REPLICATE("-", 78)
FOR i = 0 TO 23
        @ i,40 SAY "|"
NEXT
@ 11,40 SAY "."

FOR i = 0 to 79
        y = 11 - 11 * SIN(i * PI()/20)
        @ y,i SAY "."
NEXT
@ 23,0      && Move cursor below graph
SET TALK ON


Portability

Not supported in dBASE III PLUS.


See Also

ASIN( )

COS( )

DTOR( )

PI( )

RTOD( )

SET DECIMALS

TAN( )


SKIP

See Also	Example	Fields and Records

Moves the record pointer in the current or specified work area.

Syntax

SKIP
[<expN>]
[IN <alias>]

<expN>

The number of records dBASE for Windows moves the record pointer forward or backward in the table open in the current or specified work area. If <expN> evaluates to a negative number, the record pointer moves backward. SKIP with no <expN> argument moves the record pointer forward one record.

IN <alias>

Specifies the work area in which to move the record pointer. You can specify a work area number (1 through 225), letter (A through J), or alias name. The work area letter or alias name must be enclosed in quotes. SKIP without IN <alias> moves the record pointer in the current work area.

Description

Use SKIP to move the record pointer relative to its current position. For an unindexed table, the record pointer moves a specified number of records. For an indexed table, the record pointer skips the specified number of records following the index record order.

If you issue a SKIP command when the record pointer is at the last record in a table, EOF( ) returns .T. Issuing any additional SKIP commands returns an error. Similarly, if you issue a SKIP -1 command when the record pointer is at the first record of a file, BOF( ) returns .T., and a subsequent negative SKIP command returns an error.

SKIP IN <alias> lets you advance the record pointer in another work area without selecting that work area first with the SELECT command.


SKIP Example

The following example uses SKIP to move the record pointer through the records of a table to display or print a listing of selected fields:

SET SAFETY OFF
SET TALK OFF
USE Country EXCLUSIVE
INDEX ON GNP TAG GNP
? CENTER("Country List-Lowest GNP First")
?
DO WHILE .NOT. EOF()
    ? Name AT 2, GNP AT 20, Capital AT 40
    SKIP
ENDDO
CLOSE ALL

SKIP accompanied with a negative expression can be used to accomplish the reverse of the previous example:

USE Country EXCLUSIVE
INDEX ON Population TAG Pop
? CENTER("Country List-Most Populous First")
?
GO BOTTOM
DO WHILE .NOT. BOF()
    ? Name AT 2, Population AT 20, Capital AT 40
    SKIP-1
ENDDO
CLOSE ALL
SET TALK ON
SET SAFETY ON
RETURN


See Also

ALIAS( )

BOF( )

EOF( )

GO

SCAN


SLEEP

See Also	Example	Portability	Programs

Pauses a program for a specified interval or until a specified time.

Syntax

SLEEP <seconds expN> |
UNTIL <time expC> [,<date expC>]

<seconds expN>

The number of seconds to pause the program. The numeric expression must evaluate to an integer ranging from 1 to 65,535 (1 second to about 18 hours). Counting starts from the time you issue the SLEEP command.

UNTIL <time expC>

Causes program execution to pause until a specified time (<time expC>) on the current day. If you also specify <date expC>, the program pauses until the time on that day. The time and date dBASE uses are the system time and date. You can set the system time with SET TIME and the system date with SET DATE TO. If the time has already passed, SLEEP UNTIL <time expC> has no effect.

The <time expC> argument is a character expression that must evaluate to a time in HH<delimiter>MM<delimiter>SS (24-hour) format. A typical format for <time expC> is "HH:MM:SS". The delimiter is conventionally a colon but can be any other single keyboard character except a number. HH is a 1- or 2-digit number of hours, MM a 1- or 2-digit number of minutes, and SS a 1- or 2-digit number of seconds.

<date expC>

An optional date until which the program is to pause. The <date expC> argument is a character expression (not a date expression) that must evaluate to a date in MM<delimiter>DD<delimiter>YY format if SET DATE is AMERICAN. (The typical format is "MM/DD/YY".) The delimiter for <date expC> is conventionally a forward slash (/) but can be any other single keyboard character except a number. MM is a one- or two-digit number of months, DD a one- or two-digit number of days, and YY a one- or two-digit number of years. If the date has already passed, SLEEP UNTIL <time expC> [,<date expC>] has no effect. If you want to specify a value for <date expC>, you must also specify a value for <time expC>.

Description

Use SLEEP to pause a program either for <seconds expN> seconds or until a specified time (<time expC>). The specified time is the same day the program is running unless you specify a date with <date expC>. If SET ESCAPE is ON, you can interrupt SLEEP by pressing Esc.

Note:	If SET ESCAPE is OFF, there is no way to interrupt SLEEP. However, you can use Ctrl+Esc and Alt+Tab to switch to another Windows application, or Alt+F4 to exit dBASE.

Although SLEEP can generate a pause from the Command window, programmers use it primarily within programs. For example, you can use SLEEP to generate a pause between multiple displaying windows or to allow a user to read a message on the screen or complete an action. Pauses are also useful when you need to delay program execution until a specific time.

SLEEP is an alternative to using a DO WHILE loop, a FOR...NEXT loop, or WAIT to generate pauses in a program. SLEEP is more accurate than using loops because it is independent of the execution speed of the system. You can also use INKEY(<expN>) if you want the user to be able to interrupt the pause and continue with program processing.


SLEEP Example

The following example uses SLEEP to delay execution for five seconds:

SET ESCAPE ON
* ESCAPE ALLOWS YOU TO ABORT THE SLEEP COMMAND
SLEEP 5

The next example uses SLEEP to delay execution until 7:30 p.m. on the same day the program is running:

SET ESCAPE ON
* ESCAPE ALLOWS YOU TO ABORT THE SLEEP COMMAND
SLEEP UNTIL "19:30:00"

The last example uses SLEEP to delay execution until 5:30 p.m.: on May 31, 1997 (SET DATE is AMERICAN):

SET ESCAPE ON
* ESCAPE ALLOWS YOU TO ABORT THE SLEEP COMMAND
SLEEP UNTIL "17:30:00", "05/31/97"


Portability

Not supported in dBASE IV or dBASE III PLUS.


See Also

DO WHILE

FOR...NEXT

INKEY( )

SET DATE TO

SET TIME

WAIT


SORT

See Also	Example	Table Organization

Copies the current table to a new table, arranging records in the specified order.

Syntax

SORT TO <filename> | ?
[[TYPE] PARADOX | DBASE]
ON <field 1> [/A | /D [/C]]
[,<field 2> [/A | /D [/C]] ... ]
[<scope>]
[FOR <condition 1>]
[WHILE <condition 2>]
[ASCENDING | DESCENDING]

<filename> | ?

The new table file to copy and sort the current table's records to. By default, dBASE for Windows assigns a .DBF extension to <filename> and saves the file in the current directory. The ? option displays a dialog box, in which you specify the name of the target file and the directory to save it in.

You can also create a table in a database (defined using the IDAPI Configuration Utility) by specifying the database as a prefix (enclosed in colons) to the name of the table, that is, :database name:table name. If the database is not already open, dBASE for Windows displays a dialog box, in which you specify the parameters, such as a login name and password, necessary to establish a connection to that database.

[TYPE] PARADOX | DBASE

Specifies the type of table you want to create. The TYPE keyword is included for readability only; it has no effect on the operation of the command.

Specifying DBASE creates a dBASE table (the default). If you do not include an extension for <filename>, dBASE for Windows assigns a .DBF extension.

Specifying PARADOX creates a Paradox table with a .DB extension.

ON <field 1>

Makes <field 1> the first field of <filename>and sorts <filename> records by the values in <field 1>, which can be any data type except binary, memo, or OLE.

/A

Sorts records in ascending order (A to Z; 1 to 9; past to future; false then true). Since this is the default sort order, include /A for readability only.

/D

Sorts records in descending order.

/C

Removes the distinction between uppercase and lowercase letters. When you specify both A and C, or both D and C, use only one forward slash (for example, /AC).

<field 2> [</A | /D> [/C]]  ...

Sorts on a second field so that the new table is ordered first according to <field 1>, then, for identical values of <field 1>, according to <field 2>. If a third field is specified, records with identical values in <field 1> and in <field 2> are then sorted according to <field 3>. The sorting continues in this way for as many fields as are specified.

<scope>

The number of records to copy from the current table to <filename> and sort. RECORD <n> identifies a single record by its record number. NEXT <n> identifies n records, beginning with the current record. ALL specifies all records. REST specifies all records from the current record to the end of the file.

FOR <condition 1>
WHILE <condition 2>

Determines which records are affected by SORT. FOR restricts SORT to records that meet <condition 1>. WHILE starts with the current record and continues with each subsequent record as long as <condition 2> is true.

ASCENDING

Sorts all specified fields for which you do not include a sort order in ascending order. Since this is the default, include ASCENDING for readability only.

DESCENDING

Sorts all specified fields for which you do not include a sort order in descending order.

Description

The SORT command creates a new table in which the records in the current table are positioned in the order of the specified key fields. Records marked for deletion are ignored if SET DELETED is ON.

When you use SORT, dBASE creates a temporary index file. During the sorting process, your disk must have space for this temporary index file and the new table file.

SORT differs from INDEX in that it creates a new table rather than provide an index to the original table. Although using SORT is generally not as efficient as using an index to organize tables, you might want to use SORT for the following applications:

To archive an outdated table and store it in a sorted order

To create a table that is a sorted subset of an original table

To maintain a small table that needs to be sorted in only one order

To create an ordered table where record numbers are sequential and contiguous

You might also want to sort a table according to the order of an index file that it commonly uses if the data in the table does not change frequently, since dBASE for Windows can access a table sorted in index order much faster than an unsorted table. In a table sorted in index order, sequential records are next to each other on the disk.


SORT Example

The following example uses SORT to make new tables:

USE Clients
SET DELETED ON
* remove the deleted records
SORT TO ClientC ON Company /C
USE ClientC
BROWSE FIELDS Company;
  TITLE "Sorted by Company, case ignored"

ClientC is sorted by Company ignoring upper- and lowercase.

USE Clients
SORT TO ClientP ;
  ON State_Prov , City /D, Company /DC;
  FOR Zip_postal = "9" TYPE PARADOX
* Sort:
*       State Ascending by default
*       City Descending
*       Company descending and ignoring case
*       Only Zip_postal codes beginning with 9
*       Creating a paradox table
SET DBTYPE TO PARADOX
USE ClientP
BROWSE;
  FIELDS Company, City, State_Prov, Zip_postal ;
  TITLE "Paradox file"
SET DBTYPE TO  && reset to dBASE


See Also

INDEX


SOUNDEX( )

See Also	Example	Portability	String Data

Returns a four-character string that represents the SOUNDEX (sound-alike) code of another string.

Syntax

SOUNDEX(<expC> | <memo field>)

<expC> | <memo field>

The string or memo field for which to calculate the soundex code. The string or memo can be any word or nonword that is a particular sound when spoken. The string or memo can also be more than one word or nonword with spaces between the words.

Description

SOUNDEX( ) returns a four-character code that represents the phonetic value of a character expression or memo field. The code is in the form "letter digit digit digit," where "letter" is the first alphabetic character in the expression being evaluated. The more phonetically similar two strings are, the more similar their SOUNDEX codes.

Use SOUNDEX( ) to find words that sound similar, or are spelled similarly, such as names like "Smith," "Smyth," and "Smythe." Using the U.S. language driver, these all evaluate to S531. You can index a table on the SOUNDEX( ) value of a field, then use FIND or SEEK with SOUNDEX( ) for names that users want to search for. For example, if a user wants to search for "Smith," convert "Smith" to SOUNDEX("Smith"), then search for that code in a table with a master index based on SOUNDEX(lastname). You can also use SOUNDEX( ) with LOCATE.

SOUNDEX( ) returns "0000" if the character expression or memo field is an empty string or if the first nonblank character is not a letter. SOUNDEX( ) returns 0's for the first digit encountered and for all following characters, regardless of whether they are digits or alphabetic characters.

To compare the SOUNDEX values of two character expressions or memo fields, use DIFFERENCE( ). If you want to compare the character-by-character similarity between two strings rather than the phonetic similarity, use LIKE( ).

SOUNDEX( ) is language driver-specific. For more information on language drivers, see Appendix C in the Programmer's Guide.

If the current language driver is U.S., SOUNDEX( ) does the following to calculate the phonetic value of a string:

Ignores leading spaces.

Ignores the letters A, E, I, O, U, Y, H, and W.

Ignores case.

Converts the first nonblank character to uppercase and makes it the first character in the SOUNDEX code.

Converts B, F, P, and V to 1.

Converts C, G, J, K, Q, S, X, and Z to 2.

Converts D and T to 3.

Converts L to 4.

Converts M and N to 5.

Converts R to 6.

Removes the second occurrence of any adjacent letters that receive the same digits as phonetic values.

Pads the end of the resulting string with zeros if fewer than three digits remain.

Truncates the resulting string to three digits if more than three digits remain.

Concatenates the first character of the code to the remaining three digits to create the "letter digit digit digit" soundex code.


SOUNDEX( ) Example

The following example uses SOUNDEX( ) to get a code value for the sound of each text string:

? SOUNDEX("bo")                    && Returns B000
? SOUNDEX("beau")                  && Returns B000
? SOUNDEX("bow")                   && Returns B000
? SOUNDEX("bow") = SOUNDEX("beau") && Returns .T.
? SOUNDEX("Conrad")                && Returns C563
? SOUNDEX("")                      && Returns 0000
? SOUNDEX("1BorlandWay")           && Returns 0000
? SOUNDEX("Go5ldenArches")         && Returns G000
? SOUNDEX("Gol5denArches")         && Returns G400

The next example uses SOUNDEX( ) when displaying the contents of a field:

USE Clients
? TRIM(City) + " returns a value of " +;
  SOUNDEX(City);
        && Returns "Atlanta returns a value of A345"
CLOSE DATABASES


Portability

Not supported in dBASE III PLUS. The <memo field> argument is not supported in dBASE IV.


See Also

DIFFERENCE( )

FIND

INDEX

LIKE( )

LOCATE

SEEK

SET EXACT


SPACE( )

See Also	Example	Portability	String Data

Returns a specified number of space characters.

Syntax

SPACE(<expN>)

<expN>

The number of spaces to return.

Description

SPACE( ) returns a character string composed of a specified number of space characters. The space character is ASCII code 32. The largest number of spaces you can specify is 32766, the maximum length of a string.

If <expN> is 0, SPACE( ) returns an empty string. If <expN> is less than 0, dBASE displays an error.

To create a string using a character other than space, use REPLICATE( ).


SPACE( ) Example

The following example uses SPACE( ) to initialize character memory variables of a specified length.

mCompany=SPACE(20)           && mCompany contains 20 spaces
STORE SPACE(20) TO mCompany  && same as above

The following example uses SPACE( ) to create spacing in output text. The example would return a trimmed city name, a comma and space, a two-letter State code, five spaces and the Zipcode.

USE Clients
SCAN
? Company
? Contact
? Address
? TRIM(City) + ", " + State_Prov + SPACE(5);
+ Zip_P_Code
?
ENDSCAN


Portability

Both dBASE IV and dBASE III PLUS limit the return value of SPACE( ) to 254 characters.


See Also

ASC( )

CHR( )

REPLICATE( )


SQLERROR( )

See Also	Example	Portability	Error Handling and Debugging

Returns the number of the last server error.

Syntax

SQLERROR( )

Description

Use SQLERROR( ) to determine the error number of the last server error. To learn the text of the error message itself, use SQLMESSAGE( ).

See the table in the description of ERROR( ) that compares ERROR( ), MESSAGE( ), DBERROR( ), DBMESSAGE( ), SQLERROR( ), SQLMESSAGE( ), and CERROR( ).

See Error Messages for a listing of all error messages.


SQLERROR( ) Example

The following example uses SQLERROR( ) and SQLMESSAGE( ) to return an SQL error number and SQL error message to an ON ERROR routine that displays a MDI form with an error report:

ON ERROR DO ErrHndlr WITH ERROR(), MESSAGE(), ;
  SQLERROR(), SQLMESSAGE(), PROGRAM(), LINENO()
SET DBTYPE TO DBASE
OPEN DATABASE CAClients
SET DATABASE TO CAClients
errorCode = SQLEXEC("SELECT Company, City FROM ;
  Company WHERE State_Prov='CA'", "StateCA.DBF")
IF errorCode = 0
  SET DATABASE TO
  USE StateCa
  LIST
ENDIF
RETURN

PROCEDURE ErrHndlr
PARAMETERS nErrorNo, cErrMess, nSQLErrorNo, ;
  cSQLErrMess, cProgram, nLineNo
DEFINE FORM HeadsUp FROM 10,20 TO 20,55;
  PROPERTY Text "Heads Up"
DEFINE TEXT Line1 OF HeadsUp AT 2,10 ;
  PROPERTY Text "An Error has occurred",;
  Width 24, ColorNormal "R+/W"
DEFINE TEXT Line2 OF HeadsUp AT 4,2;
  PROPERTY Text ;
  IIF(ERROR()=240,cSqlErrMess,cErrMess),;
  Width 33
DEFINE TEXT Line3 OF HeadsUp AT 5,2;
  PROPERTY Text "Number: " + ;
  IIF(ERROR()=240,STR(nSQLErrorNo),STR(nErrorno)),;
  Width 24
DEFINE TEXT Line4 OF HeadsUp AT 6,2;
  PROPERTY Text "Program: "+ cProgram,;
  Width 22
DEFINE TEXT Line5 OF HeadsUp AT 7,2;
  PROPERTY Text "Line #: " + STR(nLineno),;
  Width 22
OPEN FORM HeadsUp


Portability

Not supported in dBASE IV or dBASE III PLUS.


See Also

CERROR( )

DBERROR( )

DBMESSAGE( )

ERROR( )

MESSAGE( )

ON ERROR

RETRY

SQLMESSAGE( )


SQLEXEC( )

See Also	Example	Portability	Table Basics

Executes an SQL statement in the current database or on specified dBASE or Paradox tables.

Syntax

SQLEXEC(<SQL statement expC> [,<Answer table expC>] )

<SQL statement expC>

A character string that contains an SQL statement. The SQL statement must follow server-specific dialect rules for the current database and must be enclosed in quotes. For Paradox and dBASE tables, the dialect is the same as that used by the Borland InterBase database server, which is ANSI-compliant. Character strings and SQL or IDAPI reserved words contained within the SQL statement must also be enclosed in either single or double quotes. (Single quotes are normally used.)

<Answer table expC>

Paradox or dBASE table that stores the data returned by an SQL SELECT statement; must also be in quotes.If you specify a file without including its path, dBASE for Windows creates the file in the current directory, then in the path you specify with SET PATH. If you specify a file without including its extension, dBASE for Windows assumes the default table type specified with the SET DBTYPE command. If you do not specify a table name, dBASE for Windows creates a table named Answer with the extension defined by the current DBTYPE setting.

You can also specify the name of an already open database (defined for a file directory location only) as a prefix (enclosed in colons) to the name of the answer table, that is, :database name:table name. You cannot specify the location of an answer table on a database server.

Description

SQLEXEC( ) executes an SQL statement in the current database set by SET DATABASE, or if a database is not set, on tables in the current or a specified directory. (You can preface the name of a table with its directory location or specify an already open database by enclosing the database name in colons, for example, :database name:table name. If you are using Borland SQL Link to connect to a database server, dBASE for Windows passes the SQL statement you specify directly to the database server where the database selected by SET DATABASE resides.

When an SQL statement contains SQL or IDAPI reserved words and you are executing the statement on dBASE or Paradox tables, you need to enclose the reserved words in single (') or double (") quotes and use SQL table aliases (different than the aliases associated with dBASE tables) to identify fields, for example:

SELECT * FROM company.dbf b WHERE b.'CHAR' = 'element'

You can use table aliases to qualify fields specified in the SELECT, WHERE, GROUP BY, or ORDER BY clauses of SELECT statements. This is particularly useful when querying data from more than one table. SQLEXEC( ) returns error codes with the same values as those returned by ERROR( ) and MESSAGE( ); a value of zero indicates that no error occurred as a result of the statement's execution. If an error occurs, you can use DBERROR( ) and DBMESSAGE( ) functions to return IDAPI errors or use the SQLERROR( ) and SQLMESSAGE( ) functions to obtain information directly from the database server about the cause of an error. (Also, the ERROR( ) function returns an error code of 240 if a server error occurs.)


SQLEXEC( ) Example

The following example executes an SQL SELECT statement on the server table Company:

SET DBTYPE TO DBASE
OPEN DATABASE CAClients
SET DATABASE TO CAClients
errorCode = SQLEXEC("SELECT Company, City FROM ;
  Company WHERE State_Prov='CA'", "StateCA.DBF")
IF errorCode = 0
  SET DATABASE TO
  USE StateCa
  LIST
ENDIF
RETURN


Portability

Not supported in dBASE IV or dBASE III PLUS.


See Also

Using Local SQL

DBERROR( )

DBMESSAGE( )

ERROR( )

MESSAGE( )

OPEN DATABASE

SET DATABASE

SET DBTYPE

SET PATH

SQLERROR( )

SQLMESSAGE( )


SQLMESSAGE( )

See Also	Example	Portability	Error Handling and Debugging

Returns the most recent server error message.

Syntax

SQLMESSAGE( )

Description

Use SQLMESSAGE( ) to determine the error message of the last server error. To learn the error code, use SQLERROR( ).

See Error Messages for a listing of all error messages.


SQLMESSAGE( ) Example

See SQLERROR( ) for an example of using SQLMESSAGE( ).


Portability

Not supported in dBASE IV or dBASE III PLUS.


See Also

CERROR( )

DBERROR( )

DBMESSAGE( )

ERROR( )

MESSAGE( )

ON ERROR

RETRY

SQLERROR( )


SQRT( )

See Also	Example	Numeric Data

Returns the square root of a number.

Syntax

SQRT(<expN>)

<expN>

A positive number whose square root to return. If <expN> is a negative number, dBASE returns an error.

Description

SQRT( ) returns as a float the positive square root of a non-negative number. For example SQRT(36) returns 6 because 6^2=36. The square root of 0 is 0.

An alternate way to find the square root is to raise the value to the power of 0.5. For example, the following two commands return the same value:

? SQRT(36)	&& returns 6.00
? 36^.5	&& returns 6.00

Use SET DECIMALS to set the number of decimal places SQRT( ) displays.


SQRT( ) Example

The following example uses SQRT( ) to compute the length of a rafter after room width and rise to the peak have been entered by the user:

SET PROCEDURE TO PROGRAM(1) ADDITIVE
LOCAL f
f=NEW Rafter()
f.OPEN()
CLASS Rafter OF FORM
  this.Top=2
  this.Left=2
  this.Width=45
  this.Height=12
  this.Text = "Rafter Computer"
DEFINE ENTRYFIELD Room OF THIS AT 2,35;
  PROPERTY Picture "999",Value 0, Width 8
DEFINE ENTRYFIELD Rise OF THIS at 4,35;
  PROPERTY Picture "99",Value 0, Width 8
DEFINE ENTRYFIELD RaftLength OF THIS AT 6,35;
  PROPERTY Width 9, Value 0,;
    OnGotFocus Results
DEFINE TEXT Ln1 OF THIS AT 2,3;
  PROPERTY Text "Enter width of room:",;
    Width 25
DEFINE TEXT Ln2 OF THIS AT 4,3;
  PROPERTY Text "Enter height of rise:",;
    Width 25
DEFINE TEXT Ln3 OF THIS AT 6,3;
  PROPERTY Text "Cut rafter to this length:",;
    Width 30, ColorNormal "R/W"
DEFINE PUSHBUTTON Exit OF THIS AT 9,11;
  PROPERTY TEXT "Exit", OnClick {;Form.Close()}
ENDCLASS

FUNCTION Results
Form.RaftLength.Value=;
STR(SQRT(((Form.Room.Value/2)^2)+;
(Form.Rise.Value^2)),5,2)
RETURN .T.


See Also

EXP( )

LOG( )

LOG10( )

SET DECIMALS


STATIC

See Also	Example	Portability	Memory Variables

Declares local memory variables that you can use only in the subroutine where they are declared but whose values remain in memory until you exit dBASE.

Syntax

STATIC <variable 1> [ = <value 1> ] [,<variable 2> [ = <value 2> ] ... ]

<variable>

The variable to declare static.

<value>

The value to assign to the variable.

Description

Use STATIC to declare memory variables available only to a particular subroutine but public in memory duration. Static variables are different from other types of memory variables in two important ways:

You can declare and assign a value to a static variable in a single statement.

Static variables initialized in a single statement are assigned the initialization value only the first time the subroutine is run.

When you declare a variable STATIC in a subroutine--a program, procedure, or user-defined function (UDF)--that variable is visible only within that subroutine. It is not visible to higher- or lower-level subroutines. However, when the subroutine ends, the static variable remains in memory, with the value it had when the subroutine ended. If the subroutine is called again, the variable has the value it had when the subroutine last ended, and keeps that value until the subroutine changes it.

When you declare a variable STATIC without assigning it a value, dBASE creates the variable and assigns it the value .F.

Because static variables are not released when the subroutine in which they are created ends, you can use them to retain values for subsequent times that subroutine runs. To do this, declare and initialize the variable in a single statement, as shown below:

** subroutine mtest
STATIC mvar = 100

The first time dBASE encounters this statement, mvar is initialized to a value of 100. If the subroutine mtest is run again, mvar is not reinitialized to a value of 100. Instead, mvar retains whatever value it had when mtest last ended.

See PUBLIC for a table that compares the scope and availability of public, private, local, and static variables. See Chapter 5 in the Programmer's Guide for more information on initializing and retaining values of static variables.


STATIC Example

The following example branches from a main program to several lower-level procedures to demonstrate that STATIC variables are available only at the program level in which they are declared and that they hold that value even if the variable is changed in another procedural level:

* **Main.Prg***
CLOSE ALL
CLEAR ALL
CLEAR
SET TALK OFF
? "**Main.PRG**"
STATIC nTotal
PUBLIC cString
nTotal = 7109.50
cString= "Hello"
ON ERROR ? "Variable not available";
                      && Displays message on error
? nTotal              && Returns 7109.50
? cString             && Returns "Hello"
DO Primary            && Branch to Proc Primary
?
? "**Back to Main.PRG**"
? nTotal              && 7109.50-Still static value;
                         after return from lower;
                         level procedures

PROCEDURE Primary
?
? "**Proc Primary**"  && Orientation only
STATIC Deadline       && Var declared Static in;
                         Procedure Primary
? Deadline            && .F. because has no stored;
                         value
Deadline = {12/31/99} && Initialize variable
? Deadline            && Now it has a value
DO Proc1              && Branch to Proc1
RETURN                && Return to line after ;
                         DO Primary in Main

PROCEDURE Proc1
?
? "**Proc Proc1**"    && Orientation only
? cString             && "Hello" is Public
? nTotal              && "Var not available"-Static ;
                         in Main
? Deadline            && "Var not available"-Static ;
                         in Primary
Do Sub1               && Branch to Sub1
?
? "**Back to Proc1**"
? nTotal              && "Var not available"-Static ;
                         in another procedure
RETURN                && Return to last line of  ;
                         Primary

PROCEDURE Sub1
?
? "**Proc Sub1**"     && Orientation only
nTotal = 8801.11      && nTotal initialized to new ;
                         value but still a Static ;
                         variable
? nTotal              && 8801.11 - declared in ;
                         current proc
? cString             && "Hello" - Public variable
RETURN                && Return to line after ;
                         DO Sub1 in Proc1


Portability

Not supported in dBASE III PLUS or dBASE IV.


See Also

CLEAR MEMORY

DECLARE

LOCAL

PRIVATE

PUBLIC

RELEASE

STORE


STORE

See Also	Example	Portability	Memory Variables

Stores an expression to specified memory variables or array elements.

Syntax

STORE <exp> TO <memvar list> | <array element list>
or
<memvar> | <array element>  = <exp>

<exp>

The expression to store.

TO <memvar list> | <array element list>

Stores <exp> to the memory variable(s) of <memvar list> or to the array elements of <array element list>. You must DECLARE the array before using STORE.

<memvar> | <array element>  = <exp>

The single memory variable or array element to store <exp> to with the assignment operator (=). You must DECLARE the array before using =.

Description

Use STORE to store any valid expression to a single memory variable, to several memory variables, or to one or more array elements. Use = to store any valid expression to a single memory variable or a single array element. When <exp>is a field name, the contents of that field are stored. You can specify a field of any data type, including memo.

To specify the scope of a variable, use LOCAL, PRIVATE, PUBLIC, or STATIC before assigning a value to the variable. Memory variables are not linked to a particular session--only the scope of a variable determines its accessibility within an application.

When you issue STORE, dBASE does one of the following:

Creates a new memory variable and stores <exp> to it, or overwrites an existing memory variable with the same name and scope and stores <exp> to it. (You can use TYPE( ) to determine if a memory variable exists). The memory variable is assigned the same data type as <exp>. SET SAFETY has no effect on STORE commands.

Stores <exp> to the existing array element you specify. If the data type of the array element is different from that of <exp>, STORE changes the array element data type to match the data type of <exp>. You can also use AFILL( ) to store the same value to multiple elements in an array.

If you use STORE to create a variable with the same name as a field in the current table and later use the variable name in a command line, distinguish the memory variable by prefixing it with m->. This is shown in the following example.

** Current

 table has a field named "author"
STORE "Hugo" to author
? author	&& displays contents of field
? m->author	&& displays "Hugo"

You can use STORE or STORE MEMO to store a memo field. STORE stores a record's memo field, including carriage return(s) and linefeed(s), to a single memory variable or element of an array. STORE MEMO stores each line of a memo field to one element of an existing array.


STORE Example

The following example uses STORE to place four state abbreviations in four elements of a one-dimensional array named States and then uses a counting DO WHILE loop to retrieve records from the Clients table for the respective states stored in memory:

SET TALK OFF
SET SAFETY OFF
DECLARE States[4]
STORE "TX" TO States[1]
STORE "WA" TO States[2]
STORE "GA" TO States[3]
STORE "MN" TO States[4]
USE Clients EXCLUSIVE
INDEX ON Company Tag Company
CLEAR
Cnt = 1
? CENTER("Company Listing for "+States[1] ;
  +", "+States[2]+ ", "+States[3]+" and "  ;
  +States[4])
?
DO WHILE Cnt < 5
  SCAN FOR State_Prov = States[Cnt]
  ? Company AT 5, Contact, State_Prov
  ENDSCAN
  Cnt=Cnt+1
ENDDO
CLOSE ALL
SET TALK ON
SET SAFETY ON


Portability

Array element lists are not supported in dBASE III PLUS.


See Also

ACCEPT

AFILL( )

DECLARE

INPUT

LOCAL

PRIVATE

PUBLIC

RESTORE

SAVE

SET SAFETY

STATIC

STORE MEMO

WAIT


STORE AUTOMEM

See Also	Example	Portability	Fields and Records

Stores the contents of all the current record's fields to a set of memory variables.

Syntax

STORE AUTOMEM

Description

STORE AUTOMEM copies every field of the current record to a set of matching automem variables. Each memory variable has the same name, length, and data type as one of the fields. dBASE for Windows creates these memory variables if they do not already exist.

Automem variables let you temporarily store the data from table records, manipulate the data as memory variables rather than as field values, and then return the data to the table (using REPLACE AUTOMEM, APPEND AUTOMEM, or INSERT AUTOMEM).

STORE AUTOMEM is one of three commands that create automem variables. The other two, USE <filename> AUTOMEM and CLEAR AUTOMEM, initialize empty automem variables for the fields of the current table. Neither of these commands transfers data to the automem variables it creates, and the variables do not contain data until other commands store it to them. The empty variables created by USE...AUTOMEM and CLEAR AUTOMEM are typically used to append, insert, or replace data from outside the program, such as in a data entry form, into a table. STORE AUTOMEM transfers data from a table into automem variables.

Using memory variables in programming editing sequences gives you more control over data editing than using field values directly. When you specify a field as a GET argument in an @...SAY...GET line, after the field is edited using READ, dBASE for Windows returns the edited field directly to the table. When you use a memory variable as a GET argument, you can perform other operations on the edited variable, such as validating the data, before using REPLACE AUTOMEM to store the value back in the table.


STORE AUTOMEM Example

The following example uses STORE AUTOMEM to copy field values to a set of automem variables for records that are marked for deletion. The LOCATE command initiates a search for the first marked record and a DO WHILE .NOT. EOF( ) loop with a CONTINUE command copies all other marked records to Temp.DBF:

SET SAFETY OFF
SET DELETED OFF
CLOSE DATABASES
USE Clients IN 1
SELECT 1
COPY STRUCTURE TO Temp
USE Temp IN 2
LOCATE FOR DELETED()
  IF FOUND()
    DO WHILE .NOT. EOF()
      STORE AUTOMEM
      SELECT 2
      APPEND AUTOMEM
      SELECT 1
      CONTINUE
    ENDDO
    SELECT 2
    BROWSE
  ELSE
    ? "No records marked for Deletion"
  ENDIF
RETURN


Portability

Not supported in dBASE IV or dBASE III PLUS.


See Also

CLEAR AUTOMEM

REPLACE

USE


STORE MEMO

See Also	Example	Portability	Fields and Records

Stores the text of a memo field to an array-type memory variable.

Syntax

STORE MEMO <memo field> TO ARRAY <array name>

<memo field>

The memo field from which text is retrieved and stored in an array.

TO ARRAY <array name>

The array in which text from the memo field is stored. Each array element stores one line of text from the memo field. The length of each line can be up to the number of characters specified by SET MEMOWIDTH.

Description

Use STORE MEMO to store the text of memo fields to array memory variables. (STORE AUTOMEM lets you store the contents of the current record in automem variables for all types of fields except memo fields.) After editing the contents of the array elements that hold the contents of a memo field, use REPLACE MEMO to save the new values back in the memo field.

Initialize the array using the DECLARE command before using STORE MEMO. <array name> must be a one-dimensional array.

Make sure that you initialize arrays used with the STORE MEMO command so that they have enough elements to hold all the memo field text. If the memo field text exceeds the size of the array, dBASE for Windows truncates the text to fit the size of the array and the lines at the end of the memo field are lost when you use REPLACE MEMO. Make sure that the array has enough elements to hold the largest memo you plan to edit. You can use MEMLINES( ) to determine the number of elements you need for any particular memo field you have.

dBASE for Windows assigns the character type to each array element that holds memo field text. If the memo field text does not fill the array, the remaining array elements retain their original values (.F. as a default).


STORE MEMO Example

The following example uses STORE MEMO to place text from a memo field in an array_type memory variable:

SET TALK OFF
Colwidth = 50
Mwidth = SET("MEMOWIDTH")
SET MEMOWIDTH TO Colwidth
USE Company
DO WHILE .NOT. EOF()
CLEAR
Linecnt = 1
IF .NOT. ISBLANK(Notes)
  DECLARE Memoline[MEMLINES(Notes)]
  STORE MEMO Notes TO ARRAY Memoline
  DO WHILE Linecnt <= MEMLINES(Notes)
    @ Linecnt,12 GET memoline[linecnt]
     linecnt = linecnt + 1
  ENDDO
  READ
  replace_yn = "C"
  @ linecnt + 2,2 SAY "Do you want to Replace " + ;
  "the original text, Add to it, or Cancel? (R/A/C)";
  GET replace_yn PICTURE "!" ;
     VALID replace_yn $ "RAC"
  READ
  DO CASE
    CASE replace_yn = "R"
      REPLACE MEMO Notes WITH ARRAY Memoline
    CASE replace_yn = "A"
      REPLACE MEMO Notes ;
        WITH ARRAY Memoline ADDITIVE
    CASE replace_yn = "C"
      CLEAR
      EXIT
  ENDCASE
ENDIF
SKIP
ENDDO
CLOSE ALL
SET MEMOWIDTH TO Mwidth


Portability

Not supported in dBASE IV or dBASE III PLUS.


See Also

DECLARE

MEMLINES( )

MLINE( )

REPLACE MEMO

STORE


STR( )

See Also	Example	Portability	Expressions and Type Conversion

Returns the character string equivalent of a specified numeric expression.

Syntax

STR(<expN> [, <length expN> [, <decimals expN> [, <expC>]]])

<expN>

The numeric or float expression to return as a character string.

<length expN>

The length of the character string to return. The valid range is 1 to 20, inclusive, and includes a decimal point, decimal digits, and minus sign characters. The default is 10. If <length expN> is smaller than the number of integer digits in <expN>, STR( ) returns asterisks (*).

<decimals expN>

The number of characters to reserve for decimal digits. The default and lowest allowable value is 0. If you do not specify a value for <decimals expN>, STR( ) rounds <expN> to the nearest whole number. If you want to specify a value for <decimals expN>, you must also specify a value for <length expN>.

<expC>

The character to pad the beginning of the returned character string with when the length of the returned string is less than <length expN> digits long. The default pad character is a space. If you want to specify a value for <expC>, you must also specify values for <length expN> and <decimals expN>. You can specify more than one character for <expC>, but STR( ) uses only the first one.

Description

Use STR( ) to convert numeric data to character data, so you can manipulate it as characters. For example, you can index on a numeric field in combination with a character field by converting the numeric field to character with STR( ).

dBASE rounds and pads numbers to fit within parameters you set with <length expN> and <decimals expN>, following these rules:

If <decimals expN> is smaller than the number of decimals in <expN>, STR( ) rounds to the most accurate number that will fit in <length expN>. For example, STR(10.765,5,1) returns " 10.8" (with a single leading space), and STR(10.765,5,2) returns "10.77".

If <length expN> is not large enough for <decimals expN> number of decimal places, STR( ) rounds <expN> to the most accurate number that will fit in <length expN>. For example, STR(10.765,4,3) returns "10.8".

If <decimals expN> is larger than the number of decimals in <expN>, and <length expN> is larger than the returned string, STR( ) adds zeros (0) to the end of the returned string. dBASE only adds enough zero to bring the number of decimal digits to a maximum of <decimals expN>.

If the returned string is still shorter than <length expN>, dBASE pads the left to fill to the length of <length expN>. For example, STR(10.765,8,6) returns "10.76500" for a returned length of 8; STR(10.765,7,6) returns "10.7650"for a returned length of 7; and STR(10.765,12,6) returns "    10.765000" (with three leading spaces) for a returned length of 12.


STR( ) Example

The following example uses STR( ) to display the contents of a numeric field concatenated with a character string:

SET TALK OFF
USE Clients
SET FILTER TO StartBal > 0
* Selects only those records with positive StartBal
GO TOP
? StartBal                      && Returns 456.00
? "The starting balance was $" + ;
   STR(StartBal,8,2)            && Returns $  456.00
? "The starting balance can also be formatted as $" ;
   + LTRIM(STR(StartBal,8,2))   && Returns $456.00
? "Or format the starting balance as " + ;
   LTRIM(STR(StartBal,8,2,"$")) && Returns $$456.00


Portability

The <exp C> argument is not supported in dBASE IV or dBASE III PLUS.


See Also

SET POINT

SET SEPARATOR

SUBSTR( )

VAL( )


STUFF( )

See Also	Example	Portability	String Data

Returns a string with specified characters removed and others inserted in their place.

Syntax

STUFF(<target expC> | <target memo field>,
    	<start expN>, <quantity expN>, <replacement expC>)

<target expC> | <target memo field>

The string or memo field to remove characters from and replace with new characters.

<start expN>

The character position in the string or memo field at which to start removing characters.

<quantity expN>

The number of characters to remove from the string or memo field.

<replacement expC>

The characters to insert in the string or memo field.

Description

STUFF( ) returns a target character expression or target memo field with a replacement character string inserted at a specified position. Starting at the position you specify, <start expN>, STUFF( ) removes a specified number, <quantity expN>, of characters from the original string. STUFF( ) returns a maximum of 32766 characters, the maximum length of a string.

If the target character expression is an empty string or the target memo field is empty, STUFF( ) returns the replacement string.

If <start expN> is less than or equal to 0, STUFF( ) treats <start expN> as 1. If <quantity expN> is less than or equal to 0, STUFF( ) inserts the replacement string at position <start expN> without removing any characters from the target.

If <start expN> is greater than the length of the target, STUFF( ) does not remove any characters and appends the replacement string to the end of the target.

If the replacement string is empty, STUFF( ) removes the characters specified by <quantity expN> from the target, starting at <start expN>, without adding characters.


STUFF( ) Example

The following example uses STUFF( ) to change the text in a series of strings:

? STUFF("Jenson",5,1,"e")      && Returns "Jensen"
? STUFF("Johnson",6,0,"t")     && Returns "Johnston"
? STUFF("",2,5,"father")       && Returns "father"
? STUFF("rose",0,1,"n")        && Returns "nose"
? STUFF("rose",5,2,"bud")      && Returns "rosebud"
? STUFF("rosebud",5,3,"")      && Returns "rose"

The next example uses STUFF( ) to replace all occurrences of "&" with "and" in the Company field of Temp.DBF, which is a copy of the Clients table:

USE Clients
COPY TO TEMP
USE TEMP
SET TALK OFF
SCAN
  IF "&" $ Company
      REPLACE Company with ;
      STUFF(Company,AT("&",Company),1,"and")
  ENDIF
ENDSCAN
SET TALK ON
RETURN


Portability

The <memo field> argument is not supported in dBASE IV or dBASE III PLUS.


See Also

AT( )

LEFT( )

RAT( )

REPLICATE( )

RIGHT( )

SPACE( )

SUBSTR( )


SUBSTR( )

See Also	Example	Portability	String Data

Returns a substring derived from a specified character string or memo field.

Syntax

SUBSTR(<expC> | <memo field>, <start expN> [, <length expN>])

<expC> | <memo field>

The string or memo field to extract characters from.

<start expN>

The character position in the string or memo field to start extracting characters.

<length expN>

The number of characters to extract from the string or memo field.

Description

Starting in a character expression or memo field at the position you specify for <start expN>, SUBSTR( ) returns the number of characters you specify for <length expN>. SUBSTR( ) returns a maximum of 32766 characters, the maximum length of a string. If <length expN> is zero or a negative number, SUBSTR( ) returns an empty string.

If you do not specify <length expN>, SUBSTR( ) returns all characters starting from position <start expN> to the end of the string. If <length expN> is greater than the number of characters from <start expN> to the end of the string, SUBSTR( ) returns only as many characters as are left in the string, without adding space characters to achieve the specified length. You can use LEN( ) to determine the actual length of the returned string.

The following conditions cause dBASE to return an error:

<expC> is an empty string

<memo field> is empty

<start expN> is zero

<start expN> is a negative number

<start expN> is greater than the number of characters in <expC> or <memo field>

When SUBSTR( ) returns characters from a memo field, it counts two characters for each carriage-return and linefeed combination (CR/LF) in the memo field.

Use the substring operator ($) to learn if one string exists within another. See Language Definition for more information on operators.


SUBSTR( ) Example

The following examples use SUBSTR( ) to extract a portion of a text string:

? SUBSTR("Data",1)           && Returns "Data"
? SUBSTR("retrieval",7,3)    && Returns "val"
? SUBSTR("is",1,1)           && Returns "i"
? SUBSTR("made",3,1)         && Returns "d"
? SUBSTR("easy",1)           && Returns "easy"

SUBSTR( ) can be used for many ordering and data manipulation tasks. For example, to order a table by the first three numbers of a phone number (disregarding area code) when data is entered in a character field in the format "451-463-9000", create an index tag using SUBSTR( ).

USE COMPANY EXCLUSIVE
INDEX ON SUBSTR(Phone,5,3) TAG Phexch

To convert field data entered as uppercase to upper- and lowercase, use the following commands (field length = 20).

USE Address
REPLACE ALL Lname WITH;
  UPPER(SUBSTR(Lname,1,1))+LOWER(SUBSTR(Lname,2,19))

The previous example applies only to cases where a single name or text string resides in a field. If you want to capitalize all first letters of multiple strings in a field, use PROPER( ):

REPLACE ALL Lname with PROPER(Lname)


Portability

The <memo field> argument is not supported in dBASE III PLUS. Both dBASE IV and dBASE III PLUS limit the return value of SUBSTR( ) to 254 characters, and both return an error if <start expN> or <length expN> is zero or if <length expN> is a negative number.


See Also

AT( )

LEFT( )

LEN( )

PROPER( )

RAT( )

RIGHT( )

STUFF( )


SUM

See Also	Example	Table Organization

Computes a total for specified numeric and float fields in the current table and stores the results in memory variables or an array.

Syntax

SUM
[<exp list>]
[<scope>]
[FOR <condition 1>]
[WHILE <condition 2>]
[TO <memvar list> | TO ARRAY <array name>]

<exp list>

The numeric or float fields, expressions incorporating numeric or float fields, or expressions converting character fields to numeric or float values to sum.

<scope>

The number of records to sum. RECORD <n> identifies a single record by its record number. NEXT <n> identifies n records, beginning with the current record. ALL specifies all records. REST specifies all records from the current record to the end of the file.

FOR <condition 1>
WHILE <condition 2>

Determines which records are affected by SUM. FOR restricts SUM to records that meet <condition 1>. WHILE starts processing with the current record and continues with each subsequent record as long as <condition 2> is true.

TO <memvar list> | TO ARRAY <array name>

TO <memvar list> specifies a list of memory variables where you want to store totals. If <memvar list> includes array subscripts, the array(s) must already exist. TO ARRAY <array name> specifies an array in which you want to store totals.

Description

The SUM command totals the value of numeric expressions and stores the results in a list of memory variables or individual elements of an array. If SET TALK is ON, dBASE for Windows also displays results in the results pane of the Command window.

The number of memory variables specified must be exactly the same as the number of specified numeric expressions you want to total. The position of fields in <exp list> determines the order of values passed to <memvar list>. If you specify an array, it must be one-dimensional, and you must initialize individual elements before storing results in the array using the SUM command.

SUM is similar to TOTAL, which operates on an indexed or sorted table to create a second table containing the sums of the numeric and float fields of records grouped on a key expression.


SUM Example

The following example uses SUM to calculate the total of year-to-date sales of all companies:

USE Company
SUM Ytd_sales TO Ytd_sum
? "The total Ytd Sale was $", ;
   Ytd_sum PICTURE "99,999,999.99"

In this example there is no need to index the table, since every record must be read.


See Also

AVERAGE

CALCULATE

COUNT

TOTAL


SUSPEND

See Also	Example	Error Handling and Debugging

Suspends program execution, temporarily passing control to the Command window.

Syntax

SUSPEND

Description

SUSPEND lets you interrupt program execution at a specific point, a break point. The program remains suspended until you issue RESUME or CANCEL, or until you exit dBASE. If you issue RESUME, the program resumes from the break point. If you issue CANCEL, dBASE cancels program execution and clears it from memory. (CANCEL cancels all files called with DO, including ones that are suspended. You must close any procedure files with CLOSE PROCEDURE.)

While a program is suspended, you can enter commands in the Command window. For example, you can check and change the status of files, memory variables, SET commands, and so on; however, dBASE ignores any changes you make to the program while it is suspended. If you want to correct a suspended program, issue CANCEL, edit the program, and then run it again.

If you initialize memory variables in the Command window while a program is suspended, dBASE makes them private at the program level that suspension occurred.

You should not return to a suspended program by issuing DO <filename> in the Command window. If you do so, you might eventually run out of memory. You will also end up with "nested" SUSPEND statements, and may not know that a program is still suspended. If you want to run a suspended program from the beginning, issue CANCEL and then DO <filename>.


SUSPEND Example

The following program prompts the entry of a 2-letter state abbreviation and lists the clients within that state. If the program failsto return a list of clients, the programmer might insert the SUSPEND command just after the second CLEAR to halt the program so that trouble shooting commands could be issued at the Command window such as: ? mState to determine the value in the variable mState, LIST FOR STATE_PROV = "CA", DISPLAY MEMORY, DISPLAY STATUS. Issue the command RESUME when ready to proceed with the remainder of the program:

CLEAR
SET TALK OFF
USE CLIENTS
ACCEPT "Enter 2 letter State abbreviation: ";
  TO mState
CLEAR
SUSPEND                  && To be removed after ;
                            troubleshooting complete
? CENTER("Clients in "+UPPER(mState))
?
SCAN FOR State_Prov = UPPER(mState)
  ? Company, Contact, Startbal
ENDSCAN
RETURN


See Also

CANCEL

DO

RESUME

QUIT


TAG( )

See Also	Example	Portability	Table Organization

Returns the name of an .NDX file or .MDX file tag name.

Syntax

TAG( [<.mdx filename expC>,] <index number expN> [,<alias>] )

<.mdx filename expC>

The name of the multiple index file in which to look for a tag in the <index number expN> position.

<index number expN>

The number of the open .NDX file or index tag in the multiple index file whose name you want to return.

<alias>

A work area number (1 through 225), letter (A through J), or alias name. The work area letter or alias name must be enclosed in quotes.

Description

TAG( ) returns the name of an .NDX file or .MDX tag for the index specified by <index number expN>. The index number indicates the position of an index in the list of open indexes in the current or specified work area opened with the USE or SET INDEX commands. If no index number is specified, TAG( ) returns the name of the master index.

If you specify an .MDX file name, TAG( ) returns tag names that appear in the specified multiple index file. The order in which tag names are listed in the multiple index file determines the order in which TAG( ) returns tag names.

If you do not specify an .MDX file name, TAG( ) returns the tag name in the open index list and checks .NDX files first. TAG( ) next checks the production .MDX index tags and then other open .MDX files in the order you opened them.

If no index or tag exists in the specified position, TAG( ) returns an empty string ("").


TAG( ) Example

The following example uses TAG( ) to determine the names of index files open for the current table:

USE Company EXCLUSIVE
INDEX ON CompCode   TAG CompCode
INDEX ON Company    TAG Company
INDEX ON Zip_P_Code TAG Zip
* There are now at least 3 indexes in Company.mdx.
FOR i=1 TO TAGCOUNT()
  * TAGCOUNT() is the
  * total number of indexes in Company.mdx
  ? "Tag",i, TAG(i)
NEXT i


Portability

Not supported in dBASE III PLUS.


See Also

DBF( )

DISPLAY STATUS

KEY( )

MDX( )

NDX( )

ORDER( )

SET INDEX

SET ORDER

TAGCOUNT( )

TAGNO( )

USE


TAGCOUNT( )

See Also	Example	Portability	Table Organization

Returns the number of active indexes in a specified work area or .MDX multiple index file.

Syntax

TAGCOUNT( [<.mdx filename expC> [,<alias>]] )

<.mdx filename expC>

Specifies the multiple index file that contains the index tag you want to check. If you specify a file without including its path, dBASE for Windows looks for the file in the current directory, then in the path you specify with SET PATH. If you specify a file without including its extension, dBASE for Windows assumes an .MDX extension.

<alias>

A work area number (1 through 225), letter (A through J), or alias name. The work area letter or alias name must be enclosed in quotes.

Description

TAGCOUNT( ) returns the total number of open indexes or the number of index tag names in a specified .MDX file. TAGCOUNT( ) returns 0 if there are no indexes or index tags open for the current or specified work area, or if the multiple index file specified with <filename> does not exist. If you do not specify an .MDX file name, TAGCOUNT( ) returns the total number of indexes in the specified work area (.NDX files are included). If you do not specify an alias, TAGCOUNT( ) returns the total number of indexes in the current work area.


TAGCOUNT( ) Example

The following example uses TAGCOUNT( ) to determine the number of indexes open for the current table:

CLOSE ALL
USE Company IN SELECT() EXCLUSIVE
SELECT Company
INDEX ON CompCode TAG CompCode
INDEX ON Company  TAG Company
* Compcode and Company are in the production mdx
INDEX ON Zip_P_Code      TAG Zip      OF Location
* Zip is in Location.mdx
INDEX ON City     TO City
* City is in City.ndx
SET INDEX TO CITY, Location ORDER Zip
* There are now at least 2 tags in Company.mdx
* There is one in Location.mdx
* There is another index open in City.ndx
? "There are " + LTRIM(STR(TAGCOUNT())) + ;
   " active indexes in workarea "  + ;
   LTRIM(STR(WORKAREA()))
WAIT
DISPLAY STATUS


Portability

Not supported in dBASE III PLUS.


See Also

DBF( )

DISPLAY STATUS

KEY( )

MDX( )

NDX( )

ORDER( )

SET INDEX

SET ORDER

TAG( )

TAGNO( )

USE

WORKAREA( )


TAGNO( )

See Also	Example	Portability	Table Organization

Returns the index number of the specified index.

Syntax

TAGNO( [<tag name expC> [,<.mdx filename expC> [,<alias>] ] ] )

<tag name expC>

The name of the index tag that you want to return the position of. If you do not specify a tag name, TAGNO( ) returns the position of the master index.

<.mdx filename expC>

The name of the multiple index file that contains the specified index tag. If you do not specify an .MDX file name, TAGNO( ) returns the position of the tag name for all open index files in the same work area, including .NDX files at the top of the index list.

<alias>

A work area number (1 through 225), letter (A through J), or alias name. The work area letter or alias name must be enclosed in quotes.

Description

TAGNO( ) returns a number that indicates the position of the specified index name in the list of open indexes in the current or specified work area. The order of indexes is determined by the order in which they were opened with the USE or SET INDEX commands.

If you do not specify a tag name, TAGNO( ) returns the number of the master index. If you do not specify an .MDX file name, TAGNO( ) searches the list of open index files in the specified work area, including .NDX files. If you do not specify an alias, TAGNO( ) operates on the list of open indexes in the current work area.

TAGNO( ) returns an error if the specified index tag or .MDX file does not exist.


TAGNO( ) Example

The following example uses TAGNO( ) to determine the number of the specified index (.NDX) files:

USE Company EXCLUSIVE
INDEX ON CompCode   TO CompCode
INDEX ON Company    TO Company
INDEX ON Zip_Postal TO Zip
INDEX ON State_prov TO State_Prov
INDEX ON City       TO City
SET INDEX TO ;
  CompCode, Company, City, State_Prov, Zip
? TAG(),TAGNO()
* eg "COMPCODE"   8
? TAGNO("CompCode")  && e.g. 8
? TAGNO("Company")   && e.g. 1
? TAGNO("City")      && e.g. 6
? TAGNO("State")     && e.g. 3
? TAGNO("Zip")       && e.g. 11


Portability

Not supported in dBASE III PLUS.


See Also

DBF( )

DISPLAY STATUS

KEY( )

MDX( )

NDX( )

ORDER( )

SET INDEX

SET ORDER

TAG( )

TAGCOUNT( )

USE

WORKAREA( )


TAN( )

See Also	Example	Portability	Numeric Data

Returns the trigonometric tangent of an angle.

Syntax

TAN(<expN>)

<expN>

The size of the angle in radians. To convert an angle's degree value to radians, use DTOR( ). For example, to find the tangent of a 30-degree angle, use TAN(DTOR(30)).

Description

TAN( ) calculates the ratio between the side opposite an angle and the side adjacent to the angle in a right triangle. TAN( ) returns a float that increases from zero to plus or minus infinity. TAN( ) returns zero when <expN> is 0, pi, or 2*pi radians. TAN( ) is undefined (returns infinity) when <expN> is pi/2 or 3*pi/2 radians.

Use SET DECIMALS to set the number of decimal places TAN( ) displays.

The cotangent of an angle is the reciprocal of the tangent of the angle. To return the cotangent of an angle, use 1/TAN( ).


TAN( ) Example

The following examples use TAN( ) to return the tangent (in radians) of a defined angle:

SET DECIMALS TO 6
? TAN(PI())               && Returns  0.000000
? TAN(PI()/2)             && Returns infinity
? TAN(PI()/4)             && Returns  1.000000
? TAN(DTOR(150))          && Returns -0.577350
? TAN(DTOR(-150))         && Returns  0.577350


Portability

Not supported in dBASE III PLUS.


See Also

ATAN( )

ATN2( )

COS( )

DTOR( )

PI( )

RTOD( )

SET DECIMALS

SIN( )


TARGET( )

See Also	Example	Portability	Table Organization

Returns the name of a table linked to the current or specified work area.

Syntax

TARGET(<expN> [,<alias>] )

<expN>

Specifies the position of the relation in the SET RELATION list for the current or specified table that you want to determine the relation for.

<alias>

Specifies the work area from which you define a relation with the SET RELATION command. If you do not specify an alias for the work area, TARGET( ) assumes that the relation was set from the current work area. You can enter a work area number (1 through 225), letter (A through J), or alias name. The work area letter or alias name must be enclosed in quotes.

Description

TARGET( ) returns the name of a table that is linked to the table in the current or specified work area by relations defined with the SET RELATION command. If you do not specify an alias,TARGET( ) assumes the relation is set from the current work area. The TARGET( ) function returns an empty string ("") if no relation is set in the <expN> position of the SET RELATION list.


TARGET( ) Example

The following example uses TARGET( ) to determine the names of the child tables linked to Company in the following sample:

CLOSE DATABASE
USE Contact EXCLUSIVE
INDEX ON CompCode TAG CompCode
SELECT 2
USE Typeco EXCLUSIVE
SELECT Typeco
INDEX ON Type TAG Type
SELECT 3
USE Company
SET RELATION TO CompCode INTO Contact
SET RELATION TO Type     INTO Typeco ADDITIVE
?  "RELATION:",RELATION(1) , "TARGET:",TARGET(1)
* displays Compcode CONTACT
?  "RELATION:",RELATION(2) , "TARGET:",TARGET(2)
* displays Compcode TYPECO
select 20
? "TARGET:",TARGET(1,"Company")   && works from any work area
* displays CONTACT


Portability

Not supported in dBASE IV or dBASE III PLUS.


See Also

CREATE

CREATE VIEW...FROM ENVIRONMENT

DISPLAY STATUS

RELATION( )

SET( )

SET RELATION

SET VIEW


TEXT

See Also	Example	Portability	Input/Output

Displays the lines between TEXT and ENDTEXT as a block of text. This command is supported primarily for compatibility with dBASE IV. In dBASE for Windows, use DEFINE with the Text class to display text in forms.

Syntax

TEXT
<text characters>

ENDTEXT

<text characters>

The lines of text to display as a block.

Default

By default, output from TEXT goes to the screen. If you want the text to go to the printer or to a file, use SET PRINTER or SET ALTERNATE, respectively.

Description

Use TEXT to output blocks of text from a program. For example, you can use TEXT to display a brief description of a procedure that is about to begin. For text that will never change, TEXT is slightly easier than using ? or @ SAY commands to achieve the same result.

TEXT can display text in the Command window or in a dBASE IV window opened with ACTIVATE WINDOW. If the text line is wider than the width of the dBASE IV window to which you are outputting it, dBASE wraps the text to the next line. If the text contains more lines than fit in the current size of the dBASE IV window, dBASE scrolls the output when it reaches the last line of the window. TEXT does not wrap output going to the Command window.

Except for wrapping, dBASE displays the text exactly as in the program file; embedded macros are not expanded.


TEXT Example

The following example positions the cursor and then uses TEXT ... ENDTEXT to display a fixed block of text:

@ 2,0         && position cursor
TEXT

When you use the TEXT command, your
program displays your text at run time.
You do not need to use quotation marks to
delimit the text. You may enter as
many characters as you need.

ENDTEXT


Portability

In dBASE IV and dBASE III PLUS, a semicolon (;) at the end of a line is treated as text. In dBASE for Windows, it is treated as a line continuation character.


See Also

@...SAY...GET

?

??

ACTIVATE WINDOW

DEFINE

SET ALTERNATE

SET PRINTER


TIME( )

See Also	Example	Date and Time Data

Returns the system time as a character string in HH:MM:SS or HH:MM:SS.hh format.

Syntax

TIME([<exp>])

<exp>

Any expression, which causes TIME( ) to return the current time to the hundredth of a second.

Description

TIME( ) returns a character expression that is your system time. If you do not pass TIME( ) an expression, it returns the current system time in HH:MM:SS format, where HH is the hour, MM the minutes, and SS the seconds.

If you pass TIME( ) an expression, it returns the current system time in HH:MM:SS.hh, where .hh is hundredths of a second. The expression value you pass to TIME( ) has no effect on the time it returns other than to make it include hundredths of a second.


TIME( ) Example

See the example of SECONDS( ) for an example of TIME( ).


See Also

ELAPSED( )

SET TIME


TOTAL

See Also	Example	Table Organization

Creates a table that stores totals for specified numeric and float fields of records grouped by common key values.

Syntax

TOTAL ON <key expC> TO <filename> | ? | <filename skeleton>
[[TYPE] PARADOX | DBASE]
[<scope>]
[FOR <condition 1>]
[WHILE <condition 2>]
[FIELDS <field list>]

<key expC>

The key expression of the master index or the name of the field on which the current table has been sorted.

TO <filename> | ? | <filename skeleton>

Directs output to the dBASE table named <filename>. By default, dBASE for Windows assigns a .DBF extension to <filename> and saves the file in the current directory. The ?  and <filename skeleton> options display a dialog box, in which you specify the name of the target file and the directory to save it in.

You can also create a table in a database (defined using the IDAPI Configuration Utility) by specifying the database as a prefix (enclosed in colons) to the name of the table, that is, :database name:table name. If the database is not already open, dBASE for Windows displays a dialog box, in which you specify the parameters, such as a login name and password, necessary to establish a connection to that database.

[TYPE] PARADOX | DBASE

Specifies the type of table to create. The TYPE keyword is included for readability only; it has no effect on the operation of the command.

Specifying PARADOX creates a Paradox table with a .DB extension.

Specifying DBASE creates a dBASE table (the default). If you do not include an extension for <filename>, dBASE assigns a .DBF extension.

<scope>

The number of records to total. RECORD <n> identifies a single record by its record number. NEXT <n> identifies n records, beginning with the current record. ALL specifies all records. REST specifies all records from the current record to the end of the file.

FOR <condition 1>
WHILE <condition 2>

Determines which records are affected by TOTAL. FOR restricts TOTAL to records that meet <condition 1>. WHILE starts processing with the current record and continues with each subsequent record as long as <condition 2> is true.

FIELDS <field list>

Specifies which numeric and float fields to total. If you do not include FIELDS, dBASE totals all numeric and float fields.

Description

Use TOTAL to total the value of numeric fields in a table and create a second table to store the results. The numeric fields in the table storing the results contain totals for all records that have the same key value in the original table.

The current table must be either indexed or sorted on the key field. All records with the same key field become a single record in the table storing the result totals. All numeric fields appearing in the fields list contain totals. All other fields contain data from the first record of the set of records with identical keys.

TOTAL is similar to SUM, except that SUM operates on an indexed or unindexed table, returning a sum for all records of each numeric field. SUM does not create another table, but stores the results to memory variables or an array.


TOTAL Example

The following example uses TOTAL on the Company table to calculate the total of year to date sales in each state:

CLOSE DATABASE
USE Company  EXCLUSIVE
INDEX ON State_Prov TAG State
* First index Company table by State
* Index requires exclusive on
USE COMPANY SHARED
* TOTAL does not need exclusive on
TOTAL ON State_Prov TO StateTot
SELECT 2
USE StateTot
BROWSE FIELDS State_Prov, Ytd_sales;
  TITLE "Total sales per state"

StateTot contains one record per state.


See Also

AVERAGE

CALCULATE

COUNT

SUM


TRANSFORM( )

See Also	Example	String Data

Returns a string containing data in a specified format.

Syntax

TRANSFORM(<exp>, <picture expC>)

<exp>

The character, numeric, logical, or date expression to be formatted.

<picture expC>

The string containing the template characters necessary to format <exp>. The template characters are the same as those used in the PICTURE or FUNCTION option of ? and ??, the Function property of the Entryfield class, etc. Precede any FUNCTION template characters used with TRANSFORM( ) with an explicit @ symbol. For more information about the FUNCTION option, see Function.

Description

TRANSFORM( ) returns an expression in the PICTURE or FUNCTION format you indicate with <picture expC>. Use TRANSFORM( ) to format data when the command you are using allows expressions but does not include a PICTURE or FUNCTION option. For example, use TRANSFORM( ) to format data in report and label forms, and to format DISPLAY and LIST output. Such formatting includes aligning text and displaying numbers in scientific notation.


TRANSFORM( ) Example

The following example uses TRANSFORM( ) to print or display Startbal amounts with commas and Baldate in English format (day/month/year):

CLEAR
USE Clients  EXCLUSIVE
INDEX ON Company TO Comp
SET FIELDS TO Company, Startbal, Baldate
SCAN
  ? Company, TRANSFORM(Startbal,"999,999.99"),;
    TRANSFORM(Baldate,"@E");
* Display balance with commas and date in English format
ENDSCAN
CLOSE DATABASES


See Also

?

??

CLASS ENTRYFIELD


TRIM( )

See Also	Example	Portability	String Data

Returns a string with no trailing space characters.

Syntax

TRIM(<expC> | <memo field>)

<expC> | <memo field>

The string or memo field to remove the trailing space characters from.

Description

TRIM( ) returns a character expression or memo field with no trailing space characters. TRIM( ) returns a maximum of 32766 characters, the maximum length of a string. TRIM( ) is identical to RTRIM( ).

Using TRIM( ) with a memo field removes trailing spaces only at the end of the last line of the field. To remove trailing spaces from a particular line of a memo field, use LTRIM( ) with MLINE( ).

To remove leading space characters from a string or memo field, use LTRIM( ).


TRIM( ) Example

The following example uses TRIM( ) to remove trailing spaces from text in a character field:

USE Company
X = City + State + zip
? X
* Returns "Scotts Valley       CA        95066"
X=TRIM(City)+", "+TRIM(State)+SPACE(2)+ZIP
? X
* Returns "Scotts Valley, CA  95066"


Portability

The <memo field> argument is not supported in dBASE IV or dBASE III PLUS. Both dBASE IV and dBASE III PLUS limit the return value of TRIM( ) to 254 characters.


See Also

LEFT( )

LTRIM( )

MLINE( )

RIGHT( )

STR( )

SUBSTR( )


TYPE

See Also	Example	Portability	Disk and File Utilities

Display the contents of an ASCII file.

Syntax

TYPE <filename 1> | ? | <filename skeleton 1>
[MORE]
[NUMBER]
[TO FILE <filename 2> | ? | <filename skeleton 2> ] | [TO PRINTER]

<filename> | ? | <filename skeleton>

The file whose contents to display, also called the source file. TYPE ? and TYPE <filename skeleton> display a dialog box from which you can select a file. If you specify a file without including its path, dBASE looks for the file in the current directory, then in the path you specify with SET PATH. You must specify a file-name extension.

MORE

Pauses output when it fills the Command window; otherwise, the output scrolls through the Command window to the end of the file.

NUMBER

Precedes each line of output with its line number.

TO FILE <filename 2> | ? | <filename skeleton>

Directs output to the text file <filename 2>, also called the target file, as well as to the results pane of the Command window. By default, dBASE assigns a .TXT extension to <filename 2> and saves the file in the current directory. The ? and <filename skeleton> options display a dialog box in which you specify the name of the target file and the directory to save it in.

TO PRINTER

Directs output to the printer, as well as to the results pane of the Command window.

Description

Use TYPE to display, copy, or print the contents of ASCII files.

If you TYPE a file TO FILE or TO PRINTER, dBASE adds two lines of output at the beginning of the saved or printed output. The first line is a blank line, and the second line contains the full path name and date stamp of the source file. If you specify NUMBER, these two lines are not numbered; numbering begins with 1 at the first actual line of the source file. If you specify MORE and cancel output before completion, *** INTERRUPTED *** appears in the results pane of the Command window, but does not appear in the incomplete saved or printed output.

If SET SAFETY is ON and a file exists with the same name as the target file, dBASE displays a dialog box asking if you want to overwrite the file. If SET SAFETY is OFF, any existing file with the same name is overwritten without warning.


TYPE Example

The following examples use TYPE:

TYPE Results.txt
* Writes to the screen
TYPE Results.txt MORE
* Pauses at each screenful
TYPE Myfile.prg NUMBER
* Displays line numbers
TYPE Myfile.prg NUMBER TO FILE Myfile1.prg
* Writes with numbers to new file
TYPE Myfile.prg NUMBER TO FILE ?
* Opens dialog box for file name
TYPE Myfile.prg TO PRINTER
* prints Myfile.prg


Portability

Only a TO PRINT option is supported in dBASE III PLUS. The MORE, ?, and <filename skeleton> options are not supported in dBASE IV. If you don't specify a file extension with the TO FILE <filename> option, dBASE IV adds .PRT instead of .TXT.


See Also

COPY FILE

EJECT

SET ALTERNATE

SET PRINTER

SET SAFETY


TYPE( )

See Also	Example	Expressions and Type Conversion

Returns a character string that indicates a specified expression's data type.

Syntax

TYPE(<exp> | <expC>)

<exp> | <expC>

The expression whose type to evaluate and return.

Description

TYPE( ) can evaluate only character-based expressions. You can use <exp> (no quotes) only if you are evaluating a memory variable that contains either the name of a database field or character string that references an expression. Otherwise, use <expC> to evaluate a literal expression, a field name, or a memory variable.

For example, if your database has a field named "START," you can determine the type of this field in two ways. Either use TYPE("START"), or store the field name to a memory variable (STORE "START" TO mvar) and use TYPE(mvar).

A similar principle applies to memory variables that are not field names:

If you issue STORE "1+2=5" TO mvar, TYPE(mvar) returns L. This is because dBASE interprets TYPE(mvar) as "What type of expression does the character string contained in mvar represent?" The character string contained in mvar is "1+2=5", which is a logical expression, so dBASE returns L.

If you issue STORE "1+2=5" TO mvar, TYPE("mvar") returns C However, dBASE interprets TYPE("mvar") as "What type of data does the variable mvar contain?" Since "1+2=5" is a character string, dBASE returns C in this case.

Memory variables may also evaluate to other memory variables. For example, if you issue STORE 10 TO mnum and STORE "mnum" TO mvar, TYPE( mvar) returns N. Again, this is because dBASE evaluates TYPE(mvar) as "What type of expression does the character string contained in mvar represent?" The character string in mvar is "mnum," which represents a variable that contains the number 10, so dBASE returns N.

If you want to evaluate a memory variable that does not evaluate to a character string, you must use <expC>, as shown in the following example.

STORE DATE() TO mvar
? TYPE(mvar)   && returns an error because mvar does
               && not contain a character string.
? TYPE("mvar") && returnsD

TYPE( ) always returns a character string. The following table lists the values TYPE( ) returns.

If <exp> | <expC>contains this type of data	TYPE( ) returns
dBASE array variable	A
dBASE or Paradox binary field (BLOB)	B
dBASE bookmark variable	BM
dBASE character field or string variable, Paradox alphanumeric field	C
dBASE code block variable	CB
dBASE date field or variable, Paradox date field	D
dBASE float field, Paradox numeric or currency field	F
dBASE function pointer variable	FP
OLE (general)	G
dBASE logical field or variable	L
dBASE or Paradox memo field	M
dBASE numeric field or integer variable	N
dBASE object variable	O
dBASE SAVE SCREEN variable	S
dBASE or Paradox undefined variable, field, or invalid expression	U


TYPE( ) Example

The following examples use TYPE( ) to determine the data type of a specified expression.

USE Clients
? TYPE("Company")            && Returns C
? TYPE("BalDate")            && Returns D
? TYPE("StartBal")           && Returns N
mDate={12/31/99}             && date type variable
? TYPE("mdate")              && Returns D
? TYPE(mdate)                && Returns error message
mField = "Startbal"          && name of a field
? TYPE(mfield)               && Returns N
mStartbal=Startbal           && contents of a field
? TYPE(mStartbal)            && Returns error message
? TYPE("mStartbal")          && Returns F


See Also

EMPTY( )

ISBLANK( )

STORE


UNIQUE( )

See Also	Example	Portability	Table Organization

Indicates whether a specified index was created with the UNIQUE keyword (or with SET UNIQUE ON).

Syntax

UNIQUE([[<.mdx filename expC>,] <index position expN> [,<alias>]])

<.mdx filename expC>

Specifies a multiple index file that contains the index tag you want to check.

<index position expN>

Selects an index file or tag by the position of an index tag in an .MDX file or the position of an index file in the list of open indexes for the current or a specified table. The index position number specifies the position of the index within the list of open indexes as opened with the SET INDEX or USE commands.

<alias>

A work area number (1 through 225), letter (A through J), or alias name. The work area letter or alias name must be enclosed in quotes.

Description

The UNIQUE( ) function returns .T. if the index specified by the optional <index position expN> parameter was created with the INDEX...UNIQUE option, or INDEX with SET UNIQUE ON. If you do not specify an index number, UNIQUE( ) checks the master index or index tag for the current or specified work area.

The UNIQUE( ) function returns .F. when

The master index or the specified index or index tag number was not created with the INDEX...UNIQUE option or INDEX with UNIQUE set ON.

You do not include an index number and the current table does not have a master index.

No open index or index tag in the current or specified work area has the specified index number.

UNIQUE( ) returns an error if a specified index or filename does not exist.


UNIQUE( ) Example

The following example uses UNIQUE( ) to determine if the key for a specified index was created as a UNIQUE index:

USE Company EXCLUSIVE
INDEX ON CompCode TAG CompCode
SET ORDER TO TAG Compcode
? TAG(), "Unique = ", UNIQUE()
INDEX ON State_Prov TAG State OF Location UNIQUE
SET ORDER TO TAG State OF Location
? TAG(), "Unique = ", UNIQUE()
? TAG(1), "Unique = ", UNIQUE(1), MDX(1)
* UNIQUE can reference an index by position
* This is the first index of Company.mdx


Portability

Not supported in dBASE III PLUS.


See Also

DESCENDING( )

FOR( )

INDEX

KEY( )

MDX( )

NDX( )

ORDER( )

SET UNIQUE

TAG( )

TAGCOUNT( )

TAGNO( )

WORKAREA( )


UNLOCK

See Also	Example	Portability	Shared Data

Unlocks the current table if you locked it with FLOCK( ). Unlocks all records in the current table you locked with RLOCK( ) or LOCK( ).

Syntax

UNLOCK
[ALL | IN <alias>]

ALL

In all work areas, unlocks all tables you locked with FLOCK( ) and all records you locked with RLOCK( ) or LOCK( ).

IN <alias>

Unlocks the alias table <alias> if you locked it with FLOCK( ), or unlocks all of its records you locked with RLOCK( ) or LOCK( ). <alias> is a work area number (1 through 225), letter (A through J), or alias name. The work area letter or alias name must be enclosed in quotes. If you don't include <alias>, UNLOCK unlocks the current table.

Description

Use UNLOCK to unlock file locks you obtained with FLOCK( ), or to unlock record locks you obtained with RLOCK( ) or LOCK( ). Issue UNLOCK at the same workstation as the one at which you issued the FLOCK( ), RLOCK( ), and LOCK( ) functions. UNLOCK cannot release locks obtained through other workstations.

If you are browsing or editing a table, and the record pointer is on a record or an entry field representing a field in the table, pressing Ctrl+O toggles the current record between a locked and unlocked state. That is, if the record is locked, Ctrl+O unlocks it; if the record is unlocked, Ctrl+O locks it.

When you set a relation to a parent table with SET RELATION and then unlock the parent table or records in the parent table with UNLOCK, dBASE also unlocks related tables or records. For more information on relating tables, see SET RELATION.


UNLOCK Example

See FLOCK( ) for an example for UNLOCK.


Portability

Not supported in dBASE III PLUS.


See Also

FLOCK( )

RLOCK( )

SET RELATION


UPDATE

See Also	Example	Table Organization

Replaces data in the specified fields of the current table with data from another table.

Syntax

UPDATE ON <key exp> FROM <alias>
REPLACE <field 1> WITH <exp 1>
[, <field 2> WITH <exp 2> ... ]
[RANDOM]
[REINDEX]

<key exp>

The key expression that is common to both the current table and a table in a second work area.

FROM <alias>

Specifies a table open in another work area that provides updates to the current table.

REPLACE <field 1> WITH <exp 1>

Specifies the field in the current table to be updated with the table specified by FROM <alias>. If a field specified by WITH <exp1> is in a different work area from the current table, identify the field by its alias, for example, alias->field.

[ ,<field n> WITH <exp n> ...]

Specifies additional fields to be updated.

RANDOM

Specified when the updating table is neither indexed nor sorted. (Current table must be indexed on the key expression common to both tables.)

REINDEX

Specifies that all affected non-master indexes are rebuilt once the update operation finishes.

Description

The UPDATE command uses data from a specified table to replace field values in the current table. It makes the changes by matching records in the two files based on a single key field.

The current table must be indexed on the field in the key expression. Unless the RANDOM option is used, the table in the specified work area should also be indexed or sorted on the same field. Fields that are included in the key expression must have identical names in the two tables.


UPDATE Example

The following example uses UPDATE to recalculate the totals for each order in the Orders table from the LineItem table. UPDATE cannot look up multiple records, so LineItem is totalled on Order_No to a new table, LineTot, and Orders is updated from LineTot:

SET TALK ON
* to show the record counts
CLOSE ALL
USE ORDERS EXCLUSIVE
SELECT 2
USE LineItem
INDEX ON Order_no TAG Orders
TOTAL ON Order_no TO LineTot
USE LineTot
SELECT Orders
UPDATE ON Order_no FROM LineTot;
  REPLACE Tot_inv WITH LineTot->Total
* Only orders with lineitems will be updated.
* With Talk ON you will see the number of records
* that were updated.


See Also

APPEND FROM

JOIN

REPLACE

SELECT

SET RELATION


UPDATED( )

See Also	Example	Portability	Input/Output

Returns .T. (true) if you changed the contents of any @...GET fields or memory variables in the results pane of the Command window or the current dBASE IV window. This command is supported primarily for use with dBASE IV windows. In dBASE for Windows, use properties such as OnChange to manage changed information in forms.

Syntax

UPDATED( )

Description

UPDATED( ) returns .T. if any of the @...GET fields or memory variables in the results pane of the Command window or the current dBASE IV window have changed since you activated these @...GETs. To activate the @...GET fields or memory variables you have issued to appear in a window you have opened with ACTIVATE WINDOW, issue READ. If the @...SAY...GETs are in an open format file, you can issue APPEND, BROWSE [FORMAT], CHANGE, EDIT, or INSERT, as well as READ, to activate them in a window you have opened with ACTIVATE WINDOW.

When no @...GET field exists in the current window, the @...GET fields or memory variables haven't been activated, or when no @...GET field has been updated, UPDATED( ) returns .F.

Use UPDATED( ), for example, as part of a user-defined function (UDF) in the VALID or HELP clause of an @…SAY…GET to make the value the function returns depend on whether the user changes or adds data to the @...GET memory variable or field. See @...SAY...GET for a description of this command.


UPDATED( ) Example

In this example, after a READ, UPDATED( ) is used to determine whether any fields have been updated. If so, an update procedure is called. If not, no changes are made.

Name=space(20)
Address=space(20)
@ 5,5 SAY "Name" GET Name
@ 6,6 SAY "Address" GET Address
READ

IF UPDATED()
  DO UpdateProc
ENDIF


Portability

In dBASE III PLUS, @...GET fields just occur on the screen. In dBASE IV, @...GET fields can appear on the screen outside of windows and can occur in the context of a window opened with ACTIVATE WINDOW.


See Also

@...SAY...GET

ACTIVATE WINDOW

OnChange

READ

READKEY( )

READMODAL( )

SET FORMAT

VARREAD( )


UPPER( )

See Also	Example	Portability	String Data

Converts all lowercase characters in a string to uppercase and returns the resulting string.

Syntax

UPPER(<expC> | <memo field>)

<expC> | <memo field>

The character string or memo field to convert to uppercase.

Description

UPPER( ) converts the lowercase alphabetic characters in a character expression or memo field to uppercase. UPPER( ) ignores digits and other characters. UPPER( ) returns a maximum of 32766 characters, the maximum length of a string.

The current language driver defines the character values that are lowercase and uppercase alphabetic. In a U.S. language driver, a lowercase alphabetic character is from a to z, and an uppercase alphabetic character is from A to Z. See Appendix C in the Programmer's Guide for information about language drivers.


UPPER( ) Example

The following example uses UPPER( ) to convert lowercase text to uppercase when comparing two strings:

? UPPER("Technical")          && Returns "TECHNICAL"
? UPPER("Technical") = "Technical";
                              && Returns .F.
? UPPER("")                   && Returns ""
? UPPER("12 apples")          && Returns "12 APPLES"

UPPER( ) is frequently used to ensure that character data matches for various comparisons. The following example uses UPPER( ) to ensure a match during a SEEK:

SET EXACT OFF
USE Animals EXCLUSIVE
INDEX ON UPPER(Name) TAG Name
mSearch="Boa"
SEEK UPPER(msearch)
IF FOUND()
    EDIT
ENDIF
RETURN


Portability

The <memo field> argument is not supported in dBASE IV or dBASE III PLUS.


See Also

CHARSET( )

ISALPHA( )

ISLOWER( )

ISUPPER( )

LDRIVER( )

LOWER( )

PROPER( )

SET LDCHECK


USE

See Also	Example	Table Basics

Opens the specified table, associated memo (.DBT) files, and production index (.MDX) files, if any.

Syntax

USE
[<filename 1> | ? | <filename skeleton 1>
[ [TYPE] PARADOX | DBASE]
[IN <alias>]
[INDEX <index name list> |
<? list> | <index name skeleton list>]
[ORDER [TAG] <.ndx filename> |
<tag name> [OF <.mdx filename>]]
[AGAIN]
[ALIAS <alias name>]
[AUTOMEM]
[EXCLUSIVE | SHARED]
[NOSAVE]
[NOUPDATE]]

<filename 1> | ? | <filename skeleton 1>

The table file you want to open. USE ? and USE <filename skeleton 1> displays a dialog box, from which you can select a table file. If you specify a file without including its path, dBASE for Windows looks for the file in the current directory, then in the path you specify with SET PATH. If you specify a file without including an extension or specifying its type, dBASE for Windows assumes the file type specified with the SET DBTYPE command.

You can also open a table in a database (defined using the IDAPI configuration utility) by specifying the database as a prefix (enclosed in colons) to the name of the table, that is, :database name:table name. If the database is not already open, dBASE for Windows displays a dialog box in which you specify the parameters, such as a login name and password, necessary to establish a connection to that database.

[[TYPE] PARADOX | DBASE]

Specifies the type of table to open. The TYPE keyword is included for readability only; it has no effect on the operation of the command.

Specifying PARADOX opens a Paradox table with a .DB extension.

Specifying DBASE opens a dBASE table (the default). If you do not include an extension for <filename>, dBASE for Windows assumes a .DBF extension.

IN <alias>

Specifies a work area. You can enter a work area number (1 through 225), letter (A through J), or alias name. The work area letter or alias name must be enclosed in quotes.

INDEX <.index name list> | <? list> | <index name skeleton list>

Applicable to dBASE indexes only. (Indexes on Paradox and SQL tables are specified by the ORDER clause.) Opens up to 100 individual index files for the specified table. <index name list> can include single (.NDX) and multiple index file (.MDX) names. If the first file in <index name list> is a single index file, and you do not use the ORDER option, the single index file becomes the master index. INDEX <? list> and INDEX <index name skeleton list> displays a dialog box, from which you can choose an existing index file.

ORDER [TAG] <tag name>

Makes the <tag name> index file the master index. When opening a Paradox table, you may specify a secondary index as the master index; otherwise, the PRIMARY index is used. When opening an SQL table, you can also specify an index to use as the master index.

If you do not include the ORDER clause and the first file name after INDEX is a single index .NDX file, the single index file is the master index. If you do not include ORDER and the first file name after INDEX is a multiple index .MDX file, the table does not use a master index.

OF <.mdx filename>

The multiple index file that includes <tag name>. Without OF <filename>, dBASE searches for <tag name> in a multiple index file with the same root name as the table.

ORDER [TAG] <.ndx filename>

Makes the single index file, <.ndx filename>, the master index.

AGAIN

Opens a table and its related index files in the current or specified work area, leaving the table open in one or more other work areas.

ALIAS <alias name>

Specifies an alternate alias name for the current work area. The default alias name is the table name unless you use the AGAIN option.

AUTOMEM

Initializes a memory variable for each field of the specified table (not including memo, binary, or OLE types). The memory variables are assigned the same names and types as the fields.

EXCLUSIVE | SHARED

EXCLUSIVE opens the table so that no other users can open the table until you close it; SHARED allows other users access while the table is opened. The default setting depends on whether you are accessing tables in a shared environment or the LOCALSHARE setting in a single-user environment.

NOSAVE

Used to open a .DBF file as a temporary table. When you close a file opened with NOSAVE, it is erased along with its associated memo file. If you inadvertently open a table with the NOSAVE option, use COPY TO to save the data.

NOUPDATE

Prevents users from altering, deleting, or recalling any records in the table.

Description

The USE command opens an existing table, production (.MDX) index file, and associated .DBT file if the table contains binary, memo, or OLE fields). Optionally, USE also opens any associated .NDX or non-production .MDX index files that you specify. You need to open a table before you can access any data stored in the table.

USE with no other argument closes the open table, indexes, and format file in the current work area. USE IN <alias>, with no file name argument, closes the table and related files in the specified work area. CLOSE TABLES closes tables in all work areas.

You can open a table in any available work area. When opening a table, you can name the work area by including the ALIAS option in the USE command line. ALIAS names follow the same rules as file names. Aliases are used when referring to a table from another work area.

USE...INDEX specifies index files that are opened and maintained for a particular table. The ORDER option specifies the master index from the list of indexes opened with the INDEX option and the production .MDX index. USE...INDEX is identical to USE followed by SET INDEX. See the SET INDEX and SET ORDER commands for an explanation of the open index order and specifying a master index.

You can include .NDX as well as .MDX index file names with the INDEX option. If a table has an .NDX and an .MDX index file with the same name, dBASE for Windows opens indexes listed in the .MDX index file. In that case, to open the single index you would need to specify its full name, including its extension.

Use the NOSAVE option of USE to open a table as a temporary file. dBASE for Windows automatically erases the table, along with the associated memo and index files listed previously, when you close the table.

The AUTOMEM option, which creates memory variables for all fields of the table (excluding binary, memo, and OLE type fields), initializes the memory variables according to the data type in the field as follows:

Character	All blanks
Float	0
Numeric	0
Logical	.F.
Date	/  /
USE...AUTOMEM lets you create memory variables corresponding to fields in a table for updating data values in an application program. See the APPEND AUTOMEM and STORE AUTOMEM for more information on using automem variables.


USE Example

The following example demonstrates USE to open Flights and Aircrdb tables ordered by an .MDX tag in the next two available work areas:

CLOSE DATABASES
USE Flights ORDER Aircraft EXCLUSIVE IN SELECT()
USE Aircrdb IN SELECT()
SELECT Aircrdb
SET RELATION TO Aircraft INTO Flights

The following example opens the Clients table and automatically creates memory variables from each of the field values:

SELECT 1
USE Clients ORDER Company AUTOMEM EXCLUSIVE
DISPLAY MEMORY TO PRINT
* Displays memory variables created with AUTOMEM
* from Clients table.
CLOSE DATABASES

The following example opens a Paradox table:

USE Customer TYPE PARADOX
BROWSE
CLOSE DATABASES


See Also

ALIAS( )

APPEND AUTOMEM

CLEAR AUTOMEM

CLOSE...

SELECT

SELECT( )

SET INDEX

SET ORDER

STORE AUTOMEM


VAL( )

See Also	Example	Expressions and Type Conversion

Returns a specified character string as a numeric or float value.

Syntax

VAL(<expC>)

<expC>

The character expression to return as a numeric or float value, or the character expression beginning with the number to return as a numeric or float value.

Description

Use VAL( ) to convert character expressions to numbers of numeric or float type. Once you convert character data to numeric or float data, you can perform arithmetic operations with it.

If the character string you specify contains both letters and numbers, VAL( ) returns the value of the entire number to the left of the first nonnumeric character. If the string contains a nonnumeric character other than a blank space in the first position, VAL( ) returns 0. For example, VAL("ABC123ABC456") returns 0, VAL("123ABC456ABC") returns 123, and VAL("  123") also returns 123.


VAL( ) Example

The following examples use VAL( ) to return the numeric value of a character string, variable or field.

SET TALK OFF
? VAL("123AB34")             && Returns 123
? VAL("-32")                 && Returns -32
Strng1 = "BAY672"
? VAL(Strng1)                && Returns 0
Strng2 = "345 Alcott Lane"
? VAL(Strng2)                && Returns 345

**FldDemo.Prg**
Strng2 = "345 Alcott Lane"
USE Clients ORDER Company
SEEK "Brown Designs"
IF FOUND()
   REPLACE ADDRESS WITH Strng2
ENDIF
? VAL(Address)               && Returns 345
SET TALK ON
CLOSE ALL
** End FldDemo.PRG**

The following example uses VAL( ) to convert character data in the Zip_P_Code field to numeric type to filter only those records in the western region of Clients table.

SET TALK OFF
USE Clients EXCLUSIVE
INDEX ON Zip_P_Code TAG ZIP
SET FILTER TO VAL(Zip_P_Code)>80000
GO TOP
? CENTER("Phone List")
? CENTER("Western Region")
?
SCAN
  ? Company, Contact, Areacode, Phone, Extension
ENDSCAN
CLOSE ALL
SET TALK ON
RETURN


See Also

SET DECIMALS

SET POINT

SET SEPARATOR

STR( )


VALIDDRIVE( )

See Also	Example	Portability	Disk and File Utilities

Returns .T. if the specified drive exists and can be read. Returns .F. if the specified drive does not exist or cannot be read.

Syntax

VALIDDRIVE(<drive expC>)

<drive expC>

Drive letter of the drive to be tested, optionally followed by a colon. If you specify more than one letter in <drive expC>, dBASE evaluates only the drive represented by the first letter.

Description

Use VALIDDRIVE( ) to determine if a specified drive exists and is ready before using CD, SET DEFAULT, SET DIRECTORY or SET PATH. VALIDDRIVE( ) is also useful if your program copies files to or from a drive, or includes drive letters in any file names.

VALIDDRIVE( ) can verify any drive specified, including drives created by partitioning a hard disk and network drives.


VALIDDRIVE( ) Example

The following examples use VALIDDRIVE( ):

? VALIDDRIVE("C:")  && .T.
? VALIDDRIVE("A:")  && .T. if A drive has floppy ready
* .T. if A drive has floppy ready
? VALIDDRIVE("Z:")  && .T. if Z drive exists

In the following example, VALIDDRIVE( ) checks a floppy drive, the B drive. If VALIDDRIVE( ) returns false then the user is asked to insert a floppy disk. This code will loop three times.

K=1      && set up a counter
DO WHILE .NOT. VALIDDRIVE("B:") .AND. K<=3
  WAIT "Put a disk in drive B and press any key"
  K=K+1  && increment the counter
ENDDO


Portability

Not supported in dBASE IV or dBASE III PLUS.


See Also

CD

SET DEFAULT

SET DIRECTORY

SET PATH


VARREAD( )

See Also	Example	Portability	Input/Output

Returns the name of the current memory variable or field when you issue READ after @…GET. This command is supported primarily for compatibility with dBASE IV. In dBASE for Windows, use the Name property to identify an object in a form.

Syntax

VARREAD( )

Description

VARREAD( ) returns the name of the memory variable or field in the current @...GET in the Command window or the current window after you have activated the @...GETs. To activate the @...GET fields or memory variables you have issued to appear in a window you have opened with ACTIVATE WINDOW, issue READ. If the @...SAY...GETs are in an open format file, you can issue APPEND, BROWSE [FORMAT], CHANGE, EDIT, or INSERT, as well as READ, to activate them in a window you have opened with ACTIVATE WINDOW.

When no @...GET field exists in the current window or when the current @...GET field is not activated, VARREAD( ) returns an empty string ("").

Use VARREAD( ), for example, with a user-defined function (UDF) that is the argument of a HELP option in an @…GET command. VARREAD( ) in this situation determines which GET field the cursor is currently in when F1 is pressed.


VARREAD( ) Example

In this example, VARREAD( ) and READVAL( ) operate within a function, SHOWVAL( ), which is the VALID clause for both GET fields in a READ operation:

Name=space(20)
Address=space(20)
@ 5,5 SAY "Name" GET Name;
  VALID REQUIRED SHOWVAL()
@ 6,6 SAY "Address" GET Address;
  VALID REQUIRED SHOWVAL()
READ

FUNCTION SHOWVAL
@ 10,0 SAY ;
  "The current read variable is "+VARREAD()
@ 12,0 SAY ;
  "The current read variable value is "+READVAL()
WAIT
RETURN .t.


Portability

In dBASE III PLUS, @...GET fields do not occur in windows, just on the screen. In dBASE IV, @...GET fields can appear on the screen outside of windows and can occur in the context of a window opened with ACTIVATE WINDOW.


See Also

@...SAY...GET

ACTIVATE WINDOW

READ

READKEY( )

READMODAL( )

SET FORMAT

UPDATED( )


VERSION( )

See Also	Example	Environment

Returns a character string that is the name and version number of the currently running version of dBASE.

Syntax

VERSION( )

Description

Use VERSION( ) in programs that use features specific to different versions of dBASE. For example, you can use VERSION( ) to learn what version of dBASE is in use and then execute code specific to that version.


VERSION( ) Example

The following example tests if the user is running dBASE for Windows:

IF "WINDOW"$UPPER(VERSION())
* Does "WINDOW" occur in the version name?
  ? "Running Windows"  && Yes
ELSE
  * User is not running a Windows version of dBASE
  WAIT "You must have dBASE for Windows"+;
    "to run this program"
ENDIF


See Also

OS( )


WAIT

See Also	Example	Input/Output

Pauses the current program, optionally accepts a single character as data input, and continues execution when any key is pressed. This command is supported primarily for compatibility with dBASE IV. In dBASE for Windows, WAIT is useful only if you are sending output to the results pane of the Command window and want to pause at particular points.

Syntax

WAIT
[<prompt expC>]
[TO <memvar>]

<prompt expC>

A character expression that prompts the user for input.

TO <memvar>

Assigns a single character to the memory variable you specify for <memvar> as a character-type variable. If <memvar> does not exist, dBASE creates it. If <memvar> does exist, WAIT overwrites it.

Default

If you don't specify <prompt expC>, dBASE displays "Press any key to continue" when you issue WAIT.

Description

Use WAIT to halt program execution temporarily (for example, to display data without enabling editing). Pressing any key exits WAIT and resumes program execution.

Note

If SET ESCAPE is ON, pressing Esc at the WAIT prompt causes dBASE to interrupt program execution. If SET ESCAPE is OFF , pressing Esc in response to WAIT causes program execution to resume the same as any other key.

Although you use WAIT primarily to pause a program until the user presses a key, you can also use it to store the pressed key to a character memory variable. If the user presses Enter without typing any characters, WAIT assigns an empty string ("") to <memvar>.


WAIT Example

Wait can be used without a prompt or an input variable:

WAIT

The default prompt then appears on the next row, in column 0:

* Press any key to continue ...

The following example shows WAIT with a prompt:

WAIT "Press any key to move to the next screen"

This examples shows WAIT with a prompt and input variable:

WAIT;
  "Do you wish to print the report (Y/N)? ";
   to Answer


See Also

SET ESCAPE


WINDOW( )

See Also	Example	Portability	dBASE IV Windows

Returns the name of the active dBASE IV-style window. This command is supported primarily for compatibility with dBASE IV. In dBASE for Windows, use INSPECT( ) to return information associated with forms.

Syntax

WINDOW( )

Description

Use WINDOW( ) to obtain the name of the active window, which is the window that currently has input focus.

When multiple windows are open, input focus is determined by

The order in which the windows or forms are opened; the window last opened is the active window.

The order in which windows were listed in the ACTIVATE WINDOW command that opened them; the window listed last receives input focus first.

The window name is returned as an uppercase string. If no window is active or open, WINDOW( ) returns an empty string.


WINDOW( ) Example

The following example opens three tiled windows, browses two fields of the Contact table in Window C and uses WINDOW( ) to return the currently active window name to a memory variable for later recall:

SELECT A
USE COMPANY
SELECT B
USE CONTACT
CLEAR
DEFINE WINDOW A FROM 1,1 TO 15,40 DOUBLE
DEFINE WINDOW B FROM 5,5 TO 18,60 DOUBLE
DEFINE WINDOW C FROM 10,10 TO 23,50 DOUBLE
ACTIVATE WINDOW A,B,C
CurrWin=WINDOW()
BROWSE FIELDS COMPCODE, CONTACT
DEACTIVATE WINDOW C        && Cleared from screen
SELECT A
BROWSE FIELDS COMPANY, YTD_SALES
DEACTIVATE WINDOW B        && Cleared from screen
WAIT "Window A remains open - press any key"
DEACTIVATE WINDOW ALL      && Windows still in memory
ACTIVATE WINDOW &CurrWin   && Window C back again
?
WAIT "Window C returns - press any key"
CLEAR WINDOWS              && Cleared from memory
CLEAR                      && Clear screen
RETURN


Portability

Not supported in dBASE III PLUS.


See Also

DEFINE

INSPECT( )


WORKAREA( )

See Also	Example	Portability	Table Basics

Returns a number representing the currently selected work area.

Syntax

WORKAREA( )

Description

The WORKAREA( ) function returns the number of the currently selected work area. Use WORKAREA( ) in a program to save the current work area number and then later restore that work area using the SELECT command.


WORKAREA( ) Example

See DBF( ) and SELECT( ) for an examples of using WORKAREA( ).


Portability

Not supported in dBASE IV or dBASE III PLUS.


See Also

DBF( )

SELECT

SELECT( )


YEAR( )

See Also	Example	Date and Time Data

Returns the year of a specified date expression as a 4-digit number.

Syntax

YEAR(<expD>)

<expD>

The date expression, in the current date format, whose corresponding year number to return.

Description

YEAR( ) returns a date's 4-digit year number. The SET CENTURY setting has no effect on YEAR( ).

Enter <expD> in the current date format as determined by SET DATE, DBASEWIN.INI, or the International option of the Windows Control Panel (in that order). That is, SET DATE settings override those in DBASEWIN.INI, and settings in DBASEWIN.INI override those in the Windows Control Panel. Be sure <expD> matches the date format in use when your program runs.

If you pass an invalid date to YEAR( ), dBASE converts the date to a valid one and returns the 4-digit year of that date. If you pass an empty or non-date expression delimited with braces ({ }) to YEAR( ), it returns 0. If you pass a non-date expression or an expression that is not delimited with braces to YEAR( ), it returns an error.

You can use STR(YEAR( )) to index on a date field in combination with a character field.


YEAR( ) Example

See the example of CMONTH( ) for the use of YEAR( ).


See Also

DATE( )

DAY( )

DOW( )

MONTH( )

SET CENTURY

STR( )


ZAP

See Also	Example	Fields and Records

Removes all records from the current table.

Syntax

ZAP

Description

ZAP is the fastest way to delete all records from a table. DELETE ALL, followed by PACK, also deletes all records from a table. Using ZAP requires a table be opened exclusively.

When SET SAFETY is ON and you issue ZAP, dBASE for Windows displays a warning message asking you to confirm the operation before removing records.


ZAP Example

The following example uses ZAP to permanently remove all records from the current table:

USE Clients
SET TALK OFF
SET SAFETY ON
COPY TO TEMP
USE TEMP EXCLUSIVE
zap_yn = "N"
ACCEPT "Do you want to remove all records? (Y/N)" ;
  TO zap_yn
READ
IF UPPER(zap_yn) = "Y"
   ZAP
? "All records have been removed from " + ;
   ALIAS()
ENDIF
CLOSE ALL
SET TALK ON


See Also

DELETE

PACK

SET SAFETY


ActiveControl

See Also	Properties	Forms

Contains a reference to the object that currently has focus.

Property of Class

FORM

Data Type

Object reference

Description

Use the ActiveControl property to reference the object that currently has focus.

An object gets focus in three ways:

The user tabs to the object.

The user clicks the object.

The SetFocus( ) method of the object is executed.

Use ActiveControl to find out which object currently has focus and make branching decisions accordingly. For example, the following command looks at the Name property of the current object:

? MyForm.ActiveControl.Name

You can also use ActiveControl to access or change a property of the object with focus. For example, the following command disables whatever object currently has focus:

MyForm.ActiveControl.Enabled =.FExample

The following example uses ActiveControl and NextObj to return the name of the current and next entry field objects when the right mouse is clicked on a form. This would be useful on a form where entry fields had no accompanying text to identify the fields:

LOCAL f
f=NEW EntryForm()
f.OPEN()
CLASS Entryform OF FORM
  this.View="Company.DBF"
  this.OnRightMouseDown={;Fcs="Current Field: " + ;
    Form.ActiveControl.Name; Form.Txt1.Text=Fcs}
  this.OnRightMouseUp={;Fcs2="Next Field:     " + ;
    Form.NextObj.Name; Form.Txt2.Text=Fcs2}
DEFINE ENTRYFIELD Company OF THIS;
  PROPERTY Datalink "Company->Company",;
  Top 3, Left 1, Width 20, Name "Company"
DEFINE ENTRYFIELD State OF THIS;
  PROPERTY Datalink "Company->State_Prov",;
  Top 5, Left 1, Name "State"
DEFINE TEXT Txt1 OF THIS;
  PROPERTY Text " ",;
  Top 8, Left 1, Width 25
DEFINE TEXT Txt2 OF THIS;
  PROPERTY Text " ",;
  Top 9, Left 1, Width 25
ENDCLASS


See Also

_curobj

First

ID

NextObj


Add( )

See Also	Example	Properties	Forms

Adds an element to a one-dimensional array object.

Property of Class

ARRAY

Description

Use the Add( ) method to add a single element to a one-dimensional array object.

Add( ) requires <expN>, a parameter that specifies what value to put in the new element. For example, an array object with 10 elements acquires an eleventh element containing 100 when <expN> is 100, as with:

MyArray = NEW ARRAY(10)
MyArray.Add(100)

See Insert( ) for another way to add elements to an array object


Add( ) Example

USE Customer.DBF

* Initialize an array object

ObjArr=NEW ARRAY(RECCOUNT())

* Fill 1-dimensional array with values

* from Name field of Customer.DBF

GO TOP

FOR i=1 TO RECCOUNT()

  ObjArr[i]= Customer->Name

  SKIP

NEXT i

* Use ADD() to add an additional element

* to the 1-dimensional array and place

* a customer name in that element.

ObjArr.ADD(1)

Cnt=ObjArr.SIZE     && Returns new number of elements

ObjArr[Cnt] = "George Benson Dive Works"

* Display Contents array

FOR i=1 TO Cnt

? ObjArr[i] AT 10

NEXT i


See Also

Grow( )

Insert( )

Resize( )


Advise( )

See Also	Example	Properties

Requests that a server application notify dBASE when an item in a server topic changes.

Property of Class

DDELINK

Description

Use the Advise( ) method to create a hot link to an item in a server topic. A hot link makes the server notify dBASE when the item changes.

A server topic can be anything that the server application understands, but it is usually a document you open in the external application. For example, a data-exchange program might start a session in Quattro Pro for Windows, open one of its spreadsheet files (the topic), and use Advise( ) to establish a hot link to one of its cells.

Advise( ) requires the <item> parameter, which identifies the hot-linked item in the server topic. This item can be any single element, such as a field in a table or a cell in a spreadsheet. For example, you can specify cell C2 of Page A in a Quattro Pro spreadsheet file by passing the parameter "A:C2". When the contents of the cell are altered, Quattro Pro notifies dBASE and a subroutine (which you specify with the OnNewValue property) is executed automatically.


Advise( ) Example

PUBLIC LinkObj

LinkObj = NEW DDELINK()

LinkObj.OnNewValue = Valuehandler;

               && Codeblock or function pointer

LinkObj.Initiate("QPW","Demo.WB1")

LinkObj.Advise("A:A1");

               && Notified when cell A:A1 changes


See Also

Execute( )

Initiate( )

OnNewValue

Peek( )

Poke( )

Server

Terminate( )

Timeout

Topic

Unadvise( )


Alias

See Also	Example	Properties	Forms

Determines the table that is accessed by a browse object.

Property of Class

BROWSE

Data Type

Character

Default

The default for Alias is an empty string.

Description

Use the Alias property to identify a table to display in a browse object.

An alias is an alternate name given to an open table file, and can consist of

A name you specify with the ALIAS option of the USE command.

The file name of the table (if you did not assign the table an alias).

The letter that corresponds to the work area of the table. This alias can be any letter from A to J.

For example, when the parent form is based on a query that opens two or more files in a parent-child relation, you can use Alias to determine which table appears in the browse object.

For more information on aliases and work areas, see SELECTand USE.


Alias Example

NEW operator syntax:

this.Alias = "Animals"

DEFINE object syntax:

DEFINE BROWSE Br1 OF THIS;

PROPERTY Alias "Animals"


See Also

DataLink

DEFINE


Alignment

See Also	Example	Properties	Forms

Positions a graphic in an image object or text in a text object.

Property of Class

IMAGE, TEXT

Data Type

Numeric

Default

The default for Alignment is 0 (Top Left).

Description

Use Alignment when an image object or a text object is larger than the image or text it contains.

For example, if you store graphics in a binary field and link this field to an image object through the DataSource property, the user can display each image by moving from record to record. If the images vary in size, the smaller images might not fill the entire object. Use alignment to position the images within the object.

You can assign the following settings to the Alignment property of a text object:

Setting	Description
0 (Top Left)	Adjacent to the top edge and the left edge
1 (Top Center)	Adjacent to the top edge and centered horizontally
2 (Top Right)	Adjacent to the top edge and the right edge
3 (Center Left)	Centered vertically and adjacent to left edge
4 (Center)	Centered horizontally and vertically
5 (Center Right)	Centered vertically and adjacent to right edge
6 (Bottom Left)	Adjacent to the bottom edge and the left edge
7 (Bottom Center)	Centered horizontally and adjacent to the bottom edge
8 (Bottom Right)	Adjacent to the bottom edge and the right edge
9 (Wrap Left)	Wraps strings that exceed the width of the text object
You can assign the following settings to the Alignment property of an image object:

0 (Stretch)	Enlarged to fill the entire image object
1 (Top Left)	Adjacent to the left edge and the top edge
2 (Center)	Centered
Note:	Specify the dimensions of a text object or an image object with the Height and Width properties.


Alignment Example

NEW operator syntax:

Heading = NEW Text(this)

  Heading.Text = "Animals of the World"

  Heading.Alignment = 7

  Heading.Border = .T.

DEFINE object syntax:

DEFINE TEXT Heading OF THIS;

  PROPERTY;

    Text "Animals of the World",;

    Alignment 7,;

    Border .T.


See Also

Height

Width


Append

See Also	Example	Properties	Forms

Determines if records can be added to a table in a browse object.

Property of Class

BROWSE

Data Type

Logical

Default

The default for Append is true (.T.).

Description

Set Append to false (.F.) when you want to prevent users from adding records to a table. For example, an application might allow executives to view or even modify existing customer accounts, without letting them add new accounts.


Append Example

NEW operator syntax:

CompanyBrowse = New BROWSE(this)

  CompanyBrowse.Top = 3

  CompanyBrowse.Left = 1

  CompanyBrowse.Width = 60

  CompanyBrowse.Alias = "Company"

  CompanyBrowse.Append = .F.

  CompanyBrowse.Delete = .F.

  CompanyBrowse.Modify = .F.

DEFINE object syntax:

DEFINE BROWSE CompanyBrowse OF THIS;

   FROM 3,1 TO 13,40;

     Property;

      Alias "Company",;

      Append .F. ,;

      Delete .F. ,;

      Modify .F.


See Also

Delete

Modify


AutoSize

See Also	Example	Properties	Forms

Determines if a form is automatically sized to contain its objects when the form is opened.

Property of Class

FORM

Data Type

Logical

Default

The default for AutoSize is false (.F.).

Description

Use AutoSize to determine how a form is sized and proportioned.

If you set the AutoSize property of a form to true (.T.), the form is automatically adjusted to contain its objects when it is opened. If you set AutoSize to false (.F.), the form assumes its default dimensions when it is opened.

The default dimensions of a form are determined by the following:

The settings you give to the Height and Width properties

The FROM...TO clause of the DEFINE FORM command, if you used that command to create the form

The size and proportion the user last gave to the form with the mouse or the Size option of the Control Menu

When you set the AutoSize property of a form to true, the default dimensions are ignored. The user can still move or resize the form, but if the form is closed and reopened it is automatically resized again to contain its objects.


AutoSize Example

NEW operator syntax:

EntryForm = NEW Form()

  EntryForm.Autosize = .F.

DEFINE object syntax:

DEFINE FORM EntryForm ;

  Property;

      Autosize .F.


See Also

Height

Left

Width


Before

See Also	Example	Properties	Forms

Specifies which other object an object precedes in the tabbing order of the form.

Property of Class

BROWSE, CHECKBOX, COMBOBOX, EDITOR, ENTRYFIELD, LISTBOX, MENU, OLE, PUSHBUTTON, RADIOBUTTON, SCROLLBAR, SPINBOX, TEXT

Data Type

Object reference

Description

Use the Before property to control the tabbing order of the objects in a form.

When a form holds two or more objects that users can select, the user can move from object to object by pressing Tab or Shift+Tab. The order in which focus moves from object to object is known as the tabbing order.

When you insert an object reference that points to one object (Object A) into the Before property of another object (Object B), the tabbing order of the form is changed so that

When the user presses Tab to move from object to object, Object B precedes Object A.

When the user presses Shift+Tab to move from object to object, Object A precedes Object B.


Before Example

NEW operator syntax:

LOCAL f
f = NEW XFORM()
f.Open()

CLASS XFORM OF FORM
   this.Left =         50.20
   this.Width =         38.40
   this.Text = "Form"
   this.HelpId = ""
   this.HelpFile = ""
   this.View = "COMPANY.DBF"
   this.Top =          9.06
   this.Height =          7.94

   DEFINE ENTRYFIELD ENTRYFIELD2 OF THIS;
       PROPERTY;
         Left          9.00,;
         Width         18.80,;
         DataLink "COMPANY->STATE_PROV",;
         Border .T.,;
         Top          4.00,;
         Height          1.00

   DEFINE ENTRYFIELD ENTRYFIELD1 OF THIS;
       PROPERTY;
         Left          9.00,;
         Width         20.00,;
         DataLink "COMPANY->COMPANY",;
         Border .T.,;
         Top          2.00,;
         Height          1.00

ENDCLASS

DEFINE object syntax:

DEFINE ENTRYFIELD Company OF THIS;

  Property Datalink "Company->Company",;

  Top 4, Left 9, Width 18.80

DEFINE ENTRYFIELD State OF THIS;

  Property Datalink "Company->State_Prov",;

  Top 2, Left 9, Before this.Company


See Also

_curobj


Border

See Also	Example	Properties	Forms

Determines if an object is surrounded with a border.

Property of Class

EDITOR, ENTRYFIELD, IMAGE, OLE, RECTANGLE, SPINBOX, TEXT

Data Type

Logical

Default

The default for Border is true (.T.).

Description

You can prevent a rectangle object from having a border by setting the Border property to false (.F.). To restore the border, set the Border property to true.

By default, the border is a single line that surrounds the object. If you set a related property named BorderStyle to 1 (Raised), the object appears elevated, and if you set BorderStyle to 2 (Lowered), the object appears lowered.


Border Example

NEW operator syntax:

Heading = NEW TEXT(this)

  Text = "Data Entry Screen"

  Top  = 1

  Left = 5

  Border = .T.

DEFINE object syntax:

DEFINE TEXT Heading OF EntryForm;

  Property;

      Text "Data Entry Screen",;

      Top  0,;

      Left  5,;

      Border .T.


See Also

CLASS RECTANGLE

BorderStyle


BorderStyle

See Also	Example	Properties	Forms

Determines the border characterstics of a rectangle object.

Property of Class

RECTANGLE

Data Type

Numeric

Default

The default for BorderStyle is 0 (Normal).

Description

Use BorderStyle to set the appearance of a rectangle object.

BorderStyle	Result

0 (Normal)	Rectangle is surrounded by a 3-D line with a title.

1 (Raised)	Rectangle appears elevated.

2 (Lowered)	Rectangle appears lowered.

When you set BorderStyle to 1 or 2, the label that is displayed in the top left corner of the rectangle disappears.


BorderStyle Example

NEW operator syntax:

Bx1 = NEW RECTANGLE(this)

  Top  = 1

  Left = 5

  Width = 30

  Height = 15

  BorderStyle = 2    && Lowered border style

DEFINE object syntax:

DEFINE RECTANGLE Bx1 OF THIS;

  Property;

    Top  1,;

    Left  5,;

    Width 30,;

    Height 15,;

    BorderStyle 1    && Raised border style


See Also

Border

CLASS RECTANGLE


Bottom

See Also	Example	Properties	Forms

Sets the row position of the lower end of a line object.

Property of Class

LINE

Data Type

Numeric

Description

Use the Bottom property in combination with the Right, Left, and Top properties to determine the position and length of a line object.

Each unit of the value you assign to Bottom is the average height of characters in the active font of the parent form. For example, if you set the Bottom property of a line object to 17.5, the lower end of the line is positioned 17.5 characters down.


Bottom Example

DEFINE LINE Ln1 OF THIS;

  PROPERTY;

    Left 10,;          && Vertical line from 3,10;

    Top 3,;               to 8,10

    Width 4,;

    Bottom 8,;

    ColorNormal "RB/W"

DEFINE LINE Ln2 OF THIS;

  PROPERTY;

    Left 3,;           && Horizontal line from 8,3

    Top 8,;               8,33

    Width 4,;

    Bottom 8,;

    Right 33,;

    ColorNormal "RB/W"


See Also

CLASS FORM

Right

ScaleFontName

ScaleFontSize

Top

Width


Checked

See Also	Example	Properties	Forms

Determines if a checkmark appears beside a menu command.

Property of Class

MENU

Data Type

Logical

Default

The default for Checked is false (.F.).

Description

Use Checked to indicate that a condition or a process is turned on or off.

The checkmark appears to the left of the menu command when you set the Checked property to true (.T.); the checkmark is removed when you set the Checked property to false. The user usually adds or removes a checkmark by clicking the menu item.

You can query the current Checked setting and make branching decisions accordingly. For example, if Checked is true, you can execute a procedure or a codeblock; and if Checked is false, you can execute a different procedure or codeblock (or none at all).


Checked Example

NEW operator syntax:

Edit = NEW MENU(this.Main.View)

  Edit.Text = "Edit"

  Edit.Checked = .T.

DEFINE object syntax;

DEFINE MENU Edit OF THIS;

  PROPERTY ;

  Text "Edit",;

  Checked .T.


See Also

DEFINE


ClassName

See Also	Example	Properties	Forms

A read-only property that identifies the class that the object is based on.

Property of Class

BROWSE, CHECKBOX, COMBOBOX, DDELINK, DDETOPIC, EDITOR, ENTRYFIELD, FORM, IMAGE, LINE, LISTBOX, MENU, OLE, PUSHBUTTON, RADIOBUTTON, RECTANGLE, SCROLLBAR, SPINBOX, TEXT

Data Type

Character

Default

The name of the class the object is based on.

Description

Use ClassName to find out which class an object was created from. The ClassName value is set when you create the object, and is read-only.


ClassName Example

NEW operator syntax:

this.Fld1 = NEW ENTRYFIELD(this)

  this.Fld1.OnLostFocus = CheckIt

DEFINE object syntax:

DEFINE ENTRYFIELD Fld1 OF THIS;

  PROPERTY OnLostFocus Checkit

PROCEDURE CheckIt

IF This.Classname = "ENTRYFIELD"

   ? this.Value        && contents to Command window

ENDIF                  && results pane or printer


See Also

Name


Close( )

See Also	Example	Properties	Forms

Closes a form.

Property of Class

FORM

Description

Use Close( ) to close an open form.

When you close a form, dBASE does the following:

1.	Executes the Valid subroutine or codeblock of the current object. If it returns a value of false (.F.), the form does not close.

2.	Executes the OnLostFocus subroutine or codeblock of the current object.

3.	Executes the OnLostFocus subroutine or codeblock of the form.

4.	Removes the form and the objects it contains from the screen.

5.	Executes the OnClose subroutine or codeblock of the form.

6.	Removes the form definition from memory if there are no object references pointing to the form.

If the form definition is not removed from memory, you open the form again with Open( ) or OPEN FORM.


Close( ) Example

NEW operator syntax:

this.Exit = NEW PUSHBUTTON(this)

  this.Top=16

  this.Left=14

  this.Text="Exit"

  this.Height=2

  this.OnClick {;Form.Close()}

DEFINE object syntax:

DEFINE PUSHBUTTON Exit OF THIS;

  PROPERTY Text "Exit", Height 2,;

  Top 16, Left 14,;

  OnClick {;Form.Close()}


See Also

CLOSE FORMS

Open( )

OPEN FORM

ReadModal( )

READMODAL( )


ColorHighlight

See Also	Example	Properties	Forms

Sets the color of the object that has focus.

Property of Class

ENTRYFIELD, LISTBOX, OLE, SPINBOX

Data Type

Character

Default

The default for ColorHighlight is N/W.

Description

You can specify two color settings with ColorHighlight: a foreground color (for text), and a background color. Color settings are specified with a color code, and settings must be separated with a forward slash (/). For a list of color codes, see ColorNormal.

Use the ColorHighlight and ColorNormal properties of an object so that users can differentiate visually when an object has focus and when it does not.

Note:	You can specify a setting for ColorHighlight with the Choose Color dialog box, which lets you choose a predefined color or design a color of your own. To access the Choose Color dialog box, click on the Tool button next to the ColorHighlight item in the Object Inspector.


ColorHighlight Example

See DataLink for an example of ColorHighlight.


See Also

ColorNormal

DEFINE


ColorNormal

See Also	Example	Properties	Forms

Sets the color of an object that is not currently selected.

Property of Class

BROWSE, CHECKBOX, EDITOR, ENTRYFIELD, FORM, LISTBOX, OLE, SPINBOX, TEXT

Data Type

Character

Default

The default for ColorNormal is N/W (black over a white background).

Description

You can specify two color settings with ColorNormal: a foreground color (for text), and a background color. Color settings are specified with a color code, and settings must be separated with a forward slash (/). For color monitors, the color codes are

Black	N	Magenta	RB
Blue	B	Brown	RG
Green	G	White	W
Cyan	GB	Blank	X
Red	R

These settings have no effect on monochrome monitors.

You can also specify intensity (brightness) attributes. For both color and monochrome monitors, the attribute code for high-intensity foreground is +, and the attribute code for high-intensity background is *. For example, if you want the text in an entry field to appear in bright blue over a white background, set the ColorNormal property to B+/W.

For monochrome monitors, I is an alternate attribute code for high intensity.

Use the ColorNormal and ColorHighlight properties of an object so that users can differentiate visually when an object has focus and when it does not.

Note:	You can specify a setting for ColorNormal with the Choose Color dialog box, in which you choose a predefined color or design a color of your own. To access the Choose Color dialog box, click on the Tool button next to the ColorNormal item in the Object Inspector.


ColorNormal Example

See DataLink for an example of ColorNormal.


See Also

ColorHighlight

DEFINE


Count( )

See Also	Example	Properties	Forms

Returns the number of prompts in a list box.

Property of Class

LISTBOX

Description

Use Count( ) when you cannot anticipate the number of prompts a list box might have at runtime. For example, when you specify FILE *.* for the DataSource property, the number of prompts varies when files are added to or deleted from the default directory.

You can use Count( ) to control loops that evaluate user choices in a multiple-choice list box. For example, you can see which prompts were chosen by evaluating each prompt with the Selected( ) method in a DO...WHILE loop.

Make a list box multiple-choice by setting the Multiple property to true (.T.).


Count( ) Example

The following example defines a form that contains a listbox that displays names from the Animals.DBF table. Property Multiple .T. lets the user select more than one listbox prompt. The OnRightMouseDown property calls procedure Checked, which uses the methods Count( ) and Selected( ) to send the selected prompts to the Command window results pane with each OnRightMouseDown:

LOCAL f
f = NEW XFORM()
f.Open()

CLASS XFORM OF FORM
   this.Left =         52.80
   this.Width =         40.60
   this.Text = "Animals of the World"
   this.HelpId = ""
   this.OnRightMouseDown = CHECKED
   this.HelpFile = ""
   this.Top =          3.12
   this.Height =         20.00

   DEFINE LISTBOX LB1 OF THIS;
       PROPERTY;
         Left         10.00,;
         ColorNormal "N/W*",;
         Width         20.00,;
         DataSource "FIELD ANIMALS->NAME",;
         Multiple .T.,;
         ColorHighLight "W+/B",;
         Top          4.00,;
         Height         12.00

ENDCLASS

PROCEDURE Checked
FOR i=1 TO Form.LB1.Count()
  ? Form.LB1.Selected(i)
NEXT i
RETURN


See Also

FOR...NEXT

LISTCOUNT( )

LISTSELECTED( )

Selected( )

Multiple


CurSel

See Also	Example	Properties	Forms

Determines which prompt is selected in a list box.

Property of Class

LISTBOX

Data Type

Numeric

Default

The default for CurSel is 0.

Description

Use CurSel to specify which list box prompt is highlighted.

CurSel lets you place the highlight on a prompt other than the prompt last chosen by the user. For example, an OnLostFocus subroutine might use CurSel to highlight the top prompt each time the user moves focus to a different object.


CurSel Example

NEW operator syntax:

this.LB1 = NEW LISTBOX(this)

  this.Lb1.Top=4

  this.Lb1.Left=6

  this.Lb1.Width=20

  this.Lb1.Height=12

  this.Lb1.DataSource="FIELD Animals->Name"

  this.Lb1.CurSel= 3

DEFINE object syntax:

DEFINE LISTBOX LB1 OF THIS;

  PROPERTY;

  Top 4, Left 6, Width 20, Height 12,;

  DataSource "FIELD Animals->Name",;

  CurSel 3


See Also

Count( )

Selected( )


DataLink

See Also	Example	Properties	Forms

Links an object in a form to a table field.

Property of Class

CHECKBOX, COMBOBOX, EDITOR, ENTRYFIELD, OLE, RADIOBUTTON, SPINBOX

Data Type

Character

Default

The default for DataLink is an empty string.

Description

If you create a check box, entry field, radio button, or spin box to access table data, you need to establish a link between the object and a field in the table with DataLink. Once you have established the link, any changes entered through the object are inserted into the field automatically.

When the user moves from record to record, the change is reflected in the object. For example, if an entry field is linked to a table field and the user moves to another record, the value in the entry field is updated with the current table field value.

The DataLink property is similar to the DataSource property. However, data displayed through the DataLink property can be changed, while data displayed through the DataSource property is always read-only. For example, the DataSource property of a combo box determines its prompts (which are read-only values), while the DataLink property determines which field is affected by the user's input.

Note:	You can select a field with the Choose Field dialog box. To access the Choose Field dialog box, click the Tool button next to the DataLink item in the Object Inspector.


DataLink Example

NEW operator syntax:

Company = NEW ENTRYFIELD(this)

Company.Top = 3

Company.Left = 1

Company.Datalink = "Company"

Company.ColorHighlight = "B/W"

Company.ColorNormal   = "W/B"

Company.Function = "@!"

DEFINE object syntax:

DEFINE Entryfield Company OF THIS;

  AT 3,1;

  Property;

     Datalink "Company",;

     ColorHighlight "B/W",;

     ColorNormal   "W/B",;

     Function "@!"


See Also

Alias

DataSource

DEFINE

Fields


DataSource

See Also	Example	Properties	Forms

Determines which data is displayed in a list box, a combo box, or an image object.

Property of Class

COMBOBOX, IMAGE, LISTBOX

Data Type

Character

Default

The default for DataSource is an empty string.

Description

You need to specify a valid value for the DataSource property to display an image in an image object, or prompts in a list box or a combo box.

The DataSource property is similar to the DataLink property. However, data displayed through the DataLink property can be changed, while data displayed through the DataSource property is always read-only.

You can specify one of five DataSource values for a list box or a combo box:

FILE <filename skeleton expC> creates prompts from file names in the current default directory.

FIELD <field name> creates prompts from all the values in a field in a table file. Each prompt represents a record, and you can move from record to record by selecting different prompts. To create prompts that do not move from record to record, copy the field into an array object with COPY TO ARRAY, then use the DataSource ARRAY <array name> option (described in this list).

STRUCTURE creates prompts from all the field names in a table.

ARRAY <array name> creates prompts from elements in an array object.

TABLES creates prompts from the names of all tables in the currently open database. See OPEN DATABASE for information on databases.

To evaluate which prompts were chosen from a list box, use LISTSELECTED( ) or Selected( ).

Note:	You can specify one of three DataSource values for an image object:

RESOURCE <resource id><DLL name> designates a DLL file and a resource within it. <DLL name> is the name of the DLL file and must include the file name extension if the DLL file is not already in memory. <resource id> is a numeric literal that identifies a bitmap image in the DLL file.

FILENAME <filename> is the name of a file containing a bitmap image.

BINARY <binary field> is the name of a binary field containing bitmap images.


DataSource Example

NEW operator syntax:

this.COMBOBOX1 = NEW COMBOBOX(this)

this.COMBOBOX1.DataLink = "Company"

this.COMBOBOX1.Value = "General Consolidated"

    DataSource = "FIELD COMPANY"

* or

*   DataSource = "STRUCTURE"

* or

*   DataSource = "FILE '*.PRG'"

* or

*   DataSource = "TABLES"

* or

*   DataSource = "Array 'ComboList'"

DEFINE object syntax:

DEFINE COMBOBOX COMBOBOX1 OF THIS;

  PROPERTY;

    DataLink "Company",;

    Value "General Consolidated",;

    DataSource "FIELD COMPANY"

* or

*   DataSource "STRUCTURE"

* or

*   DataSource "FILE '*.PRG'"

* or

*   DataSource "TABLES"

* or

*   DataSource "Array 'ComboList'"


See Also

DEFINE


Default

See Also	Example	Properties	Forms

Determines if a pushbutton is a default pushbutton.

Property of Class

PUSHBUTTON

Data Type

Logical

Default

The default for Default is false (.F.).

Description

Use the Default property to make a pushbutton the default pushbutton when the user submits a form by pressing Enter. Setting the Default property of a pushbutton to true gives the pushbutton a visual highlight that identifies it as the default.

Setting the Default property to true (.T.) causes two things to happen when the user presses Enter:

The OnClick subroutine of the default pushbutton executes.

The ID property of the default pushbutton is passed to the OnSelection routine of the parent form.

The OnSelection subroutine can use the ID value to make branching decisions.

However, if the user clicks on any pushbutton, the OnClick subroutine of that pushbutton executes. The ID value of that pushbutton is passed to the OnSelection subroutine, even if the Default property of another pushbutton is true.

If you give more than one pushbutton a Default value of true, the last pushbutton to get the value is the default. If you give all pushbuttons a Default value of false, the pushbutton that you created first is the default.


Default Example

NEW operator syntax:

BUTTON1 = New PUSHBUTTON(this)

BUTTON1.Text = "BUTTON1"

BUTTON1.Top = 3.00

BUTTON1.Onclick = Push1

BUTTON2 = New PUSHBUTTON(this)

BUTTON2.Text = "BUTTON2"

BUTTON2.Top = 8.00

BUTTON2.Onclick = Push2

BUTTON2.Default = .T.

DEFINE object syntax:

DEFINE PUSHBUTTON BUTTON1 OF THIS;

   PROPERTY;

      Text "BUTTON1",;

      Top  3.00,;

      Onclick Push1

DEFINE PUSHBUTTON BUTTON2 OF THIS;

   PROPERTY;

      Text "BUTTON2",;

      Top 8.00,;

      Onclick Push2,;

      Default .T.


See Also

DEFINE

OnClick


Delete

See Also	Example	Properties	Forms

Determines if records in a browse object can be marked for deletion.

Property of Class

BROWSE

Data Type

Logical

Default

The default for Delete is true (.T.).

Description

Set Delete to false to prevent users from marking records for deletion. For example, an application might allow certain users to view records but, for reasons of security, not allow them to delete records.

Note:	A record is not removed from a table when it is marked for deletion; it is removed only when you execute the PACK command or when the user chooses the Utilities | Pack command of the Table menu.


Delete Example

NEW operator syntax:

DEFINE BROWSE Br1 OF this

  this.Br1.Delete=.F.

  this.Br1.Top=4

  this.Br1.Left=3

  this.Br1.Width=32

  this.Br1.Height=12

DEFINE object syntax:

DEFINE BROWSE Br1 OF THIS FROM 4,3 TO 16,35;

    PROPERTY;

   Delete .F.


See Also

Append

Modify


Delete( )

See Also	Example	Properties

Deletes an element from a one-dimensional array object or a row or column from a two-dimensional array object.

Property of Class

ARRAY

Description

Use Delete( ) to delete selected elements from an array without changing the size of the array. Delete( ) does the following:

Deletes an element from a one-dimensional array, or deletes a row or column from a two-dimensional array

Moves all remaining elements toward the beginning of the array (up if a row is deleted, to the left if an element or column is deleted)

Inserts .F. values in the last position or positions

For information about deleting elements and moving remaining elements toward the end of the array, see Insert( ). For information about replacing elements without moving remaining elements, see Fill( ). To change the size of an array, use Grow( ) or Resize( ).


Delete( ) Example

USE Animals.DBF

* Initialize an array object

ObjArr=NEW ARRAY(RECCOUNT(),3)

* Fill array with values from Animals.DBF

COPY TO ARRAY ObjArr FIELDS Name, Area, Weight

* Use DELETE() to remove the Weight values from

* column 3 and replace with false (.F.)

ObjArr.DELETE(3,2)

* Display results of DELETE()

FOR i=1 TO RECCOUNT()

? ObjArr[i,1],ObjArr[i,2],ObjArr[i,3]

NEXT i


See Also

ADEL( )

Add( )

Insert( )


Dimensions

See Also	Example	Properties

Specifies the number of dimensions in an array object.

Property of Class

ARRAY

Data Type

Numeric

Description

Use Dimensions to find out whether an array object is one-dimensional or multi-dimensional.

Dimensions is a read-only property.


Dimensions Example

USE Customer.DBF

* Initialize an array object

ObjArr=NEW ARRAY(RECCOUNT())

* Fill 1-dimensional array with values

* from Name field of Customer.DBF

GO TOP

FOR i=1 TO RECCOUNT()

  ObjArr[i] = Customer->Name

  SKIP

NEXT i

* Use Dimensions to return array dimensions

* and GROW() to add a second column to the

* existing array and enter Ytd_Sales data

* in new second column.

IF ObjArr.Dimensions=1

  ObjArr.GROW(2)

  GO TOP

  FOR i=1 TO RECCOUNT()

    ObjArr[i,2]=Customer->Ytd_Sales

    SKIP

  NEXT i

ENDIF

* Display Contents of 2-dimensional array

FOR i=1 TO RECCOUNT()

? ObjArr[i,1], ObjArr[i,2]

NEXT i


See Also

Add( )

ALEN( )

Delete( )

Fields( )

Insert( )

Resize( )


Dir( )

See Also	Example	Properties

Stores the name, size, date stamp, time stamp, and DOS attributes of files to an array object.

Property of Class

ARRAY

Description

Use the Dir( ) method to store file information to an array object. The Dir( ) method is similar to the ADIR( ) function.

Dir( ) accepts two optional parameters:

<filename skeleton expC> identifies file names with a wildcard character string. For example, to return information on tables only, use "*.DBF" as <filename skeleton expC>. If you omit <filename skeleton expC>, Dir( ) stores information about all files except hidden or system files in the current directory.

<file attribute list expC> specifies one or more DOS file attributes. The meaning of each attribute is as follows:

Character	Meaning

D	Include directories

H	Include hidden files

S	Include system files

V	Include volume label only

When you specify more than one letter for <file attribute list expC>, include all the letters between quotation marks. If you specify a value for <file attribute list expC>, also include a value for <filename skeleton expC>.

When you include the letter V in <file attribute list expC>, Dir( ) ignores <filename skeleton expC> and all other characters in the attribute list and stores the volume label to a one-element array object.

The array object is dynamically sized to fit all returned information.


Dir( ) Example

The following example uses Array( ) to initialize an array object and Dir( ) to fill the array with DOS directory file information. The FOR...NEXT loop traverses the array to display the results of the Dir( ) operation. Note the use of Size( ) to return the number of elements in the array. Dividing the number of elements by the number of file attributes that DIR( ) copies yields the number of rows in the array:

ObjArr=NEW ARRAY()
ObjArr.DIR("*.PRG","D")
FOR i=1 TO ObjArr.Size/5
? ObjArr[i,1],ObjArr[i,2] AT 20,;
  ObjArr[i,3] AT 35,ObjArr[i,4] AT 45,;
  ObjArr[i,5] AT 55
NEXT i


See Also

ADIR( )

Fields( )


DisabledBitmap

See Also	Example	Properties	Forms

Specifies the graphic image to display in a pushbutton when the pushbutton is disabled.

Property of Class

PUSHBUTTON

Data Type

Character

Default

The default for DisabledBitmap is an empty string.

Description

Use DisabledBitmap to indicate visually when a pushbutton is not available for use.

A pushbutton is disabled when

Its Enabled property is set to false (.F.).

Its When property returns a value of false.

The DisabledBitmap setting can take one of two forms:

RESOURCE <resource id> <dll name> specifies a bitmap resource and the DLL file that holds it. (A DLL file is a precompiled library of external routines and resources written in non-dBASE languages such as C and Pascal.) You can obtain the resoure ID with a resource editor such as Resource Workshop.

FILENAME <filename> specifies a bitmap file (which usually has the file-name extension .BMP).

If you specify a character string with Text and an image with DisabledBitmap, the image is displayed with the character string when the pushbutton is disabled. When you specify no image with DisabledBitmap, the Text property character string is displayed with low intensity when the pushbutton is disabled.

Note:	You can select a bitmap file with the Choose Bitmap dialog box. To access the Choose Bitmap dialog box, click the Tool button next to the DisabledBitmap item in the Object Inspector.


DisabledBitmap Example

NEW operator syntax:

Go = NEW PUSHBUTTON(this)

Go.DisabledBitmap = "RESOURCE 20 EntryIcn.dll"

* or

* Go.DisabledBitmap = "FILENAME PushDis.bmp"

* or

* Go.DisabledBitmap = "BINARY PushDis"

DEFINE object syntax:

DEFINE PUSHBUTTON Go OF THIS;

  Property;

    DisableBitmap "RESOURCE 20 EntryIcn.dll"

* or

*   DisableBitmap "FILENAME PushDis.bmp"

* or

*   DisableBitmap "BINARY PushDis"


See Also

DEFINE

DownBitmap

Enabled

FocusBitmap

UpBitmap


DoVerb( )

See Also	Example	Properties	Forms

Starts an action in an OLE server application.

Property of Class

OLE

Description

Use DoVerb( ) to initiate an action from an OLE document stored in an OLE field and to specify what action to take.

Every OLE object accepts one or more verbs. Each verb determines which actions are taken, and each is represented by a number. For example, most sound applications accept one of two verbs:

0 (Play) plays a sound stored in an OLE field.

1 (Edit) opens the Sound Recorder to edit the sound.

Some OLE documents have only one verb. For example, Quattro Pro for Windows has only 0 (The Edit verb).

DoVerb accepts two parameters:

<OLE verb> The numeric value of the verb.

<title> A text string to display in the title bar of the server window (if <OLE verb> causes a window to appear).

Note:	You can determine which verbs are accepted by an OLE document with the following steps:

1.	In a browse object, double-click on the OLE field containing the document. This opens the OLE viewer.

2.	Open the Edit menu. The OLE object is the last menu item; for example, if the OLE was created by the Windows Sound Recorder, the last menu item is Sound Object.

3.	Click once on this menu item; if the OLE document accepts more than one verb, they are displayed as menu items in a child menu. If the OLE document accepts only one verb, that verb is executed.

You can also view OLE verbs through the Windows registration database, which you can examine with the Registration Info Editor. You access the editor by starting a session in Windows in verbose mode and specifying regedit as a parameter, as with:

win regedit /v


DoVerb( ) Example

The following program creates a form that displays an OLE object and a pushbutton. The OnClick subroutine of the pushbutton uses DoVerb to start an action in an OLE server.

LOCAL f
f = NEW XFORM()
f.Open()

CLASS XFORM OF FORM
   this.Left =         18.80
   this.Width =        101.80
   this.MousePointer =          1
   this.Text = "Form"
   this.HelpId = ""
   this.HelpFile = ""
   this.View = "PICTURES.QBE"
   this.Top =         -0.06
   this.Height =         24.23

   DEFINE OLE OLE1 OF THIS;
       PROPERTY;
         Left          3.00,;
         Width         97.00,;
         DataLink "PICTURES->BITMAPOLE",;
         Border .T.,;
         Top          1.00,;
         Height         19.00

   DEFINE PUSHBUTTON BUTTON1 OF THIS;
       PROPERTY;
         Left         39.00,;
         ColorNormal "N/W",;
         Width         22.00,;
         OnClick CLASS::BUTTON1_ONCLICK,;
         Text "Click me to edit this image.",;
         Default .T.,;
         Top         21.00,;
         Height          2.00

   Procedure BUTTON1_OnClick
   form.OLE1.DoVerb(0, "This Title Is Optional")
ENDCLASS


See Also

CLASS OLE

REPLACE OLE


DownBitmap

See Also	Example	Properties	Forms

Specifies the graphic image to display in a pushbutton when the user presses the button.

Property of Class

PUSHBUTTON

Data Type

Character

Default

The default for DownBitmap is an empty string.

Description

Use DownBitmap to give visual confirmation when the user clicks a pushbutton. When the user releases the mouse button or moves the pointer off the pushbutton, the image or text specified by UpBitmap or Text is displayed.

The DownBitmap setting can take one of two forms:

RESOURCE <resource id> <dll name> Specifies a bitmap resource and the DLL file that holds it. (A DLL file is a precompiled library of external routines and resources written in non-dBASE languages such as C and Pascal.) You can obtain the resoure ID with a resource editor such as Resource Workshop.

FILENAME <filename> specifies a bitmap file (which usually has the file-name extension .BMP).

When you specify a character string for the pushbutton with Text and an image with DownBitmap, the image is displayed with the character string when the user clicks the pushbutton.

Note:	You can select a bitmap file with the Choose Bitmap dialog box. To access the Choose Bitmap dialog box, click the Tool button next to the DownBitmap item in the Object Inspector.


DownBitmap Example

See UpBitmap for an example of DownBitmap.


See Also

DEFINE

DisabledBitmap

Enabled

FocusBitmap

Text

UpBitmap


Element( )

See Also	Example	Properties

Returns the number of a specified element in an array object.

Property of Class

ARRAY

Description

Use Element( ) when you know the subscripts of an element in a two-dimensional array object and need the element number for use with another method, such as Scan( ). The Element( ) method is similar to the AELEMENT( ) function.

An element number indicates the sequential position of an element in the array. In one-dimensional arrays, the element number is the same as the subscript, so there is no need to use Element( ); for example, Element(3) returns 3, Element(5) returns 5, and so on.

Element( ) accepts two parameters:

<subscript1 expN> is the first subscript number of the element. In a one-dimensional array, <subscript1 expN> is the same as the element number. In a two-dimensional array, <subscript1 expN> identifies a row.

<subscript2 expN> specifies the column of the element when the array object is two-dimensional. If you omit <subscript2 expN>, dBASE assumes the value 1. If the array object is one-dimensional, dBASE ignores <subscript2 expN>.

Element( ) is the inverse of Subscript( ), which returns the row or column subscript number of an element when you specify the element number.


Element( ) Example

USE Animals.DBF

* Initialize an array object

ObjArr=NEW ARRAY(RECCOUNT(),3)

* Fill array with values from Animals.DBF

COPY TO ARRAY ObjArr FIELDS Name, Area, Weight

* Use ELEMENT() to return the array element number

* of all Name values in the 1st column.

FOR i=1 TO RECCOUNT()

? ObjArr[i,1], ObjArr.Element(i,1)

NEXT i


See Also

AELEMENT( )

Scan( )

Subscript( )


Enabled

See Also	Example	Properties	Forms

Determines if an object can be selected.

Property of Class

BROWSE, CHECKBOX, COMBOBOX, EDITOR, ENTRYFIELD, FORM, LISTBOX, MENU, OLE, PUSHBUTTON, RADIOBUTTON, SCROLLBAR, SPINBOX

Data Type

Logical

Default

The default for Enabled is true (.T.).

Description

When you set the Enabled property of an object to true, the user can select and use the object. When you set the Enabled property to false (.F.), the object is dimmed and the user cannot select or use the object.

You usually set the Enabled property to false when a required condition is not met. For example, the Valid subroutine of an entry field might disable an OK pushbutton when the user has not entered correct data into the entry field.


Enabled Example

NEW operator syntax:

Compcode = NEW ENTRYFIELD(this)
Compcode.Top = 3
Compcode.Left = 1
Compcode.Datalink = "CompCode"
Compcode.Enabled = .F.
* user cannot change Compcode

DEFINE object syntax:

DEFINE Entryfield Compcode OF THIS;
  AT 3,1;
  Property;
     Datalink "CompCode",;
     Enabled .F.


See Also

Visible


EscExit

See Also	Example	Properties	Forms

Determines if the user can close a form by pressing Esc.

Property of Class

FORM

Data Type

Logical

Default

The default for EscExit is true (.T.).

Description

Set EscExit to false (.F.) to prevent the user from closing a form by pressing Esc.


EscExit Example

NEW operator syntax:

LOCAL f
f=NEW EntryForm()
f.OPEN()
CLASS EntryForm OF FORM
  this.Top=2
  this.Left=2
  this.Height=10
  this.Width = 20
  this.EscExit=.F.

DEFINE object syntax:

DEFINE FORM EntryForm ;
  PROPERTY;
  Top 2, Left 2, Height 10, Width 20,;
  EscExit .F.


See Also

ON ESCAPE

SET ESCAPE


Execute( )

See Also	Example	Properties

Sends a command string to a DDE server application in its own language.

Property of Class

DDELINK

Description

Use the Execute( ) method to send macro instructions to a server application.

Execute( ) requires the <command> parameter, which is a string consisting of at least one command in the language of the server. Surround each command with the delimiters required by the server application. For example, each Quattro Pro command is surrounded with braces ({ }). Some applications accept multiple commands separated by brackets. For information, consult your DDE server documentation.

Before you can send a command string to a server, you must open the server application, open the document, and establish a DDE link. For information on establishing DDE links, see Initiate( ) and Chapter 26 in the Programmer's Guide.


Execute( ) Example

PUBLIC LinkObj
LinkObj = NEW DDELINK()
LinkObj.Initiate("QPW","Demo.WB1")
? LinkObj.Execute('{OPEN "C:INFO\Data.TXT",W}');
            && Creates text file Data.TXT
? LinkObj.Execute('{WRITELN +A1}');
            && Send contents of QPW cell A1 to;                                           	            Data.TXT
? LinkObj.Execute('{WRITELN +A2}');
            && Send contents of QPW cell A2 to;
               Data.TXT
? LinkObj.Execute('{CLOSE}');
            && Closes Data.TXT


See Also

Advise( )

Initiate( )

OnNewValue

Peek( )

Poke( )

Server

Terminate( )

Timeout

Topic

Unadvise( )


Fields

See Also	Example	Properties	Forms

Specifies the fields to display in a browse object, and the field options to apply to each field.

Property of Class

BROWSE

Data Type

Character

Default

The default for Fields is an empty string.

Description

The value you place in Fields must be surrounded by quotation marks and should have the following format:

"<field 1> [<field option list 1>] |
<calculated field 1> = <exp1> [<calculated field option list 1>]
[, <field 2> [<field option list 2>] |
<calculated field 2> = <exp1> [<calculated field option list 2>], ...]"

The fields are displayed in the order they are listed, and the field option lists affect the way the fields are displayed. The options are as follows:

/<column width>	The width of the column within which <field 1> appears when <field 1> is character type
/B = <exp 1>, <exp 2> [/F]	RANGE option; forces any value entered in <field 1> to fall within <exp 1> and <exp 2>, inclusive. RANGE REQUIRED option; the /F option prevents a previously entered value from being accepted if it does not fall between <exp 1> and <exp 2>, inclusive
/H = <expC>	HEADER option; causes <expC> to appear above the field column in the Table Records window, replacing the field name
/P = <expC>	PICTURE option; displays <field 1> according to the PICTURE or FUNCTION clause <expC>
/R	READ-ONLY option; specifies that <field 1> is read-only and cannot be edited
/V = <condition> [/F] [/E = <expC>]	VALID option; allows a new <field 1> value to be entered only when <condition> evaluates to .T. VALID REQUIRED option; the /F option prevents the user from leaving <field 1> and the editing session from ending until <condition> evaluates to .T. ERROR MESSAGE option; /E = <expC> causes <expC> to appear when <condition> evaluates to .F.
/W = <condition>	WHEN option; allows <field 1> to be edited only when <condition> evaluates to .T.
Read-only calculated fields are composed of an assigned field name and an expression that results in the calculated field value, as with Commission = Rate * Saleprice. Options for calculated fields affect the way these fields are displayed. These options are as follows:

/<column width>	The width of the column within which <calculated field 1> is displayed
/H = <expC>	Causes <expC> to appear above the calculated field column in the Table Records window, replacing the calculated field name
Calculated fields are read-only.

Note:	You can select a field with the Browse Field Picker. To access the Browse Field Picker, click the Tool button next to the Fields item in the Object Inspector.


Fields Example

NEW operator syntax:

this.Br1 = NEW BROWSE(this)
  this.Br1.Alias="Contact"
  this.Br1.Fields="CompCode /R,Contact"
  this.Br1.Top=4
  this.Br1.Left=3
  this.Br1.Width=32
  this.Br1.Height=12

DEFINE object syntax:

DEFINE BROWSE Br1 OF THIS;
  PROPERTY;
  Top 4, Left 3, Width 32, Height 12,;
  Alias "Contact",;
  Fields "CompCode /R, Contact"


See Also

Alias

DataLink

DataSource

SET FIELDS


Fields( )

See Also	Example	Properties

Stores the structure information of the current table to an array object and returns the number of fields whose characteristics are stored.

Property of Class

ARRAY

Description

Use the Fields( ) method to store information about the structure of the current table in an array object. Each row in the array object contains information on a single field in the current table. The Fields( ) method is similar to the AFIELDS( ) function.

Fields( ) dynamically sizes the array object so the number of rows is at least equal to the number of fields in the current table, and the number of columns is at least four. If the array contains more elements than are needed to store the table structure, the extra elements are left unchanged.

The following table shows which field characteristics Fields( ) stores, and in which column the information is placed:

Column 1	Column 2	Column 3	Column 4
Field name (character data type)	Field type (character data type)	Field length (numeric data type)	Decimal places (numeric data type)
dBASE uses the following codes for field types: C--character, D--date, L--logical, M--memo, N--numeric, F--float, G--ole, B--binary.

Fields( ) stores the same information into an array object that COPY TO...STRUCTURE EXTENDED stores into a table, except Fields( ) does not create a row containing FIELD_IDX information.


Fields( ) Example

USE Customer.DBF

* Initialize an array object to hold

* the structure of Customer.DBF.

ObjArr=NEW ARRAY(FLDCOUNT(),4)

* Fill array with .DBF file structure

* information.

ObjArr.Fields()

* Display array contents in the Command

* window results pane.

FOR i=1 TO FLDCOUNT()

? ObjArr[i,1],ObjArr[i,2] AT 20,;

  ObjArr[i,3] AT 25, ObjArr[i,4] AT 35

NEXT i


See Also

AFIELDS( )

COPY TO...STRUCTURE EXTENDED

Dir( )

Element( )

Scan( )

Sort( )

Subscript( )


FieldWidth

See Also	Example	Properties	Forms

Specifies the width of a character field in a browse object.

Property of Class

BROWSE

Data Type

Numeric

Default

The default for FieldWidth is the length of the table field or the length of the field name, whichever is greater.

Description

Use FieldWidth to limit the display width of a character field in a browse object.

If the text in a character field exceeds the field length, the user accesses the entire field by scrolling within it.


FieldWidth Example

NEW operator syntax:

USE Animals.DBF

LOCAL f

f=NEW Brws()

f.OPEN()

CLASS Brws OF FORM

  this.Width = 45

  this.Br1=NEW BROWSE(this)

  this.Br1.Top=2

  this.Br1.Left=1

  this.Br1.Width=40

  this.Br1.Height=10

  this.Br1.FieldWidth=10

ENDCLASS

DEFINE object syntax:

* Form definition

DEFINE BROWSE Br1 OF THIS;

  PROPERTY;

  Top 2, Left 1, Width 40,;

  Height 10, FieldWidth 10


See Also

ShowHeading

ShowRecNo


Fill( )

See Also	Example	Properties

Inserts a specified value into one or more locations in an array object.

Property of Class

ARRAY

Description

Use the Fill( ) method to insert a value into all or some elements of an array object. The Fill( ) method is similar to the AFILL( ) function.

Fill( ) accepts three parameters:

<exp> is the value to insert into the array object.

<start expN> is the element number at which to begin inserting <exp>. (If you know only the element's subscripts, you can use Element( ) to determine the element number.) If you do not specify <start expN>, dBASE begins at the first element in the array object.

<count expN> is the number of elements in which to insert <exp>, starting at element <start expN>. If you do not specify <count expN>, Fill( ) inserts <exp> from <start expN> to the last element in the Array. If you specify a value for <count expN>, also specify a value for <start expN>.

If you do not specify <start expN> or <count expN>, Fill( ) fills all elements with <exp>.


Fill( ) Example

Use Animals.Dbf

* Initialize an array object

ObjArr=NEW ARRAY(RECCOUNT(),3)

* Fill all elements with the string "Test" and

* display contents in Command window results pane

ObjArr.Fill("Test")

FOR i=1 TO RECCOUNT()

? ObjArr[i,1],ObjArr[i,2], ObjArr[i,3]

NEXT i


See Also

AFILL( )

Dir( )

Element( )

Fields( )

Subscript( )


First

See Also	Example	Properties	Forms

Determines which object is the first to get focus when its parent form is opened.

Property of Class

FORM

Data Type

Object reference

Description

Use the First property to reference the object that gets focus initially when you open a form. First is a read-only property.

When a form holds two or more objects that users can select, the user can move from object to object by pressing Tab or Shift+Tab. The order in which focus moves from object to object is known as the tabbing order. The object reference variable contained in First references the object at the beginning of the tabbing order.

For more information on object reference variables, see Chapter 10 in the Programmer's Guide.


First Example

NEW operator syntax:

LOCAL f

f=NEW EntryForm()

f.OPEN()

CLASS Entryform OF FORM

  this.view="Company.DBF"

  this.Fld1 = NEW Entryfield(this)

  this.Fld1.Top = 3

  this.Fld1.Left = 1

  this.Fld1.Width=20

  this.Fld1.Datalink = "Company->Company"

  this.Fld2 = NEW Entryfield(this)

  this.Fld2.Top = 5

  this.Fld2.Left = 1

  this.Fld2.Datalink = "Company->State_Prov"

  this.Fld2.Before = this.First

ENDCLASS

DEFINE object syntax:

DEFINE Entryfield Company OF THIS;

  Property Datalink "Company->Company",;

  WIDTH 20, Top 3, Left 1

DEFINE Entryfield State OF THIS;

  Property Datalink "Company->State_Prov",;

  Before this.First, Top 5, Left 1


See Also

ActiveControl

_curobj

Before

NextObj

SetFocus( )


FocusBitmap

See Also	Example	Properties	Forms

Specifies the graphic image to display in a pushbutton when the pushbutton has focus.

Property of Class

PUSHBUTTON

Data Type

Character

Default

The default for FocusBitmap is an empty string.

Description

Use FocusBitmap to indicate visually when a pushbutton is selected.

The FocusBitmap setting can take one of two forms:

RESOURCE <resource id> <dll name> specifies a bitmap resource and the DLL file that holds it. (A DLL file is a precompiled library of external routines and resources written in non-dBASE languages such as C and Pascal.) You can obtain the resoure ID with a resource editor such as Resource Workshop.

FILENAME <filename> specifies a bitmap file (which usually has the file-name extension .BMP).

If you specify a character string with Text and an image with FocusBitmap, the image is displayed with the character string when the pushbutton has focus.

Note:	You can select a bitmap file with the Choose Bitmap dialog box. To access the Choose Bitmap dialog box, click the Tool button next to the FocusBitmap item in the Object Inspector.


FocusBitmap Example

See DownBitmap for an example of FocusBitmap.


See Also

DEFINE

DisabledBitmap

DownBitmap

Enabled

UpBitmap


Follow

See Also	Example	Properties	Forms

Determines if the display in a browse object follows a record to its new index order when a key field value is changed.

Property of Class

BROWSE

Data Type

Logical

Default

The default for Follow is true (.T.).

Description

Set Follow to true (.T.) to prevent the apparent disappearance of a record in a browse object when the records are in indexed order and the user changes a value in a key field.

When records are in indexed order, changing a key field value in a record changes the position of the record in the table. In a browse object, the changed record might disappear from the display view. Setting Follow to true prevents this.


Follow Example

NEW operator syntax:

this.Br1 = NEW BROWSE(this)

  this.Br1.Alias="Contact"

  this.Br1.Fields="CompCode,Contact"

  this.Follow=.F.

  this.Br1.Top=4

  this.Br1.Left=3

  this.Br1.Width=32

  this.Br1.Height=12

DEFINE object syntax:

DEFINE BROWSE Br1 OF THIS;

  PROPERTY;

  Top 4, Left 3, Width 32, Height 12,;

  Alias "Contact", Follow .F.,;

  Fields "CompCode, Contact"


See Also

Modify


FontBold

See Also	Example	Properties	Forms

Determines if an object displays characters in bold type.

Property of Class

BROWSE, CHECKBOX, COMBOBOX, EDITOR, ENTRYFIELD, LISTBOX, PUSHBUTTON, RADIOBUTTON, RECTANGLE, SPINBOX, TEXT

Data Type

Logical

Default

The default for FontBold is false (.F.) for all classes except EDITOR, ENTRYFIELD, PUSHBUTTON, RADIOBUTTON, SPINBOX, and TEXT.

Description

Use FontBold when you want to draw attention to text in an object prompt or text in an entry area.

For example, when you set FontBold property of a check box to true (.T.), the check box prompt is displayed in bold type. When you set the FontBold property of an entry field to true, the text in the entry field is displayed in bold type.


FontBold Example

See FontName for an example of FontBold.


See Also

FontItalic

FontName

FontSize

FontStrikeOut

FontUnderline


FontItalic

See Also	Example	Properties	Forms

Determines if an object displays characters in italic type.

Property of Class

BROWSE, CHECKBOX, COMBOBOX, EDITOR, ENTRYFIELD, LISTBOX, PUSHBUTTON, RADIOBUTTON, RECTANGLE, SPINBOX, TEXT

Data Type

Logical

Default

The default for FontItalic is false (.F.).

Description

Use FontItalic when you want to give emphasis to text in an object prompt or text in an entry area.

For example, when you set the FontItalic property of a check box to true (.T.), the prompt is displayed in italic type. When you set the FontItalic property of an entry field to true, the text in the entry field is displayed in italic type.


FontItalic Example

See FontName for an example of FontItalic.


See Also

FontBold

FontName

FontSize

FontStrikeOut

FontUnderline


FontName

See Also	Example	Properties	Forms

Determines which font is applied to characters displayed in an object.

Property of Class

BROWSE, CHECKBOX, COMBOBOX, EDITOR, ENTRYFIELD, LISTBOX, PUSHBUTTON, RADIOBUTTON, RECTANGLE, SPINBOX, TEXT

Data Type

Character

Default

The default for FontName is MS Sans Serif.

Description

Use FontName to determine the visual appearance of characters in an object. For example, you can display characters in Arial format by inserting "Arial" into the Name property of a text object.

If the font you specify with FontName is not installed in your Windows environment, dBASE uses the default font, MS Sans Serif.

Note:	You can select a font with the Font dialog box, which displays all installed fonts. To access the Font dialog box, click on the Tool button next to the FontName item in the Object Inspector. You can also open the Font dialog box with the GETFONT( ) function.


FontName Example

NEW operator syntax:

Code = NEW ENTRYFIELD(this)

Code.Top = 5

Code.Left = 20

Code.Datalink = "Contact->CompCode"

Code.Height = 2

Code.FontBold = .T.

Code.FontSize = 12.00

Code.FontName = "Arial"

Code.FontItalic  = .T

DEFINE object syntax:

DEFINE ENTRYFIELD Code OF THIS;

  Property;

     Top 5, Left 20

     Datalink "Contact->CompCode",;

     Height 2,;

     FontBold .T.,;

     FontSize 12.00,;

     FontName "Arial",;

     FontItalic .T.


See Also

FontBold

FontItalic

FontSize

FontStrikeOut

FontUnderline

ScaleFontName


FontSize

See Also	Example	Properties	Forms

Specifies the size of text characters in an object.

Property of Class

BROWSE, CHECKBOX, COMBOBOX, EDITOR, ENTRYFIELD, LISTBOX, PUSHBUTTON, RADIOBUTTON, RECTANGLE, SPINBOX, TEXT

Data Type

Numeric

Description

Use FontSize to adjust the size of characters displayed in an object. Character size is given in point size; the higher the point size, the larger the characters in the font.


FontSize Example

NEW operator syntax:

 this.Txt2 =NEW Text(this)

    this.Txt2.Top = 5

    this.Txt2.Left = 0

    this.Txt2.Alignment = 4

    this.Txt2.Text = "is here in '94"

    this.Txt2.Height = 2

    this.Txt2.Width = 50

    this.Txt2.FontSize = 16

DEFINE object syntax:

 DEFINE TEXT Txt2 OF THIS AT 5,4;

    PROPERTY;

      Alignment 4,;

      Text "is here in '94",;

      Height 2,;

      Width 50,;

      FontSize 16


See Also

FontBold

FontItalic

FontName

FontStrikeOut

FontUnderline

ScaleFontSize


FontStrikeOut

See Also	Example	Properties	Forms

Determines if an object displays characters in strikeout type.

Property of Class

CHECKBOX, COMBOBOX, EDITOR, ENTRYFIELD, LISTBOX, PUSHBUTTON, RADIOBUTTON, RECTANGLE, SPINBOX, TEXT

Data Type

Logical

Default

The default for FontStrikeOut is false (.F.).

Description

Use FontStrikeOut when you want to draw a line through text in an object.

For example, when you set the FontStrikeOut property of a check box to true (.T.), the check box prompt is displayed in strikeout type. When you set the FontStrikeOut property of an entry field to true, the text in the entry field is displayed in strikeout type.


FontStrikeOut Example

NEW operator syntax:

LOCAL f

f=NEW StrkOut()

f.OPEN()

CLASS StrkOut OF FORM

   this.ETF1 = NEW ENTRYFIELD(this)

   this.ETF1.Top = 2

   this.ETF1.Left = 16

   this.ETF1.Width=6

   this.ETF1.Value = SPACE(6)

   this.ETF1.FontStrikeOut=.T.

ENDCLASS

DEFINE object syntax:

* Form definition

DEFINE ENTRYFIELD ETF1 OF THIS;

  PROPERTY Top 2, Left 16, Width 6,;

  Value SPACE(6), FontStrikeOut .T.


See Also

FontBold

FontItalic

FontName

FontSize

FontUnderline


FontUnderline

See Also	Example	Properties	Forms

Determines if an object displays characters in underlined type.

Property of Class

CHECKBOX, COMBOBOX, EDITOR, ENTRYFIELD, LISTBOX, PUSHBUTTON, RADIOBUTTON, RECTANGLE, SPINBOX, TEXT

Data Type

Logical

Default

The default for FontUnderline is false (.F.).

Description

Use FontUnderline when you want to underscore text in an object prompt or text in an entry area.

For example, when you set a the FontUnderline property of a check box to true (.T.), the check box prompt is underlined. When you set the FontUnderlined property of an entry field to true, the text in the entry field is underlined.


FontUnderline Example

See FontName for an example of FontUnderline.


See Also

FontBold

FontItalic

FontName

FontSize

FontStrikeOut


Function

See Also	Example	Properties	Forms

Formats text displayed in an object.

Property of Class

ENTRYFIELD, SPINBOX, TEXT

Data Type

Character

Default

The default for Function is an empty string.

Description

The argument you give to Function consists of one or more function symbols, which should not be separated by spaces, commas, or other characters.

dBASE recognizes the following function symbols:

(	Encloses negative numbers in parentheses.

!	Converts letters to uppercase.

^	Displays numbers in exponential form.

$	Inserts a dollar sign or the symbol defined with SET CURRENCY TO instead of leading spaces.

A	Restricts entry to alphabetic characters.

B	Left-aligns a numeric entry.

C	Displays CR (credit) after a positive number.

D	Displays and accepts entry of a date in the current SET DATE format.

E	Displays and accepts entry of a date in European (DD/MD/YY) format.

I	Centers the entry.

J	Right-aligns the entry.

L	Displays numbers with leading zeros.

M	Sequentially displays predefined options each time the user presses SpaceBar. Specify the options by listing them (separated with commas) after @M.

R	Inserts literal characters into the display without including them in the field.

S<n>	Limits the width of the display to <n> characters and horizontally scrolls the characters within it in <n> columns. <n> must be a positive integer.

T	Removes leading and trailing spaces from character values.

V<n>	Wraps a character string within a width specified by <n>. The width is measured in inches multiplied by 10 (for example, an <n> value of 15.5 is equivalent to 1.55 inches).

X	Displays DB (debit) after a negative number.

Z	Displays zeros as a blanks.


Function Example

See DataLink for an example of Function.


See Also

DEFINE

Picture


GetTextExtent( )

See Also	Example	Properties	Forms

Returns the length of a text string in units based on the font size of a parent form.

Property of Class

TEXT

Description

Use GetTextExtent( ) to calculate a value for the Width property of a text object. For example, you need to adjust the Width setting of a text object each time a new character string is displayed, if the new string exceeds the current width of the text object.

GetTextExtent( ) compares the font of the text object with the font of the parent form and returns the width of the character string in character units. The width of a character unit is equal to the width of a column in the coordinate plane of the parent form. Placing the character unit width of the string in the Width property of the text object resizes the object to contain the string.

GetTextExtent( ) accepts the <text string> parameter, a character string.


GetTextExtent( ) Example

This example creates a form with two long entry fields. On leaving the second field, OnLostFocus property calls a procedure that initializes a string variable from the concatenation of both entry fields. The procedure then uses GetTextExtent( ) to return the length of the string (according to the current font) so that the width property of text object T1 can be changed to accommodate the concatenated string:

LOCAL f
f = NEW XFORM()
f.Open()

CLASS XFORM OF FORM
   this.HelpFile = ""
   this.Top =          2.76
   this.Height =         11.71
   this.Text = "Form"
   this.Left =         53.00
   this.Width =         41.80
   this.HelpId = ""

   DEFINE ENTRYFIELD FNAME OF THIS;
       PROPERTY;
         Top          3.00,;
         Height          1.00,;
         Value "                    ",;
         Border .T.,;
         Left          6.00,;
         Width         20.00

   DEFINE ENTRYFIELD LNAME OF THIS;
       PROPERTY;
         OnLostFocus CLASS::XLENGTH,;
         Top          5.00,;
         Height          1.00,;
         Value "                    ",;
         Border .T.,;
         Left          6.00,;
         Width         20.00

   DEFINE TEXT T1 OF THIS;
       PROPERTY;
         Top          7.00,;
         Height          1.00,;
         Border .F.,;
         Text "First and Last Name",;
         ColorNormal "N/W",;
         Left          6.00,;
         Width         25.00

         PROCEDURE xLength
           ExtString =;
           TRIM(form.Fname.Value)+" "+form.Lname.Value
           Form.T1.Width =;
           form.T1.GetTextExtent(ExtString)
           Form.T1.Text = ExtString

ENDCLASS


See Also

FontName

FontSize

LEN( )

ScaleFontName

ScaleFontSize


Group

See Also	Example	Properties	Forms

Starts an object group in the tabbing order of the parent form.

Property of Class

CHECKBOX, PUSHBUTTON, RADIOBUTTON

Data Type

Logical

Description

Use Group to determine if an object is part of a group within which the user can move focus with the arrow keys.

When you use Group to group two or more radio buttons together, the user can select only one button from the group at a time. This is useful when you want the user to select one out of several values.

To create a group, set the Group property of the first object in the group to true. For all other objects that belong to the group, set Group to false (.F.). The next object with a Group setting of true begins another group.


Group Example

NEW operator syntax:

Answer=""

Yes = New RADIOBUTTON(this)

Yes.Text = "Yes"

Yes.DataLink = "Answer"

Yes.Group = .F.

No = New RADIOBUTTON(this)

No.Top = 5

No.Text = "No"

No.DataLink = "Answer"

DEFINE object syntax:

Answer=""

DEFINE RADIOBUTTON Yes OF THIS;

   PROPERTY;

      Text "Yes",;

      DataLink "Answer",;

      Group .F.

DEFINE RADIOBUTTON No OF THIS;

   PROPERTY;

      Top 5,;

      Text "No",;

      DataLink "Answer"


See Also

_curobj

ID

TabStop


Grow( )

See Also	Example	Properties

Adds elements to an array object.

Property of Class

ARRAY

Description

Use the Grow( ) method to add an element, row, or column to an array object. All new elements have the value logical .F. The Grow( ) method is similar to the AGROW( ) function.

Grow( ) accepts one required <expN> parameter, which can be 1 or 2. If you attempt to assign a value other than 1 or 2, dBASE displays the error message "Invalid function argument".

If you set <expN> to 1, Grow( ) adds a single element to a one-dimensional array object or a row to a two-dimensional array object.

If you set <expN> to 2, Grow( ) adds a column to the array object. If the array object is one-dimensional, Grow( ) makes it two-dimensional; it moves existing elements to the first column and fills the second column with .F. values.

If the array object is two-dimensional, Grow( ) adds a column at the end of the array and fills the new elements with .F. values.

See Insert( ) for another way to add elements to an array object. To add multiple rows or columns to an array object, use Resize( ).


Grow( ) Example

USE Customer.DBF

* Initialize an array object

ObjArr=NEW ARRAY(RECCOUNT())

* Fill 1-dimensional array with values

* from Name field of Customer.DBF

GO TOP

FOR i=1 TO RECCOUNT()

  ObjArr[i]=Customer->Name

  SKIP

NEXT i

* Use GROW() to add a second column to the

* existing array and enter Ytd_Sales data

* in new second column.

ObjArr.GROW(2)

GO TOP

FOR i=1 TO RECCOUNT()

  ObjArr[i,2]=Customer->Ytd_Sales

  SKIP

NEXT i

* Display Contents of 2-dimensional array

FOR i=1 TO RECCOUNT()

? ObjArr[i,1], ObjArr[i,2]

NEXT i


See Also

AGROW( )

Insert( )

Resize( )


Height

See Also	Example	Properties	Forms

Determines the height of an object.

Property of Class

BROWSE, CHECKBOX, COMBOBOX, EDITOR, ENTRYFIELD, FORM, IMAGE, LISTBOX, OLE, PUSHBUTTON, RADIOBUTTON, RECTANGLE, SCROLLBAR, SPINBOX, TEXT

Data Type

Numeric

Description

Use the Height property in combination with the Width property to adjust the size of an object. The setting you give to Height determines the distance from the base of an object to its top.

Each unit of the value you assign to Height is the average height of characters in the active font of the parent form. For example, if you set the Height property of an editor object to 17.5, the editor object is 17.5 characters high.

Since Height accepts integer or noninteger values, you can adjust the height of an object to a high degree of precision.


Height Example

NEW operator syntax:

Code = NEW ENTRYFIELD(this)

Code.Top = 5

Code.Left = 1

Code.Datalink = "Contact->CompCode"

Code.Height = 2

Code.Left = 20

* Because the default height for an

* entryfield is 1.17, setting height to

* 2 in this example merely offers additional

* space around the field value.

DEFINE object syntax:

DEFINE ENTRYFIELD Code OF THIS AT 5,1;

  Property;

     Datalink "CompCode",;

     Height 2, Left 20


See Also

Left

Top

Width


HelpFile

See Also	Example	Properties	Forms

Identifies a Windows Help file (.HLP) that contains context-sensitive Help topics.

Property of Class

BROWSE, CHECKBOX, COMBOBOX, EDITOR, ENTRYFIELD, FORM, LISTBOX, MENU, OLE, PUSHBUTTON, RADIOBUTTON, SCROLLBAR, SPINBOX

Data Type

Character

Default

The default for HelpFile is an empty string.

Description

Use HelpFile in combination with HelpID to connect an object to a topic in a Windows Help file. For example, HelpID might identify a Help topic that gives instructions on using a combo box.

Enter the name of the Help file into the HelpFile property, and set the HelpID property to the Help keyword of the topic. When the user gives focus to the object and presses F1, Windows Help opens the Help file and displays the Help topic.

For information on creating Help files and Help topics, see your Windows documentation.

Note:	Any subroutine you specify with the OnHelp property overrides the values you assign to HelpFile and HelpID.


HelpFile Example

NEW operator syntax:

Company = NEW ENTRYFIELD(this)

Company.Top = 3

Company.Left = 1

Company.Datalink = "Company"

Company.HelpFile = "DataEntr"

Company.HelpId = 100

DEFINE object syntax:

DEFINE ENTRYFIELD Company OF THIS AT 3,1;

  Property;

     Datalink "Company",;

     HelpFile "DataEntr",;

     HelpId 100


See Also

HELP

HelpID

OnHelp

SET HELP


HelpID

See Also	Example	Properties	Forms

Specifies the Help keyword of a Windows Help topic.

Property of Class

BROWSE, CHECKBOX, COMBOBOX, EDITOR, ENTRYFIELD, FORM, LISTBOX, MENU, OLE, PUSHBUTTON, RADIOBUTTON, SCROLLBAR, SPINBOX

Data Type

Character

Default

The default for HelpID is an empty string.

Description

Use HelpID in combination with HelpFile to connect an object with a topic in a Windows Help file (.HLP). For example, HelpFile might contain a Help topic that gives instructions on using the objects in a form.

Set the HelpID property to the Help keyword of the topic and enter the name of the Help file into the HelpFile property. When the user gives focus to the object and presses F1, the Help system opens the Help file and displays the Help topic.

Note:	Any subroutine you specify with the OnHelp property overrides the values you assign to HelpID and HelpFile.


HelpID Example

See HelpFile for an example of HelpId.


See Also

HELP

HelpFile

OnHelp

SET HELP


hWnd

See Also	Example	Properties	Forms

Specifies an object handle.

Property of Class

BROWSE, CHECKBOX, COMBOBOX, EDITOR, ENTRYFIELD, FORM, IMAGE, LISTBOX, PUSHBUTTON, RADIOBUTTON, RECTANGLE, SCROLLBAR, SPINBOX

Data Type

Numeric

Default

There is no default for hWnd; Windows generates the value automatically.

Description

An object handle is a unique numeric value that Windows generates automatically for each object you create. External functions written in other languages such as C, Pascal, or ASM use this handle to identify the object. For example, you can pass the object handle of a form as a parameter to an external function, perhaps allowing the function to open or close the form.

Such external functions are held in external C libraries such as Windows API or a customized DLL file you create yourself. For more information on external functions and on DLL files, see EXTERN, LOAD DLL, and Chapter 25 in the Programmer's Guide.

The hWnd property is read-only.


hWnd Example

DEFINE FORM Entry FROM 2,2 TO 30,70

DEFINE ENTRYFIELD Company OF THIS;

  PROPERTY;

    Datalink "Company"

    FormHandle=Entry.hwnd            && e.g. 14260

    CompanyHandle=Entry.Company.hwnd && e.g. 14348


See Also

EXTERN

LOAD DLL


ID

See Also	Example	Properties	Forms

Identifies an object with a numeric value.

Property of Class

BROWSE, CHECKBOX, COMBOBOX, EDITOR, ENTRYFIELD, FORM, IMAGE, LISTBOX, MENU, PUSHBUTTON, RADIOBUTTON, SCROLLBAR, SPINBOX

Data Type

Numeric

Description

Use ID to give a unique identifier to an object.

For example, when the user chooses a pushbutton, the form is submitted, executing the subroutine or codeblock you assigned with the OnSelection property or the ON SELECTION FORM command. The value in ID is passed to the subroutine or codeblock, identifying the pushbutton that submitted the form.

If you wish, you can can use the ID value to make branching decisions based on which object executed the OnSelection subroutine. To be sure that ID correctly identifies the object it represents, give it a unique value for each object.

The ID property of menu objects is generated by dBASE automatically, and is read-only.


ID Example

NEW operator syntax:

Date = NEW ENTRYFIELD(this)

Date.Datalink = "Clients->Baldate"

Date.Id = 10

DEFINE object syntax:

DEFINE ENTRYFIELD Date OF THIS;

  PROPERTY Datalink "Clients->Baldate",;

  ID 10


See Also

OnSelection

ON SELECTION FORM

PARAMETERS


Initiate( )

See Also	Example	Properties

Starts a conversation with an external application.

Property of Class

DDELINK

Description

Use Initiate( ) to open a channel of communication (known as a DDE link) between dBASE and an external Windows application.

Use a DDE link to exchange data and instructions with another application. For example, a data-exchange program might use Initiate( ) to establish a link with Quattro Pro for Windows and open one of its spreadsheet files, then copy data from the spreadsheet to a dBASE table.

If the external application is not already running when you execute Initiate( ), dBASE tries to start the application before establishing the DDE link. If the attempt is unsuccessful, Initiate( ) returns a value of false (.F.).

Initiate( ) requires two parameters:

<server> is the main executable file of the server application.

<topic> is the name of the data file to open in the server session.

To terminate the DDE link, use the Terminate( ) method.


Initiate( ) Example

PUBLIC LinkObj

LinkObj = NEW DDELINK()

LinkObj.Initiate("QPW","Demo.WB1");

               && Attempt to establish a link with a;

                  QPW server


See Also

Advise( )

Execute( )

OnNewValue

Peek( )

Poke( )

Server

Terminate( )

Timeout

Topic

Unadvise( )


Insert( )

See Also	Example	Properties

Inserts a .F. value into an element in a one-dimensional array object, or inserts .F. values into a row or column of elements in a two-dimensional array object.

Property of Class

ARRAY

Description

Use Insert( ) to insert .F. values into selected elements in an array object without changing the size of the array object. Insert( ) does the following:

Inserts an element in a one-dimensional array, or inserts a row or column in a two-dimensional array

Moves all remaining elements toward the end of the array (down if a row is inserted, to the right if an element or column is inserted)

Inserts .F. values in the newly created element or elements

Insert( ) accepts two parameters:

<position expN> specifies the number of the element at which to insert the new element when the array object is one-dimensional. Specifies a row or column when the array object is two-dimensional.

2 determines if Insert( ) inserts a row or a column in a two-dimensional array object. If you specify 2, it inserts a row; otherwise, it inserts a column. Insert( ) ignores this parameter if the array object is one-dimensional.

For information about inserting elements by moving remaining elements toward the beginning of the array, see Delete( ). For information about replacing elements without moving remaining elements, see Fill( ). To change a one-dimensional array to two-dimensional, use Grow( ) or Resize( ).


Insert( ) Example

USE Animals.DBF

* Initialize an array object

ObjArr=NEW ARRAY(RECCOUNT(),3)

* Fill array with values from Animals.DBF

COPY TO ARRAY ObjArr FIELDS Name, Area, Weight

* Use Insert() to replace weight values in

* column 3 with .F..

ObjArr.Insert(3,2)

* Display results to Command window results pane

FOR i=1 TO RECCOUNT()

? ObjArr[i,1],ObjArr[i,2],ObjArr[i,3]

NEXT i


See Also

Add( )

Delete( )

Resize( )


Key

See Also	Example	Properties	Forms

Executes a subroutine when the user enters a keystroke in an entry field or a browse object.

Property of Class

BROWSE, ENTRYFIELD

Data Type

Function pointer or codeblock

Description

Use Key to evaluate and modify each character that the user enters in an entry field or browse object. For example, an entry field that accepts passwords might convert each character the user inputs to an asterisk.

Like other event properties, the Key property accepts

Functions

Procedures

Codeblocks

For information on these subroutines, see Chapter 4 in the Programmer's Guide. For information on writing event-handling routines, see Chapter 14 in the Programmer's Guide.

Key sends two parameters to its subroutine:

<nChar> is the ASCII decimal number of the new character entered by the user.

<nPosition> is the position of the new character in the string.

For example, when the third character entered in an entry field is "a", the <nChar> parameter is 97 and the <nPosition> parameter is 3.

Note:	You can write a subroutine with the Procedure Editor, a window in which you enter dBASE program code. To access the Procedure Editor, click on the Tool button next to the Key item in the Object Inspector.


Key Example

NEW operator syntax:

Company = NEW ENTRYFIELD(this)

Company.Datalink = "Company->Company"

Company.Key = AnyKey

* A Function Anykey will be called

FUNCTION ANYKEY(nChar, nPosition)

* process the keystroke

RETURN nChar + 1

DEFINE object syntax:

DEFINE ENTRYFIELD Company OF THIS;

  PROPERTY;

     Datalink "Company->Company",;

     Key AnyKey


See Also

OnChange

OnGotFocus


Left

See Also	Example	Properties	Forms

Specifies the position of the left border of an object relative to its parent form, or the position of a form relative to the desktop.

Property of Class

BROWSE, CHECKBOX, COMBOBOX, EDITOR, ENTRYFIELD, FORM, IMAGE, LINE, LISTBOX, OLE, PUSHBUTTON, RADIOBUTTON, RECTANGLE, SCROLLBAR, SPINBOX

Data Type

Numeric

Description

Use the Left property in combination with the Top property to position an object in a form or position a form in the desktop. (The Top property specifies the position of the top border.) Left and Top accept integer or noninteger values.

If you use the FROM or AT clauses of the DEFINE command and specify a value for the Left property, dBASE positions the object with the Left property.

Each unit of the value you assign to Left is the average width of characters in the active font of the parent form. For example, if you set the Left property of a line to 20, the left end of the line is positioned 20 characters from the left edge of the form.


Left Example

See Height for an example of Left.


See Also

CLASS FORM

Bottom

Height

Right

ScaleFontName

ScaleFontSize

Top

Width


LineNo

See Also	Example	Properties	Forms

Sets the current line in an editor object.

Property of Class

EDITOR

Data Type

Numeric

Default

The default for LineNo is 1.

Description

Use LineNo to move the cursor to a specified line in an editor object.

When you move the cursor to a line, the cursor maintains its original column position if the new line is long enough. If the line is not long enough, the cursor is placed at the end of the line.


LineNo Example

LOCAL f

f=NEW AdjustEdit()

f.OPEN()

CLASS AdjustEdit OF EDITOR

this.LineNo = 15 && Move cursor to 15th line.

ENDCLASS


See Also

Wrap


LinkFileName

See Also	Example	Properties	Forms

Identifies which OLE document file (if any) is linked with the current OLE field when that field is displayed in an OLE viewer.

Property of Class

OLE

Data Type

Character

Default

The default for LinkFileName is an empty string.

Description

Use LinkFileName to identify which OLE document file is linked with the current OLE field when that field is displayed in an OLE viewer.

An OLE viewer displays an OLE document (sometimes called an OLE object). An OLE document can be a graphic image, a document created by a word processor, or any other data object created by an external application. This external application is known as the OLE server. For example, a bitmap file (.BMP) created in Paintbrush can be an OLE document, and Paintbrush can be an OLE server, if you link the bitmap file to an OLE field with the Cut and Paste Link commands of the Edit menu. LinkFileName contains the name of this file.

LinkFileName is a read-only property.


LinkFileName Example

The following program creates a form that displays an OLE object and a pushbutton. The OnClick subroutine of the pushbutton uses LinkFileName to display the name of the document file in a message box.

LOCAL f
f = NEW XFORM()
f.Open()

CLASS XFORM OF FORM
   this.HelpFile = ""
   this.Top =          0.47
   this.Height =         26.00
   this.Text = "Form"
   this.View = "PICTURES.QBE"
   this.MousePointer =          1
   this.Left =         23.00
   this.Width =        101.20
   this.HelpId = ""

   DEFINE OLE OLE1 OF THIS;
       PROPERTY;
         DataLink "PICTURES->BITMAPOLE",;
         Top          1.00,;
         Height         21.00,;
         Border .T.,;
         Left          1.00,;
         Width         99.00

   DEFINE PUSHBUTTON BUTTON1 OF THIS;
       PROPERTY;
         Top         23.00,;
         Height          2.00,;
         OnClick CLASS::BUTTON1_ONCLICK,;
         Text "Push me for name of bitmap file.",;
         ColorNormal "N/W",;
         Default .T.,;
         Left         36.00,;
         Width         31.00

   Procedure BUTTON1_OnClick
   MSGBOX(form.OLE1.LinkFileName, "Here's the file...")

ENDCLASS


See Also

OleType

ServerName


Maximize

See Also	Example	Properties	Forms

Determines if a form can be maximized.

Property of Class

FORM

Data Type

Logical

Default

The default for Maximize is true (.T.).

Description

Like other windows, a form normally has a Minimize button and a Maximize button at the upper right corner. Choosing Minimize reduces the form to an icon, and choosing Maximize expands the form to fill the work area of the desktop.

Setting the Maximize property to false (.F.) removes the Maximize button, preventing the user from maximizing the form. This is useful when you want portions of the work area to be visible at all times, as when other forms are open or when the user needs access to the Command window.

Note:	When you set the MDI property of a form to true, the Maximize setting is ignored and the user can always maximize the form.


Maximize Example

NEW operator syntax:

f=NEW EntryForm()

f.OPEN()

CLASS EntryForm OF FORM

  this.MDI = .F.

  this.Maximize = .F.

  this.Minimize = .F.

ENDCLASS

DEFINE object syntax:

DEFINE FORM Entry FROM 1,1 TO 30,35;

  Property;

      MDI = .F.,;

      Maximize .F.,;

      Minimize .F.


See Also

MDI

Moveable

Minimize

Sizeable


MaxLength

See Also	Example	Properties	Forms

Specifies the scrolling width of an entry field.

Property of Class

ENTRYFIELD

Data Type

Numeric

Description

Use MaxLength to set a limit on how many columns the user can scroll text to the left in an entry field.

For example, the user can input data into an entry field even if it is not linked to a field. It might be necessary to limit the number of characters the user can input so the contents of the entry field can be placed in a character field later. Setting the MaxLength property to a number at or below the length of the field ensures that the user cannot enter too long of a string.

The columns are as wide as the average width of characters of the active font.


MaxLength Example

NEW operator syntax:

Company = NEW ENTRYFIELD(this)

Company.Top = 3

Company.Left = 1

Company.Datalink = "Company"

Company.MaxLength  = 10

DEFINE object syntax:

DEFINE ENTRYFIELD Company OF THIS;

  AT 3,1;

  Property;

     Datalink "Company",;

     MaxLength  10


See Also

Function

Height

Picture

ScaleFontName

ScaleFontSize

Width


MDI

See Also	Example	Properties	Forms

Determines if a form conforms to the Windows Multiple Document Interface (MDI) standard.

Property of Class

FORM

Data Type

Logical

Default

The default for MDI is true (.T.).

Description

MDI (Mutiple-Documents Interface) is a Windows feature that lets you open multiple document windows within the application window. An application such as dBASE uses MDI to manage multiple documents or multiple views of the same document within the main application window. These views or documents appear in separate document windows. If you want your form to appear as a document window, set MDI to true.

The following lists some of the characteristics of document windows:

Like application windows, they are moveable and sizeable

They are listed on the Windows menu even when they are active.

They have a Control-menu box, Maximize and Minimize buttons, and a title bar that contains the window name.

When they are active, their menus replace the menus in the main menu bar. (When the MDI property is false (.F.), the menus are displayed in the menu bar of the form instead.)

When you set the MDI property to true:

The form is a child of the application window.

The Minimize setting is ignored, so the user can always minimize the form.

The Maximize setting is ignored, so the user can always maximize the form.

The Sizeable setting is ignored, so the user can always resize the form.

The Moveable setting is ignored, so the user can always move the form.

The SysMenu setting is ignored, so the Control menu (also known as the system menu) is always accessible from the Control Menu box, a button at the upper left corner of a form.

The shortcut keystroke that closes the form is Ctrl+F4 instead of Alt+F4; that is, Alt+F4 closes the application window, while Ctrl+F4 closes the form.

An MDI form is modeless by definition, since focus can be removed from it. Consequently, you cannot open an MDI form with the READMODAL( ) function or the ReadModal( ) method.

For more information on MDI, consult your Windows documentation.


MDI Example

NEW operator syntax:

LOCAL f

f = NEW EntryForm()

f.MDI  = .F.

f.Open()

DEFINE object syntax:

DEFINE FORM EntryForm ;

  Property MDI  .F.

OPEN FORM EntryForm


See Also

CLASS FORM

Maximize

MenuFile

Minimize

Moveable

Sizeable

SysMenu


MenuFile

See Also	Example	Properties	Forms

Assigns a predefined menu system to a form.

Property of Class

FORM

Data Type

Character

Default

The default for MenuFile is an empty string.

Description

Use MenuFile to specify a menu definition file (.MNU) for a form.

A menu definition file is a text file that contains dBASE code for generating menus. dBASE displays the menus in the form or the Application window (depending on the MDI setting) when you open the form.

Note:	You can create a menu definition file with the Menu Designer, which you access by clicking the Tool button next to the MenuFile property in the Object Inspector.


MenuFile Example

NEW operator syntax:

LOCAL f

f=NEW Equipmnt()

CLASS Equipmnt OF FORM

  this.MDI = .F.

  this.ColorNormal = "W/B"

  this.Text = "Flight Equipment Management"

  this.Width = 78.00

  this.Height = 40.00

  this.View = "Equipmnt.QBE"

  this.MenuFile = "Equipmnt.MNU"

* See Equipmnt.WFM and Equipmnt.MNU on the

* DBASEWIN\SAMPLES directory.

DEFINE object syntax:

DEFINE FORM Equipmnt;

  PROPERTY;

  MDI .F.,;

  ColorNormal "W/B",;

  Width 78, Height 40,;

  View "Equipmnt.QBE",;

  MenuFile "Equipmnt.MNU"


See Also

CLASS MENU


Minimize

See Also	Example	Properties	Forms

Determines if a form can be minimized.

Property of Class

FORM

Data Type

Logical

Default

The default for Minimize is true (.T.).

Description

Like other windows, a form normally has a Minimize button and a Maximize button at the upper right corner. Choosing Minimize reduces the form to an icon, and choosing Maximize expands the form to fill the work area of the desktop.

Setting the Minimize property to false (.F.) removes the Minimize button, preventing the user from minimizing the form. This is useful when you want the form to be visible any time it is open, as when it contains objects or information that must be dealt with immediately.

Note:	When you set the MDI property of a form to true, the Minimize setting is ignored and the user can always minimize the form.


Minimize Example

See Maximize for an example of Minimize.


See Also

MDI

Moveable

Maximize

Sizeable


Mode

See Also	Example	Properties	Forms

Specifies the format of a browse object.

Property of Class

BROWSE

Data Type

Numeric

Default

The default for Mode is 0 (Browse).

Description

Use Mode to determine how data is displayed in a browse object.

You can assign Mode one of three values:

Mode value	Display format	Shows

0 (Browse)	Row-and-column display	Mutiple records

1 (Form Edit)	Form layout	Single record

2 (Columnar Edit)	Single-column layout	Single record

If the Toggle property is true (.T.), the user can switch between all of these formats by pressing F2.


Mode Example

NEW operator syntax:

CompanyBrowse = NEW BROWSE(this)

CompanyBrowse.Top = 3

CompanyBrowse.Left = 1

CompanyBrowse.Height = 10

CompanyBrowse.Width = 59

CompanyBrowse.Alias = "Company"

CompanyBrowse.Mode = 2

CompanyBrowse.Fields="Company,Ytd_Sales;

  :H='Sales,Ytd'"

DEFINE object syntax:

DEFINE BROWSE CompanyBrowse OF THIS;

  FROM 3,1 TO 13,60;

    PROPERTY;

      Alias "Company", Mode 2,;

      Fields "Company,Ytd_Sales:H='Sales, Ytd'"


See Also

BROWSE

CLASS BROWSE

EDIT


Modify

See Also	Example	Properties	Forms

Determines if the user can alter records in a browse or editor object.

Property of Class

BROWSE, EDITOR

Data Type

Logical

Default

The default for Modify is true (.T.).

Description

Set Modify to false (.F.) when you want to prevent users from changing records in a browse object. For example, a card catalog program might manage records on books in a library, and each record might hold a book description in a memo field. The program could let users view the descriptions in a browse object, but prevent users from altering them.


Modify Example

NEW operator syntax:

this.Br1=NEW BROWSE(this)

  this.Br1.Alias="Contact"

  this.Br1.Modify=.F.

  this.Br1.Top=4

  this.Br1.Left=3

  this.Br1.Width=32

  this.Br1.Height=12

DEFINE object syntax:

DEFINE BROWSE Br1 OF THIS;

  PROPERTY;

    Alias "Contact", Modify .F.,;

    Top 4, Left 3, Width 32, Height 12


See Also

Append

Delete


MousePointer

See Also	Example	Properties	Forms

Changes the appearance of the mouse pointer.

Property of Class

BROWSE, CHECKBOX, COMBOBOX, EDITOR, ENTRYFIELD, FORM, IMAGE, LISTBOX, OLE, PUSHBUTTON, RADIOBUTTON, RECTANGLE, SCROLLBAR, SPINBOX, TEXT

Data Type

Numeric

Default

The default for MousePointer is 0 (Default).

Description

Use MousePointer to provide a visual cue when the user moves the mouse pointer over an object. For example, one pointer style might mean an object is disabled, while another pointer style might mean the object is ready for input.

You can specify the following settings for MousePointer:

0  (Default)	N/A
1  (Arrow)
2  (Cross)
3  (IBeam)
4  (Icon)
5  (Size)
6  (Size NESW)
7  (Size S)
8  (Size NWSE)
9  (Size E)
10  (UpArrow)
11  (Wait)


MousePointer Example

NEW operator syntax:

DEFINE BROWSE Br1 OF THIS

  this.MousePointer=1

  this.Br1.Top=4

  this.Br1.Left=3

  this.Br1.Width=32

  this.Br1.Height=12

DEFINE object syntax:

DEFINE BROWSE Br1 OF THIS FROM 4,3 TO 16,35;

    PROPERTY MousePointer 1


See Also

OnMouseMove


Move( )

See Also	Example	Properties	Forms

Repositions and resizes an object in its parent form.

Property of Class

BROWSE, CHECKBOX, COMBOBOX, EDITOR, ENTRYFIELD, FORM, IMAGE, LISTBOX, OLE, RADIOBUTTON, PUSHBUTTON, RECTANGLE, SCROLLBAR, SPINBOX, TEXT

Description

Use the Move( ) method to change an objects position and dimensions.

Move( ) uses four parameters:

<left column expN> sets the position of the left border, affecting the value in the Left property.

<top row expN> sets the position of the top border, affecting the value in the Top property.

<width expN> sets the width, affecting the value in the Width property.

<height expN> sets the height, affecting the value in the Height property.

The units of distance you specify for Move( ) are based on the average width and height of characters in the active font.


Move( ) Example

NEW operator syntax:

this.Lb1 = NEW LISTBOX(THIS)

  this.Lb1.DataSource="FIELD Animals->Name"

  this.Lb1.Top=4

  this.Lb1.Left=6

  this.Lb1.Width=20

  this.Lb1.Height=12

  this.Lb1.OnRightMouseDown {;Form.Move(6,10,15,5)}

DEFINE object syntax:

DEFINE LISTBOX LB1 OF THIS;

    PROPERTY;

      DataSource "FIELD Animals->Name",;

      Top 4,;

      Left 6,;

      Width 20,;

      Height 12,;

      OnRightMouseDown {;Form.Move(6,10,15,5)}


See Also

Height

Left

ScaleFontName

ScaleFontSize

Top

Width


Moveable

See Also	Example	Properties	Forms

Determines if a form can be moved with the mouse.

Property of Class

FORM

Data Type

Logical

Default

The default for Moveable is true (.T.).

Description

When you set the Moveable property of a form to true, the form has a title bar at the top. The user can place the mouse over the title bar, hold the left mouse button down, and drag the form to another location. A form can be moved only if it has a title bar.

When you set the MDI property of a form to true, the Moveable setting is ignored and the user can always move the form.


Moveable Example

NEW operator syntax:

LOCAL f

f=NEW EntryForm()

f.OPEN()

CLASS EntryForm OF FORM

  this.Moveable = .F.

ENDCLASS

DEFINE object syntax:

DEFINE FORM EntryForm;

  Property Moveable .F.

OPEN FORM EntryForm


See Also

Left

Sizeable

Top


Multiple

See Also	Example	Properties	Forms

Determines if more than one item in a list box can be selected.

Property of Class

LISTBOX

Data Type

Logical

Default

The default for Multiple is false (.F.).

Description

When you set the Multiple property to true (.T.), the user can choose any number of the list box items (or none at all), and the list box is said to be multiple-choice. If you set Multiple to false, the user can choose only one prompt from the list box.

Multiple-choice list boxes are useful for allowing the user to make several choices at once. For example, a program written for a Human Resources department might allow the user to select several job applicants for interviewing. This program could let the user choose one or more applicants from a multiple-choice list box. (Each chosen prompt is tagged with a checkmark.)

Note:	To evaluate which prompts were chosen, use LISTSELECTED( ) or Selected( ).


Multiple Example

NEW operator syntax:

LB1 = NEW LISTBOX(this)

LB1.DataSource = "FIELD COMPANY->COMPANY"

LB1.Multiple = .T.

LB1.OnRightMouseDown = Checked

* Multiple companies can be chosen

DEFINE object syntax:

DEFINE LISTBOX LB1 OF THIS;

  PROPERTY;

    DataSource "FIELD COMPANY->COMPANY",;

    Multiple .T., OnRightMouseDown Checked

PROCEDURE Checked
FOR i=1 TO Form.LB1.Count()
  ? Form.LB1.Selected(i)
NEXT i
RETURN


See Also

Count( )

LISTSELECTED( )

Selected( )


Name

See Also	Example	Properties	Forms

A read-only property that specifies the name of an object.

Property of Class

BROWSE, CHECKBOX, COMBOBOX, EDITOR, ENTRYFIELD, FORM, IMAGE, LISTBOX, MENU, PUSHBUTTON, RADIOBUTTON, SCROLLBAR, SPINBOX, TEXT

Data Type

Character

Default

The default for Name is the name dBASE assigns to the object when you create it. For example, dBASE automatically assigns "BUTTON1" to the Name property of the first pushbutton you create with the Form Designer.

Description

Use the Name property to name an object.

When you create an object with the DEFINE command, you specify a name for the object with the <object name> parameter. For more information, see DEFINE.

When you create an object with the NEW operator, you can specify a name for the object with the second (optional) parameter. For example, the following commands create a form and an image object to display in it:

MyForm = NEW FORM()
MyImage = NEW IMAGE(MyForm, "OurImage")

The Name property of the new image object contains "OurImage".

Name is a read-only property.


Name Example

NEW operator syntax:

XXX = NEW LISTBOX(this)

XXX.DataSource = "FIELD COMPANY->Zip_P_Code"

XXX.Name = "ZipList"

* ZipList overrides XXX as the name of the object

DEFINE object syntax:

DEFINE LISTBOX XXX OF THIS;

  PROPERTY;

      DataSource "FIELD COMPANY->ZIP",;

      Name "ZipList"


See Also

DEFINE

ID


NextCol( )

See Also	Example	Properties	Forms

Returns the number of the next highest column position where an object can be placed in a form.

Property of Class

FORM

Description

Use NextCol( ) in combination with NextRow( ) to prevent the overlapping of objects in a form. For example, if you create an entry field, NextCol( ) returns the coordinate of the next available column and NextRow( ) returns the coordinate of the next available row.You can place a new object at these coordinates without covering the entry field.

The column coordinates returned by NextCol( ) are as wide as the average width of characters in the active font of the form.


NextCol( ) Example

LOCAL f

f=NEW EntryForm()

f.OPEN()

CLASS EntryForm of FORM

DEFINE ENTRYFIELD Fname OF this;

  PROPERTY;

  Top 3, Left 2, Width 20,;

  Value SPACE(20)

DEFINE ENTRYFIELD Lname OF this;

  PROPERTY;

  Top 5, Left 2, Width 20,;

  Value SPACE(20)

* Use NextRow() and NextCol() to define a

* pushbutton adjacent to and 4 columns to

* the right of the entry field Lname.

DEFINE PUSHBUTTON PB1 OF this;

  PROPERTY Text "Proceed",;

  Top this.NextRow()-2,;

  Left this.NextCol()+4,;

  Width 10

ENDCLASS


See Also

COL( )

NextRow( )

ROW( )

ScaleFontName

ScaleFontSize


NextObj

See Also	Example	Properties	Forms

Contains a reference to the object that follows the current object in the tabbing order of a parent form.

Property of Class

FORM

Data Type

Object reference

Description

Use NextObj to reference the next object to receive input focus when the user presses Tab.

Use NextObj in Valid subroutines to determine if validation is needed before moving to the next object. For example, the following commands determine if the next object is a Cancel pushbutton:

IF (MyForm.NextObj.Name = "Cancel")
RETURN .T.   && No validation is required.
ELSE
RETURN Validate()  && Validation routine
ENDIF


NextObj Example

The following example uses ActiveControl and NextObj to return the name of the current and next entry field objects when the right mouse is clicked on a form. This would be useful on a form where entry fields had no accompanying text to identify the fields:

LOCAL f
f=NEW EntryForm()
f.OPEN()
CLASS Entryform OF FORM
  this.View="Company.DBF"
  this.OnRightMouseDown={;Fcs="Current Field: " + ;
    Form.ActiveControl.Name; Form.Txt1.Text=Fcs}
  this.OnRightMouseUp={;Fcs2="Next Field:     " + ;
    Form.NextObj.Name; Form.Txt2.Text=Fcs2}
DEFINE ENTRYFIELD Company OF THIS;
  PROPERTY Datalink "Company->Company",;
  Top 3, Left 1, Width 20, Name "Company"
DEFINE ENTRYFIELD State OF THIS;
  PROPERTY Datalink "Company->State_Prov",;
  Top 5, Left 1, Name "State"
DEFINE TEXT Txt1 OF THIS;
  PROPERTY Text " ",;
  Top 8, Left 1, Width 25
DEFINE TEXT Txt2 OF THIS;
  PROPERTY Text " ",;
  Top 9, Left 1, Width 25
ENDCLASS


See Also

ActiveControl

_curobj

First

SetFocus( )


NextRow( )

See Also	Example	Properties	Forms

Returns the number of the next highest row position where an object can be placed in a form.

Property of Class

Form

Description

Use NextRow( ) in combination with NextCol( ) to prevent the overlapping of objects in a form. For example, if you create an entry field, NextRow( ) returns the coordinate of the next available row, and NextCol( ) returns the coordinate of the next available column; you can place a new object at these coordinates without covering the entry field.

The row coordinates returned by NextRow( ) are as wide as the average line of characters in the active font of the form.


NextRow( ) Example

See NextCol( ) for an example of using NextRow( ).


See Also

COL( )

NextRow( )

ROW( )


Notify( )

See Also	Example	Properties

Notifies a client application that a dBASE item was changed.

Property of Class

DDETOPIC

Description

Use Notify( ) in a DDE server program to tell a client application that an item in the dBASE server session was changed.

OnPoke subroutines often execute Notify( ) when an external application sends dBASE a Poke request. For example, a Quattro Pro data-exchange application might use its {POKE} command to send dBASE a value, causing the OnPoke subroutine to execute. The OnPoke subroutine could insert the value into a field, then execute Notify( ) to inform Quattro Pro that the field changed.

Notify( ) accepts one parameter, <item>. Use this parameter to tell the client application which field, variable, or array element changed. For example, if an OnPoke subroutine changed the value in a field named LASTNAME, the subroutine might execute the following command:

MyDDETopic.Notify("LASTNAME")

The client application must establish a hot link before Notify( ) has an effect. For information on hot links, see OnAdvise.


Notify( ) Example

See CLASS DDETOPIC for an example of using Notify( ).


See Also

Advise( )

Execute( )

Initiate( )

OnNewValue

Peek( )

Poke( )

Server

Terminate( )

Timeout

Topic

Unadvise( )


OldStyle

See Also	Example	Properties	Forms

Determines if a check box or a radio button is displayed in the default Windows style or in 3-D style.

Property of Class

CHECKBOX, ENTRYFIELD, LISTBOX, RADIOBUTTON, RECTANGLE, SPINBOX, TEXT

Data Type

Logical

Default

The default for OldStyle is false (.F.).

Description

Use OldStyle to determine the appearance of an object. When you set OldStyle to true (.T.), the object is displayed in Windows style; when you set OldStyle to false, the object is displayed in 3-D style.


OldStyle Example

NEW operator syntax:

CheckOld = NEW CHECKBOX(this)

CheckOld.Oldstyle = .T.

DEFINE object syntax:

DEFINE CHECKBOX CheckOld OF THIS;

  Property;

    Oldstyle .T.


See Also

PatternStyle

BorderStyle


OleType

See Also	Example	Properties	Forms

Returns a number that reveals whether an OLE field is empty, contains an embedded document, or contains a link to a document file.

Property of Class

OLE

Data Type

Character

Default

The default for OleType is 0 (empty).

Description

Use OleType to determine whether an OLE field is empty, contains a link to a document file, or contains an embedded document.

An OLE viewer displays an OLE document (sometimes called an OLE object). An OLE document can be a graphic image, a document created by a word processor, or any other data object created by an external application. This external application is known as the OLE server. (The OLE server must have OLE capability.)

For example, a graphic image created in Paintbrush can be an OLE document, and Paintbrush can be an OLE server, if you do one of the following:

Embed the document (or a portion of it) in an OLE field with the Cut and Paste commands of the Edit menu.

Link the file containing the document to an OLE field with the Cut and Paste Link commands of the Edit menu.

When the current OLE field is empty-that is, when it contains no embedded OLE document and no link to an OLE document-OleType contains 0. When the OLE field contains an embedded document, OleType contains 1. When the OLE field contains a link to a document file, OleType contains 2.

OleType is a read-only property.


OleType Example

See DoVerb( ) for an example of using OleType.


See Also

LinkFileName

ServerName


OnAdvise

See Also	Example	Properties

Executes a subroutine when an external application requests a DDE hot link to an item in a dBASE server topic.

Property of Class

DDETOPIC

Data Type

Function pointer or codeblock

Description

Use OnAdvise in a DDE server program to respond to a request for a hot link and to determine which dBASE data item the link applies to. (A hot link lets you use the Notify( ) method to tell the client when the item changes.)

OnAdvise receives <item>, a parameter that identifies the dBASE data item. Your server program can use this item for any purpose. For example, it might identify a dBASE field, variable, or array element.

Item names are often held in tables or array objects when multiple hot links are established. For example, a client application might request a hot link to a field, passing the field name through the <item> parameter. Each time, the OnAdvise subroutine could place the field name in an array object.

The OnPoke subroutine could search this array object each time a field is changed; if the name of the changed field is found in the array object, the routine could execute Notify( ).


OnAdvise Example

See CLASS DDETOPIC for an example of using OnAdvise property.


See Also

Advise( )

Execute( )

Initiate( )

OnNewValue

Peek( )

Poke( )

Server

Terminate( )

Timeout

Topic

Unadvise( )


OnAppend

See Also	Example	Properties	Forms

Executes a subroutine when a record is added to a table.

Property of Class

BROWSE, FORM

Data Type

Function pointer or codeblock

Description

Use OnAppend to perform an action each time a new record is created.

OnAppend lets your application respond each time new information is added to a table. For example, a browse object might use an OnAppend subroutine to set a logical field named NEWFIELD to true (.T.) automatically each time the user adds a new record.


OnAppend Example

NEW operator syntax:

Browser = NEW BROWSE(this)

Browser.text = "Sample for OnAppend"

Browser.OnAppend = DataCheck

DEFINE object syntax:

DEFINE BROWSE Browser OF THIS;

  PROPERTY;

  Text  "Sample for OnAppend",;

  OnAppend DataCheck

PROCEDURE DataCheck

IF LEN(Client->Name) = 0

  ? "You must add a name"

ENDIF


See Also

OnChange

OnNavigate


OnChange

See Also	Example	Properties	Forms

Executes a subroutine when the user changes the value displayed in an object.

Property of Class

BROWSE, CHECKBOX, COMBOBOX, ENTRYFIELD, LISTBOX, OLE, RADIOBUTTON, SCROLLBAR, SPINBOX

Data Type

Function pointer or codeblock

Description

Use OnChange to execute a routine when the user performs any of the following actions:

Changes a value in a field and moves to another row in a browse object

Inserts or removes a checkmark in a check box

Changes a value in an entry field

Changes a value in the text box portion of a combo box or a spin box

Selects a different radio button

Moves the slider button in a scrollbar object

The OnChange subroutine of an OLE object executes each time the record pointer moves from one record to another.

For example, an application might let the user change a customer's social security number through an entry field. To verify the change, you can assign to the OnChange property a function that displays a dialog box prompting the user to confirm the change.

Like other event properties, the OnChange property accepts a

Function

Procedure

Codeblock

For information on these subroutines, see Chapter 4 in the Programmer's Guide. For information on writing event-handling routines, see Chapter 14 in the Programmer's Guide.

Note:	You can write a subroutine with the Procedure Editor, a window in which you enter dBASE program code. To access the Procedure Editor, click on the Tool button next to the OnChange item in the Object Inspector.


OnChange Example

NEW operator syntax:

Company = NEW EntryField(this)

Company.Top = 3

Company.Left = 1

Company.Datalink = "Company->Company"

Company.OnChange = ChkChg

DEFINE object syntax:

DEFINE EntryField Company OF THIS;

  PROPERTY Top 3, Left 1, ;

  DataLink "Company->Company",;

  OnChange ChkChg


See Also

OnAppend

OnNavigate


OnClick

See Also	Example	Properties	Forms

Executes a subroutine when the user chooses a pushbutton or a menu item.

Property of Class

MENU, PUSHBUTTON

Data Type

Function pointer or codeblock

Description

Use OnClick to assign an action to a pushbutton or a menu item. A Quit pushbutton, for example, might have a function assigned to its OnClick property that terminates program execution.

Like other event properties, the OnClick property accepts a

Function

Procedure

Codeblock

For information on these subroutines, see Chapter 4 in the Programmer's Guide. For information on writing event-handling routines, see Chapter 14 in the Programmer's Guide.

Note:	You can write a subroutine with the Procedure Editor, a window in which you enter dBASE program code. To access the Procedure Editor, click on the Tool button next to the OnClick item in the Object Inspector.

The subroutine specified by OnClick is executed only if

the Enabled property of the pushbutton is true

the When property of the pushbutton evaluates to true (.T.)


OnClick Example

NEW operator syntax:

Next = NEW PUSHBUTTON(this)

Next.Text = "Next Entry"

Next.OnClick = {;SKIP}

DEFINE object syntax:

DEFINE PUSHBUTTON Next OF THIS;

  Property;

    Text "Next Entry",;

    Onclick {;SKIP}


See Also

OnLeftDblClick

OnLeftMouseDown

OnLeftMouseUp

OnMiddleDblClick

OnMiddleMouseDown

OnMiddleMouseUp

OnRightDblClick

OnRightMouseDown

OnRightMouseUp

OnSelection


OnClose

See Also	Example	Properties	Forms

Executes a subroutine when a form is closed.

Property of Class

FORM, OLE

Data Type

Function pointer or codeblock

Description

Use OnClose to perform an action automatically when a form is closed. For example, the OnClose property might perform clean-up operations such as closing procedure files, restoring settings, closing tables, and releasing objects.

Like other event properties, the OnClose property accepts a

Function

Procedure

Codeblock

For information on these subroutines, see Chapter 4 in the Programmer's Guide. For information on writing event-handling routines, see Chapter 14 in the Programmer's Guide.

Before executing the OnClose subroutine, dBASE does the following:

1.	Executes the Valid subroutine (if any) of the object that currently has input focus. If it returns a value of false (.F.), the form does not close.

2.	Executes the OnLostFocus subroutine (if any) of the object that currently has input focus.

3.	Executes the OnLostFocus subroutine (if any) of the form.

After dBASE executes the OnClose subroutine, it closes the form, its objects, and all its child forms.

The OnClose subroutine of an OLE object executes when the parent form is closed.

Note:	You can write a subroutine with the Procedure Editor, a window in which you enter dBASE program code. To access the Procedure Editor, click on the Tool button next to the OnClose item in the Object Inspector.


OnClose Example

NEW operator syntax:

LOCAL f

f=NEW EntryForm()

f.OPEN()

CLASS EntryForm OF FORM

   this.OnClose Cleanup  && Function that closes;

                            tables and other program;

       elements

ENDCLASS

DEFINE object syntax:

DEFINE FORM EntryForm;

  PROPERTY OnClose Cleanup


See Also

OnChange

OnClick

OnGotFocus

OnHelp

OnLostFocus

OnMove

OnOpen

OnSize


OnExecute

See Also	Example	Properties

Executes a subroutine when a client application sends a command string to a DDE server program.

Property of Class

DDETOPIC

Data Type

Function pointer or codeblock

Description

Use the OnExecute property to perform an action when an external application (known as the client application) sends a directive to dBASE for Windows. This directive can be any string of characters.

OnExecute receives <cmd>, a parameter that contains the directive sent by the client application. If the directive is a dBASE command, the subroutine can execute it. For example, the client application might send the character string "CLOSE DATABASES". The subroutine could execute the command using the macro substitution function, as with

&Cmd

In this case, the macro substitution function (&) makes dBASE treat the contents of Cmd as a command instead of a character string.

If the directive is not a command, the subroutine can use it to make branching decisions. For example, a stock trading routine might receive either of two character strings, "BUY" or "SELL". The routine could use an IF...ELSE...ENDIF statement to execute one procedure or another accordingly.

For more information on the DDETopic object class, see CLASS DDETOPIC and Chapter 26 in the Programmer's Guide.


OnExecute Example

See CLASS DDETOPIC for an example of using OnExecute property.


See Also

Advise( )

Execute( )

Initiate( )

OnNewValue

OnPeek

OnPoke

Peek( )

Poke( )

Server

Terminate( )

Timeout

Topic

Unadvise( )


OnGotFocus

See Also	Example	Properties	Forms

Executes a subroutine when an object receives focus.

Property of Class

BROWSE, CHECKBOX, COMBOBOX, EDITOR, ENTRYFIELD, FORM, LISTBOX, PUSHBUTTON, RADIOBUTTON, SCROLLBAR, SPINBOX

Data Type

Function pointer or codeblock

Description

Use OnGotFocus to perform an action automatically each time an object is selected. For example, a browse object that accesses sensitive information might use its OnGotFocus property to display a dialog box that prompts for a password. If the user fails to enter the correct password, focus could be given to another object.

Like other event properties, the OnGotFocus property accepts a

Function

Procedure

Codeblock

For information on these subroutines, see Chapter 4 in the Programmer's Guide. For information on writing event-handling routines, see Chapter 14 in the Programmer's Guide.

Note:	You can write a subroutine with the Procedure Editor, a window in which you enter dBASE program code. To access the Procedure Editor, click on the Tool button next to the OnGotFocus item in the Object Inspector.

OnGotFocus differs from When, which specifies a condition that must evaluate to true (.T.) before an object can receive focus.


OnGotFocus Example

NEW operator syntax:

Company = NEW ENTRYFIELD(this)

Company.Top = 3

Company.Left = 1

Company.Datalink = "Company"

Company.OnGotFocus = GetReady

DEFINE object syntax:

DEFINE Entryfield Company OF THIS;

  Property;

  Top 3, Left 1,;

  Datalink "Company",;

  OnGotFocus GetReady


See Also

OnClick

OnClose

OnHelp

OnLostFocus

OnMove

OnOpen

OnSize


OnHelp

See Also	Example	Properties	Forms

Executes a subroutine when the user presses F1 while an object has focus.

Property of Class

BROWSE, CHECKBOX, COMBOBOX, EDITOR, ENTRYFIELD, FORM, LISTBOX, MENU, PUSHBUTTON, RADIOBUTTON, SCROLLBAR, SPINBOX

Data Type

Function pointer or codeblock

Description

Use OnHelp to execute a dBASE routine (instead of a Help topic in a Windows Help file) when the user presses F1. For example, a Human Resources program might allow users to search for employee names in a combo box. The OnHelp property could open a dialog box explaining how to find names quickly by entering characters instead of scrolling the combo box prompts.

Like other event properties, the OnChange property accepts

Functions

Procedures

Codeblocks

For information on these subroutines, see Chapter 4 in the Programmer's Guide. For information on writing event-handling routines, see Chapter 14 in the Programmer's Guide.

Note:	You can write a subroutine with the Procedure Editor, a window in which you enter dBASE program code. To access the Procedure Editor, click on the Tool button next to the OnHelp item in the Object Inspector.

The subroutine you specify with OnHelp overrides the compiled Help specified in HelpID and HelpFile.


OnHelp Example

NEW operator syntax:

Resume = New EDITOR(this)

Resume.Top = 3

Resume.Left = 1

Resume.OnHelp = EditHelp

DEFINE object syntax:

DEFINE EDITOR Resume OF THIS;

  AT 3,1;

  Property;

    OnHelp EditHelp


See Also

HELP

HelpFile

OnChange

OnClick

OnClose

OnGotFocus

OnLostFocus

OnMove

OnOpen

OnSize


OnLeftDblClick

See Also	Example	Properties	Forms

Executes a subroutine when the user double-clicks a form or an object.

Property of Class

BROWSE, CHECKBOX, COMBOBOX, EDITOR, ENTRYFIELD, FORM, IMAGE, LISTBOX, MENU, OLE, PUSHBUTTON, RADIOBUTTON, RECTANGLE, SCROLLBAR, SPINBOX, TEXT

Data Type

Function pointer or codeblock

Description

Use OnLeftDblClick to perform an action when the user double-clicks with the left mouse button. OnLeftDblClick can also trap Shift, Ctrl, middle mouse button, or right mouse button presses if they occur at the same time the user double-clicks the button.

OnLeftDblClick passes three parameters to its subroutine:

<Flags> is a single-byte value that tells you which other keys and mouse buttons were pressed when the user double-clicked the button.

<Col> is the horizontal position of the mouse when the user double-clicked the button.

<Row> is the vertical position of the mouse when the user double-clicked the button.

<Flags> parameter

If you want, you can use the Flags parameter with the BITSET( ) function to detect different key and mouse button combinations. BITSET( ) evaluates a numeric value and returns true (.T.) or false (.F.), depending on whether a particular bit in the value is on (1) or off (0). You give BITSET( ) two parameters:

The <Flags> value itself

The bit in <Flags> to evaluate

The values you can pass to BITSET( ) through the second parameter are as follows:

Simultaneous keypress	Second parameter

Right mouse button	1

Shift	2

Ctrl	3

Middle mouse button	4

For example, to determine if the user pressed Shift while double-clicking the object, use BITSET(Flags, 2). If the user did, BITSET( ) returns true. If BITSET(Flags, 3) and BITSET(Flags, 1) both return true, Ctrl and right mouse button were pressed during the event. You can use such information in IF...ELSE...ENDIF or DO CASE...ENDCASE statements to assign different actions to different key and mouse button combinations.

<Col> and <Row> parameters

The <Col> and <Row> parameters indicate where the double-click event occurred, letting you make decisions accordingly. For example, the OnLeftDblClick property of a form might execute different actions, depending on where the double-click event occurred in the form. The <Col> and <Row> coordinates are expressed in character units.

Like other event properties, the OnLeftDblClick property accepts:

Functions

Procedures

Codeblocks

For information on these subroutines, see Chapter 4 in the Programmer's Guide. For information on writing event-handling subroutines, see Chapter 14 in the Programmer's Guide.

Note:	You can write a subroutine with the Procedure Editor, a window in which you enter dBASE program code. To access the Procedure Editor, click the Tool button next to the OnLeftDblClick item in the Object Inspector.


OnLeftDblClick Example

NEW operator syntax:

LOCAL f

f=NEW EntryForm

f.OPEN()

CLASS EntryForm OF FORM

   this.OnLeftDblClick = SelectEntry

ENDCLASS

DEFINE pbject syntax:

DEFINE FORM EntryForm;

  Property OnLeftDblClick SelectEntry


See Also

BITSET( )

OnLeftMouseDown

OnLeftMouseUp

OnMiddleDblClick

OnMiddleMouseDown

OnMiddleMouseUp

OnRightDblClick

OnRightMouseDown

OnRightMouseUp


OnLeftMouseDown

See Also	Example	Properties	Forms

Executes a subroutine when the user presses the left mouse button while the pointer is over a form or an object.

Property of Class

BROWSE, CHECKBOX, COMBOBOX, EDITOR, ENTRYFIELD, FORM, IMAGE, LISTBOX, MENU, OLE, PUSHBUTTON, RADIOBUTTON, RECTANGLE, SCROLLBAR, SPINBOX, TEXT

Data Type

Function pointer or codeblock

Description

Use OnLeftMouseDown to perform an action when the user presses the left mouse button. OnLeftMouseDown can also trap Shift, Ctrl, middle mouse button, or right mouse button presses if they occur at the same time the user presses the button.

OnLeftMouseDown passes three parameters to its subroutine:

<Flags> is a single-byte value that tells you which other keys and mouse buttons were pressed when the user pressed the button.

<Col> is the horizontal position of the mouse when the user pressed the button.

<Row> is the vertical position of the mouse when the user pressed the button.

<Flags> parameter

If you want, you can use the Flags parameter with the BITSET( ) function to detect different key and mouse button combinations. BITSET( ) evaluates a numeric value and returns true (.T.) or false (.F.), depending on whether a particular bit in the value is on (1) or off (0). You give BITSET( ) two parameters:

The <Flags> value itself

The bit in <Flags> to evaluate

The values you can pass to BITSET( ) through the second parameter are as follows:

Simultaneous keypress	Second parameter

Right mouse button	1

Shift	2

Ctrl	3

Middle mouse button	4

For example, to determine if the user pressed Shift while clicking the object, use BITSET(Flags, 2). If the user did, BITSET( ) returns true. If BITSET(Flags, 3) and BITSET(Flags, 1) both return true, Ctrl and the right mouse button were pressed during the event. You can use such information in IF...ELSE...ENDIF or DO CASE...ENDCASE statements to assign different actions to different key and mouse button combinations.

<Col> and <Row> parameters

The <Col> and <Row> parameters indicate where the click event occurred, letting you make decisions accordingly. For example, the OnLeftMouseDown property of a form might execute different actions, depending on where the click event occurred in the form. The <Col> and <Row> coordinates are expressed in character units.

Like other event properties, the OnLeftMouseDown property accepts:

Functions

Procedures

Codeblocks

For information on these subroutines, see Chapter 4 in the Programmer's Guide. For information on writing event-handling routines, see Chapter 14 in the Programmer's Guide.

Note:	You can write a subroutine with the Procedure Editor, a window in which you enter dBASE program code. To access the Procedure Editor, click the Tool button next to the OnLeftMouseDown item in the Object Inspector.


OnLeftMouseDown Example

NEW operator syntax:

LOCAL f

f=NEW EntryForm()

f.OPEN()

CLASS EntryForm OF FORM

  this.OnLeftMouseDown = OkToMove

  this.OnLeftMouseUp = StopMove

ENDCLASS

DEFINE object syntax:

DEFINE FORM EntryForm;

  PROPERTY OnLeftMouseDown OkToMove,;

    OnLeftMouseUp StopMove

OPEN FORM EntryForm


See Also

BITSET( )

OnLeftDblClick

OnLeftMouseUp

OnMiddleDblClick

OnMiddleMouseDown

OnMiddleMouseUp

OnRightDblClick

OnRightMouseDown

OnRightMouseUp


OnLeftMouseUp

See Also	Example	Properties	Forms

Executes a subroutine when the user releases the left mouse button while the pointer is over a form or an object.

Property of Class

BROWSE, CHECKBOX, COMBOBOX, EDITOR, ENTRYFIELD, FORM, IMAGE, LISTBOX, MENU, OLE, PUSHBUTTON, RADIOBUTTON, RECTANGLE, SCROLLBAR, SPINBOX, TEXT

Data Type

Function pointer or codeblock

Description

Use OnLeftMouseUp to perform an action when the user releases the left mouse button. OnLeftMouseUp can also trap Shift, Ctrl, middle mouse button, or right mouse button presses if they occur at the same time the user releases the button.

OnLeftMouseUp passes three parameters to its subroutine:

<Flags> is a single-byte value that tells you which other keys and mouse buttons were pressed when the user released the button.

<Col> is the horizontal position of the mouse when the user released the button.

<Row> is the vertical position of the mouse when the user released the button.

<Flags> parameter

If you want, you can use the Flags parameter with the BITSET( ) function to detect different key and mouse button combinations. BITSET( ) evaluates a numeric value and returns true (.T.) or false (.F.), depending on whether a particular bit in the value is on (1) or off (0). You give BITSET( ) two parameters:

The <Flags> value itself

The bit in <Flags> to evaluate

The values you can pass to BITSET( ) through the second parameter are as follows:

Simultaneous keypress	Second parameter

Right mouse button	1

Shift key	2

Ctrl key	3

Middle mouse button	4

For example, to determine if the user pressed Shift while clicking the object, use BITSET(Flags, 2). If the user did, BITSET( ) returns true. If BITSET(Flags, 3) and BITSET(Flags, 1) both return true, Ctrl and the right mouse button were pressed during the event. You can use such information in IF...ELSE...ENDIF or DO CASE...ENDCASE statements to assign different actions to different key and mouse button combinations.

<Col> and <Row> parameters

The <Col> and <Row> parameters indicate where the upward-click event occurred, letting you make decisions accordingly. For example, the OnLeftMouseUp property of a form might execute different actions, depending on where the left upward-click event occurred in the form. The <Col> and <Row> coordinates are expressed in character units.

Like other event properties, the OnLeftMouseUp property accepts:

Functions

Procedures

Codeblocks

For information on these subroutines, see Chapter 4 in the Programmer's Guide. For information on writing event-handling subroutines, see Chapter 14 in the Programmer's Guide.

Note:	You can write a subroutine with the Procedure Editor, a window in which you enter dBASE program code. To access the Procedure Editor, click on the Tool button next to the OnLeftMouseUp item in the Object Inspector.


OnLeftMouseUp Example

See OnLeftMouseDown for an example of OnLeftMouseUp.


See Also

BITSET( )

OnLeftDblClick

OnLeftMouseDown

OnMiddleDblClick

OnMiddleMouseDown

OnMiddleMouseUp

OnRightDblClick

OnRightMouseDown

OnRightMouseUp


OnLostFocus

See Also	Example	Properties	Forms

Executes a subroutine when focus is removed from an object.

Property of Class

BROWSE, CHECKBOX, COMBOBOX, EDITOR, ENTRYFIELD, FORM, LISTBOX, OLE, PUSHBUTTON, RADIOBUTTON, SCROLLBAR, SPINBOX

Data Type

Function pointer or codeblock

Description

Use OnLostFocus to perform an action automatically when an object loses focus. For example, an entry field might provide access to an important table field in which a valid entry must be made. When the user attempts to move focus to another object, the OnLostFocus property could present a dialog box containing the confirmation prompt "Are you sure?" with two pushbuttons labeled Yes and Edit Again.

Like other event properties, the OnLostFocus property accepts a

Function

Procedure

Codeblock

For information on these subroutines, see Chapter 4 in the Programmer's Guide. For information on writing event-handling routines, see Chapter 14 in the Programmer's Guide.

Note:	You can write a subroutine with the Procedure Editor, a window in which you enter dBASE program code. To access the Procedure Editor, click on the Tool button next to the OnLostFocus item in the Object Inspector.

OnLostFocus differs from Valid, which specifies a condition that must evaluate to true (.T.) before the object can lose focus.


OnLostFocus Example

NEW operator syntax:

Spin1 = NEW SPINBOX(this)

Spin1.Datalink = "TaxRate"

Spin1.Top = 2

Spin1.Left = 4

Spin1.Height = 2

Spin1.OnLostFocus = Recompute

* Recompute is a FUNCTION that performs an

* action and returns .T. or some value.

DEFINE object syntax:

DEFINE SPINBOX Spin1 OF THIS;

  PROPERTY Datalink "Taxrate",;

  Top 2, Left 4, Height 2,;

  OnLostFocus Recompute


See Also

OnChange

OnClick

OnClose

OnGotFocus

OnHelp

OnMove

OnOpen

OnSize


OnMiddleDblClick

See Also	Example	Properties	Forms

Executes a subroutine when the user double-clicks with the middle mouse button while the pointer is on a form or an object.

Property of Class

BROWSE, CHECKBOX, COMBOBOX, EDITOR, ENTRYFIELD, FORM, IMAGE, LISTBOX, MENU, OLE, PUSHBUTTON, RADIOBUTTON, RECTANGLE, SCROLLBAR, SPINBOX, TEXT

Data Type

Function pointer or codeblock

Description

Use OnMiddleDblClick to perform an action when the user double-clicks with the middle mouse button. OnMiddleDblClick can also trap Shift, Ctrl, left mouse button, or right mouse button presses if they occur at the same time the user double-clicks the button.

OnMiddleDblClick passes three parameters to its subroutine:

<Flags> is a single-byte value that tells you which other keys and mouse buttons were pressed when the user double-clicked the button.

<Col> is the horizontal position of the mouse when the user double-clicked the button.

<Row> is the vertical position of the mouse when the user double-clicked the button.

<Flags> parameter

If you want, you can use the Flags parameter with the BITSET( ) function to detect different key and mouse button combinations. BITSET( ) evaluates a numeric value and returns true (.T.) or false (.F.), depending on whether a particular bit in the value is on (1) or off (0). You give BITSET( ) two parameters:

The <Flags> value itself

The bit in <Flags> to evaluate

The values you can pass to BITSET( ) through the second parameter are as follows:

Simultaneous keypress	Second parameter

Left mouse button	0

Right mouse button	1

Shift	2

Ctrl	3

For example, to determine if the user pressed Shift while clicking the object, use BITSET(Flags, 2). If the user did, BITSET( ) returns true. If BITSET(Flags, 3) and BITSET(Flags, 0) both return true, Ctrl and the left mouse button were pressed during the event. You can use such information in IF...ELSE...ENDIF or DO CASE...ENDCASE statements to assign different actions to different key and mouse button combinations.

<Col> and <Row> parameters

The <Col> and <Row> parameters indicate where the middle double-click event occurred, letting you make decisions accordingly. For example, the OnMiddleDblClick property of a form might execute different actions, depending on where the double-click event occurred in the form. The <Col> and <Row> coordinates are expressed in character units.

Like other event properties, the OnMiddleDblClick property accepts

Functions

Procedures

Codeblocks

For information on these subroutines, see Chapter 4 in the Programmer's Guide. For information on writing event-handling subroutines, see Chapter 14 in the Programmer's Guide.

Note:	You can write a subroutine with the Procedure Editor, a window in which you enter dBASE program code. To access the Procedure Editor, click on the Tool button next to the OnMiddleDblClick item in the Object Inspector.


OnMiddleDblClick Example

NEW operator syntax:

LOCAL F1

F1=NEW Trips()

F1.OPEN()

CLASS Trips OF FORM

  this.Text = "Trip Schedule"

  this.Top = 2

  this.Left = 2

  this.Width = 38

  this.Height = 18

  this.OnMiddleMouseDblClick = AnimalKingdom

* AnimalKingdom is a FUNCTION that performs

* an action and returns .T. or some value.

ENDCLASS

DEFINE object syntax:

DEFINE FORM Trips;

  PROPERTY Text "Trip Schedule",;

  Top 2, Left 2, Width 38, Height 18

  OnMiddleMouseDblClick AnimalKingdom

OPEN FORM Trips


See Also

BITSET( )

OnLeftDblClick

OnLeftMouseDown

OnLeftMouseUp

OnMiddleMouseDown

OnMiddleMouseUp

OnRightDblClick

OnRightMouseDown

OnRightMouseUp


OnMiddleMouseDown

See Also	Example	Properties	Forms

Executes a subroutine when the user presses the middle mouse button while the pointer is over a form or an object.

Property of Class

BROWSE, CHECKBOX, COMBOBOX, EDITOR, ENTRYFIELD, FORM, IMAGE, LISTBOX, MENU, OLE, PUSHBUTTON, RADIOBUTTON, RECTANGLE, SCROLLBAR, SPINBOX, TEXT

Data Type

Function pointer or codeblock

Description

Use OnMiddleMouseDown to perform an action when the user presses the middle mouse button. OnMiddleMouseDown can also trap Shift, Ctrl, left mouse button, or right mouse button presses if they occur at the same time the user presses the button.

OnMiddleMouseDown passes three parameters to its subroutine:

<Flags> is a single-byte value that tells you which other keys and mouse buttons were pressed when the user pressed the button.

<Col> is the horizontal position of the mouse when the user pressed the button.

<Row> is the vertical position of the mouse when the user pressed the button.

<Flags> parameter

If you want, you can use the Flags parameter with the BITSET( ) function to detect different key and mouse button combinations. BITSET( ) evaluates a numeric value and returns true (.T.) or false (.F.), depending on whether a particular bit in the value is on (1) or off (0). You give BITSET( ) two parameters:

The <Flags> value itself

The bit in <Flags> to evaluate

The values you can pass to BITSET( ) through the second parameter are as follows:

Simultaneous keypress	Second parameter

Left mouse button	0

Right mouse button	1

Shift	2

Ctrl	3

For example, to determine if the user pressed Shift while clicking the object, use BITSET(Flags, 2). If the user did, BITSET( ) returns true. If BITSET(Flags, 3) and BITSET(Flags, 0) both return true, Ctrl and the left mouse button were pressed during the event. You can use such information in IF...ELSE...ENDIF or DO CASE...ENDCASE statements to assign different actions to different key and mouse button combinations.

<Col> and <Row> parameters

The <Col> and <Row> parameters indicate where the middle click event occurred, letting you make decisions accordingly. For example, the OnMiddleMouseDown property of a form might execute different actions, depending on where the middle click event occurred in the form. The <Col> and <Row> coordinates are expressed in character units.

Like other event properties, the OnMiddleMouseDown property accepts:

Functions

Procedures

Codeblocks

For information on these subroutines, see Chapter 4 in the Programmer's Guide. For information on writing event-handling subroutines, see Chapter 14 in the Programmer's Guide.

Note:	You can write a subroutine with the Procedure Editor, a window in which you enter dBASE program code. To access the Procedure Editor, click on the Tool button next to the OnMiddleMouseDown item in the Object Inspector.


OnMiddleMouseDown Example

NEW operator syntax:

LOCAL F1

F1=NEW Trips()

F1.OPEN()

CLASS Trips OF FORM

  this.Text = "Trip Schedule"

  this.Top = 2

  this.Left = 2

  this.Width = 38

  this.Height = 18

  this.OnMiddleMouseDown = AnimalKingdom

* AnimalKingdom is a FUNCTION that performs

* an action and returns .T. or some value.

ENDCLASS

DEFINE object syntax:

DEFINE FORM Trips FROM 2,2 TO 20,40;

  PROPERTY Text "Trip Schedule",;

  OnMiddleMouseDown AnimalKingdom

OPEN FORM Trips


See Also

BITSET( )

OnLeftDblClick

OnLeftMouseDown

OnLeftMouseUp

OnMiddleDblClick

OnMiddleMouseUp

OnRightDblClick

OnRightMouseDown

OnRightMouseUp


OnMiddleMouseUp

See Also	Example	Properties	Forms

Executes a subroutine when the user releases the middle mouse button while the pointer is over a form or an object.

Property of Class

BROWSE, CHECKBOX, COMBOBOX, EDITOR, ENTRYFIELD, FORM, IMAGE, LISTBOX, MENU, OLE, PUSHBUTTON, RADIOBUTTON, RECTANGLE, SCROLLBAR, SPINBOX, TEXT

Data Type

Function pointer or codeblock

Description

Use OnMiddleMouseUp to perform an action when the user releases the middle mouse button. OnMiddleMouseUp can also trap Shift, Ctrl, left mouse button, or right mouse button presses if they occur at the same time the user releases the button.

OnMiddleMouseUp passes three parameters to its subroutine:

<Flags> is a single-byte value that tells you which other keys and mouse buttons were pressed when the user released the button.

<Col> is the horizontal position of the mouse when the user released the button.

<Row> is the vertical position of the mouse when the user released the button.

<Flags> parameter

If you want, you can use the Flags parameter with the BITSET( ) function to detect different key and mouse button combinations. BITSET( ) evaluates a numeric value and returns true (.T.) or false, depending on whether a particular bit in the value is on (1) or off (0). You give BITSET( ) two parameters:

The <Flags> value itself

The bit in <Flags> to evaluate

The values you can pass to BITSET( ) through the second parameter are as follows:

Simultaneous keypress	Second parameter

Left mouse button	0

Right mouse button	1

Shift key	2

Ctrl key	3

For example, to determine if the user pressed Shift while clicking the object, use BITSET(Flags, 2). If the user did, BITSET( ) returns true. If BITSET(Flags, 3) and BITSET(Flags, 0) both return true, Ctrl and the left mouse button were pressed during the event. You can use such information in IF...ELSE...ENDIF or DO CASE...ENDCASE statements to assign different actions to different key and mouse button combinations.

<Col> and <Row> parameters

The <Col> and <Row> parameters indicate where the middle upward-click event occurred, letting you make decisions accordingly. For example, the OnMiddleMouseUp property form might execute different actions, depending on where the middle upward-click event occurred in the form. The <Col> and <Row> coordinates are expressed in character units.

Like other event properties, the OnMiddleMouseUp property accepts:

Functions

Procedures

Codeblocks

For information on these subroutines, see Chapter 4 in the Programmer's Guide. For information on writing event-handling subroutines, see Chapter 14 in the Programmer's Guide.

Note:	You can write a subroutine with the Procedure Editor, a window in which you enter dBASE program code. To access the Procedure Editor, click on the Tool button next to the OnMiddleMouseUp item in the Object Inspector.


OnMiddleMouseUp Example

NEW operator syntax:

LOCAL F1

F1=NEW Trips()

F1.OPEN()

CLASS Trips OF FORM

  this.Text = "Trip Schedule"

  this.Top = 2

  this.Left = 2

  this.Width = 38

  this.Height = 18

  this.OnMiddleMouseUp = CostSched

* CostSked is a FUNCTION that performs

* an action and returns .T. or some value.

ENDCLASS

DEFINE object syntax:

DEFINE FORM Trips;

  PROPERTY Text "Trip Schedule",;

  Top 2, Left 2, Width 38, Height 18,;

  OnMiddleMouseUp CostSched

OPEN FORM Trips


See Also

BITSET( )

OnLeftDblClick

OnLeftMouseDown

OnLeftMouseUp

OnMiddleDblClick

OnMiddleMouseDown

OnRightDblClick

OnRightMouseDown

OnRightMouseUp


OnMouseMove

See Also	Example	Properties	Forms

Executes a subroutine when the user moves the mouse in a form.

Property of Class

FORM

Data Type

Function pointer or codeblock

Description

Use OnMove to perform actions automatically when the user moves the mouse.

Like other event properties, the OnMouseMove property accepts

Functions

Procedures

Codeblocks

For information on these subroutines, see Chapter 4 in the Programmer's Guide. For information on writing event-handling routines, see Chapter 14 in the Programmer's Guide.

OnMouseMove passes three parameters to its subroutine:

<Flags> is a single-byte value that tells you which keys and mouse buttons were pressed while the user moved the mouse. You can interpret this value with the BITSET( ) function, which examines individual bits in numeric values.

<Col> is the horizontal position of the mouse after the move.

<Row> is the vertical position of the mouse after the move.

The <Col> and <Row> parameters reveal the new position, letting you make decisions accordingly. For example, when the user moves the mouse to a restricted region of a form, the OnMouseMove subroutine might use <Col> and <Row> to detect the action and display a warning dialog box.

For more information on interpreting the <Flags> parameter, see the mouse event properties (such as OnLeftMouseDown and OnRightMouseDown).

Note:	You can write a subroutine with the Procedure Editor, a window in which you enter dBASE program code. To access the Procedure Editor, click the Tool button next to the OnMouseMove item in the Object Inspector.


OnMouseMove Example

NEW operator syntax:

LOCAL F1

F1=NEW Trips()

F1.OPEN()

CLASS Trips OF FORM

  this.Text = "Trip Schedule"

  this.Top = 2

  this.Left = 2

  this.Width = 38

  this.Height = 18

  this.OnMouseMove = CostList

* CostList is a FUNCTION that performs

* an action and returns .T. or some value.

ENDCLASS

DEFINE object syntax:

DEFINE FORM Trips;

  PROPERTY Text "Trip Schedule",;

  Top 2, Left 2, Width 38, Height 18,;

  OnMouseMove CostList

OPEN FORM Trips


See Also

OnClick

OnLeftDblClick

OnLeftMouseDown

OnLeftMouseUp

OnMiddleDblClick

OnMiddleMouseDown

OnMiddleMouseUp

OnRightDblClick

OnRightMouseDown

OnRightMouseUp


OnMove

See Also	Example	Properties	Forms

Executes a subroutine after a form is opened and after the user moves the form.

Property of Class

FORM

Data Type

Function pointer or codeblock

Description

Use OnMove to perform actions automatically when a form is opened or moved.

Like other event properties, the OnMove property accepts

Functions

Procedures

Codeblocks

For information on these subroutines, see Chapter 4 in the Programmer's Guide. For information on writing event-handling routines, see Chapter 14 in the Programmer's Guide.

OnMove passes two parameters to its subroutine:

<Left> is the new horizontal position of the upper left corner.

<Top> is the new vertical position of the upper right corner.

Use the Left and Top parameters to make branching decisions. For example, when the user moves a form over another form, the OnMove subroutine of the moved form might use Left and Top to calculate a new position for the obscured form.

Note:	You can write a subroutine with the Procedure Editor, a window in which you enter dBASE program code. To access the Procedure Editor, click on the Tool button next to the OnMove item in the Object Inspector.


OnMove Example

NEW operator syntax:

LOCAL F1

F1=NEW Trips()

F1.OPEN()

CLASS Trips OF FORM

  this.Text = "Trip Schedule"

  this.Top = 2

  this.Left = 2

  this.Width = 38

  this.Height = 18

  this.OnRightClick = {;Form.Move(10,10,20,10)}

  this.OnMove = ShowCost

* ShowCost is a FUNCTION that performs

* an action and returns .T. or some value.

ENDCLASS

DEFINE object syntax:

DEFINE FORM Trips;

  PROPERTY Text "Trip Schedule",;

  Top 2, Left 2, Width 38, Height 18,;

  OnRightClick {;Form.Move(10,10,20,10)},;

  OnMove ShowCost

OPEN FORM Trips


See Also

OnChange

OnClick

OnClose

OnGotFocus

OnHelp

OnLeftMouseDown

OnLostFocus

OnOpen

OnSize


OnNavigate

See Also	Example	Properties	Forms

Executes a subroutine when a the record pointer in a table is moved.

Property of Class

BROWSE, FORM

Data Type

Function pointer or codeblock

Description

Use OnNavigate to make your application respond each time the user moves from one record to another.

OnNavigate lets you detect the user's movements through a table. For example, a browse object might use an OnNavigate subroutine to log user activity; each time the user moves from one record to another, the subroutine could store the record number in an array object or in another table.


OnNavigate Example

NEW operator syntax:

LOCAL f
f = NEW XFORM()
f.Open()

CLASS XFORM OF FORM
   this.HelpFile = ""
   this.Top =          5.71
   this.Height =         15.82
   this.Text = "Form"
   this.Left =         39.00
   this.Width =         72.60
   this.HelpId = ""

   DEFINE BROWSE BROWSE1 OF THIS;
       PROPERTY;
         OnNavigate {;?Compcode+SPACE(5)+Contact},;
         Top          3.00,;
         Height         10.00,;
         FontBold .F.,;
         ColorNormal "N/W",;
         Fields "CompCode, Contact",;
         Left          7.00,;
         Width         59.00

ENDCLASS

DEFINE object syntax:

USE Contact

SET PRINTER ON

DEFINE FORM Brws FROM 1,1 TO 15,40

DEFINE BROWSE Br1 OF Brws;

  PROPERTY Alias "Contact",;

    Height 15, Fields "CompCode, Contact",;

    Top 1, Left 1, Width 40, Height 15,;

    OnNavigate {;? Compcode+SPACE(5)+Contact}

OPEN FORM Brws


See Also

OnAppend

OnChange


OnNewValue

See Also	Example	Properties

Executes a subroutine when a hot-linked item in a DDE server document changes.

Property of Class

DDELINK

Data Type

Function pointer or codeblock

Description

Use OnNewValue to perform an action when a hot-linked server item is changed. A hot link, which you create with the Advise( ) method, tells the server to notify dBASE when the item changes.

A server document is a file you open in an external application. For example, a data-exchange application might start a session in Quattro Pro for Windows and open one of its spreadsheet files (the server document). You can establish hot links to one or more cells in the spreadsheet with Advise( ), then use OnNewValue to specify a codeblock that executes each time one of the cells is changed.

OnNewValue receives two parameters:

<item> identifies the server item written to. It can specify the hot-linked item, such as a field in a table or a cell in a spreadsheet. For example, "A:H3" specifies cell H3 of Page A in a Quattro Pro spreadsheet file.

<value> is the new value of the hot-linked server item.

The codeblock can use these parameters to evaluate the change and make decisions accordingly.


OnNewValue Example

PUBLIC LinkObj

LinkObj = NEW DDELINK()

LinkObj.OnNewValue = Valuehandler;

               && Codeblock or function pointer

LinkObj.Initiate("QPW","Demo.WB1")

LinkObj.Advise("A:A1");

               && Notified when cell A:A1 changes


See Also

Advise( )

Execute( )

Initiate( )

Peek( )

Poke( )

Server

Terminate( )

Timeout

Topic

Unadvise( )


OnOpen

See Also	Example	Properties	Forms

Executes a subroutine when a form is opened.

Property of Class

BROWSE, CHECKBOX, COMBOBOX, EDITOR, ENTRYFIELD, FORM, IMAGE, LISTBOX, OLE, PUSHBUTTON, RADIOBUTTON, RECTANGLE, SCROLLBAR, SPINBOX, TEXT

Data Type

Function pointer or codeblock

Description

Use OnOpen to execute an action when a form is opened.

The OnOpen subroutine of an object executes whenever the parent form is opened. The OnOpen subroutine of a form executes any time the form itself is opened.

Like other event properties, the OnOpen property accepts

Functions

Procedures

Codeblocks

For information on these subroutines, see Chapter 4 in the Programmer's Guide. For information on writing event-handling routines, see Chapter 14 in the Programmer's Guide.

Note:	You can write a subroutine with the Procedure Editor, a window in which you enter dBASE program code. To access the Procedure Editor, click on the Tool button next to the OnOpen item in the Object Inspector.

Any subroutine you assign to the OnMove property of the form also executes when the form is opened.


OnOpen Example

NEW operator syntax:

LOCAL F1

F1=NEW Trips()

F1.OPEN()

CLASS Trips OF FORM

  this.Text = "Trip Schedule"

  this.Top = 2

  this.Left = 2

  this.Width = 38

  this.Height = 18

  this.OnOpen = FltSched

* FltSched is a FUNCTION that performs

* an action and returns .T. or some value.

ENDCLASS

DEFINE object syntax:

DEFINE FORM Trips FROM 2,2 TO 20,40;

  PROPERTY Text "Trip Schedule",;

  OnOpen FltSched

OPEN FORM Trips


See Also

OnClose

OnGotFocus

OnLostFocus

OnMove

OnSize


OnPeek

See Also	Example	Properties

Executes a subroutine when a client application tries to read an item from a DDE server application.

Property of Class

DDETOPIC

Data Type

Function pointer or codeblock

Description

Use the OnPeek property to send a value to a client application when the client application makes a Peek request.

OnPeek receives <item>, a parameter that identifies the dBASE data item that the client application wants to read.

Use the RETURN command to send the requested item to the client. For example, a Quattro Pro for Windows application might execute a {PEEK} command, sending a field name through <item>. The OnPoke subroutine could use RETURN to send the field contents to the client, as with

RETURN &Item

In this case, the macro substitution function (&) makes dBASE treat the contents of Item as a field name instead of a character string, so the contents of the field are sent to the client.

For more information on the DDETopic object class, see CLASS DDETOPIC and Chapter 26 in the Programmer's Guide.


OnPeek Example

See CLASS DDETOPIC for an example of using OnPeek property.


See Also

Advise( )

Execute( )

Initiate( )

OnNewValue

OnPoke

Peek( )

Poke( )

Server

Terminate( )

Timeout

Topic

Unadvise( )


OnPoke

See Also	Example	Properties

Executes a subroutine when a client application attempts to insert a value into a DDE server item.

Property of Class

DDETOPIC

Data Type

Function pointer or codeblock

Description

Use the OnPoke property to receive a value from a client application and insert it in a data element when the client application makes a Poke request.

OnPoke receives two parameters:

<item> Identifies the data item in which the value is inserted. This item can be any string.

<value> Identifies the value to insert in the data item.

For example, a client application might send a field name and a value to put in the field. The OnPoke subroutine might insert the value in the field using the REPLACE command and the macro substitution function, as with:

REPLACE &Item WITH Value

In this case, the macro substitution function (&) makes dBASE treat the contents of Item as a field name instead of a character string.

For more information on the DDETopic object class, see CLASS DDETOPIC and Chapter 26 in the Programmer's Guide.

Note:	If a client established a hot link before sending the data, you can execute the Notify( ) method from the OnPoke subroutine, informing the client application that a change occurred. For information on hot links, see OnAdvise.


OnPoke Example

See CLASS DDETOPIC for an example of using OnPoke property.


See Also

Advise( )

Execute( )

Initiate( )

OnNewValue

OnPeek

Peek( )

Poke( )

Server

Terminate( )

Timeout

Topic

Unadvise( )


OnRightDblClick

See Also	Example	Properties	Forms

Executes a subroutine when the user double-clicks with the right mouse button while the pointer is on a form or an object.

Property of Class

BROWSE, CHECKBOX, COMBOBOX, EDITOR, ENTRYFIELD, FORM, IMAGE, LISTBOX, MENU, OLE, PUSHBUTTON, RADIOBUTTON, RECTANGLE, SCROLLBAR, SPINBOX, TEXT

Data Type

Function pointer or codeblock

Description

Use OnRightDblClick to perform an action when the user double-clicks with the right mouse button. OnRightDblClick can also trap Shift, Ctrl, left mouse button, or middle mouse button presses if they occur at the same time the user double-clicks the button.

OnRightDblClick passes three parameters to its subroutine:

<Flags> is a single-byte value that tells you which other keys and mouse buttons were pressed when the user double-clicked the button.

<Col> is the horizontal position of the mouse when the user double-clicked the button.

<Row> is the vertical position of the mouse when the user double-clicked the button.

<Flags> parameter

If you want, you can use the Flags parameter with the BITSET( ) function to detect different key and mouse button combinations. BITSET( ) evaluates a numeric value and returns true (.T.) or false, depending on whether a particular bit in the value is on (1) or off (0). Give BITSET( ) two parameters:

The <Flags> value itself

The bit in <Flags> to evaluate

The values you can pass to BITSET( ) through the second parameter are as follows:

Simultaneous keypress	Second parameter

Left mouse button	0

Shift	2

Ctrl	3

Middle mouse button	4

For example, to determine if the user pressed Shift while clicking the object, use BITSET(Flags, 2). If the user did, BITSET( ) returns true. If BITSET(Flags, 3) and BITSET(Flags, 0) both return true, Ctrl and the left mouse button were pressed during the event. You can use such information in IF...ELSE...ENDIF or DO CASE...ENDCASE statements to assign different actions to different key and mouse button combinations.

<Col> and <Row> parameters

The <Col> and <Row> parameters indicate where the right double-click event occurred, letting you make decisions accordingly. For example, the OnRightDblClick property of a form might execute different actions, depending on where the right double-click event occurred in the form. The <Col> and <Row> coordinates are expressed in character units.

Like other event properties, the OnRightDblClick property accepts:

Functions

Procedures

Codeblocks

For information on these subroutines, see Chapter 4 in the Programmer's Guide. For information on writing event-handling subroutines, see Chapter 14 in the Programmer's Guide.

Note:	You can write a subroutine with the Procedure Editor, a window in which you enter dBASE program code. To access the Procedure Editor, click on the Tool button next to the OnRightDblClick item in the Object Inspector.


OnRightDblClick Example

NEW operator syntax:

LOCAL F1

F1=NEW Trips()

F1.OPEN()

CLASS Trips OF FORM

  this.Text = "Trip Schedule"

  this.Top = 2

  this.Left = 2

  this.Width = 38

  this.Height = 18

  this.OnRightDblClick = AnimalKingdom

* AnimalKingdom is a FUNCTION that performs

* an action and returns .T. or some value.

ENDCLASS

DEFINE object syntax:

DEFINE FORM Trips;

  PROPERTY Text "Trip Schedule",;

  Top 2, Left 2, Width 38, Height 18,;

  OnRightDblClick AnimalKingdom

OPEN FORM Trips


See Also

BITSET( )

OnLeftDblClick

OnLeftMouseDown

OnLeftMouseUp

OnMiddleDblClick

OnMiddleMouseDown

OnMiddleMouseUp

OnRightMouseDown

OnRightMouseUp


OnRightMouseDown

See Also	Example	Properties	Forms

Executes a subroutine when the user presses the right mouse button while the pointer is on a form or an object.

Property of Class

BROWSE, CHECKBOX, COMBOBOX, EDITOR, ENTRYFIELD, FORM, IMAGE, LISTBOX, MENU, OLE, PUSHBUTTON, RADIOBUTTON, RECTANGLE, SCROLLBAR, SPINBOX, TEXT

Data Type

Function pointer or codeblock

Description

Use OnRightMouseDown to perform an action when the user presses the right mouse button. OnRightMouseDown can also trap Shift, Ctrl, left mouse button, or middle mouse button presses if they occur at the same time the user presses the button.

OnRightMouseDown passes three parameters to its subroutine:

<Flags> is a single-byte value that tells you which other keys and mouse buttons were pressed when the user pressed the button.

<Col> is the horizontal position of the mouse when the user pressed the button.

<Row> is the vertical position of the mouse when the user pressed the button.

<Flags> parameter

If you want, you can use the Flags parameter with the BITSET( ) function to detect different key and mouse button combinations. BITSET( ) evaluates a numeric value and returns true (.T.) or false, depending on whether a particular bit in the value is on (1) or off (0). You give BITSET( ) two parameters:

The <Flags> value itself

The bit in <Flags> to evaluate

The values you can pass to BITSET( ) through the second parameter are as follows:

Simultaneous keypress	Second parameter

Left mouse button	0

Shift	2

Ctrl	3

Middle mouse button	4

For example, to determine if the user pressed Shift while clicking the object, use BITSET(Flags, 2). If the user did, BITSET( ) returns true. If BITSET(Flags, 3) and BITSET(Flags, 0) both return true, Ctrl and the left mouse button were pressed during the event. You can use such information in IF...ELSE...ENDIF or DO CASE...ENDCASE statements to assign different actions to different key and mouse button combinations.

<Col> and <Row> parameters

The <Col> and <Row> parameters indicate where the right click event occurred, letting you make decisions accordingly. For example, the OnRightMouseDown property of a form might execute different actions, depending on where the right click event occurred in the form. The <Col> and <Row> coordinates are expressed in character units.

Like other event properties, the OnRightMouseDown property accepts:

Functions

Procedures

Codeblocks

For information on these subroutines, see Chapter 4 in the Programmer's Guide. For information on writing event-handling subroutines, see Chapter 14 in the Programmer's Guide.

Note:	You can write a subroutine with the Procedure Editor, a window in which you enter dBASE program code. To access the Procedure Editor, click on the Tool button next to the OnRightMouseDown item in the Object Inspector.


OnRightMouseDown Example

NEW operator syntax:

LOCAL F1

F1=NEW Trips()

F1.OPEN()

CLASS Trips OF FORM

  this.Text = "Trip Schedule"

  this.Top = 2

  this.Left = 2

  this.Width = 38

  this.Height = 18

  this.OnRightMouseDown = AnimalKingdom

* AnimalKingdom is a FUNCTION that performs

* an action and returns .T. or some value.

ENDCLASS

DEFINE object syntax:

DEFINE FORM Trips ;

  PROPERTY Text "Trip Schedule",;

  Top 2, Left 2, Width 38, Height 18,;

  OnRightMouseDown AnimalKingdom

OPEN FORM Trips


See Also

BITSET( )

OnLeftDblClick

OnLeftMouseDown

OnLeftMouseUp

OnMiddleDblClick

OnMiddleMouseDown

OnMiddleMouseUp

OnRightDblClick

OnRightMouseUp


OnRightMouseUp

See Also	Example	Properties	Forms

Executes a subroutine when the user releases the right mouse button while the pointer is on a form or an object.

Property of Class

BROWSE, CHECKBOX, COMBOBOX, EDITOR, ENTRYFIELD, FORM, IMAGE, LISTBOX, MENU, OLE, PUSHBUTTON, RADIOBUTTON, RECTANGLE, SCROLLBAR, SPINBOX, TEXT

Data Type

Function pointer or codeblock

Description

Use OnRightMouseUp to perform an action when the user releases the right mouse button. OnRightMouseUp can also trap Shift, Ctrl, left mouse button, or middle mouse button presses if they occur at the same time the user releases the button.

OnRightMouseUp passes three parameters to its subroutine:

<Flags> is a single-byte value that tells you which other keys and mouse buttons were pressed when the user released the button.

<Col> is the horizontal position of the mouse when the user released the button.

<Row> is the vertical position of the mouse when the user released the button.

<Flags> parameter

If you want, you can use the Flags parameter with the BITSET( ) function to detect different key and mouse button combinations. BITSET( ) evaluates a numeric value and returns true (.T.) or false (.F.), depending on whether a particular bit in the value is on (1) or off (0). Give BITSET( ) two parameters:

The <Flags> value itself.

The bit in <Flags> to evaluate.

The values you can pass to BITSET( ) through the second parameter are as follows:

Simultaneous keypress	Second parameter

Left mouse button	0

Shift	2

Ctrl	3

Middle mouse button	4

For example, to determine if the user pressed Shift while clicking the object, use BITSET(Flags, 2). If the user did, BITSET( ) returns true. If BITSET(Flags, 3) and BITSET(Flags, 0) both return true, Ctrl and the left mouse button were pressed during the event. You can use such information in IF...ELSE...ENDIF or DO CASE...ENDCASE statements to assign different actions to different key and mouse button combinations.

<Col> and <Row> parameters

The <Col> and <Row> parameters indicate where the upward-right click event occurred, letting you make decisions accordingly. For example, the OnRightMouseUp property of a form might execute different actions, depending on where the upward-right click event occurred in the form. The <Col> and <Row> coordinates are expressed in character units.

Like other event properties, the OnRightMouseUp property accepts:

Functions

Procedures

Codeblocks

For information on these subroutines, see Chapter 4 in the Programmer's Guide. For information on writing event-handling subroutines, see Chapter 14 in the Programmer's Guide.

Note:	You can write a subroutine with the Procedure Editor, a window in which you enter dBASE program code. To access the Procedure Editor, click on the Tool button next to the OnRightMouseUp item in the Object Inspector.


OnRightMouseUp Example

NEW operator syntax:

LOCAL F1

F1=NEW Trips()

F1.OPEN()

CLASS Trips OF FORM

  this.Text = "Trip Schedule"

  this.Top = 2

  this.Left = 2

  this.Width = 38

  this.Height = 18

  this.OnRightMouseUp = AnimalKingdom

* AnimalKingdom is a FUNCTION that performs

* an action and returns .T. or some value.

ENDCLASS

DEFINE object syntax:

DEFINE FORM Trips ;

  PROPERTY Text "Trip Schedule",;

  Top 2, Left 2, Width 38, Height 18,;

  OnRightMouseUp AnimalKingdom

OPEN FORM Trips


See Also

BITSET( )

OnLeftDblClick

OnLeftMouseDown

OnLeftMouseUp

OnMiddleDblClick

OnMiddleMouseDown

OnMiddleMouseUp

OnRightDblClick

OnRightMouseDown


OnSelChange

See Also	Example	Properties	Forms

Executes a subroutine when the highlight is moved from one prompt to another in a list box.

Property of Class

LISTBOX

Data Type

Function pointer or codeblock

Description

Use OnSelChange to execute a response each time a new list box prompt is selected.

OnSelChange lets you detect the user's movements through a list box. For example, a list box might use an OnSelChange subroutine to log the user's activity; the subroutine could store the prompt number (the current CurSel value) in a table each time the user moves from prompt to prompt.


OnSelChange Example

NEW operator syntax:

USE Contact

SET PRINTER TO FILE Record.Txt

* NEW Form definition (Lst)

Lst1=NEW LISTBOX(this)

Lst1.Width=40

Lst1.Height=15

Lst1.DataSource="FIELD Contact->Contact"

Lst1.OnSelChange={;? CompCode+SPACE(3)+Contact}

DEFINE object syntax:

USE Contact

SET PRINTER TO FILE Record.Txt

DEFINE FORM Lst FROM 1,1 TO 15,40

DEFINE LISTBOX Lst1 OF Lst;

  PROPERTY Width 40, Height 15,;

    DataSource "FIELD Contact->Contact",;

    OnSelChange {;? CompCode+SPACE(3)+Contact}

OPEN FORM Lst


See Also

Selected( )

Count( )

CurSel


OnSelection

See Also	Example	Properties	Forms

Executes a subroutine when the user submits a form.

Property of Class

FORM

Data Type

Function pointer or codeblock

Description

Use OnSelection to specify a subroutine or a codeblock to execute when the user submits a form. When the user selects the form, the ID property of the last object to have input focus is passed to the subroutine.

A form is submitted when the user

Presses Enter when the form has focus and no browse object or editor object has focus.

Presses Spacebar when a pushbutton has focus.

Clicks a pushbutton.

When the subroutine you specify with OnSelection or ON SELECTION FORM finishes executing, program control returns to the form. However, if the subroutine executes the CLOSE FORM command, the form is closed.

OnSelection sends one parameter, controlid, to its subroutine. This parameter identifies which pushbutton submitted the form. The value in controlid is the same as the value in the ID property of the pushbutton.

Note:	You can use the ON SELECTION FORM command as an alternative to the OnSelection property.


OnSelection Example

NEW operator syntax:

LOCAL F1

F1=NEW Trips()

F1.OPEN()

CLASS Trips OF FORM

  this.Text = "Trip Schedule"

  this.Top = 2

  this.Left = 2

  this.Width = 38

  this.Height = 18

  this.OnSelection = AnimalKingdom

* AnimalKingdom is a FUNCTION that performs

* an action and returns .T. or some value.

ENDCLASS

DEFINE object syntax:

DEFINE FORM Trips ;

  PROPERTY Text "Trip Schedule",;

  Top 2, Left 2, Width 38, Height 18,;

  OnSelection AnimalKingdom


See Also

OnGotFocus

ON SELECTION FORM


OnSize

See Also	Example	Properties	Forms

Executes a subroutine after the user resizes a form.

Property of Class

FORM

Data Type

Function pointer or codeblock

Description

Use OnSize to perform actions automatically when the user resizes a form.

Like other event properties, the OnSize property accepts

Functions

Procedures

Codeblocks

For information on these subroutines, see Chapter 4 in the Programmer's Guide. For information on writing event-handling routines, see Chapter 14 in the Programmer's Guide.

OnSize passes three parameters to its subroutine:

<nType> is a numeric value that indicates how the user resizes the form. nType has three possible values:

0: the user resized the form with the mouse or restored the form from a maximized or minimized condition.

1: the user minimized the form.

2: the user maximized the form.

<width> is the new width of the object.

<height> is the new height of the object.

The height and width parameters reveal the new size, letting you make decisions accordingly.

Note:	You can write a subroutine with the Procedure Editor, a window in which you enter dBASE program code. To access the Procedure Editor, click on the Tool button next to the OnSize item in the Object Inspector.

When the user resizes a form that does not have input focus initially, the When and OnGotFocus subroutines are executed first.

Before the user can resize a form manually, the Sizeable property must be set to true (.T.).


OnSize Example

NEW operator syntax:

LOCAL F1

F1=NEW Trips()

F1.OPEN()

CLASS Trips OF FORM

  this.Text = "Trip Schedule"

  this.Top = 2

  this.Left = 2

  this.Width = 38

  this.Height = 18

  this.OnSize = Shuffle

* Shuffle is a FUNCTION that performs

* an action and returns .T. or some value.

ENDCLASS

DEFINE object syntax:

DEFINE FORM Trips FROM 2,2 TO 20,40;

  PROPERTY Text "Trip Schedule",;

  Top 2, Left 2, Width 38, Height 18,;

  OnSize Shuffle

OPEN FORM Trips


See Also

OnChange

OnClick

OnClose

OnGotFocus

OnHelp

OnLeftMouseDown

OnLostFocus

OnMove

OnOpen

Sizeable


OnUnadvise

See Also	Example	Properties

Executes a subroutine when dBASE is requested to stop notifying the client application when a dBASE data item changes.

Property of Class

DDETOPIC

Data Type

Logical

Description

Use the OnUnAdvise method to respond to the termination of a hot link. (A hot link lets you use the Notify( ) method to notify the client when an item changes.)

OnUnAdvise receives the <item> parameter, the name of a dBASE data item that the client application monitored. This item can be any dBASE field, variable, or array element.

Item names are often held in tables or array objects when multiple hot links are established. For example, when a client application requests a hot link to a field, it passes the field name to the OnAdvise subroutine. Each time, the OnAdvise subroutine can place the field name in an array object.

An OnPoke subroutine can search this array object each time a field is changed. If the name of the changed field is found in the array object, the routine can execute Notify( ). The OnUnadvise( ) property can remove the field name from the array, preventing further notifications for that field.


OnUnadvise Example

See CLASS DDETOPIC for an example of using OnUnAdvise property.


See Also

Advise( )

Execute( )

Initiate( )

OnNewValue

Peek( )

Poke( )

Server

Terminate( )

Timeout

Topic

Unadvise( )


Open( )

See Also	Example	Properties	Forms

Opens a form as a modeless window.

Property of Class

FORM

Description

Use the Open( ) method to open a form and display its objects.

The form you open with Open( ) is modeless, and has the following characteristics:

While the form is open, focus can be transferred to other forms.

Execution of the routine that opened the form continues after the form is opened and active.

Open forms as modeless windows when you want more than one form open at once.

Note:	To open a form as a modal window, use the ReadModal( ) method or the READMODAL( ) function. For example, forms that serve as dialog boxes are modal, since they halt program execution until the user inputs a response.

Open( ) is identical to the OPEN FORM command.


Open( ) Example

LOCAL f
f = NEW XFORM()
f.Open()

CLASS XFORM OF FORM
   this.HelpFile = ""
   this.Top =          2.23
   this.Height =         20.00
   this.Text = "See..it opens"
   this.Left =         35.00
   this.Width =         73.80
   this.HelpId = ""

ENDCLASS


See Also

CLOSE...

Close( )

OPEN FORM

ReadModal( )

READMODAL( )


Parent

See Also	Example	Properties	Forms

An object reference that points to the parent form of an object or a menu.

Property of Class

BROWSE, CHECKBOX, COMBOBOX, EDITOR, ENTRYFIELD, IMAGE, LINE, LISTBOX, MENU, OLE, PUSHBUTTON, RADIOBUTTON, RECTANGLE, SCROLLBAR, SPINBOX, TEXT

Data Type

Object reference

Description

Use Parent to reference the parent form of an object.

Set the Parent property with the OF <form name> clause of the DEFINE or REDEFINE command when you create the object. You can also set the Parent property with the <form name> parameter you specify for the object when you create the object with the NEW operator.

You can move a menu object from one form to another by changing the Parent property of the menu object. The Parent property is read-only for all other classes.


Parent Example

The following example creates a form with a main menu presenting the text string "File". A submenu selection of File is "Change Parent Text", which uses the Parent property to change "File" to the string "New Text":

DEFINE FORM f1
DEFINE MENU Main OF f1
DEFINE MENU mFile OF f1.Main;
  PROPERTY;
  Text "File"
DEFINE MENU mCp OF f1.Main.mFile;
  PROPERTY;
  Text "Change Parent Text",;
  OnClick {;this.Parent.Text = "New Text"}
OPEN FORM f1


See Also

ActiveControl

Before

First


PatternStyle

See Also	Example	Properties	Forms

Specifies a predefined Windows background hatching pattern.

Property of Class

RECTANGLE

Data Type

Numeric

Default

The default for PatternStyle is 0.

Description

Use PatternStyle to select a predefined Windows background hatching pattern for a rectangle object.

You can specify the following settings for PatternStyle:

Number	Description	Example
0	Solid
1	BDiagonal
2	Cross
3	Diagcross
4	Fdiagonal
5	Horizontal
6	Vertical


PatternStyle Example

NEW operator syntax:

Comp = NEW ENTRYFIELD(this)

Comp.Datalink = "Clients->Company"

Comp.PatternStyle = 3

DEFINE object syntax:

DEFINE ENTRYFIELD Comp OF THIS;

  PROPERTY Datalink "Clients->Company",;

  PatternStyle 3


See Also

ColorHighlight

ColorNormal


Peek( )

See Also	Example	Properties

Retrieves a data item from a DDE server.

Property of Class

DDELINK

Description

Use the Peek( ) method to read data from a DDE server topic.

A server topic is usually a file you open in an external application. For example, a data-exchange program might start a session in Quattro Pro for Windows, open one of its spreadsheet files (the topic), and use Peek( ) to read one of its cells.

Peek( ) requires <item>, a parameter that identifies a data item in the server topic. This item can be any single element, such as a field in a table or a cell in a spreadsheet. For example, you can read cell C2 of Page A in a Quattro Pro spreadsheet file by passing the <item> parameter "A:C2".

Before you can query data from a server topic, you need to establish a DDE link to it. For information on establishing DDE links, see Initiate( ) and Chapter 26 in the Programmer's Guide.


Peek( ) Example

PUBLIC LinkObj

LinkObj = NEW DDELINK()

IF LinkObj.Initiate("QPW","Demo.WB1")

  ? "Connection to QPW initiated"

ELSE

  ? "Connection to QPW failed"

ENDIF

mValue1=LinkObj.Peek("A:A1")

? mValue1


See Also

Advise( )

Execute( )

Initiate( )

OnNewValue

Poke( )

Server

Terminate( )

Timeout

Topic

Unadvise( )


Pen

See Also	Example	Properties	Forms

Specifies the pattern of a line object.

Property of Class

LINE

Data Type

Numeric

Default

The default for Pen is 0 (Solid).

Description

Use Pen to control the appearance of a line object.

You can specify any of five settings for Pen:

Number	Description	Example
0	Solid
1	Dash
2	Dot
3	Dash Dot
4	DashDotDot


Pen Example

NEW operator syntax:

Ln2=NEW LINE(this)

Ln2.Left=3

Ln2.Top=8

Ln2.Bottom=8

Ln2.Right=33

Ln2.Pen = 3              && Dash Dot

DEFINE object syntax:

DEFINE LINE Ln2 OF THIS;

  PROPERTY Left 3, Top 8, Bottom 8,;

    Right 33, Pen 3      && Dash Dot


See Also

PatternStyle


Picture

See Also	Example	Properties	Forms

Formats text in an entry field, a spin box, or a text object.

Property of Class

ENTRYFIELD, SPINBOX, TEXT

Data Type

Character

Default

The default for Picture is an empty string.

Description

Specify the picture setting with a character string called a template. A template can consist of

Picture template characters, which represent and modify individual characters in the text string.

Function symbols, which usually modify the entire text string. (For information on function symbols, see the Function property.)

Literal characters, which are inserted into the text string.

Here are the picture template characters:

9	Restricts entry of character data to numbers, and restricts entry of numeric

data to numbers and + and - signs

#	Restricts entry to numbers, spaces, periods, and signs

!	Converts letters to uppercase

$	Inserts a dollar sign or the symbol defined with SET CURRENCY TO instead of leading blanks

*	Inserts asterisks in place of leading spaces

.	Marks the position of the decimal point

,	Separates thousands with a comma (or with another character indicated by SET SEPARATOR)

A	Restricts entry to alphabetic characters

L	Restricts entry to T, t, F, f, Y, y, N, or n, and converts it to uppercase

N	Restricts entry to letters and numbers

X	Allows any character

Y	Restricts entry to Y, y, N, or n, and restricts display to Y and N

If you use function symbols in a template, precede them with the @ symbol. If you combine template characters and function symbols in the same template, list function symbols first and separate them from the template characters with a space.

Note:	You can specify a picture template with the Choose Template dialog box, which lets you enter picture templates. To access the Choose Template dialog box, click the Tool button next to the Picture item in the Object Inspector.


Picture Example

NEW operator syntax:

FLD1.Picture = "@!"

* or

FLD1.Picture = "$999,999,999.99"

* or

FLD1.Picture = "99:99:99"

DEFINE object syntax:

DEFINE ENTRYFIELD FLD1 OF THIS;

  PROPERTY Datalink "<char, numeric or date field>",;

  Picture "@!"

* or

  Picture "$999,999,999.99"

* or

  Picture "99:99:99"


See Also

@...SAY...GET

DEFINE

Function

TRANSFORM( )


Poke( )

See Also	Example	Properties

Inserts data into a server document.

Property of Class

DDELINK

Description

Use the Poke( ) method to write data to a server document.

A server document is a file you open in an external application. For example, a data-exchange program might start a session in Quattro Pro for Windows, open one of its spreadsheet files, and use Poke( ) to write a value into one of its cells.

Poke( ) requires two parameters:

<item> is the element you write to in the server document. It can be any single item, such as a field in a table or a cell in a spreadsheet. For example, "B:G2" specifies Cell G2 of Page B in a Quattro Pro spreadsheet file.

<value> is the value you write to the server document. For example, you can pass a literal or the value stored in a field.

Before you can send data to a server document, you need to open the server application, open the document, and establish a DDE link to it. For information on establishing DDE links, see Initiate( ) and Chapter 26 in the Programmer's Guide.


Poke( ) Example

PUBLIC LinkObj

LinkObj = NEW DDELINK()

IF LinkObj.Initiate("QPW","Demo.WB1")

  ? "Connection to QPW initiated"

ELSE

  ? "Connection to QPW failed"

ENDIF

LinkObj.Poke("A:A3","198")

mValue2=LinkObj.Peek("A:A3")

? mValue2          && Confirm success of .POKE()


See Also

Advise( )

Execute( )

Initiate( )

OnNewValue

Peek( )

Server

Terminate( )

Timeout

Topic

Unadvise( )


Print( )

See Also	Example	Properties	Forms

Prints a form and the objects it contains.

Property of Class

FORM

Description

Use the Print( ) method to print a form on a selected printer.

Executing the Print( ) method opens the Print dialog box, which lets the user determine:

The number of pages to print

The print quality

The number of copies to print

If the output goes to the printer or to a file

If the output is collated

The user clicks the OK button to print the form.

Executing the Print( ) method is equivalent to selecting File | Print. To determine which printer receives the output, execute the CHOOSEPRINTER( ) function.


Print( ) Example

The following example defines a form that includes a browse object. When the user has located a record or subset of records to print, clicking the right mouse calls a codeblock that uses PRINT( ) to send currently displayed records to the printer:

LOCAL f
f = NEW XFORM()
f.Open()

CLASS XFORM OF FORM
   this.HelpFile = ""
   this.Top =          5.71
   this.Height =         14.71
   this.Text = "Form"
   this.View = "ANIMALS.DBF"
   this.OnRightMouseDown = {;this.Print()}
   this.Left =         34.20
   this.Width =         86.80
   this.HelpId = ""

   DEFINE BROWSE BR1 OF THIS;
       PROPERTY;
         Top          3.00,;
         Height          8.00,;
         FontBold .F.,;
         ColorNormal "N/W",;
         Left          8.00,;
         Width         69.00

ENDCLASS


See Also

CHOOSEPRINTER( )

PRINTJOB...ENDPRINTJOB

SET PRINTER


RangeMax

See Also	Example	Properties	Forms

Determines the upper limit for values the user can enter in a spin box.

Property of Class

SCROLLBAR, SPINBOX

Data Type

Date or numeric

Default

The default for RangeMax is 100.00.

Description

Use RangeMax in combination with RangeMin to specify a range restriction for values entered into a scroll bar or a spin box. (RangeMax sets the upper limit and RangeMin sets the lower limit.) For example, an application that lets the user input a percentage might prevent the the input of a value less than 0 or greater than 100.

Users must enter a value within the specified range before they can give focus to another object.

Note:	Range restrictions have effect only when the RangeRequired property is true (.T.).


RangeMax Example

NEW operator syntax:

SPNBX1.RangeMax = 100

* or

SPNBX1.RangeMax = {12/31/94}

DEFINE object syntax:

DEFINE SpinBox Spn1 OF THIS;

  PROPERTY DataLink "<numeric or date field>",;

  RangeMax 100

  * or

  RangeMax {12/31/94}


See Also

RangeMin

RangeRequired

Valid

ValidErrorMsg

ValidRequired


RangeMin

See Also	Example	Properties	Forms

Determines the lower limit for values the user can enter in a spin box.

Property of Class

SCROLLBAR, SPINBOX

Data Type

Date or numeric

Default

The default for RangeMin is 1.

Description

Use RangeMin in combination with RangeMax to specify a range restriction for values entered into a scroll bar or a spin box. (RangeMin sets the lower limit and RangeMax sets the upper limit.) For example, an application that lets the user input a percentage might prevent the input of a value less than 0 or greater than 100.

Users must enter a value within the specified range before they can give focus to another object.

Note:	Range restrictions have effect only when the RangeRequired property is true (.T.).


RangeMin Example

NEW operator syntax:

SPNBX1.RangeMin = 1

* or

SPNBX1.RangeMin = {01/01/94}

DEFINE object syntax:

DEFINE SpinBox Spn1 OF THIS;

  PROPERTY DataLink "<numeric or date field>",;

  RangeMin 1

  * or

  RangeMin {01/01/94}


See Also

RangeMax

RangeRequired

Valid

ValidErrorMsg

ValidRequired


RangeRequired

See Also	Example	Properties	Forms

Determines whether the range you specify with the RangeMax and RangeMin properties is enforced.

Property of Class

SPINBOX

Data Type

Logical

Default

The default for RangeRequired is false (.F.).

Description

Set RangeRequired to true (.T.) when you want to enforce a range limitation specified by the RangeMax and RangeMin properties.

For example, when the RangeRequired property of a spin box is set to true, dBASE detects any range error and forces the user to correct the problem. Users must enter a value within the specified range before they can give focus to another object.


RangeRequired Example

NEW operator syntax:

Date = NEW ENTRYFIELD(this)

Date.Datalink = "Clients->Baldate"

Date.RangeRequired = .T.

Date.RangeMax = {12/31/95}

DEFINE object syntax:

DEFINE ENTRYFIELD Date OF THIS;

  PROPERTY Datalink "Clients->Baldate",;

  RangeRequired .T., RangeMax {12/31/95}


See Also

RangeMax

RangeMin

Valid

ValidErrorMsg


ReadModal( )

See Also	Example	Properties	Forms

Opens a form as a modal window.

Property of Class

FORM

Description

Use ReadModal( ) to open a form as a modal window. A modal window has the following characteristics:

While the form is open, focus cannot be transferred to other forms.

Execution of the routine that opened the form stops until the form is closed. When the form is closed, control transfers to the command line after the one that opened the form.

Many applications use modal forms as dialog boxes, which typically require users to take an action before the dialog box can be closed.

You cannot open a form with the ReadModal( ) method or the READMODAL( ) function when the MDI property is set to true.

To open a form as a modeless window, use the Open( ) method or the OPEN FORM command.

The ReadModal( ) method is identical to the READMODAL( ) function.


ReadModal( ) Example

LOCAL f

f=NEW EntryForm()

f.readmodal()

CLASS EntryForm OF FORM

  this.MDI=.F.

  this.Top=2

  this.Left=2

  this.Width=38

  this.Height=13

* subsequent object definitions

ENDCLASS


See Also

Close( )

CLOSE...

OPEN FORM

Open( )

READMODAL( )


Reconnect( )

See Also	Example	Properties

Attempts to restart a terminated conversation with a DDE server application and returns true (.T.) if successful.

Property of Class

DDELINK

Description

Use Reconnect( ) to restore a DDE link that was terminated with the Terminate( ) method.

Use a DDE link to exchange data and instructions with another application. For example, a data-exchange program might establish a link with Quattro Pro for Windows and open one of its spreadsheet files, then copy data from the spreadsheet to a dBASE table.

When you terminate a DDE link with Terminate( ), you can restore it with Reconnect. When you terminate the link with the Release( ) method, the link cannot be restored and you need to create the DDELink object again.


Reconnect( ) Example

PUBLIC LinkObj

LinkObj = NEW DDELINK()

LinkObj.Initiate("QPW","Demo.WB1")

* Subsequent program operations completed; link

* do longer required

LinkObj.Terminate()

* Later in program, DDE link object again needed

LinkObj.Reconnect()


See Also

Initiate( )

Release( )

Terminate( )


Release( )

See Also	Example	Properties	Forms

Removes an object definition from memory.

Property of Class

BROWSE, DDELINK, DDETOPIC, CHECKBOX, COMBOBOX, EDITOR, ENTRYFIELD, FORM, IMAGE, LINE, LISTBOX, MENU, OLE, PUSHBUTTON, RADIOBUTTON, RECTANGLE, SCROLLBAR, SPINBOX, TEXT

Description

Use Release( ) to conserve memory resources when an object is no longer needed. For example, when an application does not need a form, removing the form from memory frees up memory for other purposes.

Note: When a form is closed, dBASE releases it from memory automatically if there is no object reference pointing to it.


Release( ) Example

NEW operator syntax:

LOCAL f

f=NEW EntryForm()

f.OPEN()

  CLASS EntryForm OF FORM

    this.Top=2

    this.Left=2

    this.Width=38

    this.Height=13

    this.OnClose={;Form.Release()}

* Subsequent object definitions

ENDCLASS

DEFINE object syntax:

DEFINE FORM EntryForm;

  PROPERTY Top 2, Left 2, Width 38, Height 13,;

  OnClose {;Form.Release()}

* Other control definitions

OPEN FORM EntryForm


See Also

RELEASE OBJECT


Resize( )

See Also	Example	Properties

Increases or decreases the number of elements in an array object.

Property of Class

ARRAY

Description

Use the Resize( ) method to add or remove rows and columns from an array object. The Resize( ) method is similar to the ARESIZE( ) function.

Resize( ) accepts three parameters:

<new rows expN>--The number of rows in the resized array object. <new rows expN> must always be a positive, nonzero value.

<new cols expN>--The number of columns in the resized array object. <new cols expN> must always be 0 or a positive value. If you omit this option, Resize( ) changes the number of rows and leaves the number of columns the same.

<retain values expN>--Determines how the array elements are rearranged when rows are added or removed. To see the effect of <retain values expN>, see ARESIZE( ).


Resize( ) Example

USE Customer.DBF

* Initialize array object

ObjArr=NEW ARRAY(RECCOUNT())

* Fill 1-dimensional array with values

* from Name field of Customer.DBF

GO TOP

FOR i=1 TO RECCOUNT()

  ObjArr[i]=Customer->Name

  SKIP

Next i

* Use RESIZE() to add two additional columns to the

* existing array and enter Ytd_Sales and phone data

* in the new columns.

ObjArr.RESIZE(RECCOUNT(),3,1)

GO TOP

FOR i=1 TO RECCOUNT()

  ObjArr[i,2]=Customer->YTD_Sales

  ObjArr[i,3]=Customer->Phone

  SKIP

Next i

* Display Contents of 3-dimensional array

FOR i = 1 TO RECCOUNT()

? ObjArr[i,1], ObjArr[i,2], ObjArr[i,3]

Next i


See Also

Add( )

Insert( )

Grow( )

ARESIZE( )

Insert( )


Right

See Also	Example	Properties	Forms

Specifies the position of the right end of a line object relative to its parent form.

Property of Class

LINE

Data Type

Numeric

Description

Use the Right property in combination with the Bottom, Left, and Top properties to determine the position and length of a line object.

Each unit of the value you assign to Right is the average width of characters in the active font of the parent form. For example, if you set the Right property of a line to 20, the right end of the line is positioned 20 characters to the right.


Right Example

DEFINE LINE Ln1 OF THIS;

  PROPERTY;

    Left 10,;          && Vertical line from 3,10

    Top 3,;            && to 8,10

    Width 4,;

    Bottom 8,;

    ColorNormal "RB"

DEFINE LINE Ln2 OF THIS;

  PROPERTY;

    Left 3,;           && Horizontal line from 8,3

    Top 8,;            && to 8,33

    Width 4,;

    Bottom 8,;

    Right 33,;

    ColorNormal "RB"


See Also

Height

ScaleFontName

ScaleFontSize

Top

Width


ScaleFontName

See Also	Example	Properties	Forms

Determines which font the coordinate plane of the form is based on.

Property of Class

FORM

Data Type

Character

Default

The default for FontName is MS Sans Serif.

Description

Use ScaleFontName in combination with ScaleFontSize to determine the height of rows and the width of columns in the coordinate plane of a form.

The coordinate plane is a two-dimensional grid of row and column coordinates. The height of rows and the width of columns in the coordinate plane depend primarily on

The active font of the form, which you specify with ScaleFontName. Different fonts have different widths and heights, so changing the specification in ScaleFontName can alter the height of rows and the width of columns.

The size of the font, which you specify with ScaleFontSize. (The value you specify for ScaleFontSize is in points).

Together, the row height and column width of a coordinate plane make up a character unit. Properties such as Height and Width use character units to determine object size and position. For example, the Height property expresses height by character units, as with:

MyForm.MyObj.Height = 2.4 && 2.4 character units

The actual height of the object depends on the number of character units and on character unit size.

For more information on the coordinate plane, see Chapter 16 in the Programmer's Guide.

Note:	You can select a font with the Font dialog box, which displays all installed fonts. To access the Font dialog box, click on the Tool button next to the ScaleFontName item in the Object Inspector. You can also open the Font dialog box with the GETFONT( ) function.


ScaleFontName Example

LOCAL f

f=NEW Scale()

f.OPEN()

CLASS Scale OF FORM

  this.ScaleFontName = "Courier"

  this.ScaleFontSize = 15

   DEFINE TEXT Txt1 OF THIS;

     PROPERTY Text "dBASE for Windows",;

     Width 40, Top 5, Alignment 4

ENDCLASS


See Also

Bottom

GetTextExtent( )

Height

Right

Top

Width


ScaleFontSize

See Also	Example	Properties	Forms

Determines the height of each row and the width of each column in the coordinate plane of a form.

Property of Class

FORM

Data Type

Numeric

Default

The default for ScaleFontSize is 8.00.

Description

Use ScaleFontSize in combination with ScaleFontName to determine the height of rows and the width of columns in the coordinate plane of a form.

The coordinate plane is a two-dimensional grid of row and column coordinates. The height of rows and the width of columns in the coordinate plane depend primarily on

The active font of the form, which you specify with ScaleFontName. Different fonts have different average widths and heights, so changing the specification in ScaleFontName can alter the height of rows and the width of columns.

The size of the font, which you specify with ScaleFontSize. (The value you specify for ScaleFontSize is in points).

Together, the row height and column width of a coordinate plane make up a character unit. Properties such as Height and Width use character units to determine object size and position. For example, the Height property expresses height by character units, as with:

MyForm.MyObj.Height = 4.5 && 4.5 Character units

The actual height of the object depends on the number of character units and on character unit size.

For more information on the coordinate plane, see Chapter 16 in the Programmer's Guide.


ScaleFontSize Example

LOCAL f

f=NEW Scale()

f.OPEN()

CLASS Scale OF FORM

  this.ScaleFontName = "Courier"

  this.ScaleFontSize = 15

   DEFINE TEXT Txt1 OF THIS;

     PROPERTY Text "dBASE for Windows",;

     Width 40, Top 5, Alignment 4

ENDCLASS


See Also

Bottom

Height

Right

Top

Width


Scan( )

See Also	Example	Properties

Searches an array object for a specified value.

Property of Class

ARRAY

Description

Use the Scan( ) method to search an array object for a value. For example, if an array object contains customer names, use Scan( ) to find the location in which a particular name appears. The Scan( ) method is similar to the ASCAN( ) function.

Scan( ) returns the element number of the first element that matches the expression if the search is successful, or 0 if the search is unsuccessful. If necessary, use Subscript( ) to determine the subscript numbers of the element. For more information about element numbers and subscripts, see Element( ) and Subscript( ).

Scan( ) accepts three parameters:

<exp> is the expression to search for.

<starting element expN> is the element number of the element at which to start searching. Without <starting element expN>, Scan( ) starts searching at the first element.

<elements expN> is the number of elements that Scan( ) searches. Without <elements expN>, Scan( ) searches the array object from <starting element expN> to the last element. If you specify a value for <elements expN>, also specify a value for <starting element expN>.

When <exp> contains string data, Scan( ) is case-sensitive, so you might want to use UPPER( ), LOWER( ), or PROPER( ) to match the case of <exp> with the case of the data stored in the array object.

When <exp> contains string data, Scan( ) searches for an expression following the rules established by SET EXACT. If SET EXACT is ON, dBASE returns 0 if the value in <exp> is not identical to the data in an element of the array object. If SET EXACT is OFF, dBASE returns 0 if the characters in <expN> do not match the beginning characters in the data in an element of the array object. For more information, see SET EXACT.


Scan( ) Example

USE Animals.DBF

* Initialize an array object

ObjArr=NEW ARRAY(RECCOUNT(),3)

* Fill array with values from Animals.DBF

COPY TO ARRAY ObjArr FIELDS Name, Area, Weight

* Use SCAN() to search the array for the string

* "Parrot" and return the array element number.

* SUBSCRIPT() is used to return the row and column

* of the element number returned by SCAN():

String = "Parrot"

aElement = ObjArr.Scan(String)

aRow = ObjArr.SUBSCRIPT(aElement,1)

aCol = ObjArr.SUBSCRIPT(aElement,2)

? String +" is located at Row " + ;

  LTRIM(STR(aRow)) + ", Column " + ;

  LTRIM(STR(aCol))


See Also

ASCAN( )

Element( )

LOWER( )

PROPER( )

SET EXACT

Sort( )

Subscript( )

UPPER( )


ScrollBar

See Also	Example	Properties	Forms

Determines if a form or an editor object has a scroll bar.

Property of Class

EDITOR, FORM

Data Type

Numeric

Default

The default for ScrollBar is 1 (On) for editor objects and 0 (Off) for forms.

Description

Create a scroll bar to let the user page through a form or an editor object when its contents exceed its size. For example, if an editor object contains twenty lines of text and the editor object is only ten lines high, a scroll bar lets the user page up and down through the text.

ScrollBar can have any of four settings:

0: Off	The object has no scroll bar.
1: On	The object has a scroll bar.
2: Auto	Displays the scroll bar only when needed.
3: Disabled	The scroll bar is visible but it is not usable.


ScrollBar Example

LOCAL f
f = NEW XFORM()
f.Open()

CLASS XFORM OF FORM
   this.HelpFile = ""
   this.Top =          1.82
   this.Height =         20.00
   this.Text = "Form"
   this.ScrollBar =          1
   this.Left =         33.00
   this.Width =         72.00
   this.HelpId = ""

   DEFINE EDITOR ED1 OF THIS;
       PROPERTY;
         DataLink "CONTACT->NOTES",;
         Top          5.00,;
         Height         10.00,;
         Border .T.,;
         ColorNormal "N/W*",;
         ScrollBar          0,;
         Left         13.00,;
         Width         50.00

ENDCLASS


See Also

CLASS SCROLLBAR


SelectAll

See Also	Example	Properties	Forms

Determines if the value contained in an entry field or a spin box initially appears selected (highlighted).

Property of Class

ENTRYFIELD, SPINBOX

Data Type

Logical

Default

The default for SelectAll is false (.F.).

Description

Set SelectAll to true (.T.) to give the user a shortcut for deleting or replacing the initial value in an entry field or a spin box. The value (which you specify with the DataLink or Value property) is highlighted when the user gives the object focus, and the first character the user enters overwrites the value. Pressing Del or Backspace deletes the value. Pressing a direction key (such as Left arrow or Right arrow) removes the highlight without erasing the value.


SelectAll Example

NEW operator syntax:

Date = NEW ENTRYFIELD(this)

Date.Datalink = "Clients->Baldate"

Date.SelectAll = .T.

DEFINE object syntax:

DEFINE ENTRYFIELD Date OF THIS;

  PROPERTY Datalink "Clients->Baldate",;

  SelectAll .T.


See Also

Mode

Style


Selected( )

See Also	Example	Properties	Forms

Returns the currently selected prompt in a list box.

Property of Class

LISTBOX

Description

Use Selected( ) in combination with Count( ) to evaluate user choices in a multiple-choice list box. For example, you can can see which prompts were chosen by evaluating each prompt with the Selected( ) method in a FOR...NEXT loop. (If the list box has an uncertain number of prompts, use Count( ) to determine the number of times to execute the loop.)

Selected( ) accepts one optional parameter, <item>, a numeric value that identifies an item by its relative position in the list box.

Make a list box multiple-choice by setting the Multiple property to true (.T.).


Selected( ) Example

See Count( ) for an example of using Selected( ).


See Also

FOR...NEXT

Count( )

Multiple


Separator

See Also	Example	Properties	Forms

Determines if a menu item is a line that the user cannot select.

Property of Class

MENU

Data Type

Logical

Default

The default for Separator is false (.F.).

Description

Set Separator to true (.T.) when you want to use a menu item as a separator between groups of menu commands. For example, a menu titled Accounting might use a separator to emphasize the distinction between Accounts Receivable items and Accounts Payable items.


Separator Example

DEFINE FORM f1

DEFINE MENU Main OF f1

DEFINE MENU mOpt1 OF f1.Main;

  PROPERTY;

  Text "Option 1"

DEFINE MENU mSlct1 OF f1.Main.mOpt1;

  PROPERTY;

  Text "Select 1"

DEFINE MENU mLine1 OF f1.Main.mOpt1;

  PROPERTY;

  Separator .T.

DEFINE MENU mSlct2 OF f1.Main.mOpt1;

  PROPERTY;

  Text "Select 2"

DEFINE MENU mLine2 OF f1.Main.mOpt1;

  PROPERTY;

  Separator .T.

DEFINE MENU mSlct3 OF f1.Main.mOpt1;

  PROPERTY;

  Text "Select 3"

OPEN FORM f1


See Also

CLASS MENU


Server

See Also	Example	Properties

Holds the name of a DDE server application.

Property of Class

DDELINK

Data Type

Character

Description

Use Server to identify the server application that you established a DDE link to.

Create a DDE link with the Initiate( ) method. For example, Initiate( ) might establish a link to Quattro Pro for Windows, open one of its spreadsheet files, and copy data from its cells into a dBASE table.

Server holds the value of the first parameter you passed to Initiate( ), which is the name of the main executable file of the server application.


Server Example

PUBLIC LinkObj

LinkObj = NEW DDELINK()

LinkObj.Initiate("QPW","Demo.WB1")

* Subsequent program operations

IF LinkObj.Server="QPW" .AND. ;

   LinkObj.Topic = "Demo.WB1"

      mValue1=LinkObj.Peek("A:A1")

ENDIF


See Also

Advise( )

Execute( )

Initiate( )

OnNewValue

Peek( )

Poke( )

Terminate( )

Timeout

Topic

Unadvise( )


ServerName

See Also	Example	Properties	Forms

Identifies the server application that is invoked when the user double-clicks an OLE viewer object.

Property of Class

OLE

Data Type

Character

Default

The default for ServerName is an empty string.

Description

Use ServerName to anticipate which server application is activated if the user double-clicks the current OLE viewer object.

An OLE viewer object displays an OLE document. An OLE document can be a graphic image, a document created by a word processor, or any other data object created by an external application. This external application is known as the OLE server. For example, a graphic image created in Paintbrush can be an OLE document, and Paintbrush can be an OLE server, if you embed the graphic image (or a portion of it) in an OLE field with the Cut and Paste commands of the Edit menu.

ServerName is a read-only property.


ServerName Example

See DoVerb( ) for an example of using ServerName.


See Also

LinkFileName

OleType


SetFocus( )

See Also	Example	Properties	Forms

Gives focus to a form or an object in a form.

Property of Class

BROWSE, CHECKBOX, COMBOBOX, EDITOR, ENTRYFIELD, FORM, IMAGE, LISTBOX, OLE, PUSHBUTTON, RADIOBUTTON, SCROLLBAR, SPINBOX

Description

Use SetFocus( ) to make a form or an object in a form ready to receive user input.

When a form has focus, its title bar is highlighted. When an object in a form has focus, its border is highlighted. A form or object with focus is sometimes said to be current.


SetFocus( ) Example

NEW operator syntax:

LOCAL f

f=NEW EntryForm()

f.OPEN()

CLASS Entryform OF FORM

  this.View="Company.DBF"

  this.Fld1 = NEW Entryfield(this)

  this.Fld1.Top = 3

  this.Fld1.Left = 1

  this.Fld1.Width=20

  this.Fld1.Datalink = "Company->Company"

  this.Fld2 = NEW Entryfield(this)

  this.Fld2.Top = 5

  this.Fld2.Left = 1

  this.Fld2.Datalink = "Company->State_Prov"

* to shift focus to Fld2 when you move the mouse

* over the second field:

  this.Fld2.OnMouseMove = {;this.SetFocus()}

ENDCLASS

DEFINE object syntax:

DEFINE ENTRYFIELD Company OF THIS;

  Property Datalink "Company->Company",;

  Top 3, Left 1, Width 20

DEFINE ENTRYFIELD State OF THIS;

  Property Datalink "Company->State_Prov",;

  Top 5, Left 1,;

* to shift focus to Fld2 when you move the mouse

* over the second field:

  OnMouseMove {;this.SETFOCUS()}


See Also

ActiveControl

_curobj

NextObj

SET CUAENTER


ShortCut

See Also	Example	Properties	Forms

Specifies a key combination that executes the OnClick subroutine of a menu object.

Property of Class

MENU

Data Type

Character

Default

The default for ShortCut is an empty string.

Description

Use ShortCut to provide a quick way to execute a menu command with the keyboard. For example, if you assign the character string "CTRL+S" to ShortCut, the user can execute the OnClick subroutine by pressing Ctrl+S or Ctrl+s.

The value you specify with ShortCut is displayed next to the prompt you specify with the Text property.


ShortCut Example

NEW operator syntax:

FileMnt= NEW MENU ITEM(this)

FileMnt.ShortCut = "Alt+F"

DEFINE object syntax:

DEFINE MENU ITEM FileMnt OF THIS;

  PROPERTY ShortCut "Alt+F"


See Also

OnClick


ShowDeleted

See Also	Example	Properties	Forms

Determines if the delete box column in a browse object is displayed.

Property of Class

BROWSE

Data Type

Logical

Default

The default for ShowDeleted is true (.T.).

Description

Use ShowDeleted to display or omit delete boxes at the left of each record in a browse object.

The setting you give to ShowDeleted has an effect only when SET DELETED is OFF. When SET DELETED is ON, the delete boxes are never displayed.


ShowDeleted Example

NEW operator syntax:

Br1=NEW BROWSE(this)

Br1.Fields="CompCode,Contact"

Br1.ShowDeleted=.T.

DEFINE object syntax:

DEFINE BROWSE Br1 OF THIS;

    PROPERTY Fields "CompCode, Contact",;

      ShowDeleted .T.


See Also

ShowHeading

ShowRecNo


ShowHeading

See Also	Example	Properties	Forms

Determines if field name headings are displayed at the top of each column in a browse object.

Property of Class

BROWSE

Data Type

Logical

Default

The default for ShowHeading is true (.T.).

Description

Use ShowHeading to determine whether the top line in a browse object displays a record or a heading line.


ShowHeading Example

NEW operator syntax:

Br1 NEW BROWSE(this)

Br1.Fields = "Compcode,Contact"

Br1.Width = 38

Br1.Height = 17

Br1.Showheading = .F.

DEFINE object syntax:

DEFINE BROWSE Br1 OF THIS;

  PROPERTY;

    Fields "CompCode, Contact",;

    Width 38,;

    Height 17,;

    ShowHeading .F.


See Also

ShowDeleted

ShowRecNo


ShowRecNo

See Also	Example	Properties	Forms

Determines if the record number column in a browse object is displayed.

Property of Class

BROWSE

Data Type

Logical

Default

The default for ShowRecNo is true (.T.)

Description

Use ShowRecNo to display or hide record numbers at the left of each record in a browse object.

The ShowRecNo setting affects space allocation in the browse object display. For example, setting ShowRecNo to false (.F.) removes the record number column, leaving more room for displaying fields.


ShowRecNo Example

NEW operator syntax:

Br1=NEW BROWSE(this)

Br1.Fields="CompCode,Contact"

Br1.ShowRecNo=.F.

DEFINE object syntax:

DEFINE BROWSE Br1 OF THIS;

    PROPERTY Fields "CompCode, Contact",;

      ShowRecNo .F.


See Also

ShowDeleted

ShowHeading


Size

See Also	Example	Properties

Contains the number of elements in an array object.

Property of Class

ARRAY

Data Type

Numeric

Description

Use Size to find out how many elements an array object has.

Knowing the number of elements in an array lets you execute a FOR...NEXT loop to traverse the array and either read its elements or insert values into them. For more information on array traversal, see Dir( ).


Size Example

See Dir( ) for an example of using Size with array objects.


See Also

ALEN( )

Delete( )

Dimensions

Grow( )

Insert( )

Resize( )


Sizeable

See Also	Example	Properties	Forms

Determines if the user can resize a form.

Property of Class

FORM

Data Type

Logical

Default

The default for Sizeable is true (.T.).

Description

Set the Sizeable property to false to prevent the user from resizing a form.

When you set Sizeable to true, the form is bordered by a bold line, indicating that the user can change its size and dimensions with the mouse. When you set Sizeable to false (.F.), the form is bordered by a thin line. The pointer does not change when the user places it on the border, and the form cannot be resized.

Note:	When you set the MDI property of a form to true, the Sizeable setting is ignored and the user can always resize the form.


Sizeable Example

NEW operator syntax:

LOCAL F1

F1=NEW Trips()

F1.OPEN()

CLASS Trips OF FORM

  this.MDI = .F.

  this.Text = "Trip Schedule"

  this.Top = 2

  this.Left = 2

  this.Width = 38

  this.Height = 18

  this.Sizeable = .F.

ENDCLASS

DEFINE object syntax:

DEFINE FORM Trips ;

  PROPERTY Text "Trip Schedule",;

  Top 2, Left 2, Width 38, Height 18,;

  Sizeable .F., MDI .F.


See Also

Moveable

Maximize

Minimize


Sort( )

See Also	Example	Properties

Sorts the elements in a one-dimensional array object or sorts rows in a two-dimensional array object.

Property of Class

ARRAY

Description

Use the Sort( ) method to arrange array object elements in alphabetical, numerical, chronological, or logical order.

The Sort( ) method is similar to the ASORT( ) function.

The elements to sort in a one-dimensional array object must be of the same data type, and the elements of the column by which rows are to be sorted in a two-dimensional array object must be of the same data type.

Sort( ) accepts three parameters:

<starting element expN> is the number of an element at which to start sorting if the array object is one-dimensional, or the number (subscript) of the column on which to sort if the array object is two-dimensional. If you omit <starting element expN>, Sort( ) starts sorting at the first element or column in the array.

<elements to sort expN> is the number of elements to sort if the array object is one-dimensional, or the number of rows to sort if the array object is two-dimensional. If you omit <elements to sort expN>, Sort( ) sorts the rows starting at the row containing element <starting element expN> to the last row. If you specify a value for <elements to sort expN>, also need to specify a value for <starting element expN>.

<sort order expN2> is the sort order. 0 specifies ascending order (the default), and 1 specifies descending order.

For more information on sorting elements in an array object, see ASORT( ).


Sort( ) Example

USE Animals.DBF

* Initialize an array object

ObjArr=NEW ARRAY(RECCOUNT(),3)

* Fill array with values from Animals.DBF

COPY TO ARRAY ObjArr FIELDS Name, Area, Weight

* Use SORT() to order by the area values in

* column 2 of the array.

ObjArr.Sort(2)

* Display sorted array contents

FOR i=1 TO RECCOUNT()

  ? ObjArr[i,1], ObjArr[i,2], ObjArr[i,3]

NEXT i


See Also

ASORT( )

Dir( )

Fields( )

Scan( )


Sorted

See Also	Example	Properties	Forms

Determines whether the prompts in a list box or a combo box are listed in sorted order or in natural order.

Property of Class

COMBOBOX, LISTBOX

Data Type

Logical

Default

The default for Sorted is false (.F.).

Description

Set Sorted to true (.T.) when you want the prompts in a list box or a combo box to appear in sorted order (alphabetically, numerically, or chronologically). For example, a list of names is more accessible if it is sorted alphabetically.

The natural order of a list box or a combo box depends on the order in which the prompts are generated. For example, when you specify "FILE *.*" for the DataSource property of a list box, the prompts consist of the file names in the default directory. The prompts are created in the order in which the files are listed in the directory, so they are not necessarily arranged alphabetically when you set Sorted to false.


Sorted Example

NEW operator syntax:

LST1 = NEW LISTBOX(this)

LST1.DataSource = "Field Clients->Company"

LST1.Sorted = .T.

DEFINE object syntax:

DEFINE LISTBOX LST1 OF FORM THIS;

  PROPERTY DataSource "Field Clients->Company",;

  Sorted .T.


See Also

Multiple


SpeedBar

See Also	Example	Properties	Forms

Determines whether a pushbutton behaves like a SpeedBar button or a standard pushbutton.

Property of Class

PUSHBUTTON

Data Type

Logical

Default

The default for SpeedBar is false (.F.).

Description

Set SpeedBar to true (.T.) when you want a pushbutton to behave like a SpeedBar button. A SpeedBar button is not included in the tabbing order of a form; consequently, it cannot receive focus with Tab or Shift+Tab.

In Windows applications, SpeedBar buttons are quick alternatives to menu commands. They are typically used for common operations such as Cut, Copy, and Print.


Speedbar Example

NEW operator syntax:

Advance = NEW PUSHBUTTON(this)

Advance.Onclick = ChngRecno

Advance.Text = "Forward"

Advance.SpeedBar = .T.

DEFINE object syntax:

DEFINE PUSHBUTTON Advance OF THIS;

  PROPERTY  Onclick ChngRecno,;

  Text "Forward", SpeedBar .T.


See Also

DEFINE

OnClick


SpinOnly

See Also	Example	Properties	Forms

Determines if users can enter a value in the text box portion of a spin box.

Property of Class

SPINBOX

Data Type

Logical

Default

The default for SpinOnly is false (.F.).

Description

A spin box lets users enter values in a text box or select values with arrow buttons. When you set the SpinOnly property to false, the text box is enabled. When you set the SpinOnly property to true (.T.) the text box is disabled, restricting input to the predefined values offered by the arrow buttons.


SpinOnly Example

NEW operator syntax:

SP1 = NEW SPINBOX(this)

SP1.DataLink = "Country->GNP"

SP1.SpinOnly = .T.,;

SP1.Height = 2

DEFINE object syntax:

DEFINE SPINBOX SP1 OF THIS;

  PROPERTY;

    DataLink "Country->GNP",;

    SpinOnly .T., Height 2


See Also

CLASS SPINBOX


StatusMessage

See Also	Example	Properties	Forms

Specifies a message to display on the status bar while an object has focus.

Property of Class

BROWSE, CHECKBOX, COMBOBOX, EDITOR, ENTRYFIELD, FORM, LISTBOX, MENU, OLE, PUSHBUTTON, RADIOBUTTON, SCROLLBAR, SPINBOX

Data Type

Character

Default

The default for StatusMessage is an empty string.

Description

Use StatusMessage to provide instructions to the user when the user selects an object.


StatusMessage Example

NEW operator syntax:

Exit = NEW PUSHBUTTON(this)

Exit.Onclick = Compute

Exit.Text = "Exit"

Exit.StatusMessage = "Click on Exit to compile;

  results"

* Compute is a FUNCTION that performs

* an action and returns .T. or some value.

DEFINE object syntax:

DEFINE PUSHBUTTON Exit OF THIS;

  PROPERTY  Onclick Compute,;

  Text "Exit",;

  StatusMessage "Click on Exit to compile results"


See Also

Text

ValidErrorMsg


Step

See Also	Example	Properties	Forms

Determines how much a user can increment or decrement a value by clicking an arrow in a spin box.

Property of Class

SPINBOX

Data Type

Numeric

Default

The default for Step is 1.

Description

Use Step to control the rate at which a user can increase or decrease a numeric or date value. For example, a program that expresses large dollar values only in increments of $500.00 might give a spin box a Step value of 500.


Step Example

NEW operator syntax:

Spin1 = NEW SPINBOX(this)

Spin1.Datalink = "Country->GNP"

Spin1.Top = 2

Spin1.Left = 4

Spin1.Height = 2

Spin1.Step = 10

DEFINE object syntax:

DEFINE SPINBOX Spin1 OF THIS;

  PROPERTY Datalink "Country->GNP",;

  Top 2, Left 4, Height 2, Step 10


See Also

RangeMax

RangeMin


Style

See Also	Example	Properties	Forms

Specifies which parts of a combo box are usable and which parts are displayed automatically.

Property of Class

COMBOBOX

Data Type

Numeric

Default

The default for Style is 0 (Simple).

Description

Use Style to determine how the user selects values in a combo box.

The user selects a value from a combo box by entering initial characters in a text box or by selecting the value directly from the prompt list. The setting you give to Style determines whether the text box is usable and whether the prompt list is displayed automatically.

You can give Style one of three values:

Style value	Description
0 (Simple)	The dropdown list is displayed automatically.
1 (DropDown)	The user has to click the arrow to display the dropdown list.
2 (DropDownList)	The user has to click the arrow to display the dropdown list, and the text box does not accept input.


Style Example

NEW operator syntax:

DEFINE COMBOBOX Cb1 OF THIS

  this.Cb1.Style=1

  this.Cb1.Datasource="FIELD Animals->Name"

  this.Cb1.Top=4

  this.Cb1.Left=6

  this.Width=20

  this.Height=12

DEFINE object syntax:

DEFINE COMBOBOX Cb1 OF THIS FROM 4,6 TO 26,16;

    PROPERTY;

      DataSource "FIELD Animals->Name",;

      Style 1


See Also

Enabled


Subscript( )

See Also	Example	Properties

Returns the row number or the column number of a specified element in an array object.

Property of Class

ARRAY

Description

Use the Subscript( ) method when you know the number of an element in a two-dimensional array object and want to reference the element by using its subscripts. The Subscript( ) method is similar to the ASUBSCRIPT( ) function.

Subscript( ) accepts two parameters:

<element expN> is the element number.

<row/column expN> is a number, either 1 or 2, that determines whether you want to return the row or column subscript of an array object. If <row/column expN> is 1, Subscript( ) returns the number of the row subscript. If <row/column expN> is 2, Subscript( ) returns the number of the column subscript.

To determine both the row and column number of an element in a two-dimensional array object, issue Subscript( ) twice, once with a value of 1 for <row/column expN> and once with a value of 2 for <row/column expN>. For example, if the element number is 13, the following returns its subscripts:

Subscript(Form.aArray,13,1) && Returns row subscript
Subscript(Form.aArray,13,2) && Returns col subscript

In one-dimensional array objects, the number of an element is the same as its subscript, so there is no need to use Subscript( ). That is, Subscript(3) returns 3, Subscript(5) returns 5, and so on.

Subscript( ) is the inverse of Element( ), which returns the element number when you specify the subscripts of the element.


Subscript( ) Example

See Scan( ) for an example of using Subscript( ) with array objects.


See Also

ASUBSCRIPT( )

Element( )


SysMenu

See Also	Example	Properties	Forms

Determines if a form has a Control menu.

Property of Class

FORM

Data Type

Logical

Default

The default for SysMenu is true (.T.).

Description

Set SysMenu to true to create a Control menu for a form. A standard Windows feature, the Control menu is accessible from the Control-menu box, a button at the upper left corner of a form.

The Control menu provides the following options:

Restore, which restores the form to its original size after the user maximizes it.

Move, which lets the user move the form with the arrow keys.

Size, which lets the user resize the form with the arrow keys.

Minimize, which reduces the form to an icon.

Maximize, which enlarges the form.

Close, which closes the form.

When you open a form with the ReadModal( ) property or the READMODAL( ) function, the Control menu contains only the Move and Close options.

It is customary to set SysMenu to false when you create a dialog box in a Windows application.

Note:	When the MDI property of a form is true, the SysMenu setting is ignored and the form always has the Control menu.


SysMenu Example

NEW operator syntax:

F1=NEW EntryForm()

CLASS EntryForm OF FORM

  this.MDI = .F.

  this.Text = "Entry"

  this.Top = 2

  this.Left = 2

  this.Width = 38

  this.Height = 18

  this.SysMenu = .F.

ENDCLASS

DEFINE object syntax:

DEFINE FORM EntryForm ;

  Property SysMenu .F., MDI .F.,;

  Top 2, Left 2, Width 38, Height 18


See Also

Moveable

Sizeable


TabStop

See Also	Example	Properties	Forms

Determines if the user can select an object by pressing Tab or Shift+Tab.

Property of Class

BROWSE, CHECKBOX, COMBOBOX, EDITOR, ENTRYFIELD, LISTBOX, OLE, PUSHBUTTON, RADIOBUTTON, SCROLLBAR, SPINBOX

Data Type

Logical

Default

The default for TabStop is true (.T.).

Description

Set the TabStop property to false (.F.) when you want to remove an object from the tabbing order of the parent form. For example, a form might contain a pushbutton that executes a rarely used utility routine. Setting the TabStop property of the pushbutton to false prevents the pushbutton from being selected with Tab or Shift+Tab.


TabStop Example

NEW operator syntax:

Comp = NEW ENTRYFIELD(this)

Comp.Datalink = "Clients->Company"

Comp.TabStop = .F.

DEFINE object syntax:

DEFINE ENTRYFIELD Comp OF THIS;

  PROPERTY Datalink "Clients->Company",;

  TabStop .F.


See Also

Before

_curobj

Group


Terminate( )

See Also	Example	Properties

Terminates a conversation with a DDE server application.

Property of Class

DDELINK

Description

Use Terminate( ) to close a DDE link between dBASE and a server application.

Terminate( ) stops communication between dBASE and the server application, but does not close the server application itself.

When you terminate a DDE link with Terminate( ), you can restore it with Reconnect. When you terminate the link with the Release( ) method, the link cannot be restored and you need to create the DDELink object again.


Terminate( ) Example

PUBLIC LinkObj

LinkObj = NEW DDELINK()

LinkObj.Initiate("QPW","Demo.WB1")

* Subsequent program operations completed; link

* do longer required

LinkObj.Terminate()


See Also

Advise( )

Execute( )

Initiate( )

OnNewValue

Peek( )

Poke( )

Reconnect( )

Server

Timeout

Topic

Unadvise( )


Text

See Also	Example	Properties	Forms

Specifies a character string to display in or next to an object.

Property of Class

BROWSE, CHECKBOX, FORM, MENU, PUSHBUTTON, RADIOBUTTON, RECTANGLE, TEXT

Data Type

Character

Default

The default for Text is a character string dBASE assigns to the object when you create it. For example, dBASE automatically assigns "BUTTON1" to the Text property of the first pushbutton you create.

Description

Use Text to label objects or display command labels in menu items. For example, if a pushbutton closes a form, you might set the Text property to "Close" or "Cancel". To display a character string on a form, create a text object and set its Text property to the desired string.

Use a pick character to let the user give focus to an object or select a menu item. To designate a character as a pick character, precede it with an ampersand (&). For example, the following command designates C as a pick character:

MyForm.MyMenu.FirstItem.Text = "&Close"

The pick character is underlined when the object is displayed.


Text Example

NEW operator syntax:

Exit = NEW PUSHBUTTON(this)

Exit.Text = "E&xit"

Exit.Width = 15

Exit.Onclick = {;Form.Close()}

DEFINE object syntax:

DEFINE PUSHBUTTON Exit OF THIS AT 11,13 ;

  PROPERTY Text "E&xit", Width 15,;

  OnClick {;Form.Close()}


See Also

StatusMessage


TimeOut

See Also	Example	Properties

Specifies the amount of time in seconds that dBASE waits on a transaction before returning an error.

Property of Class

DDELINK

Data Type

Numeric

Default

The default for TimeOut is 10.00.

Description

Use TimeOut to set a limit on the length of time dBASE waits for a DDE transaction to complete successfully.

Errors sometimes occur when dBASE tries to exchange data with a server application or send instructions to it. Each time an attempt is made, dBASE waits for the amount of time you specify (in seconds) with TimeOut. When the transaction fails to complete in the allotted time, dBASE generates an error message.

When using DDE over a network, you may need to set TimeOut to a larger value.


TimeOut Example

PUBLIC LinkObj

LinkObj = NEW DDELINK()

LinkObj.Timeout = 30

LinkObj.Initiate("QPW","Demo.WB1")


See Also

Advise( )

Execute( )

Initiate( )

OnNewValue

Peek( )

Poke( )

Server

Terminate( )

Topic

Unadvise( )


Toggle

See Also	Example	Properties	Forms

Determines if the user can switch between two display modes in a browse object.

Property of Class

BROWSE

Data Type

Logical

Default

The default for Toggle is True (.T.).

Description

Set Toggle to false (.F.) to restrict users to one display mode in a browse object.

A browse object can display multiple records (Browse mode) or one record at a time (Edit mode). By pressing F2, the user can toggle between these modes. The default mode is Browse when you set the Mode property to 0; the default mode is Edit when you set Mode to 1 or 2. When you set Toggle to false, the user is restricted to the default mode.


Toggle Example

NEW operator syntax:

CompanyBrowse = New BROWSE(this)

  CompanyBrowse.Top = 3

  CompanyBrowse.Left = 1

  CompanyBrowse.Width = 60

  CompanyBrowse.Alias = "Company"

  CompanyBrowse.Toggle = .F.

DEFINE object syntax:

DEFINE BROWSE CompanyBrowse OF THIS;

   FROM 3,1 TO 13,40;

     Property;

      Alias "Company",;

      Toggle .F.


See Also

BROWSE

Append

Delete


Top

See Also	Example	Properties	Forms

Specifies a position for the top border of an object relative to its parent form or (if the object has no parent form) to the Windows desktop.

Property of Class

BROWSE, CHECKBOX, COMBOBOX, EDITOR, ENTRYFIELD, FORM, IMAGE, LINE, LISTBOX, OLE, PUSHBUTTON, RADIOBUTTON, RECTANGLE, SCROLLBAR, SPINBOX

Data Type

Numeric

Description

Use the Top property in combination with the Left property to position an object in a form or on the Windows desktop. (The Left property specifies the position of the left border.) Top and Left accept integer or noninteger values.

If you used the FROM or AT clause of the DEFINE command and specified a value for the Top property, dBASE positions the object with the Top property.

Each unit of the value you assign to Top is the average height of characters in the active font of the parent form. For example, if you increase the Top property of an entry field by 5.5, the entry field is 5.5 character heights above its previous position.


Top Example

NEW operator syntax:

Exit=NEW PUSHBUTTON(this)

Exit.Top = 5

Exit.Left = 2

Exit.Width = 17

Exit.Text = "Exit Program"

Exit.OnClick = {;Form.Close()}

DEFINE object syntax:

DEFINE PUSHBUTTON Exit OF Entry;

  PROPERTY Top 5, Left 2, Width 17,;

  Text "Exit Program", OnClick {;Form.Close()}


See Also

Bottom

Height

Left

Right

ScaleFontName

ScaleFontSize

Width


Topic

See Also	Example	Properties

Holds the name of the server document accessed by a DDELink object or the topic of a DDETopic object.

Property of Class

DDELINK, DDETOPIC

Data Type

Character

Default

The default for Topic is an empty string.

Description

Use Topic to

Find the server document name that was passed to the Initiate( ) method of a DDELink object

Identify the topic of a DDETopic object

Using Topic with DDELink objects

The Initiate( ) method of a DDELink object opens a channel of communication (known as a DDE link) between dBASE and an external Windows application (known as a server) and opens one of the data files used by that application (known as a server document).

Initiate( ) requires two parameters:

<server> is the main executable file of the server application

<topic> is the file name of the server document

The Topic property holds the name you pass through <topic>.

Using Topic with DDETopic objects

The topic property of a DDETopic object distinguishes the object from other DDETopic objects. For example, a dBASE server application might create two DDETopic objects, one with a topic of NASDAQ and the other with a topic of AMEX:

xServer1 = NEW DDETOPIC("NASDAQ")

xServer2 = NEW DDETOPIC("AMEX")


Topic Example

PUBLIC LinkObj

LinkObj = NEW DDELINK()

LinkObj.Initiate("QPW","Demo.WB1")

* Subsequent program operations

IF LinkObj.Server="QPW" .AND. ;

   LinkObj.Topic = "Demo.WB1"

      mValue1=LinkObj.Peek("A:A1")

ENDIF


See Also

Advise( )

Execute( )

Initiate( )

OnNewValue

Peek( )

Poke( )

Server

Terminate( )

Timeout

Unadvise( )


Unadvise( )

See Also	Example	Properties

Asks the server to stop notifying the client when an item in the server document changes.

Property of Class

DDELINK

Description

Use the Unadvise( ) method to terminate a hot link to an item in a server document. A hot link, which you create with the Advise( ) method, tells the server to notify dBASE when the item changes.

A server document is a file you open in an external application. For example, a data-exchange program might start a session in Quattro Pro for Windows, open one of its spreadsheet files, and establish a hot link to one of its cells. When the hot link is no longer necessary, remove it with Unadvise( ).

Unadvise( ) requires the <item> parameter, which identifies the item in the server document. This item can be any single element, such as a field in a table or a cell in a spreadsheet. For example, you can remove a hot link from cell C2 of Page A in a Quattro Pro spreadsheet file by passing the parameter "A:C2".


Unadvise( ) Example

PUBLIC LinkObj

LinkObj = NEW DDELINK()

LinkObj.OnNewValue = Valuehandler;

               && Codeblock or function pointer

LinkObj.Initiate("QPW","Demo.WB1")

LinkObj.Advise("A:A1");

               && Notified when cell A:A1 changes

* Subsequent program operations completed

LinkObj.UnAdvise("A:A1")


See Also

Advise( )

Execute( )

Initiate( )

OnNewValue

Peek( )

Poke( )

Server

Terminate( )

Timeout

Topic


UpBitmap

See Also	Example	Properties	Forms

Specifies the graphic image to display in a pushbutton when it is not selected.

Property of Class

PUSHBUTTON

Data Type

Character

Default

The default for UpBitmap is an empty string.

Description

Use UpBitmap to give visual confirmation that a pushbutton is enabled and the user is not clicking it.

The UpBitmap setting can take one of three forms:

RESOURCE <resource id> <dll name> specifies a bitmap resource and the DLL file that holds it. (A DLL file is a precompiled library of external routines and resources written in non-dBASE languages such as C and Pascal.) You can obtain the resoure ID with a resource editor such as Resource Workshop.

FILENAME <filename> specifies a bitmap file (which usually has the file-name extension .BMP).

BINARY <binary field> specifies a binary field containing bitmap images. If you use this option, the parent form must be based on a table or a query containing the field. You specify this table or query with the View property of the form. The image displayed always comes from the current record, so moving from record to record changes the image.

When you specify a character string for the pushbutton with Text and an image with UpBitmap, the image is displayed with the character string.

Note

You can select a bitmap file with the Choose Bitmap dialog box. To access the Choose Bitmap dialog box, click the Tool button next to the UpBitmap item in the Object Inspector.


UpBitmap Example

NEW operator syntax:

Advance = NEW PUSHBUTTON(this)

Advance.Onclick = ShowInfo

Advance.Text = "Database"

Advance.UpBitmap = "Resource #1904 Bwcc.dll"

Advance.DownBitmap = "Resource Empty Resource.dll"

Advance.StatusMessage = "Click on 'Database' for;

  country info"

DEFINE object syntax:

DEFINE PUSHBUTTON Advance OF THIS;

  PROPERTY  Onclick ShowInfo,;

  Text "Database",;

  UpBitmap "Resource #1904 Bwcc.dll",;

  DownBitmap "Resource Empty Resource.dll",;

  StatusMessage "Click on 'Database' for ;

    country info"


See Also

DEFINE

DisabledBitmap

DownBitmap

Enabled

FocusBitmap


Valid

See Also	Example	Properties	Forms

Specifies a condition that must evaluate to true (.T.) before the user can remove focus from an object.

Property of Class

ENTRYFIELD, SPINBOX

Data Type

Function pointer or codeblock

Description

Use Valid to validate data. For example, an application might use the Valid property of an entry field to detect and prevent invalid account numbers; when a user enters an incorrect value, focus cannot be given to another object until the user corrects the entry.

Like other event properties, the Valid property accepts

Functions

Procedures

Codeblocks

For information on these subroutines, see Chapter 4 in the Programmer's Guide. For information on writing event-handling routines, see Chapter 14 in the Programmer's Guide.

The subroutine you specify for Valid must return a logical value (true or false).

The Valid property resembles the RangeMax and RangeMin properties. However, RangeMax and RangeMin set only upper and lower limits, while Valid can apply other conditions. For example, an upper or lower limit cannot exclude nonconsecutive values such as 2, 7, and 9, so a Valid subroutine is required.

Note:	You can write a subroutine with the Procedure Editor, a window in which you enter dBASE program code. To access the Procedure Editor, click on the Tool button next to the Valid item in the Object Inspector.


Valid Example

NEW operator syntax:

Date = NEW ENTRYFIELD(this)

Date.Datalink = "Clients->Baldate"

Date.Valid = Valchk

DEFINE object systax:

DEFINE ENTRYFIELD Date OF THIS;

  PROPERTY Datalink "Clients->Baldate",;

  Valid Valchk


See Also

RangeMax

RangeMin

RangeRequired

ValidErrorMsg

ValidRequired

When


ValidErrorMsg

See Also	Example	Properties	Forms

Specifies a character string to display on the status bar when the Valid property of an entry field returns false (.F.).

Property of Class

ENTRYFIELD, SPINBOX

Data Type

Character

Default

The default for ValidErrorMsg is "Invalid input".

Description

Use the ValidErrorMsg property to display instructions or a warning when the user enters an incorrect value.

For example, an application might use the Valid property to detect and prevent invalid account numbers. When a user enters an invalid number, the Valid property returns false (.F.) and the message in ValidErrorMsg is displayed in the status bar.


ValidErrorMsg Example

NEW operator syntax:

Date = NEW ENTRYFIELD(this)

Date.Datalink = "Clients->Baldate"

Date.Valid = Valchk

Date.ValidErrorMsg = "Invalid date"

* Valchk is a FUNCTION that performs an

* action and returns .T. or some value.

DEFINE object syntax:

DEFINE ENTRYFIELD Date OF THIS;

  PROPERTY Datalink "Clients->Baldate",;

  Valid Valchk,;

  ValidErrorMsg "Invalid date"


See Also

StatusMessage

Valid

ValidRequired


ValidRequired

See Also	Example	Properties	Forms

Determines if the Valid event property applies to all data or to new data only.

Property of Class

ENTRYFIELD, SPINBOX

Data Type

Logical

Default

The default for ValidRequired is false (.F.).

Description

Set ValidRequired to true to validate existing data as well as new data. For ValidRequired to take effect, you need to set a validation condition with the Valid event property.

You typically set ValidRequired to true (.T.) when you change a validation condition and need to verify and update existing data. For example, a business might add a digit to its account numbers and change the Valid property of an entry field to require the new digit. If the ValidRequired property is set to true, dBASE also detects any existing account numbers that lack the digit and forces the user to make appropriate changes.

The Valid property resembles the RangeMax and RangeMin properties. However, RangeMax and RangeMin set only upper and lower limits, while Valid can apply other conditions. For example, an upper or lower limit cannot exclude nonconsecutive values such as 2, 7, and 9, so a Valid subroutine is required.


ValidRequired Example

NEW operator syntax:

Date = NEW ENTRYFIELD(this)

Date.Datalink = "Clients->Baldate"

Date.Valid = Valchk

Date.ValidRequired = .T.

Date.ValidErrorMsg = "Invalid date"

* Valchk is a FUNCTION that performs an

* action and returns .T. or some value

DEFINE object syntax:

DEFINE ENTRYFIELD Date OF THIS;

  PROPERTY Datalink "Clients->Baldate",;

  Valid Valchk, ValidRequired .T.,;

  ValidErrorMsg "Invalid date"


See Also

RangeMax

RangeMin

RangeRequired

Valid

ValidErrorMsg


Value

See Also	Example	Properties	Forms

The value contained in an object.

Property of Class

CHECKBOX, COMBOBOX, EDITOR, ENTRYFIELD, LISTBOX, RADIOBUTTON, SCROLLBAR, SPINBOX

Data Type

Numeric, float, character, or date

Default

The default for Value varies for eachobject. For example, the default for an entry field is the value stored in the table field (that the entry field is linked to) for the first record. For a check box, the default is .T. (a check box is checked by default)..

Description

Use Value to initialize data in an object or query a user's input. For example, you can use the Value property of a spin box to set the default value that appears in the text box. You can also query the Value property of an entry field to obtain the value entered by the user.


Value Example

NEW operator syntax:

BDate = NEW ENTRYFIELD(this)

BDate.Datalink = "Clients->Baldate"

BDate.Value = DATE()

DEFINE object syntax:

DEFINE ENTRYFIELD BDate OF THIS;

  PROPERTY Datalink "Clients->Baldate",;

  Value DATE()


See Also

DataLink

DataSource

LISTSELECTED( )

Selected( )

STORE


Vertical

See Also	Example	Properties	Forms

Determines whether a scroll bar is vertical or horizontal.

Property of Class

SCROLLBAR

Data Type

Logical

Default

The default for Vertical is true (.T.).

Description

Use Vertical to make a scroll bar fit with other objects on a form or to enhance the design of the form. For example, a form might not have space for a horizontal scroll bar, or a vertical scrollbar might look awkward next to a spin box.


Vertical Example

NEW operator syntax:

IncNum = NEW SCROLLBAR(this)

IncNum.Top = 7

IncNum.Left = 3

IncNum.Datalink = "Num"

IncNum.Vertical = .F.

DEFINE object syntax:

DEFINE SCROLLBAR IncNum OF THIS;

  PROPERTY DataLink "Num", Vertical .F.,;

  Top 7, Left 3


See Also

DataLink

Height

Left

Top

Width


View

See Also	Example	Properties	Forms

Specifies the name of a query or a table on which a form is based.

Property of Class

FORM

Data Type

Character

Default

The default for View is an empty string.

Description

Use View to determine which tables are automatically opened whenever the form is opened. You can assign multiple tables with a query (.QBE, .VUE), or you can assign a single table (.DBF). Although you are not required to set the View property, you should if the form accesses table data. Otherwise, every time you open the form, you need to open the table or query first.

Once you associate the form with a table or tables, you need to link objects such as entry fields and check boxes with specific fields in the table.

Note:	You can specify a value for the View property with the Choose View dialog box, which lets you choose a query or a table. To access the Choose View dialog box, click on the Tool button next to the View item in the Object Inspector.


View Example

NEW operator syntax:

LOCAL

F1=NEW EntryForm()

CLASS EntryForm OF FORM

this.Text = "Entry Form"

this.Top = 2

this.Left = 2

this.Width = 38

this.Height = 18

this.View = "Company94.QBE"

* Company94.QBE is a Query file name on which

* the Form Entry is based.

ENDCLASS

DEFINE object syntax:

DEFINE FORM EntryForm;

  Property Text "Entry Form",;

  View "Company94.QBE",;

  Top 2, Left 2, Width 38, Height 18


See Also

Alias

DataLink

DataSource


Visible

See Also	Example	Properties	Forms

Determines whether an object is visible or hidden.

Property of Class

BROWSE, CHECKBOX, COMBOBOX, EDITOR, ENTRYFIELD, FORM, IMAGE, LINE, LISTBOX, OLE, PUSHBUTTON, RADIOBUTTON, RECTANGLE, SCROLLBAR, SPINBOX, TEXT

Data Type

Logical

Default

The default for Visible is true (.T.).

Description

Use Visible when you want to display an object only if a specified condition is met or a specified action is taken. For example, you can specify conditions with event properties (such as OnClick and Valid) that set Visible to true when the user clicks an object or enters certain values.


Visible Example

NEW operator syntax:

Spin1 = NEW SPINBOX(this)

Spin1.Datalink = "Value1"

Spin1.Top = 2

Spin1.Left = 4

Spin1.Height = 2

Spin1.Visible = .F.

DEFINE object syntax:

DEFINE SPINBOX Spin1 OF THIS;

  PROPERTY Datalink "Value1",;

  Top 2, Left 4, Height 2, Visible .F.


See Also

Enabled


When

See Also	Example	Properties	Forms

Specifies a condition that must evaluate to true (.T.) before the user can give focus to an object.

Property of Class

BROWSE, CHECKBOX, COMBOBOX, EDITOR, ENTRYFIELD, LISTBOX, PUSHBUTTON, RADIOBUTTON, SCROLLBAR, SPINBOX

Data Type

Function pointer or codeblock

Description

Use When to determine when an object is available to users. For example, an application that manages sensitive customer accounts might prevent a browse object from receiving focus until the user enters the proper password into an entry field.

Like other event properties, the When property accepts

Functions

Procedures

Codeblocks

For information on these subroutines, see Chapter 4 in the Programmer's Guide. For information on writing event-handling code, see Chapter 14 in the Programmer's Guide.

The subroutine you specify for When must return a logical value (true or false).

Note:	You can write a subroutine with the Procedure Editor, a window in which you enter dBASE program code. To access the Procedure Editor, click on the Tool button next to the When item in the Object Inspector.


When Example

NEW operator syntax:

USE Company

* Form declaration

  NextRec = NEW PUSHBUTTON(this)

  NextRec.Text = "Next"

  NextRec.When = {;.NOT. EOF()}

  NextRec.OnClick = {;SKIP}

DEFINE object syntax:

DEFINE PUSHBUTTON NextRec OF THIS;

  PROPERTY;

    Text "Next",;

    When {;.NOT. EOF()},;

    OnClick {;SKIP}


See Also

Valid


Width

See Also	Example	Properties	Forms

Specifies the width of an object.

Property of Class

BROWSE, CHECKBOX, COMBOBOX, EDITOR, ENTRYFIELD, FORM, IMAGE, LINE, LISTBOX, OLE, PUSHBUTTON, RADIOBUTTON, RECTANGLE, SCROLLBAR, SPINBOX, TEXT

Data Type

Numeric

Description

Use the Width property in combination with the Height property to adjust the size of an object.

Width determines the distance from the left border to its right border. You can assign an integer or noninteger value to Width.

Each unit of the value you assign to Width is the average width of characters in the active font of the parent form. For example, if you set the Width property of an entry field to 15.5, the entry field is as wide as 15.5 characters.


Width Example

NEW operator syntax:

Action1 = NEW PUSHBUTTON(this)

Action1.Text = "Search for Open Accounts"

Action1.Onclick = Search

Action1.Width = 22

Action1.Top = 11

Action1.Left = 13

DEFINE object syntax:

DEFINE PUSHBUTTON Action1 OF THIS ;

  PROPERTY Text "Search for Open Accounts",;

  Top 11, Left 13, Width 22

  OnClick Search


See Also

Left

Height

ScaleFontName

ScaleFontSize

Top


WindowState

See Also	Example	Properties	Forms

Determines if a form is minimized, maximized, or displayed in its original size.

Property of Class

FORM

Data Type

Numeric

Default

The default for WindowState is 0 (Normal).

Description

Use WindowState to maximize, minimize, or restore a form.

The WindowState property accepts the following values:

Setting	Effect on window

0 (Normal)	Returns the form to its original size

1 (Minimized)	Reduces the form to an icon

2 (Maximized)	Enlarges the form to cover the work area of the desktop

When you set the WindowState property to 0, the form is said to be restored.


WindowState Example

NEW operator syntax:

LOCAL f

f=NEW Trips()

f.OPEN()

CLASS Trips OF FORM

  this.Text = "Trip Schedule"

  this.Top = 2

  this.Left = 2

  this.Width = 38

  this.Height = 18

  this.WindowState = 2

ENDCLASS

DEFINE object syntax:

DEFINE FORM Trips FROM 2,2 TO 20,40;

  PROPERTY Text "Trip Schedule",;

  Top 2, Left 2, Width 38, Height 18.;

  WindowState 2

OPEN FORM TRIPS


See Also

Moveable

Sizeable


Wrap

See Also	Example	Properties	Forms

Determines if an editor object wraps input text automatically.

Property of Class

EDITOR

Data Type

Logical

Default

The default for Wrap is false (.F.).

Description

Set Wrap to true (.T.) if you want dBASE to execute a carriage return automatically when a text string exceeds the width of an editor object. Set Wrap to false when you want the user to control the width of each line of text.


Wrap Example

NEW operator syntax:

Ed1=NEW EDITOR(this)

  Ed1.Wrap = .T.

  Ed1.Top = 4

  Ed1.Left = 37

  Ed1.Height = 12

  Ed1, Width = 32

  Ed1.DataSource = "MEMO Contact->Notes"

DEFINE object syntax:

DEFINE EDITOR Ed1 OF THIS;

  PROPERTY Top 4, Left 37, Height 12, Width 32,;

    Wrap .T.,;

    DataSource "MEMO Contact->Notes"


See Also

Width

Height