The SCRATCH statement closes a file if it is open, and then deletes the file.

     SCRATCH              FAIL CACHE?
    (1)            (2) (3)                     (4)      (5)

(1) T/F execution conditions

(2) Application ID

(3) File name

(4) Fail action (0=nothing, 1=warning, 2=error, 3=cancel)

(5) Cache? (Y=cache version, N=disk version)

Sets True/False Status Indicator

The SCRATCH statement modifies the current status indicators by setting the next indicator to T if the file does not exist following the SCRATCH, and to F if the file still exists. If the next indicator is set to F, the FAIL parameter determines what additional action to take. In addition, on a false condition, the predefined field STATUS CODE returns a token indicating the reason for an I/O command failure. This token can be used as a key to read the system message file to obtain a descriptive I/O error message (see STATUS CODE for details).

Note that the next indicator is set to T if the file does not exist when the SCRATCH statement executes. Scratching a nonexistent file is considered successful because the file does not exist following the SCRATCH statement.

Using the Statement

The SCRATCH statement allows you to indicate whether to scratch the cached version of a file or the disk version.

When scratching a file, you can specify a database other than the current one by setting the predefined field NEXT DATABASE. If NEXT DATABASE is blank, the current database (contained in DATABASE) is used. If NEXT DATABASE is specified in conjunction with CACHE?=Y, then NEXT DATABASE is cleared and ignored as cache files, like memory files, have only one version.

Note that NEXT DATABASE is modifiable, whereas DATABASE is not, and that NEXT DATABASE is set to blank by the SCRATCH statement.

It is possible to have several versions of a file open at the same time by using the OPEN statement on different databases. The version of a file that is scratched is the last database accessed with the OPEN statement for that file. Refer to the OPEN statement for additional explanation.


If a file is scratched, it must be created again before it can be used.

Statement Ignored

A SCRATCH statement can fail when the file is physically open for use by another user, or when the current user has insufficient privileges to scratch the file.

Related PDFs


Related Statements



In the example below, a work file called TEMP is initialized by using the SCRATCH and CREATE statements.

          SCRATCH  TAR TEMP                FAIL 0 CACHE? N