OVRDBF (Override with Database File)

OVRDBF Command syntax diagram

 

Purpose

The Override with Database File (OVRDBF) command is used to:

Parameters overridden by this command are specified in the file description, in the program, or in other previously issued file override commands. The OVRDBF command applies to physical files, logical files, and distributed data management (DDM) files.

To override (replace) a file named in the program, specify the name of that file in the FILE parameter, and specify the name of the file that overrides it (the file to be processed by the program) in the TOFILE parameter. The other parameters of this command can be used to override parameter values contained in the file description of the overriding file.

To override only certain parameters of the file named in the program, instead of replacing the entire file, specify the name of the file in the FILE parameter and specify the *FILE value for the TOFILE parameter. Then use the other parameters of this command to override specific parameters of the file. Parameters that are not specified do not affect parameters specified in the file description, in the program, or in other previously issued file override commands.

 

Restrictions

  1. In a multithreaded job, this command may only be issued from the initial thread.

  2. In a multithreaded job, only overrides scoped to the job or an ILE activation group will affect opens performed in a secondary thread.

More information on overriding files is in the File Management topic in the Information Center and the Database Programming topic in the Information Center.

 

Required Parameters

FILE
Specifies the name of the file being used by the program to which this override command is applied. If TOFILE(*FILE) is specified, a display device file must be specified. Otherwise, any device file or database file can be specified.

 

Optional Parameters

TOFILE
Specifies the qualified name of the database file that is used instead of the file specified in the FILE parameter or, if *FILE is specified, specifies that certain attributes are overridden by parameters specified in this command. The parameters specified on this OVRDBF command override the same parameters specified in the database file, in the program, or in other previously issued OVRDBF commands.

*FILE: The database file named in the FILE parameter has some of its parameters overridden by values specified in this command.

The name of the database file can be qualified by one of the following library values:

*LIBL: All libraries in the job's library list are searched until the first match is found.

*CURLIB: The current library for the job is searched. If no library is specified as the current library for the job, the QGPL library is used.

library-name: Specify the name of the library to be searched.

database-file-name: Specify the name of the database file that is used instead of the file specified in the FILE parameter.

MBR
Specifies the members used within the database file. This parameter is not valid for DDM files that reference remote systems other than the System/38 or the iSeries 400.

*FIRST: The first member in the database file is used.

*LAST: The last member of the specified physical file is used.

*ALL: All members in the file are processed sequentially. All members are opened with the same override parameters as the first member. While overrides issued prior to the open operation of the first member are processed, overrides or delete overrides issued following the open operation of the first member are not processed. EOFDLY, FMTSLR, INHWRT, or the POSITION parameter cannot be specified if MBR(*ALL) has been specified on a previously issued OVRDBF command that is still in effect for this file. An escape message is sent if any of the mutually exclusive parameters are specified.

member-name: Specify the member name that overrides (at file open time) the member name specified in the using program, or in other called OVRDBF commands. If the member name is not specified, and a TOFILE parameter other than *FILE has been specified, the first member in the file is used.

POSITION
Specifies the starting position for retrieving records from the database file. The first record to get can be at the beginning (*START) or at the end (*END) of the file, the nth record in the file (*RRN), or the record indicated by a key field value and one of the key-search values (*KEY, *KEYA, *KEYAE, *KEYB, or *KEYBE). This parameter overrides the value specified in the program, or in other called OVRDBF commands.

Note: This parameter cannot be specified if MBR(*ALL) was specified in a previously issued OVRDBF command that is still in effect for this file.

*NONE: No special positioning is required. The first I/O operation indicates the record that is retrieved.

*START: The starting position is the first record in the file. If a read-previous is specified in the program, an end-of-file condition occurs.

*END: The starting position is the last record in the file. When the next record is retrieved, an end-of-file condition is reached. If a read previous is requested, the last record of the file is retrieved.

Element 1: Relative Record Number

*RRN relative-record-number: Specify the number of the relative record (its position from the beginning of the file), preceded by the value *RRN, that is retrieved first. For example, POSITION(*RRN 480) specifies that record number 480 is retrieved next. If a read-previous is requested, the 479th record in the file is retrieved.

Element 2: Key-Search Values

The first record that is retrieved is identified by the specified key-operation, number-of-fields, record-format-name, and key-value. If a record that matches these values does not exist, an error message is sent.

Specify one of the following key-search types:

*KEYB (key-before): A record that precedes the record identified by the remaining search values (number-of-fields, record-format-name, and key-value) is the first record retrieved.

*KEYBE (key-before or equal): The record identified by the search values is the first record retrieved. If no record matches those values, the record is selected that matches the largest previous value.

*KEY (key-equal): The record identified by the search values is the first record retrieved. If a read-previous is specified in the program, the preceding record is retrieved.

*KEYAE (key-after or equal): The record identified by the search values is the first record retrieved. If no records matches those values, the record is selected with the next highest value.

*KEYA (key-after): A record that follows the record identified by the remaining search values (number-of-fields, record-format-name, and key-value) is the first record retrieved.

Specify the remaining search values as follows:

Element 3: Number of Fields

number-of-fields: Specify the number of key fields to use in the search. The number of fields specified in this parameter does not have to be the same as the actual number of fields in each key for the file. For example, if POSITION(*KEY 1 FMT1 A) is specified, the first record in the file format FMT1 that has a first key field value of A is retrieved. If a number of fields of zero are specified, the search is based on all key fields. If zero is used, the key value contains the maximum key size.

Element 4: Name of Record Format

record-format-name: Specify the name of the record format in the database file that contains the key value specified. If no record format name is specified (*N), all record formats are searched for the first record that matches the other search values.

Element 5: Key Value

key-value: Specify the first record retrieved. This value is specified as a quoted character string for character or positive zoned decimal formats, or is specified in hexadecimal form at (x'value'). You can specify up to 2000 characters in the character string.

For example, POSITION(*KEY 1 FMT2 X'123F') specifies that the system searches for a record from the record format FMT2, that a single key field is used in the search (even though the key value may have more key fields), and that the record contains the hexadecimal value 123F (the hexadecimal equivalent of packed decimal value 123).

POSITION(*KEYB 0 *N X'123F') specifies that a record of any format is retrieved next (its key value must precede the record identified by key value X'123F').

If a key is specified that contains more than one field, the key must be coded to match the definition of the key in the file. If the definition is for a key other than a character or signed decimal key, the key must be coded in hexadecimal form.

For example, suppose the key definition has the following key fields:

  • Character field (6A)

  • Packed numeric field (5P 2)

  • Signed numeric field (2S 0)

A character string the length of the entire key (6+3+2 in this example) can be specified on the POSITION parameter. POSITION(*KEY 3 YOURFMT X'E6D9C5D5C3C812345FF9F9') specifies that the system searches for the record in format YOURFMT, a key containing three fields is used in the search, and the record contains the hexadecimal value E6D9C5D5C3C812345FF9F9. The hexadecimal value corresponds to the following desired key values:

  • Hexadecimal value E6D9C5D5C3C8 corresponds to the character field key value WRENCH.

  • Hexadecimal value 12345F corresponds to the packed numeric field value +123.45.

  • Hexadecimal value F9F9 corresponds to the signed numeric field value 99.

The Distributed Data Management topic in the Information Center has more information on the effects of using the POSITION parameter with DDM files.

RCDFMTLCK
Specifies the lock state of the named record format while it is used by the program. The lock state indicates how the data associated with each format is locked. The following chart shows the lock states that are specified for each record format and the operations allowed to other programs when the lock is in effect:

Lock State Definition Other Program Operations
*SHRRD Shared read Read and update allowed
*SHRNUP Shared read, no update Read allowed, update not allowed
*SHRUPD Shared update Read and update allowed
*EXCLRD Exclusive allow read Read allowed, update not allowed
*EXCL Exclusive no read Neither read nor update allowed

An explanation of each lock state is in the CL Programming Link to PDF book.
For each record format, specify the record format name followed by one lock state value. This parameter overrides the record format locks specified in the program, in other called OVRDBF commands, and the default locks established when the member was created. If the lock state specified for the file in an Allocate Object (ALCOBJ) command is more restrictive than the lock state specified in this parameter, this parameter is ignored. Therefore, this parameter can only impose a more restrictive lock state on a record format than that specified for the file.

FRCRATIO
Specifies the number of insert, delete, or update operations that can occur on records before they are forced into auxiliary (permanent) storage. More information on this parameter is in commonly used parameters. More information on journal management is in the Journal management article in the Information Center.

This parameter overrides the force-write ratio specified in the database file, in the program, or in other previously issued OVRDBF commands.

*NONE: There is no force write ratio; the system determines when the records are written to auxiliary storage.

number-of-write-operations-before-force: Specify the number of operations. If a physical file associated with this database file is journaled, specify a larger force-write ratio.

FMTSLR
Specifies the qualified name of a record format selection program that is called when a logical file member contains more than one logical record format. The user-written selector program is called when a record is inserted into the database file and a record format name is not specified in the high-level language program. More information about the use of format selector programs is in the Database Programming topic in the Information Center. This parameter overrides the value specified in the database file and in other previously issued OVRDBF commands.

A program specified as the format selector program cannot be created with USRPRF(*OWNER) specified in the Create CL Program (CRTCLPGM) command.

 

Notes

  1. This parameter cannot be specified if MBR(*ALL) was specified in a previously issued OVRDBF command that is still in effect for this file.

  2. If a less restrictive state than that of the actual file is specified, the value will be ignored and the original value specified in the file will be used.

The name of the program can be qualified by one of the following library values:

*LIBL: All libraries in the job's library list are searched until the first match is found.

*CURLIB: The current library for the job is searched. If no library is specified as the current library for the job, the QGPL library is used.

library-name: Specify the name of the library to be searched.

program-name: Specify the name of a record format selection program called when a logical file member contains more than one logical record format.

WAITFILE
Specifies the number of seconds that the program waits for the file resources and session resources to be allocated when the file is opened. If those resources are not allocated within the specified wait time, an error message is sent to the program.

This parameter overrides the wait time specified in the database file, in the program, or in other previously issued OVRDBF commands. More information on this parameter is in commonly used parameters.

*IMMED: The program does not wait; when the file is opened, an immediate allocation of the file resources is required.

*CLS: The job default wait time is used as the wait time for the file resources being allocated.

number-of-seconds: Specify the number of seconds that the program waits for the file resources to be allocated. Valid values range from 1 through 32767 seconds.

WAITRCD
Specifies the number of seconds that a program waits for a record to be updated or deleted, or for a record read in the commitment control environment with LCKLVL(*ALL) specified. More information on record locking is in the Database Programming topic in the Information Center. If the record is not allocated in the specified wait time, an error message is sent to the program.

Note: This parameter overrides the record wait time specified in the database file, specified in the program, or in other previously issued OVRDBF commands. The minimum delay for DDM files is 60 seconds. This value may need to be longer than the delay specified for local database files.

*IMMED: The program does not wait; when a record is locked, an immediate allocation of the record is required.

*NOMAX: There is no disconnect limit.

number-of-seconds: Specify the number of seconds that the program waits for the record lock. Valid values range from 1 through 32767 seconds.

NBRRCDS
Specifies the number of records moved as a unit from auxiliary storage to main storage. (The amount of data actually moved is equal to the number of records multiplied by the physical record length, not the logical record length.) Valid values range from 1 through 32767 records. The NBRRCDS parameter is valid for sequential or random processing and is specified only when the data records are physically located in auxiliary storage in the sequence in which they are processed. This parameter overrides the number of records value specified in the program, or in other previously issued OVRDBF commands.

EOFDLY
Specifies the number of seconds to delay when the end-of-file is reached before trying to retrieve additional records. This delay allows other jobs to add records to the file, and have the new records processed without having to restart the job. When the delay time ends, the job is made active, and the database determines whether new records were added. If no new records were added, the job waits for another time delay without informing the application program. When a number of seconds is specified, no end-of-file condition occurs on the given database file until an End Job (ENDJOB) command or forced end of data (FEOD) occurs.

Note: This parameter cannot be specified if MBR(*ALL) was specified on a previously issued OVRDBF command that is still in effect for this file.

There are several ways to end a job that is waiting for records due to an EOFDLY. They are:

  • Write a record to the specified file which is recognized by the application program as a last record. The application program may then do a force end of data (FEOD) to start the end-of-file processing or close the file.

  • End the job using the controlled value (ENDJOB OPTION(*CNTRLD)) with a delay time greater than the time specified on the EOFDLY time. The DELAY parameter time specified must allow for the EOFDLY time to run out, plus time to process any new records that may have been added to the file, and any end-of-file processing that is done in the user's application. The end-of-file is set by database, and a normal end-of-file condition occurs after new records are retrieved.

  • End the job immediately (ENDJOB OPTION(*IMMED)).

  • If the job is interactive, start a system request and end the previous request.

*NONE: Normal end-of-file processing is done.

number-of-seconds: Specify the number of seconds that the program waits between each attempt to get a record when an end-of-file condition occurs. No end-of-file condition is signaled until end of data is forced, or the job is ended with the *CNTRLD option. Valid values range from 1 through 99999 seconds.

LVLCHK
Specifies whether the record format level identifiers in the program are checked against those in the device file when the file is opened. If so, the record format identifiers in the program must match those in the device file. Because the same record format name can exist in more than one file, each record format is given an internal system identifier when it is created.

Note: This parameter overrides the value specified in the database file, in the program, or in other previously issued OVRDBF commands issued in this or the following call level. Level checking cannot be done unless the program contains the record format identifiers. This command cannot override level checking from *NO to *YES.

*NO: The level identifiers are not checked when the file is opened.

EXPCHK
Specifies whether the expiration date of the named member is checked. This date check is valid only on a physical file member. This parameter overrides the value specified in the program, or in other called OVRDBF commands.

*YES: The expiration date of the physical file member is checked. If the current date is later than the expiration date, an error message is sent to the job, where it is monitored. An escape message is sent to the program.

*NO: The expiration date is not checked.

INHWRT
Specifies whether the processed records are written, deleted, or changed in the database file. This parameter tests a program without storing the processed records back in the database. This parameter overrides the INHWRT parameter in other previously issued OVRDBF commands.

Note: This parameter cannot be specified if MBR(*ALL) was specified on a previously issued OVRDBF command that is still in effect for this file.

*YES: Processed records are prevented from being written into the database; they are written only to an output device.

*NO: All new and changed processed records are written into the database, unless the program is in debug mode with UPDPROD(*NO) specified, and the file is in a production library. In that case, an escape message is sent to the program.

SECURE
Specifies whether this file is safe from the effects of previously called file override commands. If SECURE is not specified, processing occurs as if SECURE(*NO) is specified.

*NO: This file is not protected from the effects of other file overrides; its values can be overridden by the effects of previously called file override commands.

*YES: This file is protected from the effects of any file override commands previously called.

OVRSCOPE
Specifies the extent of influence (scope) of the override.

*ACTGRPDFN: The scope of the override is determined by the activation group of the program that calls this command. When the activation group is the default activation group, the scope equals the call level of the calling program. When the activation group is not the default activation group, the scope equals the activation group of the calling program.

*CALLLVL: The scope of the override is determined by the current call level. All open operations done at a call level that is the same as or higher than the current call level are influenced by this override.

*JOB: The scope of the override is the job in which the override occurs.

SHARE
Specifies whether the open data path (ODP) for the database file member is shared with other programs in the routing step. When an ODP is shared, the programs accessing the file share facilities such as the file status and the buffer.

More information on shared database files is in the Database Programming topic in the Information Center.

*NO: The ODP created by the program with this attribute is not shared with other programs in the routing step. Every time a program opens the file with this attribute, a new ODP to the file is created and activated.

Note: This includes several opens in the same program.

*YES: The ODP created with this attribute is shared with each program in the routing step that also specifies SHARE(*YES) when it opens the file, provided the scope specified on the OPNSCOPE keyword for the subsequent open of the file is compatible with the scope of the original open.

Note: When SHARE(*YES) is specified and control is passed to a program, a read operation in that program retrieves the next input record. A write operation produces the next output record.

OPNSCOPE
Specifies the extent of influence (scope) of the open operation.

*ACTGRPDFN: The scope of the open data path (ODP) is determined by the activation group of the program that called the OVRDBF command processing program. If the activation group is the default activation group, the scope is the call level of the caller. If the activation group is a non-default activation group, the scope is the activation group of the caller. In a multi-threaded job, only those shared opens within the same thread and same activation group can share this ODP.

*JOB: The scope of the open data path (ODP) is the job in which the open operation occurs. If the job is multi-threaded, only those opens from the same thread can share this ODP.

SEQONLY
Specifies, for database files whose records are processed in sequential order only, whether sequential-only processing is used on the file. This parameter also specifies the number of records transferred as a group to or from the database, if sequential-only processing is used. If a number is not specified, a default number is determined by the system. This parameter is used to improve the performance of programs that process database files in a sequential manner. This parameter overrides the value specified in the program or in other previously issued OVRDBF commands.

For files opened for input only in a program, the specified number of records is transferred as a group from the database to an internal data management buffer.

For files opened for output only in a program, a group of records is transferred to the database whenever the internal data management buffer receives the specified number of processed records from the program. For output files, sequential-only processing is valid for physical file members and for logical file members that are based on one physical file member only.

If SEQONLY(*YES) is specified, and any of the following conditions are true, the SEQONLY parameter is ignored and a message is issued.

  • The program opened the member for output only and SEQONLY(*YES) is specified with the default number of records, and the member opened is either a logical member, a unique keyed physical member, or other access paths are built over the physical member.

  • The program opened the member for other than input or output.

  • The member opened by the program for output is based on many other members.

  • The record length plus the feedback area sum exceeded 32,767 bytes.


Note: Unpredictable results occur when this parameter is used for alternate index files for DDM on a system other than an iSeries 400.

*NO: The database file is not restricted to sequential-only processing.

*YES: The database file uses sequential-only processing. A default value for the number of records transferred as a group is determined by the system based on how the file is used, the type of access path involved, and the file's record length:

  • The default is approximately the number of records that fit in an internal buffer of 4K for:

    • All database files opened for input only

    • Physical files opened for output that are only processed in either arrival sequence or in non-unique keyed sequence and that have no logical file members based on them

  • The default is 1 record for:

    • All logical files opened for output only

    • Physical files opened for output only that either have unique keyed sequence access paths or have at least one dependent logical file with a keyed sequence access path that does not share the access path of the keyed physical file member

number-of-records: Specify *YES followed by a value (ranging from 1 through 32767) for the number of records transferred between the database and the internal buffer. The user must ensure that the buffer size specified is always available to the program in the storage pool in which the program is running. The file uses sequential-only processing.

While records are in the internal data management buffer, other jobs can make changes to the same records in the database, and the program performing sequential-only input processing does not see the updates. To ensure that no other updating is done to records while they are in the buffer, the Allocate Object (ALCOBJ) command can be used in the program to specify either an *EXCLRD or an *EXCL lock on the file.

If a program performs sequential-only output processing and does not handle output errors (such as duplicate keys and conversion mapping errors) that may occur when the records in the buffer are written to the database, records in the buffer after the first record in error are not written.

If the file is opened for output and the value specified in this parameter is not the same as the force write ratio specified for the file, the value used by the system is the smaller of the two; a message stating which value is changed is sent to the user.

When processing SEQONLY(*YES) for writing records into a database file, feedback information for each record (such as relative record number) is not always changed. If such feedback information is important, specify SEQONLY(*NO) or SEQONLY(*YES 1).

More information on sequence-only database files is in the Database Programming topic in the Information Center.

DSTDTA
Specifies the data retrieval method used for a distributed file. This parameter has no effect if used against a non-distributed file. Other parameters, such as SEQONLY, still affect how the data is retrieved from each system, and this parameter controls how all the data is managed when accessing a distributed file. This parameter overrides the distributed file data retrieval method selected by the system, or specified in other previously issued OVRDBF commands.

*BUFFERED: To achieve the best performance, data from the remote system and the local system may be kept in a buffer until retrieved by the user.

*PROTECTED: Data can be buffered, but the file is locked to prevent updates by other jobs. This will give the same performance as *BUFFERED, but guarantees current data. While one job is using this option, other jobs will not be able to update the data in the file.

*CURRENT: Data is not buffered. This option results in fully live data, with maximum concurrency, but without optimal performance.

Examples for OVRDBF

Example 1: Overriding An Existing Member 

OVRDBF   FILE(ORDERSIN)  MBR(MONDAY)

This command overrides the existing member with member MONDAY. With the override in effect, the member MONDAY will be processed when the file ORDERSIN is opened.

Example 2: Overriding a Share Specification 

OVRDBF   FILE(ORDERSIN)  SHARE(*YES)

This command overrides the share specification for the file ORDERSIN. Because of this override, any subsequent opens of this file within the routing step share the ODP for the file.

Example 3: Overriding a File, Member and Lock State 

OVRDBF   FILE(INPUT)  TOFILE(PAYROLL)  MBR(MBR1)
  RCDFMTLCK((EMPDATA *EXCL))

This command overrides the file, the member, and the lock state of the record format EMPDATA. The override will cause the following to occur when the file INPUT is opened:

Additional Considerations

The following characteristics apply to the processing of DDM files on the OVRDBF command.

The Distributed Data Management topic in the Information Center has examples of how file overrides are applied in DDM.

Error messages for OVRDBF

*ESCAPE Messages

CPF180C
Function &1 not allowed.