Where allowed to run: All environments (*ALL) Threadsafe: Conditional |
Parameters Examples Error messages |
The Change Attribute (CHGATR) command allows a single attribute to be changed for a single object or a group of objects. An object name pattern can be used to change a single attribute for a group of related objects.
The CHGATR command can also be used to change an attribute of a directory tree where the specified directory, its contents, and the contents of all of its subdirectories have the attribute changed. If SUBTREE(*ALL) is specifed, the command will attempt to change the attribute for as many objects as possible within the subtree. A diagnostic message will be sent for each object that could not have its attribute changed. When all of the objects have been attempted, an escape message will be sent if there were any errors. If all of the objects had the attribute changed with no errors, then a completion message will be sent.
For more information about integrated file system commands, see the Integrated file system topic collection in the IBM i Information Center at http://www.ibm.com/systems/i/infocenter/.
Restrictions:
This command is not threadsafe if the object on which this function is operating resides in a file system that is not threadsafe. Only the following file systems are threadsafe for this function:
"Root" (/), QOpenSys, and User-Defined File System Differences
QSYS.LIB and Independent ASP QSYS.LIB File System Differences
When the *USECOUNT attribute of a database file is set, all members in that file will have their days used count reset to 0 also.
Network File System Differences
The *USECOUNT, *CCSID, *ALWSAV, *ALWCKPWRT, *DISKSTGOPT, *MAINSTGOPT, *CRTOBJAUD attributes cannot be set on objects within the Network File System or they will result in the operation failing.
QOPT File System Differences
QDLS File System Differences:
Attempting to set any other attribute other than the *SETUID or *SETGID attributes will result in the operation failing.
QFileSvr.400 Differences
Note: The QSECOFR user profiles on the source and target system must be enabled, and their passwords must match for the *CRTOBJAUD attribute change to succeed.
Attempting to set any other attribute other than the *SETUID, *SETGID, and *RSTDRNMUNL attributes will result in the operation failing.
QNTC Differences
Attempting to set any other attribute other than the *SETUID or *SETGID attributes will result in the operation failing.
Top |
Keyword | Description | Choices | Notes |
---|---|---|---|
OBJ | Object | Path name | Required, Positional 1 |
ATR | Attribute | *READONLY, *HIDDEN, *PCSYSTEM, *PCARCHIVE, *SYSARCHIVE, *CCSID, *ALWCKPWRT, *USECOUNT, *DISKSTGOPT, *MAINSTGOPT, *CRTOBJSCAN, *SCAN, *ALWSAV, *RSTDRNMUNL, *SETUID, *SETGID, *CRTOBJAUD | Required, Positional 2 |
VALUE | New value | 1-65533, *YES, *NO, *RESET, *NORMAL, *MINIMIZE, *DYNAMIC, *CHGONLY, *SYSVAL, *NONE, *USRPRF, *ALL, *CHANGE | Required, Positional 3 |
SUBTREE | Directory subtree | *NONE, *ALL | Optional |
SYMLNK | Symbolic link | *NO, *YES | Optional |
Top |
Specifies the path name of the object or a pattern to match the name of the objects to have the attribute changed. The object path name can be either a simple name or a name that is qualified with the name of the directory in which the object is located. A pattern can be specified in the last part of the path name. An asterisk (*) matches any number of characters and a question mark (?) matches a single character. If the path name is qualified or contains a pattern, it must be enclosed in apostrophes.
For more information on specifying path names, refer to "Object naming rules" in the CL topic collection in the Programming category in the IBM i Information Center at http://www.ibm.com/systems/i/infocenter/.
Note: This parameter is Unicode-enabled. See "Unicode support in CL" in the CL topic collection in the Programming category in the IBM i Information Center at http://www.ibm.com/systems/i/infocenter/ for additional information.
Top |
Specifies the attribute to be changed.
Allowed values for the New value (VALUE) parameter are:
Allowed values for the VALUE parameter are:
Allowed values for the VALUE parameter are:
Allowed values for the VALUE parameter are:
Allowed values for the VALUE parameter are:
Note: Changing the CCSID does not convert the data or the extended attributes. Changing the CCSID only changes the value associated with the object. This also applies to the data contained in the extended attributes associated with the object.
Allowed values for the VALUE parameter are:
Allowed values for the VALUE parameter are:
Allowed value for the VALUE parameter is:
Allowed values for the VALUE parameter are:
Allowed values for the VALUE parameter are:
The integrated file system scan-related exit points are:
For details on these exit points, see the APIs topic collection in the Programming category in the IBM i Information Center at http://www.ibm.com/systems/i/infocenter/.
This option can only be specified for directories in the "root" (/), QOpenSys and user-defined file systems. Even though this attribute can be set for *TYPE1 and *TYPE2 directories, only objects which are in *TYPE2 directories will actually be scanned, no matter what value is set for this attribute.
Allowed values for the VALUE parameter are:
Note: If the Scan file systems control (QSCANFSCTL) value *NOPOSTRST is not specified when an object with this attribute is restored, the object will be scanned at least once after the restore.
Note: If the Scan file systems control (QSCANFSCTL) value *NOPOSTRST is not specified when an object with this attribute is restored, the object will be scanned at least once after the restore.
The integrated file system scan-related exit points are:
For details on these exit points, see the APIs topic collection in the Programming category in the IBM i Information Center at http://www.ibm.com/systems/i/infocenter/.
This option can only be specified for stream files in the "root" (/), QOpenSys, and user-defined file systems that are not virtual volumes or network server storage spaces. Even though this attribute can be set for *TYPE1 and *TYPE2 directories, only objects which are in *TYPE2 directories will actually be scanned, no matter what value is set for this attribute.
Allowed values for the VALUE parameter are:
Note: If the Scan file systems control (QSCANFSCTL) value *NOPOSTRST is not specified when an object with this attribute is restored, the object will be scanned at least once after the restore.
Note: If the Scan file systems control (QSCANFSCTL) value *NOPOSTRST is not specified when an object with this attribute is restored, the object will be scanned at least once after the restore.
Note: It is highly recommended that this attribute not be changed for any system created objects.
Allowed values for the VALUE parameter are:
Additionally, if this object is a directory, none of the objects in the directory's subtree will be saved unless they were explicitly specified as an object to be saved. The subtree includes all subdirectories and the objects within those subdirectories.
Note: If this attribute is chosen for an object that has private authorities associated with it, or is chosen for the directory of an object that has private authorities associated with it, then the following consideration applies. When the private authorities are saved, the fact that an object has the *ALWSAV attribute as No is not taken into consideration. (Private authorities can be saved using either the Save System (SAVSYS) or Save Security Data (SAVSECDTA) command or the Save Object List (QSRSAVO) API.) Therefore, when a private authority is restored using the Restore Authority (RSTAUT) command, message CPD3776 will be seen for each object that was not saved either because it had the *ALWSAV attribute specified as No, or because the object was not specified on the save and it was in a directory that had the *ALWSAV attribute specified as No.
This restriction only applies to directories. Other types of object can have this attribute set on, however, it will be ignored. In addition, this attribute can only be specified for objects within the Network File System (NFS), QFileSvr.400, "root" (/), QOpenSys, or user-defined file systems. Both the NFS and QFileSvr.400 file systems support this attribute by passing it to the server and surfacing it to the caller. This attribute is also equivalent to the S_ISVTX mode bit for an object.
Allowed values for the VALUE parameter are:
Allowed values for the VALUE parameter are:
Allowed values for the VALUE parameter are:
This attribute can only be specified for directories in the "root" (/), QOpenSys, QSYS.LIB, independent ASP QSYS.LIB, QFileSvr.400 and user-defined file systems.
Allowed values for the VALUE parameter are:
Top |
The value used to change the attribute for the specified objects.
Top |
Specifies whether or not to change the specified attribute of the objects within the subtree if the object specified by the Object (OBJ) parameter is a directory.
Note: Pattern matching on the OBJ parameter only applies to the first level objects. If the first level object is a directory, the pattern matching does not apply to its contents or the contents of its subdirectories.
Once the command has begun processing a specific directory subtree, the objects which will be found and processed may be affected by operations that update the organization of objects within the specified directory tree. This includes, but is not limited to, the following:
In order to process the directory subtree, the system code may increase the process-scoped maximum number of file descriptors that can be opened during processing. This is done so that the command is not likely to fail due to a lack of descriptors. This process-scoped maximum value is not reset when the command completes.
Top |
If the last component in the path name is a symbolic link, specifies whether or not to change the attribute of the symbolic link or of the object pointed to by the symbolic link.
Top |
Example 1: Change Attribute for a Directory Subtree
CHGATR OBJ('/MYINFO') ATR(*HIDDEN) VALUE(*YES) SUBTREE(*ALL)
The object MYINFO will have its *HIDDEN attribute changed so it is a hidden object. If MYINFO is a directory, then all of the objects this directory contains as well as all of the objects contained in the subdirectories will have their PC hidden attribute changed because *ALL is specified for the SUBTREE parameter.
Top |
*ESCAPE Messages
Top |