CHGPF (Change Physical File)

CHGPF Command syntax diagram

 

Purpose

The Change Physical File (CHGPF) command changes the attributes of a physical file and all its members. The changed attributes are also used for all members subsequently added to the file. To change the attributes of a specific member, use the Change Physical File Member (CHGPFM) command.

 

Restrictions

  1. The user of this command must have object management authority or object alter authority for the file and execute authority to the library. An exclusive-no-read lock is required, which means no one can be using the file for any purpose.

  2. If a request to make an existing file re-use deleted records is made, but there are logical files over the physical file that specify "FIFO" or "LIFO" ordering for duplicate keys, the change is not allowed.

 

Required Parameters

FILE
Specifies the qualified name of the physical file to be changed.

Note: If a distributed data management (DDM) file is specified, then the physical file specified on the RMTFILE parameter of the Create Distributed Data Management File (CRTDDMF) command is changed on the remote system specified on the RMTLOCNAME parameter on the CRTDDMF command. More information is outlined in the SYSTEM parameter of this command.

The name of the 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.

physical-file-name: Specify the name of the physical file.

 

Optional Parameters

SYSTEM
Specifies whether the physical file is changed on the local system or on a remote system.

*LCL: The physical file is changed on the local system.

*RMT: The physical file is changed on a remote system using DDM. The physical file name specified on the FILE parameter must be the name of the DDM file (created by using the Create Distributed Data Management File (CRTDDMF) command). The DDM file contains the name of the physical file to be changed (RMTFILE parameter on the CRTDDMF command) and the name of the remote system (RMTLOCNAME parameter on the CRTDDMF command) on which the file is to be changed.

*FILETYPE: If the name specified on the FILE parameter is a DDM file, the physical file is changed on the remote system specified by the RMTLOCNAME parameter of that DDM file. Otherwise, the name specified on the FILE parameter to be changed must be the name of a local physical file.

SRCFILE
Specifies the qualified name of the source file used to change the physical file. The source file contains the specifications that describe the record format and its fields, and the access path for the file and its members. The data description specifications (DDS) that are made are described in the Database Programming topic in the Information Center and DDS Reference topic in the Information Center.

If the format attributes are changed, the data in the existing file is converted to the new attributes.

Attention:

  1. The data in the existing file is converted to the new format based on field names. If the name of a field is changed, its existing data is lost.

  2. Because you are converting data, it is strongly recommended that you save the file before you issue this command.

If the access path attributes are changed or the attributes of one of the key fields in the format are changed, a new access path may need to be built.

Note: When the data or the access path attributes are changed, the change file operation can take a long time to complete. Status messages are sent to keep the interactive user informed of the progress of the operation.

*NONE: No source file is specified. Neither the format nor the access path attributes for the file are changed.

QDDSSRC: The source file, QDDSSRC, contains the DDS used to change the physical file.

The name of the source 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.

source-file-name: Specify the name of the source file that contains the DDS used to change the physical file.

SRCMBR
Specifies the name of the source file member that contains the DDS for the physical file being changed.

Note: This parameter is valid only when a source file is specified on the SRCFILE parameter.

*FILE: The source file member name is the same as the name of the physical file being changed.

source-file-member-name: Specify the name of the source file member used to change the physical file.

OPTION
Specifies the type of output produced when the file is changed. A maximum of four of the following values can be specified in any order on this parameter. If neither or both of the values on an option are specified, the underlined value is used.

 

Notes

  1. This parameter is valid only when a source file is specified on the SRCFILE parameter.

  2. The underlined values on this parameter are similar to, but are not actually default values, and therefore they cannot be changed with the Change Command Default (CHGCMDDFT) command.

Source Listing Options

*SRC or *SOURCE: A printout is created of the source statements used to change the file, and of the errors that occur.

*NOSRC or *NOSOURCE: No printout of the source statements is created unless errors are detected. If errors are detected, they are listed along with the keyword or record format that caused the error.

Program Listing Options

*LIST: An expanded source printout is created, showing a detailed list of the file specifications that result from the source statements and references to other file descriptions.

*NOLIST: An expanded source printout is not created.

Second-Level Message Text Options

*NOSECLVL: The messages section of the DDS printout does not contain the second-level message for the errors found during DDS processing.

*SECLVL: Second-level message text is included in the source listing.

Event File Creation Options

*NOEVENTF: The compiler does not produce an event file for the CoOperative Development Environment/400 product.

*EVENTF: The compiler produces an event file that can be used by the CoOperative Development Environment/400 (CODE/400) product. The event file is created as a member in the file EVFEVENT in your object library. The CODE/400 product uses this file to offer error feedback integrated with the CODE/400 editor. This value is normally specified by the CODE/400 product on your behalf.

GENLVL
Specifies the severity level of errors at which the change operation fails. If errors occur that have a severity level greater than or equal to this value, the operation ends.

 

Notes

  1. This parameter is valid only when a source file is specified on the SRCFILE parameter.

  2. This parameter applies only to messages created while processing the DDS source. Messages created elsewhere in the file change process are not affected by this parameter.

  3. The value on this parameter must be greater than or equal to the value specified on the FLAG parameter.

20: The error severity level of 20 or above ends the change operation.

severity-level: Specify a severity level ranging from 0 through 30. The file is not changed if the severity level specified is 0.

FLAG
Specifies the minimum severity level of messages to be listed in the DDS source listing.

Note: This parameter is valid only when a source file is specified on the SRCFILE parameter.

0: The spooled file is owned by the original user profile of the job. If the job has switched to a new user profile, the original user profile is still the owner of the spooled file.

severity-level: Specify the minimum severity level of messages to be listed. Valid values range from 0 through 30. The severity level specified must be less than or equal to the severity level specified on the GENLVL parameter.

DLTDEPLF
Specifies whether the logical files that are dependent on a field are deleted if that field is removed from the file as part of the change operation. A field is removed from the file if its definition is not included in the DDS identified in the source file.

Note: This parameter is valid only when a source file is specified on the SRCFILE parameter.

*NO: The logical files are not deleted. The field on which the access paths are dependent is not removed and the file is not changed. The command ends.

*YES: The logical files that are dependent on a field that is removed from the file are deleted.

RMVCST
Specifies whether the constraint relationships are removed in the associated set of dependent files when you are deleting a parent file of a referential constraint.

Note: This parameter is valid only when DLTDEPLF(*YES) is specified.

*RESTRICT: The constraint relationships are not removed. The parent file is not removed and the file is not changed. The command ends.

*REMOVE: The constraints that are dependent on a field that is removed from the file are removed. If a unique constraint is removed, any referential constraints that are dependent on the unique constraint are also removed.

EXPDATE
Specifies the expiration date. The files cannot be overwritten until the expiration date. The expiration date must be later than or equal to the current date.

Note: An attempt to open a file member that has exceeded its expiration date causes an error message to be sent to the user. (The Remove Member (RMVM) command is used to remove the member.) If EXPDATE is specified, all members in the file are changed. The expiration date must be later than or equal to the current date. The date must be specified in the format defined by the job attributes, DATFMT and DATSEP. The date must be enclosed in apostrophes if special characters are used in the format.

*SAME: The value does not change.

*NONE: No expiration date is specified.

expiration-date: Specify the date after which the member is not used.

MAXMBRS
Specifies the maximum number of members that the physical file can have at any time. The maximum number of members specified must be greater than or equal to the current number of members in the file.

*SAME: The value does not change.

*NOMAX: The system maximum is used.

maximum-members: Specify the maximum number of members that the physical file can have. Valid values range from 1 through 32767.

ACCPTHSIZ
Specifies the maximum size of auxiliary storage that can be occupied by the following kinds of access paths:

  • The access paths that are associated with a physical file that has a keyed sequence access path.

  • The access paths that are created for referential or unique constraints, and that can be added to this file with the Add Physical File Constraint (ADDPFCST) command.

Changing the value for this file causes the access paths that are owned by the file to be rebuilt.

Note: This parameter does not apply to access paths that are created for logical files or for queries that refer to the data in a physical file.

Performance Tip For optimum performance, consider whether there is high contention for keys within the access paths when selecting the value on this parameter:

  • When there is little or no contention for keys, specifying the *MAX4GB value generally provides better performance.

  • When there is high contention for keys, specifying the *MAX1TB value generally provides better performance.

*SAME: The value does not change.

*MAX4GB: The access paths associated with this file can occupy a maximum of four gigabytes (4,294,966,272 bytes) of auxiliary storage. This value provides compatibility with releases of the operating system earlier than Version 3 Release 6 Modification 0.

*MAX1TB: The access paths associated with this file can occupy a maximum of one terabyte (1,099,511,627,776 bytes) of auxiliary storage.

Note: This value is not supported on releases of the system earlier than Version 3 Release 6 Modification 0 (V3R6M0). Therefore, if an attempt is made to save a physical file that has this attribute, and the save operation specifies a target release earlier than V3R6M0, the save operation might be unsuccessful, or if successful, the access paths are not saved. If the save operation is successful and the saved version of the file is then used to restore the physical file, the system rebuilds all of the access paths.

MAINT
Specifies the type of access path maintenance used for all members of the physical file. This parameter is valid only if the file has a keyed access path.

*SAME: The value does not change.

*IMMED: The access path is maintained for each physical file member whether the source physical file is opened or closed. The access path is changed whenever a record is updated, added to, or deleted from a member of this file or a logical file member based on a member of this file.

*REBLD: The access path is rebuilt when a file member is opened. The access path is continuously maintained until the member is closed; then the access path maintenance is ended. *REBLD is not valid for access paths that require unique key values.

*DLY: The maintenance of the access path is delayed until the member is opened for use. The access path is changed only for records that are added, deleted, or changed since the file was last closed. (While the file is open, all changes made to based-on members are immediately reflected in the access paths of the members of the opened files, no matter what is specified for the MAINT parameter.) To prevent a lengthy rebuild time when the file is opened, *DLY should be specified only when the number of changes to the access path between a close operation and the next open operation are small (when key fields in records for this access path change infrequently). *DLY is not valid for access paths that require unique key values.

If the number of changes between a close operation and the next open operation reaches approximately 10% of the access path size, the system stops saving changes and the access path is completely rebuilt the next time the file is opened.

RECOVER
Specifies, for files having immediate or delayed maintenance on their access paths, when recovery processing of the file is done if a system failure occurs while the access path is being changed.

An access path having immediate or delayed maintenance is rebuilt during IPL (before any user can run a job), after the IPL is completed (while other jobs are running), or when the file is next opened. While the access path is being rebuilt, the file must not be used by any job.

During the IPL, an Override Access Path Recovery display lists those access paths that must be recovered and what the RECOVER parameter value is for each. The user can override the RECOVER parameter value on this display. More information is available in the Backup and recovery topic in the Information Center.

An access path having rebuild maintenance is rebuilt the next time its file is opened, the time that it normally is rebuilt. This parameter is valid only for files with a keyed access path.

*SAME: The value does not change.

*NO: The access path of the file is not rebuilt. The file's access path, if not valid, is rebuilt when the file is next opened.

*AFTIPL: The file has its access path rebuilt after the IPL operation is completed. This option allows other jobs not using this file to begin processing immediately after the IPL has been completed. If a job tries to open the file while its access path is being rebuilt, a file open exception occurs.

*IPL: The file has its access path rebuilt during the IPL. This ensures that the file's access path is rebuilt before the first user program tries to use it; however, no jobs start running until after all files that specify RECOVER(*IPL) have their access paths rebuilt.

FRCACCPTH
Specifies, for files with keyed access paths only, whether access path changes are forced to auxiliary storage along with the associated records in the file whenever the access path is changed. FRCACCPTH(*YES) minimizes (but does not remove) the possibility that an abnormal job end can cause damage to the access path, which then requires it to be rebuilt.

*SAME: The value does not change.

*NO: The access path and changed records are not forced to auxiliary storage whenever the access path is changed.

*YES: The access path and changed records are forced to auxiliary storage whenever the access path is changed. If this value is specified, MAINT(*REBLD) cannot be specified.

FRCACCPTH(*YES) slows the response time of the system if the access path is changed in an interactive job. If the access path is changed frequently, the entire performance of the system is affected.

SIZE
Specifies the initial number of records in each member of the file, the number of records in each increment that is automatically added to the member size, and the number of times the increment is automatically applied.

A change to the initial number of records takes effect when a new member is added to the file or when a current member is cleared, restored, or reorganized. A change to the number of records to add for each increment, and the number of times the increment is automatically applied take effect the next time a member of the file needs an increment.

The total size of the member (first number of records plus the number of records added per increment times the number of increments) must be larger than the current size of the member. If it is smaller than the current size of the member, an error message is sent to the user, and the size does not change.

Element 1: Number of Records

*SAME: The value does not change.

number-of-records: Specify the number of records (ranging from 1 through 16777215) that can be inserted before an automatic extension occurs. If automatic extensions are not wanted, enter zeros for the second and third values in the list.

Element 2: Increment Value

*SAME: The value does not change.

increment-value: Specify the number of additional records (ranging from 0 through 32767) which, if greater than 10% of the size of the member when the maximum number of records is reached, are to be added to the member during an automatic extension.

If the number specified is not greater than 10% of the member size and not equal to zero, the member size is increased by 10%.

Specify 0 to prevent automatic extensions. This value must be 0 if the value for the number of increments is 0.

Element 3: Maximum Number of Increments

*SAME: The value does not change.

number-of-increments: Specify the maximum number of increments (ranging from 0 through 32767) that can be automatically added to the member. Enter a 0 to prevent automatic extensions. If the increment value is 0, the number of increments must be 0.

Other Single Values

*NOMAX: The system maximum is used. This option cannot be specified if ALLOCATE(*YES) is in effect.

ALLOCATE
Specifies whether storage space is allocated for the initial number of records (SIZE parameter) for each physical file member when it is added. This change takes effect the next time a new member is added to the file or when a current member is cleared, restored, or reorganized.

*SAME: The value does not change.

*NO: When a new member is added, or when an existing member is cleared, restored, or reorganized, the system determines whether additional space is needed and allocates that amount.

*YES: The amount of storage space specified in the first value of the SIZE parameter is allocated each time a new member is added, or each time an existing member is cleared, restored, or reorganized. If that amount of storage space is not available, the member is not added, and a message is sent to the user. If this parameter value is used, SIZE(*NOMAX) must not be in effect.

UNIT
This parameter is no longer supported. It exists solely for compatibility with releases earlier than Version 3 Release 6 Modification 0 of the AS/400 system. For information on using auxiliary storage pools (ASPs), refer to the Backup and recovery topic in the Information Center.

You can specify the value *SAME, the value *ANY, or a value ranging from 1 through 255 on this parameter.

FRCRATIO
Specifies the number of inserted, updated, or deleted records that are processed before they are forced to auxiliary (permanent) storage. More information is in Commonly used parameters.

If the physical file is being recorded in a journal, a larger force write ratio, or *NONE, should be specified. More information on journal management is in the Journal management article in the Information Center.

*SAME: The value does not change.

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

number-of-records-before-force: Specify the number of inserted, updated, or deleted records that are processed before they are explicitly forced to auxiliary storage.

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, or for the device or session resources to be allocated when an acquire operation is performed to the file. If those resources are not allocated within the specified wait time, an error message is sent to the program. More information is in Commonly used parameters.

Note: An immediate allocation of the device by the device resource is required when an acquire operation is performed to the file.

*SAME: The value does not change.

*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 a program waits for the file resources to be allocated to the job. 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.

*SAME: The value does not change.

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

*NOMAX: The system maximum is used.

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

SHARE
Specifies whether the open data path (ODP) for the physical file 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.

*SAME: The value does not change.

*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.

*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.

DLTPCT
Specifies the maximum percentage of deleted records that any member in the physical file can have. The percentage is based on the number of deleted records compared with the total record count in a member. This change takes effect the next time the file is opened and closed.

*SAME: The value does not change.

*NONE: No percentage is specified; the number of deleted records in the file members is not checked when a member is closed.

deleted-records-threshold-percentage: Specify the largest percentage of deleted records, ranging from 1 through 100, that any member in the file can have. If a value is larger than this percentage, a message is sent to the system history log (QHST) whenever the file is closed.

SRTSEQ
Specifies the sort sequence used for this file. The sort sequence value is used with the LANGID parameter to determine which sort sequence table is used.

Note: Changing the value for this file causes the access paths that are owned by the file to be rebuilt.

*SAME: The value does not change.

*SRC: The table specified on the ALTSEQ keyword in the data description specification (DDS) is used. If the ALTSEQ keyword is not used in the DDS, this value defaults to the *JOB value on this parameter.

*JOB: The sort sequence value used is the value for the job issuing this command to change the physical file.

*LANGIDSHR: The sort sequence table uses the same weight for multiple characters, and is the shared-weight sort sequence table associated with the language specified on the LANGID parameter.

*LANGIDUNQ: The sort sequence table must contain a unique weight for each character in the code page.

*HEX: A sort sequence table is not used. The hexadecimal values of the characters are used to determine the sort sequence.

The name of the sort sequence table 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.

sort-sequence-table-name: Specify the name of the sort sequence table to use.

LANGID
Specifies the language identifier used when *LANGIDSHR or *LANGIDUNQ is specified on the SRTSEQ parameter. The language identifier is used with the SRTSEQ and CCSID parameters to determine which sort sequence table the file will use.

Note: Changing the value for this file causes the access paths that are owned by the file to be rebuilt unless the SRTSEQ attribute is *HEX.

*SAME: The value does not change.

*JOB: The language identifier specified in the job description is used.

language-identifier: Specify a language identifier.

REUSEDLT
Specifies whether the space made available by deleting data entries is reclaimed.

*SAME: The value does not change.

*NO: The file does not reclaim space made available by deleting data entries.

*YES: The file reclaims space made available by deleting data entries. More information about the algorithm used to reclaim the deleted data is in the Database Programming topic in the Information Center.

CCSID
Specifies the coded character set identifier (CCSID) being used to describe the character data in the fields of the file.

 

Notes

  1. If this parameter is specified, SRCFILE(*NONE) also must be specified.

  2. The CCSID cannot be changed if:

    • Any explicit field- or file-level CCSIDs are specified on the CCSID keyword in the DDS for fields in the physical file, the IDDU, or the SQL.

    • The physical file is a program-described file.

    • The physical file's format contains a concatenated field.

*SAME: The CCSID does not change.

*HEX: The CCSID 65535 is used, which indicates that the character data in the fields is treated as bit data and is not converted.

coded-character-set-identifier: Specify the CCSID being used.

If a DBCS field is in the physical file, the CCSID specified must have a corresponding mixed CCSID. More information on valid CCSIDs is in the Globalization topic in the Information Center.

LVLCHK
Specifies whether the record format level identifiers in the program are checked against those in the logical file when the file is opened. If so, the record format identifiers in the program must match those in the logical file. This value can be overridden by the Override with Database File (OVRDBF) command at run time.

*SAME: The value does not change.

*YES: The level identifiers of the record formats are checked when the file is opened. If the level identifiers do not match, an error message is sent to the program requesting the open operation, and the file is not opened.

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

NODGRP
Specifies the name of a node group across which the file is distributed.

*SAME: The value does not change.

*NONE: The file is not a distributed file. All data associated with the file is on the local system.

The name of the node group 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.

node-group-name: Specify the name of a node group associated with this file.

PTNKEY
Specifies the field, or set of fields, that is used as the partition key for distributing data.

*SAME: The value does not change.

Note: This parameter is not valid when NODGRP(*NONE) is specified. If a node group name is specified (NODGRP parameter), one or more field names must be specified.

partition-key-field-name: Specify the name of a field to be used to define the partition key.

TEXT
Specifies the text that briefly describes the physical file. More information is in Commonly used parameters.

*SAME: The value does not change.

*BLANK: Text is not specified.

'description': Specify no more than 50 characters of text, enclosed in apostrophes.

Examples for CHGPF

Example 1: Changing Expiration Date for All Members 

CHGPF   FILE(QGPL/INV)  EXPDATE('10/31/89')

This command changes the expiration date for all members in physical file INV to October 31, 1989.

Example 2: Changing File Size 

CHGPF   FILE(QGPL/DDMF)  SIZE(*NOMAX)  SYSTEM(*RMT)

This command changes the size of file INV located in the QGPL library on the remote system. Prior to specifying the above command, this user had created a DDM file by specifying the command CRTDDMF FILE(QGPL/DDMF) RMTFILE(QGPL/INV) RMTLOCNAME(AS400).

Example 3: Adding, Removing, and Changing Fields 

CHGPF   FILE(QGPL/T1)  SRCFILE(QDDSSRC)

This command adds fields, removes fields, and changes field attributes based on the DDS in the source file member T1 in the source file QDDSSRC. Prior to specifying the above command, the user had edited the source member.

Error messages for CHGPF

*ESCAPE Messages

CPF326A
Operation not successful for file &1 in library &2.
CPF327F
Operation not successful for file &1 in library &2.
CPF7304
File &1 in &2 not changed.
CPF7305
File &1 in &2 changed but distributed requests failed.