LANGUAGE REFERENCE 2-119

DO

Usage

dBASE IV supports the concept of procedures within any program file by maintaining a procedure list in every object file. If a source file starts with a command other than PROCEDURE or FUNCTION, the code is com-piled as a procedure and added to the procedure list in the object file with the same name as the source file. A typical file such as:

is compiled into a file containing one Main. When you enter DO MAIN, this name is used to locate the file, and then used to locate the procedure within the file.

A source file can include more than one procedure, such as:

PROCEDURE Subb

Note that only commands found at the beginning of a file are given the default procedure name. Commands between RETURN and PROCEDURE cause a compile-time warning. You may want to keep this code in the pro-gram file, but DO will not execute these commands.

Any procedure found in an active file is available to the DO command.

If A.dbo calls B.dbo calls C.dbo, all the procedures defined within A, B, and C are available to any procedure in C. dBASE IV still supports SET PROCEDURE TO from dBASE III and dBASE III PLUS, although this com-mand is only required to gain access to procedures in a file not activated by DO filename

You may have a maximum of 32 active files. A file is active if you open it with SET PROCEDURE TO, or if a RETURN can pass control back to it.

The total number of open files, including database files, index files, format files, and command files, is determined by the FILES setting in the Config.sys file. In a DOS environment five files are reserved; therefore, you can have up to 94 files open if you set FILES 99, which is the maximum setting in Config.sys.

2-120 COMMANDS

DO

When the program called by DO is complete, control returns to the calling program (or to the dot prompt or Control Center if the DO command was issued from either of those

Memory variables and arrays created in the called program must be declared PUBLIC if they are to be used after the called program terminates. All PRIVATE memory variables and arrays created within the program are released once the program terminates.

Because DO first searches for files, you should not change the file extension once a program has been compiled. All programs should have unique names, because once compiled they can no longer be distinguished by their file extensions.

If SET DEVELOPMENT is ON, DO compares the time and date stamp of a source file with the time and date stamp of its associated file. If the file is older than the source file, DO recompiles the source file before execut-ing it.

The dBASE IV program editor, which can be accessed from MODIFY COMMAND or the Control Center, will delete an old file when a file is modified, and then recompile the new file (generating a new file) when you save it. As other text editors will not delete the old file and recompile a new one, SET DEVELOPMENT allows you to verify that DO does not execute an outdated file.

Options

The WITH option allows parameters to be passed to a procedure. The param-eter list can contain any valid dBASE expression, and you may pass up to 64 parameters. Field names take precedence over memory variables; so, to specify a memory variable as a parameter rather than a field with the same name, precede the memory variable name with

Tips

Avoid DOing a command file recursively. A command file may contain a DO command that executes itself over again, or the command file may DO a sub-routine, and that subroutine may DO the original command file. Both are recursive calls, and both cases will open two files for the same c o m m a n d file. The error messages Too many files are open or DOs nested too deep may eventually result. dBASE IV allows a default of up to 20 DOs, but you can set this from 1 to 256 by changing the value of DO in the CONFIG.DB file.

I

LANGUAGE REFERENCE

DO

A procedure should return control to the calling program with a RETURN command, not with a DO command. If a command needs to execute its own commands again, the commands should be contained in a DO WHILE loop. The c o m m a n d file should not DO itself again.

Using the DO command with a procedure file of any type extension produces a file. However, you should use the appropriate command for each type of file, such as REPORT FORM, to produce the correct file.

Special Case

If the input file has a extension, DO generates a file and executes the update query. You may rename this extension to if you want to keep your update query files separate from your program files.

Examples

The following program file, Areacalc.prg, calculates the area of a rectangle based on the formula area length width:

Program PARAMETERS

area l e n g t h M RETURN

EOP:

To execute the program file Areacalc, pass the values 4 and 6 to the memory variables and respectively, and return the correct value to the memory variable called M_result:

0

00 Areacalc 4, Compiling l i n e 5

See Also

CANCEL, COMPILE, CREATE/MODIFY QUERY/VIEW, DEBUG, FUNCTION, MODIFY COMMAND, PARAMETERS, PRIVATE, PROCEDURE, PUBLIC, RESUME, RETURN, SET DEBUG, SET DEVELOPMENT, SET ECHO, SET PROCEDURE, SET TRAP, SUSPEND

2-122 COMMANDS

DO CASE

DO CASE is a structured programming command that selects only one course of action from a set of alternatives.

Syntax

ENDCASE terminates the DO CASE structure. Command pairs such as DO and DO must be properly nested within DO CASE. Nested DO CASEs are permitted.

CASE condition sets up a condition, or logical expression such as A B or Numvar for evaluation. When the condition evaluates to a logical true all subsequent commands are carried out until any one of the following commands is reached: another CASE, OTHERWISE, or ENDCASE.

After one true CASE is found and its associated commands processed, no fur-ther CASE statements are evaluated, and dBASE IV skips immediately to the first command after ENDCASE. If no CASE statements evaluate logical true, and there is no OTHERWISE statement, the program processes the first com-mand following ENDCASE. OTHERWISE causes the program to take an alternative path of action when all previous CASE statements evaluate to log-ical false

Tips

Only one of the possible cases is acted upon, even if several apply. In situa-tions where only the first true instance is to be processed, the DO CASE command is preferable to the IF command.

The CASE construct is often used when there is a small number of excep-tions to a condition. The CASE condition statements can represent the exceptions, and the OTHERWISE statement the more common situation.

REFERENCE

I

DO CASE

Example

Compare this example with the example given for the IF command. The following CASE construct determines the magnitude of a variable and dis-plays an appropriate message:

CASE 100

is over

CASE 10

is over CASE M v a l u e 1

i s over OTHERWISE

v a l u e is 1 or

See Also

DO, DO WHILE, IF, IIF()

COMMANDS

DO WHILE

DO WHILE is a structured programming command that allows c o m m a n d statements between it and its associated ENDDO to be repeated as long as the specified condition is true.

Syntax

DO WHILE condition opens a structured procedure that processes sub-sequent commands only while the condition evaluates to true for

exam-ple, 11.

If the condition evaluates to all subsequent commands are carried out until an ENDDO, LOOP, or EXIT is encountered. ENDDO and LOOP return control to the DO WHILE command for another evaluation of the condition.

EXIT passes control to the statement following the ENDDO.

LOOP returns control to the beginning of a DO program structure. LOOP prevents the execution of the remaining commands in the DO WHILE construct.

EXIT transfers control from within a DO loop to the com-mand immediately following the ENDDO.

ENDDO must terminate a DO WHILE structure. The space following the ENDDO on the command line may be used for comments; the c o m m e n t indicator, is not needed. Comments or symbols used here will appear among compile-time warnings.

Any structured commands within a DO structure must be properly nested. Nested DO WHILEs are permitted.

If the condition evaluates to a logical false dBASE IV skips all com-mands between DO WHILE and ENDDO and goes to the command following ENDDO.

Also note that the SCAN command, introduced with dBASE IV, offers a sim-ple syntax for processing a series of records. SCAN has the same capabilities as DO WHILE.

I