IBM i OVRDBF Command Reference: TOFILE, MBR, OVRSCOPE

OVRDBF (Override with Database File) changes which file, member, or processing option a program actually uses at open time, without changing the program’s compiled file reference. This page is a parameter-level lookup. For the message-handling side of CL error recovery, see IBM i Message Files and Exception Handling in CL. For how open data paths and blocking interact with job performance, see IBM i Performance Tuning: Memory Pools, WRKACTJOB, Collection Services.

Purpose and scope

A compiled RPG, CL, or COBOL program opens a file by the name coded in its file declaration. OVRDBF lets a calling CL procedure redirect that name to a different file, member, or library, or change how the open behaves (share an ODP, run sequential-only, set a starting position), without recompiling the program.

OVRDBF does not take effect immediately. IBM’s documentation is explicit on this point: issuing the command only stores the override information; it is applied the next time the named file is opened within the override’s scope. If the file is already open when the override is issued, the override has no effect on that open instance — close and reopen (or end and restart the activation group or job, depending on scope) for it to apply.

OVRDBF affects any command or program that opens the named file by that file name within the override’s scope: RPG and COBOL programs, CL commands like CPYF or RUNSQLSTM against native files, and interactive displays driven by the same file name. It does not change the compiled program and does not persist past its scope — once the scope ends, the next open reverts to the file reference built into the program or object.

Syntax and key parameters

OVRDBF FILE(name) TOFILE(qualified-object-name) MBR(name | *FIRST | *LAST | *ALL)
       POSITION(*NONE | *START | *END | positioning-element)
       SHARE(*NO | *YES) SEQONLY(*NO | *YES record-count)
       OVRSCOPE(*ACTGRPDFN | *CALLLVL | *JOB) WAITRCD(*NOMAX | *IMMED | seconds)

FILE (required): the file name as coded in the program being overridden.
TOFILE: the qualified object to actually open; default is *FILE (no redirection, same name). The library qualifier accepts *LIBL or *CURLIB.
MBR: the member to open — a specific name, *FIRST, *LAST, or *ALL. Per IBM’s reference, if MBR is not specified and TOFILE names a file other than *FILE, the first member in that file is used. MBR(*ALL) processes every member in order under the same override and cannot be combined with POSITION.
POSITION: controls where the first read starts — *NONE (no special positioning, the default behavior when omitted), *START, *END, or a keyed/relative-record positioning element (*RRN, *KEY, *KEYB, *KEYBE, *KEYA, *KEYAE). Cannot be specified if an earlier override already set MBR(*ALL).
SHARE: *NO (each open of the file creates its own open data path) or *YES (programs in the same job that also specify SHARE(*YES) reuse one ODP, sharing buffers, record pointer, and file status). *YES is how multiple programs in one job see the same cursor position in a file.
SEQONLY: *NO (normal random/sequential access) or *YES record-count (restricts processing to sequential-only, transferring records in blocks between the database and an internal buffer — faster for straight-through reads, but other jobs can still change buffered records before your program sees them). If no record count is given, the system picks one.
OVRSCOPE: controls how far up or down the call stack the override reaches — see the dedicated section below.
WAITRCD (cross-reference only, since it governs lock-wait behavior rather than file redirection): sets how long a program waits for a locked record — *NOMAX (wait indefinitely), *IMMED (no wait), or 1–32767 seconds. It overrides the record wait time from the file description, the program, or any earlier OVRDBF command, and is distinct from WAITFILE, which governs waiting for the file object itself at open time.

OVRSCOPE and override stacking

OVRSCOPE determines which calls the override reaches:

*ACTGRPDFN (default): scope follows the activation group of the program that issues the OVRDBF. In the default activation group, this behaves like *CALLLVL; in a named activation group, the override’s scope is that activation group.
*CALLLVL: the override affects opens performed at the call level that issues the OVRDBF and any level it calls (deeper in the call stack), until that issuing call level ends.
*JOB: the override is visible for the entire job, regardless of activation group or call level, until explicitly removed or the job ends.

When two OVRDBF commands name the same FILE value within overlapping scope, the later command’s parameters take effect for the next open; parameters left unspecified on the later command do not reset values established by an earlier override — they simply carry forward. This is what IBM’s reference means by overrides stacking: each OVRDBF layers on top of the file description, the program, and any prior override still in scope, rather than replacing the whole set outright.

DLTOVR and DSPOVR

DLTOVR FILE(name | *ALL) removes an override before its scope naturally ends, so the next open falls back to the file description or an outer-scope override. DSPOVR displays the overrides currently active for the job, which is the fastest way to confirm whether a stale override from an earlier step is still in force.

Practical examples (documentation-checked, not compiler- or runtime-tested)

Basic redirection to a different library and member:

OVRDBF FILE(CUSTFILE) TOFILE(TESTLIB/CUSTOMER) MBR(CURRENT)
CALL PGM(ORDENTR)

Job-scoped override with sequential-only processing, useful for a batch step that must see the redirection regardless of which program or call level performs the open:

OVRDBF FILE(TRANFILE) TOFILE(PRODLIB/TRANHIST) SHARE(*YES) SEQONLY(*YES 100) OVRSCOPE(*JOB)
CALL PGM(BATCHPROC)

Stacked overrides targeting the same file, where the second command narrows the member without re-specifying everything:

OVRDBF FILE(CUSTFILE) TOFILE(TESTLIB/CUSTOMER) OVRSCOPE(*JOB)
OVRDBF FILE(CUSTFILE) MBR(ARCHIVE) OVRSCOPE(*JOB)
CALL PGM(RPTGEN)

Here the second override still honors TOFILE(TESTLIB/CUSTOMER) from the first because it was not re-specified, and layers MBR(ARCHIVE) on top.

Required authorities and safety implications

The user profile running the OVRDBF command needs *USE authority to the named target object through TOFILE, plus whatever authority the program’s actual read/write/update operations require. OVRDBF itself does not grant authority — it only changes which object is opened, so a job that previously failed with insufficient authority will fail the same way against the new target. Because OVRDBF FILE(*ALL)-style blanket overrides and *JOB-scoped overrides can silently redirect unrelated steps later in the same job, treat broad-scope overrides in shared job streams as a change-control risk, not just a technical convenience.

Common errors

Override not taking effect: usually an OVRSCOPE mismatch — the override was issued at a call level or activation group that ended before the target open happened, or a more specific override elsewhere in the job is being hit first.
Stale overrides in later job steps: forgetting DLTOVR after a temporary redirection leaves the override active for the rest of the job (under *JOB scope) or activation group, silently redirecting a later, unrelated use of the same file name.
MBR(*ALL) combined with POSITION: the command rejects this combination; set positioning only when a single member is targeted.
Assuming an override applies to an already-open file: it only affects opens that happen after the command runs, within scope.

Diagnosing active overrides

Run DSPOVR to list overrides currently in effect for the job before troubleshooting “it redirected to the wrong file” reports — the active override is usually visible there rather than in the calling program’s source.

Related references

Verification (evidence)

The FILE, TOFILE, MBR, POSITION, SHARE, SEQONLY, OVRSCOPE and WAITRCD parameter descriptions were checked against a live fetch of IBM’s IBM i 7.5 CL Reference page for OVRDBF (https://www.ibm.com/docs/en/i/7.5?topic=ssw_ibm_i_75/cl/ovrdbf.htm), including the OVRSCOPE(*ACTGRPDFN) default and the three OVRSCOPE values’ meanings. That page did not cover DLTOVR or DSPOVR; their descriptions here rely on general knowledge of IBM i CL commands rather than an independent fetch of their own documentation pages, and should be spot-checked before this page is treated as fully doc-verified for those two commands specifically. No example in this article was compiled or run.

CORRECTION: an earlier draft’s job-scoped override example used & at the end of a line as a CL command continuation character. & is not a documented CL continuation character — a live-fetch attempt to confirm IBM’s actual rule for continuing a CL command across multiple physical lines returned only navigation pages and repeated 404s, so no citable IBM source for a continuation character was found in this pass. Rather than publish an unverified continuation rule, the example was rewritten as a single line, which sidesteps the question entirely without asserting anything unconfirmed.

Summary

OVRDBF redirects a program’s file open by FILE name to a different TOFILE/MBR, without recompiling the program.
OVRSCOPE (*ACTGRPDFN, *CALLLVL, *JOB) controls how far the override reaches; stacked overrides on the same file layer parameters rather than replacing them wholesale.
DLTOVR removes an override before its scope ends; DSPOVR shows what is currently active.
All examples here are documentation-checked against IBM’s CL reference, not compiled or run.