CHGSRCPF (Change Source Physical File)

CHGSRCPF Command syntax diagram

 

Purpose

The Change Source Physical File (CHGSRCPF) command changes the attributes of a source physical file and its members. The changed attributes are also used for all members subsequently added to the file.

 

Restrictions

1. To change a source physical file, the user must have object management authority or object alter authority for the file and execute authority to the library.
   
2. For the user to change the file, an exclusive lock is necessary; no one may be using the file for any purpose.

 

Required Parameters

FILE

Specifies the qualified name of the source physical file that is changed.

The name of the source physical 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-physical-file-name: Specify the name of the source physical file being changed.

Note:

If a DDM file is specified, the source 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.

 

Optional Parameters

SYSTEM

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

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

*RMT: The source physical file is changed on a remote system using DDM. The source 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 source 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 source 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 source physical file.

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. The date must be specified in the format defined by the job attributes, QDATFMT and QDATSEP, and must be enclosed in apostrophes, if special characters are used in the format.

*SAME: The expiration date of the file 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 value for 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 access paths that are associated with keyed source physical files. This parameter does not apply to access paths that are created for logical files or for queries that refer to the data in a source physical file.

Performance Tip	For optimum performance, consider whether there is high contention for keys within the access path 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.

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

MAINT

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

*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 during the running of the program. The access path is continuously maintained until the member is closed; then the access path maintenance is ended.

*DLY: The maintenance of the access path is delayed until the member is opened for use. Then 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 MAINT.) 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 and the next open are small (when key fields in records for this access path change infrequently).

If the number of changes saved 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.

The access path having immediate or delayed maintenance is rebuilt during initial program load (IPL) (before any user can run a job), after the IPL is completed (while other jobs are running), or the next time the file is opened. While the access path is being rebuilt, the file cannot be used by any job.

During the IPL, an Override Access Path Recovery display will list 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 in the Backup and recovery topic in the Information Center.

The 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 the next time the file is opened.

*AFTIPL: The access path of the file is rebuilt after the IPL operation is completed. This option allows other jobs not using this file to start 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 access path of the file is 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 can 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 changes.

*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 can be 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 added for each increment, or to the number of times an increment can be automatically applied, takes effect the next time a member of the file needs an increment.

The total size of the member (initial number of records plus the product of 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, an error message is issued, 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 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 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

The force write ratio parameter specifies the number of inserted, updated, or deleted records that are processed before they are forced to auxiliary (permanent) storage. More information on this parameter is in Commonly used parameters.

If the physical file is being journaled, 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 on this parameter 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 source 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) when the file is closed.

CCSID

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

Note:

The CCSID cannot be changed if: There are any logical files defined over the source physical file. Any explicit field- or file-level CCSIDs are specified on the CCSID keyword in DDS, or on the CCSID parameter of the CRTSRCPF and CRTPF commands, for fields in the physical file. Another file shares the physical file's format.

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

TEXT

Specifies the text that briefly describes the source physical file. More information on this parameter 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 CHGSRCPF

Example 1: Changing the Expiration Date

CHGSRCPF   FILE(QGPL/INV)  EXPDATE('10/31/88')

This command changes the expiration date of all members in file INV to October 31, 1988.

Example 2: Changing Text

CHGSRCF  FILE(QGPL/DDMF)  TEXT('Inventory File')
  SYSTEM(*RMT)

This command changes the text 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).

Error messages for CHGSRCPF

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