Change Authority (CHGAUT)

Change Authority (CHGAUT)

Where allowed to run: All environments (*ALL)
Threadsafe: Yes Parameters
Examples
Error messages

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 iSeries 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 information in the iSeries Information Center at http://www.ibm.com/eserver/iseries/infocenter.
Restrictions:

When doing subtree processing, 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:

A user must either be the owner of the object or have all object (*ALLOBJ) special authority to use this command on an object.
This command must get an exclusive lock on a database file before read or object operational authority can be given to a user.
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.
This command should not be used to change the authority for an authorization list object (/QSYS.LIB/authorization-list-name.AUTL).
DTAAUT(*AUTL) is valid only with USER(*PUBLIC).
Before you give authorities to use a device, controller, or line description, its associated device, controller, or line must be varied on.
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, *NTWIRF
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 concepts and reference topic in the iSeries Information Center at http://www.ibm.com/eserver/iseries/infocenter.
This is a required parameter.

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.

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.

*NTWIRF

The NetWare Inherited Rights Filter for the file is authorized to use the object as specified in the DTAAUT and OBJAUT parameters. This value is used only by the QNetWare file system.

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.

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.

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.

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

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.

CPF223A

&1 objects changed, &2 objects not changed.

CPF22F0

Unexpected errors occurred during processing.

CPF3BF6

Path Type value is not valid.

Top

Keyword	Description	Choices	Notes
OBJ	Object	Path name	Required, Positional 1
USER	User	Single values: PUBLIC, NTWIRF 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