CLEARFILE statement

Syntax

CLEARFILE [file.variable] [ON ERROR statements] [LOCKED 
statements]

Description

Use the CLEARFILE statement to delete all records in an open dictionary or data file. You cannot use this statement to delete the file itself. Each file to be cleared must be specified in a separate CLEARFILE statement.

file.variable specifies an open file. If file.variable is not specified, the default file is assumed (for more information on default files, see the OPEN statement).

The CLEARFILE statement fails and the program terminates with a run-time error message if:

  • The file is neither accessible nor open.
  • file.variable evaluates to the null value.
  • A distributed file contains a part file that cannot be accessed, but the CLEARFILE statement clears those part files still available.
  • A transaction is active. That is, you cannot execute this statement between a BEGIN TRANSACTION (or TRANSACTION START) statement and the COMMIT (or TRANSACTION START) or ROLLBACK statement that ends the transaction.

The ON ERROR Clause

The ON ERROR clause is optional in the CLEARFILE statement. The ON ERROR clause lets you specify an alternative for program termination when a fatal error is encountered during processing of the CLEARFILE statement.

If a fatal error occurs, and the ON ERROR clause was not specified, or was ignored (as in the case of an active transaction), the following occurs:

  • An error message appears.
  • Any uncommitted transactions begun within the current execution environment roll back.
  • The current program terminates.
  • Processing continues with the next statement of the previous execution environment, or the program returns to the command prompt.

If the ON ERROR clause is used, the value returned by the STATUS function is the error number. If a CLEARFILE statement is used when any portion of a file is locked, the program waits until the file is released. The ON ERROR clause is not supported if the CLEARFILE statement is within a transaction.

The LOCKED Clause

The LOCKED clause is optional, but recommended.

The LOCKED clause handles a condition caused by a conflicting lock (set by another user) that prevents the CLEARFILE statement from processing. The LOCKED clause is executed if one of the following conflicting Locks exists:

  • Exclusive file lock
  • Intent file lock
  • Shared file lock
  • Update record lock
  • Shared record lock

If the CLEARFILE statement does not include a LOCKED clause, and a conflicting lock exists, the program pauses until the lock is released.

If a LOCKED clause is used, the value returned by the STATUS function is the terminal number of the user who owns the conflicting lock.

Example

OPEN "","TEST.FILE" ELSE PRINT "NOT OPEN"
EXECUTE "LIST TEST.FILE"
CLEARFILE
CHAIN "LIST TEST.FILE"

This is the program output:

LIST TEST.FILE 11:37:45am  03-22-94 PAGE    1
TEST.FILE
ONE
TWO
THREE
3 records listed.
LIST TEST.FILE 11:37:46am  03-22-94 PAGE    1
TEST.FILE.
0 records listed.
Parent topic: BASIC Statements and Functions