Change Authority (CHGAUT)

Where allowed to run: All environments (*ALL)
Threadsafe: Yes

The Change Authority (CHGAUT) command is used to change a user's authority for the object or group of objects named in this command. An object name pattern can be used to change authority for a group of related objects.

The CHGAUT command can also be used to change the authority of a directory tree where the directory, its contents, and the contents of all of its subdirectories are to have the authority changed. If SUBTREE(*ALL) is specified, this command will attempt to change the authority of all objects within the subtree. A diagnostic message will be sent for each object that could not have its authority changed and, when all of the objects have been attempted, an escape message will be sent. If all of the objects had their authority changed with no errors, a completion message will be sent.

If a symbolic link object is encountered, either specified in the Object (OBJ) parameter or encountered in the processing of a subtree, the value specified for the Symbolic link (SYMLNK) parameter will be applied to that symbolic link object. If processing a subtree, the processing of that branch of the subtree then stops because a symbolic link object itself cannot have subtrees.

Authority can be given to:

Named users
PUBLIC users who do not have authority specifically given to them either for the object or for the authorization list
The NetWare Inherited Rights Filter for the file (used only by the QNetWare file system)
Groups of users who do not have any authority to the object or are not on the authorization list that secures the object
Users on an established authorization list.

The AUTL value on the DTAAUT parameter specifies the authority for the following users:

Users who do not have authority specifically given to them for an object
Users who are not on the authorization list that secures the object
Users whose groups do not have authority specifically given to it
Users whose groups are not on the authorization list that secures the object.

DTAAUT(*AUTL) is allowed only with USER(*PUBLIC). User profiles cannot be secured by an authorization list.

See Appendix D of the System i Security Reference, SC41-5302 for the authorities needed to use this command.

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:

When doing subtree processing, you must also have read (*R) and execute (*X) authorities to the path name and all subdirectories within that path.
If changing authority for an object in the QSYS.LIB or independent ASP QSYS.LIB file system:
1. A user must either be the owner of the object or have all object (*ALLOBJ) special authority to use this command on an object.
2. This command must get an exclusive lock on a database file before read or object operational authority can be given to a user.
3. If a user requests authority for another specified user to a device currently in use by another authorized user, authority to the device is not given.
4. This command should not be used to change the authority for an authorization list object (/QSYS.LIB/authorization-list-name.AUTL).
5. DTAAUT(*AUTL) is valid only with USER(*PUBLIC).
6. Before you give authorities to use a device, controller, or line description, its associated device, controller, or line must be varied on.
7. For display stations or for work station message queues associated with the display station you can either: (1) enter this command at the device for which authorities are to be granted or (2) precede this command with the Allocate Object (ALCOBJ) command and follow this command with the Deallocate Object (DLCOBJ) command.

Top

Parameters

Keyword	Description	Choices	Notes
OBJ	Object	Path name	Required, Positional 1
USER	User	Single values: *PUBLIC Other values (up to 50 repetitions): Name	Optional, Positional 2
DTAAUT	New data authorities	SAME, NONE, RWX, RX, RW, WX, R, W, X, EXCLUDE, *AUTL	Optional, Positional 3
OBJAUT	New object authorities	Single values: SAME, NONE, ALL Other values (up to 4 repetitions): OBJEXIST, OBJMGT, OBJALTER, *OBJREF	Optional, Positional 4
AUTL	Authorization list	Name, *NONE	Optional
SUBTREE	Directory subtree	NONE, ALL	Optional
SYMLNK	Symbolic link	NO, YES	Optional

Top

Object (OBJ)

Specifies the object, or a pattern to match multiple objects, for which specific authorities are to be given to one or more users or to an authorization list.

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

This is a required parameter.

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.

path-name: Specify the path name of the objects for which specific authorities are to be 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.

Top

User (USER)

Specifies the users for whom authorities to the objects specified for the Object (OBJ) parameter are to be changed. If user names are specified, the authorities are changed specifically for those users.

Note: Either this parameter or the Authorization list (AUTL) parameter must be specified.

Single values

*PUBLIC: All users who do not have authority specifically given to them for the object, who are not on the authorization list, whose user group does not have any authority, or whose user group is not on the authorization list, are authorized to use the object as specified for the New data authorities (DTAAUT) and New object authorities (OBJAUT) parameters.

Other values (up to 50 repetitions)

name: Specify the user profile name of the user who you want to have specific authority for the object. Up to 50 user profile names can be specified.

Top

New data authorities (DTAAUT)

Specifies the data authorities to be given to the users specified for the User (USER) parameter. If a value other than *SAME is specified, the value replaces any data authorities that the users currently have to the objects.

*SAME: The users' data authorities to the objects do not change.
*NONE: The users do not have any of the data authorities to the objects.
*RWX: The users are given *RWX authority to the objects. The users are given *RWX authority to perform all operations on the object except those limited to the owner or controlled by object existence, object management, object alter, and object reference authority. The user can change the object and perform basic functions on the object. *RWX authority provides object operational authority and all the data authorities.
*RX: The users are given *RX authority to perform basic operations on the object, such as run a program or display the contents of a file. The user is prevented from changing the object. *RX authority provides object operational authority and read and execute authorities.
*RW: The users are given *RW authority to view the contents of an object and change the contents of an object. *RW authority provides object operational authority and data read, add, update, and delete authorities.
*WX: The users are given *WX authority to change the contents of an object and run a program or search a library or directory. *WX authority provides object operational authority and data add, update, delete, and execute authorities.
*R: The users are given *R authority to view the contents of an object. *R authority provides object operational authority and data read authority.
*W: The users are given *W authority to change the contents of an object. *W authority provides object operational authority and data add, update, and delete authorities.
*X: The users are given *X authority to run a program or search a library or directory. *X authority provides object operational authority and data execute authority.
*EXCLUDE: Exclude authority prevents the user from accessing the object.
*AUTL: The public authority of the authorization list specified in the AUTL parameter is used for the public authority for the object.

Top

New object authorities (OBJAUT)

Specifies the object authorities to be given to the users specified for the User (USER) parameter. If a value other than *SAME is specified, the value replaces any object authorities (*OBJEXIST, *OBJMGT, *OBJALTER, and *OBJREF) that the users currently have to the objects.

Single values

*SAME: The users' object authorities to the objects do not change.
*NONE: The users do not have any other object authorities (existence, management, alter, or reference). If *EXCLUDE or *AUTL is specified for the DTAAUT parameter, this value must be specified.
*ALL: All of the other object authorities (existence, management, alter, and reference) are given to the users.

Other values (up to 4 repetitions)

*OBJEXIST: The users are given object existence authority to the object.
*OBJMGT: The users are given object management authority to the object.
*OBJALTER: The users are given object alter authority to the object.
*OBJREF: The users are given object reference authority to the object.

Top

Authorization list (AUTL)

Specifies the authorization list whose users are to be given authority to the objects specified for the Object (OBJ) parameter.

Note: Either this parameter or the Users (USER) parameter must be specified. If this parameter is specified, the DTAAUT and OBJAUT parameters are ignored.

*NONE: The current authorization list is removed from the object.
name: Specify the name of the authorization list to be used to secure the object. If the object is currently secured by an authorization list, the specified authorization list will now be used to secure the object.

Top

Directory subtree (SUBTREE)

Specifies whether or not to change the objects within the subtree if the object specified by the Object (OBJ) parameter is a directory or a library.

*NONE

The objects specified by the OBJ parameter are changed. If the object is a directory or a library, it will be changed, but the directory or library contents will not be changed.

*ALL

The objects specified by the OBJ parameter are changed. If the object is a directory or a library, it will be changed as well as the contents of the directory or library and the contents of all subdirectories.

Note: Pattern matching from the OBJ parameter only applies to the first level objects. If the first level object is a directory or a library, the pattern matching does not apply to the directory or library contents or the contents of the subdirectories.

Note: This command may run a long time when SUBTREE(*ALL) is specified if there are many subdirectories to be processed.

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:

Adding, removing, or renaming object links
Mounting or unmounting file systems
Updating the effective root directory for the process calling the command
Updating the contents of a symbolic link

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

Symbolic link (SYMLNK)

If the object is a symbolic link, specifies whether or not to change the symbolic link or the object pointed to by the symbolic link.

*NO: The symbolic link object is not changed. The object pointed to by the symbolic link is changed.
*YES: If the object is a symbolic link, the symbolic link is changed. The object pointed to by the symbolic link is not changed.

Top

Examples

Example 1: Changing authority to all users

CHGAUT   OBJ('/QSYS.LIB/USERLIB.LIB/PROGRAM1.PGM')
         USER(*PUBLIC)  DTAAUT(*RW)

This command gives authority to use and change the object named PROGRAM1 to all users of the system who do not have authorities specifically given to them, who are not on an authorization list, whose user groups do not have authority to the object, or whose user groups are not on the authorization list. The object is a program (*PGM) located in the library named USERLIB. Because the OBJAUT parameter is not specified, any object authorities *PUBLIC already has remain.

Example 2: Changing authority to users on authorization List

CHGAUT   OBJ('/QSYS.LIB/MYLIB.LIB/PRGM3.PGM')  AUTL(KLIST)

This command gives to users the authority specified for them on authorization list KLIST for the object named PRGM3. The object is a program located in library MYLIB.

The following examples use the chart below:

*            sym1 (symbolic link to dir1)
*
*
*                       dir1
*                       * * *
*                     *   *   *
*                    *    *    *
*               dir2.1  dir2.2  dir2.3
*                  *      *       *
*                  *      *       *
*               dir3.1  dir3.2  sym3.3 (symbolic link to dirA)
*
*
*                       dirA
*                       * * *
*                     *   *   *
*                    *    *    *
*               dirB.1  dirB.2  dirB.3
*

**Example 3: Changing authority of a symbolic link when SYMLNK(*NO)**

CHGAUT   OBJ('/sym1')  USER(JOEUSER) DTAAUT(*RX)
                       SUBTREE(*ALL) SYMLNK(*NO)

This command will first determine if there are subtrees to process. Since the object specified in the OBJ parameter is a symbolic link, the SUBTREE parameter will be ignored because a symbolic link object does not have subtrees. Next, the object pointed to by symbolic link sym1 (dir1) will be changed because the SYMLNK parameter specifies that the symbolic link object not be changed.

In this example, JOEUSER's authority to dir1 is changed. It does not change JOEUSER's authority to the symbolic link object (sym1) and it does not change JOEUSER's authority to the contents of dir1.

**Example 4: Changing authority of a symbolic link when SYMLNK(*YES)**

CHGAUT   OBJ('/sym1')  USER(JOEUSER) DTAAUT(*R) OBJAUT(*OBJMGT)
                       SUBTREE(*ALL) SYMLNK(*YES)

This command will first determine if there are subtrees to process. Since the object specified in the OBJ parameter is a symbolic link, the SUBTREE parameter will be ignored because a symbolic link object does not have subtrees. Next, the symbolic link object (sym1) will be changed because the SYMLNK parameter specifies that the symbolic link object be changed.

In this example, JOEUSER's authority to sym1 is changed. It does not change JOEUSER's authority to the object pointed to by the symbolic link (dir1) and it does not change JOEUSER's authority to the contents of dir1.

**Example 5: Changing authority of a directory when SUBTREE(ALL) and SYMLNK(NO)**

CHGAUT   OBJ('/dir1')  USER(JOEUSER) DTAAUT(*R) OBJAUT(*OBJMGT)
                       SUBTREE(*ALL) SYMLNK(*NO)

This command will first determine if there are subtrees to process. Since the object specified in the OBJ parameter is a directory, the subtrees will be processed. When the processing of the tree encounters a *SYMLNK object, the value for the SYMLNK parameter will be applied to that *SYMLNK object. When the SYMLNK parameter is *NO, the object the symbolic link points to will be changed. The processing of that branch of the tree then stops because the *SYMLNK object itself does not have a subtree.

In this example, JOEUSER's authority to dir1, dir2.1, dir2.2, dir2.3, dir3.1, dir3.2, dirA is changed. It does not change JOEUSER's authority to sym3.3, dirB.1, dirB.2, dirB.3.

**Example 6: Changing authority of a directory when SUBTREE(ALL) and SYMLNK(YES)**

CHGAUT   OBJ('/dir1')  USER(JOEUSER) DTAAUT(*R) OBJAUT(*OBJMGT)
                       SUBTREE(*ALL) SYMLNK(*YES)

This command will first determine if there are subtrees to process. Since the object specified in the OBJ parameter is a directory, the subtrees will be processed. When the processing of the tree encounters a *SYMLNK object, the value for the SYMLNK parameter will be applied to the *SYMLNK object. When the SYMLNK parameter is *YES, the symbolic link object will be changed. The processing of that branch of the tree then stops because the *SYMLNK object itself does not have a subtree.

In this example, JOEUSER's authority to dir1, dir2.1, dir2.2, dir2.3, dir3.1, dir3.2, sym3.3 is changed. It does not change JOEUSER's authority to dirA, dirB.1, dirB.2, dirB.3.

**Example 7: Changing authority of a directory when SUBTREE(NONE) and SYMLNK(NO)**

CHGAUT   OBJ('/dir1')  USER(JOEUSER) DTAAUT(*R) OBJAUT(*OBJMGT)
                       SUBTREE(*NONE) SYMLNK(*NO)

This command will not process subtrees. Since the object specified in the OBJ parameter is not a symbolic link, the SYMLNK parameter will be ignored.

JOEUSER's authority to dir1 is changed.

NOTE:

The only way to change dirB.1, dirB.2, and dirB.3 is to specify them individually in the OBJ parameter of the change command, or to specify the change command with OBJ(dirA) and SUBTREE(*ALL).

Top

Error messages

*ESCAPE Messages

CPE3101: A non-recoverable I/O error occurred.
CPE3408: The address used for an argument was not correct.
CPE3418: Possible APAR condition or hardware failure.
CPE3474: Unknown system state.
CPFA0AA: Error occurred while attempting to obtain space.
CPFA0AB: Operation failed for object. Object is &1.
CPFA0AD: Function not supported by file system.
CPFA0A2: Information passed to this operation was not valid.
CPFA0A3: Path name resolution causes looping.
CPFA0A4: Too many open files for process.
CPFA0A7: Path name too long.
CPFA0A9: Object not found. Object is &1.
CPFA0B1: Requested operation not allowed. Access problem.
CPFA0C1: CCSID &1 not valid.
CPFA0DD: Function was interrupted.
CPFA0D4: File system error occurred. Error number &1.
CPFA08B: Path name cannot begin with *.
CPFA08C: Pattern not allowed in path name directory.
CPFA085: Home directory not found for user &1.
CPFA086: Matching quote not found in path name.
CPFA087: Path name contains null character.
CPFA088: Path name pattern not valid.
CPFA089: Pattern not allowed in path name.
CPFA09C: Not authorized to object. Object is &1.
CPFA09D: Error occurred in program &1.
CPFA09E: Object in use. Object is &1.
CPFA091: Pattern not allowed in user name.
CPFA092: Path name not converted.
CPFA094: Path name not specified.
CPFBC50: Path name or path names not found.
CPF22F0: Unexpected errors occurred during processing.
CPF223A: &1 objects changed, &2 objects not changed.
CPF2283: Authorization list &1 does not exist.
CPF3BF6: Path Type value is not valid.

Top

Change Authority (CHGAUT)

Restrictions:

Parameters

Object (OBJ)

User (USER)

Single values

Other values (up to 50 repetitions)

New data authorities (DTAAUT)

New object authorities (OBJAUT)

Single values

Other values (up to 4 repetitions)

Authorization list (AUTL)

Directory subtree (SUBTREE)

Symbolic link (SYMLNK)

Examples

Example 1: Changing authority to all users

Example 2: Changing authority to users on authorization List

The following examples use the chart below:

Example 3: Changing authority of a symbolic link when SYMLNK(*NO)

Example 4: Changing authority of a symbolic link when SYMLNK(*YES)

Example 5: Changing authority of a directory when SUBTREE(*ALL) and SYMLNK(*NO)

Example 6: Changing authority of a directory when SUBTREE(*ALL) and SYMLNK(*YES)

Example 7: Changing authority of a directory when SUBTREE(*NONE) and SYMLNK(*NO)

NOTE:

Error messages

**Example 3: Changing authority of a symbolic link when SYMLNK(*NO)**

**Example 4: Changing authority of a symbolic link when SYMLNK(*YES)**

**Example 5: Changing authority of a directory when SUBTREE(ALL) and SYMLNK(NO)**

**Example 6: Changing authority of a directory when SUBTREE(ALL) and SYMLNK(YES)**

**Example 7: Changing authority of a directory when SUBTREE(NONE) and SYMLNK(NO)**