Change Primary Group (CHGPGP)

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

Parameters Examples Error messages

The Change Primary Group (CHGPGP) command changes the primary group of an object or group of objects from one user to another. An object name pattern can be used to change authority for a group of related objects. The owner's and other user's private authorities to the object do not change.

The CHGPGP command can also be used to change the primary group of a directory tree where the directory, its contents, and the contents of all of its subdirectories are to have the primary group changed. If SUBTREE(*ALL) is specified, this command will attempt to change the primary group of all objects within the subtree. A diagnostic message will be sent for each object that could not have its primary group changed, and when all of the objects have been attempted, an escape message will be sent. If all of the objects had their primary group 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.

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:

• To change the primary group of an object in the QSYS.LIB or independent ASP QSYS.LIB file system, have all of the following:

  • Object existence (*OBJEXIST) authority for the object

  • Object operational (*OBJOPR) and *OBJEXIST authorities if the object is a file, library, or subsystem description

  • All object (*ALLOBJ) special authority, or ownership, if the object is an authorization list

  • Object management (*OBJMGT) authority, and the authorities to be revoked, for the object if revoking the authority for the old primary group

  • *OBJMGT authority for the object and the authorities to be given if a value other than *PRIVATE is specified for the DTAAUT parameter

• The new primary group user cannot be the owner of the object.

• When doing subtree processing, have read (*R) and execute (*X) authorities to the path name and all subdirectories within that path.

Top

---

 

Parameters

Keyword	Description	Choices	Notes
OBJ	Object	Path name	Required, Positional 1
NEWPGP	New primary group	Name, *NONE	Required, Positional 2
DTAAUT	New data authorities	*OLDPGP, *PRIVATE, *RWX, *RX, *RW, *WX, *R, *W, *X, *EXCLUDE, *NONE	Optional
OBJAUT	New object authorities	Single values: *NONE, *ALL Other values (up to 4 repetitions): *OBJEXIST, *OBJMGT, *OBJALTER, *OBJREF	Optional
RVKOLDAUT	Revoke current authority	*NO, *YES	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 the primary group is to be changed.

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 whose primary group is 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

 

New primary group (NEWPGP)

Specifies the user who is to be the new primary group for the object. The user profile must already exist when this command is run, and must have a group identifier (or gid) assigned to it.

This is a required parameter.

*NONE

The object does not have a primary group.

name

Specify the name of the user profile who is to be the new primary group for the object.

Top

 

New data authorities (DTAAUT)

Specifies which of the data authorities the new primary group has to the object.

*OLDPGP

The new primary group has whatever authority the old primary group had to the object.

*PRIVATE

The new primary group has the private authority that the user has to the object. If the user that is the new primary group does not have private authority to the object, the new primary group has no authority to the object.

*RWX

The new primary group has object operational and all of the data authorities to the object.

*RX

The new primary group has object operational and data read and execute authorities to the object.

*RW

The new primary group has object operational and data read, add, update, and delete authorities to the object.

*WX

The new primary group has object operational and data add, update, delete, and execute authorities to the object.

*R

The new primary group has object operational and data read authorities to the object.

*W

The new primary group has object operational and data add, update, and delete authorities to the object.

*X

The new primary group has object operational and data execute authorities to the object.

*EXCLUDE

The new primary group has exclude authority to the object.

*NONE

The new primary group does not have any of the data authorities to the object.

Top

 

New object authorities (OBJAUT)

Specifies which of the object authorities the new primary group has to the object.

Single values

*NONE

None of the other object authorities (existence, management, alter, or reference) are given to the new primary group. If *OLDPGP, *PRIVATE, or *EXCLUDE are 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 new primary group.

Other values (up to 4 repetitions)

*OBJEXIST

The new primary group has object existence authority to the object.

*OBJMGT

The new primary group has object management authority to the object.

*OBJALTER

The new primary group has object alter authority to the object.

*OBJREF

The new primary group has object reference authority to the object.

Top

 

Revoke current authority (RVKOLDAUT)

Specifies whether the authorities for the current primary group are revoked when the primary group is changed to the user specified for the New primary group (NEWPGP) parameter.

*YES

The authorities for the current primary group are revoked when the primary group is changed to the other user.

*NO

The authorities for the current primary group become a private authority when the primary group is changed to the other user.

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 the primary group of a program

 CHGPGP   OBJ('/QSYS.LIB/USERLIB.LIB/PROGRAM1.PGM')  NEWPGP(ANN)

This command changes the primary group of the program named PROGRAM1, located in the user library named USERLIB, to the group named ANN. The new primary group will have the same authority as the old primary group. The old primary group's authority is revoked.

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 2: Changing the primary group of a symbolic link when SYMLNK(*NO)

 CHGPGP   OBJ('/sym1')  NEWPGP(SAM) 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, the primary group of dir1 is changed to SAM and he will have the same authority as the old primary group. The old primary group's authority is revoked. It does not change the primary group of the symbolic link object (sym1) and it does not change the primary group of the contents of dir1.

Example 3: Changing the primary group of a symbolic link when SYMLNK(*YES)

 CHGPGP   OBJ('/sym1')  NEWPGP(JOE) 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, the primary group of sym1 is changed to JOE and he will have the same authority as the old primary group. The old primary group's authority is revoked. It does not change the primary group of the object pointed to by the symbolic link (dir1) and it does not change the primary group of the contents of dir1.

Example 4: Changing the primary group of a directory when SUBTREE(*ALL) and SYMLNK(*NO)

 CHGPGP   OBJ('/dir1')  NEWPGP(PETE)  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, the primary group of dir1, dir2.1, dir2.2, dir2.3, dir3.1, dir3.2, dirA is changed to PETE and he will have the same authority as the old primary group. The old primary group's authority is revoked. The primary group of sym3.3, dirB.1, dirB.2, dirB.3 is not changed.

Example 5: Changing the primary group of a directory when SUBTREE(*ALL) and SYMLNK(*YES)

 CHGPGP   OBJ('/dir1')  NEWPGP(GEORGE)  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, the primary group of dir1, dir2.1, dir2.2, dir2.3, dir3.1, dir3.2, sym3.3 is changed to GEORGE and he will have the same authority as the old primary group. The old primary group's authority is revoked. The primary group of dirA, dirB.1, dirB.2, dirB.3 is not changed.

Example 6: Changing the primary group of a directory when SUBTREE(*NONE) and SYMLNK(*NO)

 CHGPGP   OBJ('/dir1')  NEWPGP(BETTY)  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.

The primary group of dir1 is changed to BETTY. The old primary group's authority is revoked.

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

No objects satisfy request.

CPFA0C1

CCSID &1 not valid.

CPFA0CE

Error occurred with path name parameter specified.

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.

CPF220B

New primary group &1 does not have a gid.

CPF2204

User profile &1 not found.

CPF2213

Not able to allocate user profile &1.

CPF2217

Not authorized to user profile &1.

CPF223A

&1 objects changed, &2 objects not changed.

CPF22F0

Unexpected errors occurred during processing.

CPF3BF6

Path Type value is not valid.

Top