Grant Object Authority (GRTOBJAUT)

The Grant Object Authority (GRTOBJAUT) command grants specific authority for the objects named in the command to another user or group of users.

Authority can be given to:

If AUT(*AUTL) is specified, the PUBLIC authority for the object comes from the PUBLIC authority of the authorization list securing the object.

The AUTL parameter is used to secure an object with an authorization list or remove an authorization list from an object. User profiles cannot be secured by an authorization list (*AUTL).

This command can be used by:

A user authorized to the Database Security Administrator function of IBM i (QIBM_DB_SECADM) has the authority to authorize other users to any object in the QSYS.lib file system. In addition, this user can assign an authorization list to an object. However, the users authorized to the QIBM_DB_SECADM function cannot grant authority to themselves unless they have the authorities required for the operation (ownership, *ALLOBJ or *OBJMGT and the authorities being granted).

Note: This user can grant authority to *PUBLIC or to a GROUP profile. It is recommended that a user authorized to the QIBM_DB_SECADM function not be a member of a group profile. Auditing of the actions of this privileged user is also recommended.

Only the owner of the object, or someone with all object special authority (*ALLOBJ), can grant object management authority to a user.

A user with *ALL authority can assign a new authorization list.

When granting authority to users, the REPLACE parameter indicates whether the authorities you specify replace the user's existing authorities. The default value of REPLACE(*NO) gives the authority that you specify, but it does not remove any authority that is greater than you specified, unless you are granting *EXCLUDE authority. REPLACE(*YES) removes the user's current authorities, then grants the authority that you specify.

When granting authority with a reference object, this command gives the authority that you specify, but it does not remove any authority that is greater than you specified, unless you are granting *EXCLUDE authority.

This command gives the authority that you specify, but it does not remove any authority that is greater than you specified, unless you are granting *EXCLUDE authority or specify REPLACE(*YES).

Restrictions:

  1. This command must get an exclusive lock on a database file before read or object operational authority can be given to a user.
  2. 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.
  3. Object type *AUTL cannot be specified.
  4. AUT(*AUTL) is valid only with USER(*PUBLIC).
  5. A user must either be the owner of the object or have *ALL authority to use the AUTL parameter.
  6. The user must have object management authority to the object.
  7. If the object is a file, the user must have object operational and object management authorities.
  8. For display stations or for work station message queues associated with the display station, if this command is not entered at the device for which authorities are to be granted, it should be preceded by the Allocate Object (ALCOBJ) command and followed by the Deallocate Object (DLCOBJ) command.
  9. You must have *USE authority to the auxiliary storage pool device if one is specified.

Note: Caution should be used when changing the public authority on IBM-supplied objects. For example, changing the public authority on the QSYSOPR message queue to be more restrictive than *CHANGE will cause some system programs to fail. The system programs will not have enough authority to send messages to the QSYSOPR message queue. For more information, refer to the System i Security Reference, SC41-5302 book.

Parameters

Keyword Description Choices Notes
OBJ Object Qualified object name Required, Positional 1
Qualifier 1: Object Generic name, name, *ALL
Qualifier 2: Library Name, *LIBL, *CURLIB, *ALL, *ALLUSR, *USRLIBL, *ALLAVL, *ALLUSRAVL
OBJTYPE Object type *ALL, *ALRTBL, *BNDDIR, *CFGL, *CHTFMT, *CLD, *CLS, *CMD, *CNNL, *COSD, *CRG, *CRQD, *CSI, *CSPMAP, *CSPTBL, *CTLD, *DEVD, *DTAARA, *DTADCT, *DTAQ, *EDTD, *FCT, *FILE, *FNTRSC, *FNTTBL, *FORMDF, *FTR, *GSS, *IGCDCT, *IGCSRT, *IGCTBL, *IMGCLG, *IPXD, *JOBD, *JOBQ, *JOBSCD, *JRN, *JRNRCV, *LIB, *LIND, *LOCALE, *M36, *M36CFG, *MEDDFN, *MENU, *MGTCOL, *MODD, *MODULE, *MSGF, *MSGQ, *NODGRP, *NODL, *NTBD, *NWID, *NWSCFG, *NWSD, *OUTQ, *OVL, *PAGDFN, *PAGSEG, *PDFMAP, *PDG, *PGM, *PNLGRP, *PRDAVL, *PRDDFN, *PRDLOD, *PSFCFG, *QMFORM, *QMQRY, *QRYDFN, *RCT, *S36, *SBSD, *SCHIDX, *SPADCT, *SQLPKG, *SQLUDT, *SQLXSR, *SRVPGM, *SSND, *SVRSTG, *TBL, *TIMZON, *USRIDX, *USRPRF, *USRQ, *USRSPC, *VLDL, *WSCST Required, Positional 2
ASPDEV ASP device Name, *, *SYSBAS Optional
USER Users Single values: *PUBLIC
Other values (up to 50 repetitions): Name
Optional, Positional 3
AUT Authority Single values: *CHANGE, *ALL, *USE, *EXCLUDE, *AUTL
Other values (up to 10 repetitions): *OBJALTER, *OBJEXIST, *OBJMGT, *OBJOPR, *OBJREF, *ADD, *DLT, *READ, *UPD, *EXECUTE
Optional, Positional 4
AUTL Authorization list Name, *NONE Optional
REFOBJ Reference object Qualified object name Optional
Qualifier 1: Reference object Name
Qualifier 2: Library Name, *LIBL, *CURLIB
REFOBJTYPE Reference object type *OBJTYPE, *ALRTBL, *BNDDIR, *AUTL, *CFGL, *CHTFMT, *CLD, *CLS, *CMD, *CNNL, *COSD, *CRG, *CRQD, *CSI, *CSPMAP, *CSPTBL, *CTLD, *DEVD, *DTAARA, *DTADCT, *DTAQ, *EDTD, *FCT, *FILE, *FNTRSC, *FNTTBL, *FORMDF, *FTR, *GSS, *IGCDCT, *IGCSRT, *IGCTBL, *IMGCLG, *IPXD, *JOBD, *JOBQ, *JOBSCD, *JRN, *JRNRCV, *LIB, *LIND, *LOCALE, *M36, *M36CFG, *MEDDFN, *MENU, *MGTCOL, *MODD, *MODULE, *MSGF, *MSGQ, *NODGRP, *NODL, *NTBD, *NWID, *NWSCFG, *NWSD, *OUTQ, *OVL, *PAGDFN, *PAGSEG, *PDFMAP, *PDG, *PGM, *PNLGRP, *PRDDFN, *PRDLOD, *PSFCFG, *QMFORM, *QMQRY, *QRYDFN, *RCT, *S36, *SBSD, *SCHIDX, *SPADCT, *SQLPKG, *SQLUDT, *SQLXSR, *SRVPGM, *SSND, *SVRSTG, *TBL, *TIMZON, *USRIDX, *USRPRF, *USRQ, *USRSPC, *VLDL, *WSCST Optional
REFASPDEV Reference ASP device Name, *, *SYSBAS Optional
REPLACE Replace authority *NO, *YES Optional

Object (OBJ)

Specifies the objects for which specific authority is to be given to one or more users.

This is a required parameter.

Qualifier 1: Object

*ALL
Specific authority is to be given to all objects of the specified object type (OBJTYPE parameter). A specific library name must be specified for the library qualifier when *ALL is specified.
generic-name
Specify the generic name of the objects for which specific authority is to be given to one or more users. A generic name is a character string that contains one or more characters followed by an asterisk (*). If a generic name is specified, all objects that have names with the same prefix as the generic name are shown.
name
Specify the name of the object for which specific authority is to be given to one or more users.

Qualifier 2: Library

*LIBL
All libraries in the library list for the current thread are searched until the first match is found.
*CURLIB
The current library for the thread is searched. If no library is specified as the current library for the thread, the QGPL library is searched. If the ASP device (ASPDEV) parameter is specified when this value is used, ASPDEV(*) is the only valid value.
*USRLIBL
If a current library entry exists in the library list for the current thread, the current library and the libraries in the user portion of the library list are searched. If there is no current library entry, only the libraries in the user portion of the library list are searched. If the ASP device (ASPDEV) parameter is specified when this value is used, ASPDEV(*) is the only valid value.
*ALL
All the libraries in the auxiliary storage pools (ASPs) specified for the ASP device (ASPDEV) parameter are searched.
*ALLUSR
All user libraries in the auxiliary storage pools (ASPs) defined by the ASP device (ASPDEV) parameter are searched.

User libraries are all libraries with names that do not begin with the letter Q except for the following:

#CGULIB     #DSULIB     #SEULIB
#COBLIB     #RPGLIB
#DFULIB     #SDALIB

Although the following libraries with names that begin with the letter Q are provided by IBM, they typically contain user data that changes frequently. Therefore, these libraries are also considered user libraries:

QDSNX       QRCLxxxxx   QUSRDIRDB   QUSRVI
QGPL        QSRVAGT     QUSRIJS     QUSRVxRxMx
Start of changeQGPL38      QSYS2       QUSRINFSKR  QWQCENT
QMGTC       QSYS2xxxxx  QUSRNOTES   QWQREPOSEnd of change
QMGTC2      QS36F       QUSROND
QMPGDATA    QUSER38     QUSRPOSGS
QMQMDATA    QUSRADSM    QUSRPOSSA
QMQMPROC    QUSRBRM     QUSRPYMSVR
QPFRDATA    QUSRDIRCF   QUSRRDARS
QRCL        QUSRDIRCL   QUSRSYS

  1. 'xxxxx' is the number of a primary auxiliary storage pool (ASP).
  2. A different library name, in the format QUSRVxRxMx, can be created by the user for each previous release supported by IBM to contain any user commands to be compiled in a CL program for the previous release. For the QUSRVxRxMx user library, VxRxMx is the version, release, and modification level of a previous release that IBM continues to support.
*ALLAVL
All libraries in all available ASPs are searched.
*ALLUSRAVL
All user libraries in all available ASPs are searched. Refer to *ALLUSR for a definition of user libraries.
name
Specify the name of the library to be searched.

Object type (OBJTYPE)

Specifies the object type of the object for which specific authorities are to be given to the specified users or to an authorization list. For a complete list of supported object types when prompting this command, position the cursor on the field for this parameter and press F4 (Prompt).

This is a required parameter.

*ALL
Specific authorities for all supported object types are given to the specified users or to the authorization list.
object-type
Specify the object type of the object for which specific authorities are to be given to the specified users.

ASP device (ASPDEV)

Specifies the auxiliary storage pool (ASP) device name where the library that contains the object (OBJ parameter) is located. If the object's library resides in an ASP that is not part of the library name space associated with the job, this parameter must be specified to ensure the correct object is used as the target of this command's operation.

*
The ASPs that are currently part of the job's library name space will be searched to locate the object. This includes the system ASP (ASP number 1), all defined basic user ASPs (ASP numbers 2-32), and, if the job has an ASP group, all independent ASPs in the ASP group.
*SYSBAS
The system ASP and all basic user ASPs will be searched to locate the object. No independent ASPs will be searched, even if the job has an ASP group.
name
Specify the device name of the independent ASP to be searched to locate the object. The independent ASP must have been activated (by varying on the ASP device) and have a status of AVAILABLE. The system ASP and basic user ASPs will not be searched.

Users (USER)

Specifies one or more users to whom authority for the named object is to be given.

This is a required parameter unless either the Reference object (REFOBJ) parameter or Authorization list (AUTL) parameter is specified.

*PUBLIC
Users are authorized to use the object as specified in the AUT parameter when they do not have authority specifically given to them for the object, are not on the authorization list and none of their groups have any authority or are on the authorization list. Users who do not have any authority, and whose groups do not have any authority, are authorized to use the object as specified in the AUT parameter.
name
Specify the names of one or more users to be given specific authority for the object. Up to 50 user profile names can be specified.

Authority (AUT)

Specifies the authority to be given to the users specified for the Users (USER) parameter.

If a value is specified for this parameter, you cannot specify a value for the AUTL, REFOBJ, or REFOBJTYPE parameters.

Single values

*CHANGE
The user can perform all operations on the object except those limited to the owner or controlled by object existence (*OBJEXIST) and object management (*OBJMGT) authorities. The user can change and perform basic functions on the object. *CHANGE authority provides object operational (*OBJOPR) authority and all data authority. If the object is an authorization list, the user cannot add, change, or remove users.
*ALL
The user can perform all operations except those limited to the owner or controlled by authorization list management (*AUTLMGT) authority. The user can control the object's existence, specify the security for the object, change the object, and perform basic functions on the object. The user also can change ownership of the object.
*USE
The user can perform basic operations on the object, such as running a program or reading a file. The user cannot change the object. Use (*USE) authority provides object operational (*OBJOPR), read (*READ), and execute (*EXECUTE) authorities.
*EXCLUDE
The user cannot access the workstation object.
*AUTL
The public authority of the authorization list specified on the AUTL parameter is used for the public authority for the object.

Note: You can specify AUT(*AUTL) only when USER(*PUBLIC) is also specified.

Other values (up to 10 repetitions)

*OBJALTER
Object alter authority provides the authority needed to alter the attributes of an object. If the user has this authority on a database file, the user can add and remove triggers, add and remove referential and unique constraints, and change the attributes of the database file. If the user has this authority on an SQL package, the user can change the attributes of the SQL package. This authority is currently only used for database files and SQL packages.
*OBJMGT
Object management authority provides the authority to The security for the object, move or rename the object, and add members to database files.
*OBJEXIST
Object existence authority provides the authority to control the object's existence and ownership. If a user has special save system authority (*SAVSYS), object existence authority is not needed to perform save restore operations on the object.
*OBJOPR
Object operational authority provides authority to look at the description of an object and use the object as determined by the data authority that the user has to the object.
*OBJREF
Object reference authority provides the authority needed to reference an object from another object such that operations on that object may be restricted by the other object. If the user has this authority on a physical file, the user can add referential constraints in which the physical file is the parent. This authority is currently only used for database files.

Data authorities

*ADD
Add authority provides the authority to add entries to an object (for example, job entries to an queue or records to a file).
*DLT
Delete authority provides the authority to remove entries from an object.
*EXECUTE
Execute authority provides the authority needed to run a program or locate an object in a library.
*READ
Read authority provides the authority needed to get the contents of an entry in an object or to run a program.
*UPD
Update authority provides the authority to change the entries in an object.

Authorization list (AUTL)

Specifies the authorization list whose entries are to be used to grant authority for the object specified. You must have authorization list management (*AUTLMGT) authority for the specified authorization list.

If a value is specified for this parameter, you cannot specify a value for the AUT, REFOBJ, or REFOBJTYPE parameters.

*NONE
The authorization list that secures the object is removed. If public authority in the object is *AUTL, it is changed to *EXCLUDE.
name
Specify the name of the authorization list to be used.

Reference object (REFOBJ)

Specifies the reference object to be queried to obtain authorization information. Those authorizations are given to the object specified by the OBJ and OBJTYPE parameters. Users authorized to the reference object are authorized in the same manner to the object for which authority is to be given. Database row and column access control masks and permissions will not be changed. If the reference object is secured by an authorization list, that authorization list secures the object specified by the OBJ and OBJTYPE parameters.

If a value is specified for this parameter, you cannot specify a value for the AUT or AUTL parameters.

name
Specify the name of the reference object.

Qualifier 2: Library

*LIBL
All libraries in the library list for the current thread are searched until the first match is found.
*CURLIB
The current library for the thread is searched. If no library is specified as the current library for the thread, the QGPL library is used.
name
Specify the name of the library to be searched.

Reference object type (REFOBJTYPE)

Specifies the object type of the reference object specified for the Reference object (REFOBJ) parameter.

*OBJTYPE
The object type of the reference object is the same as the object type specified for the Object type (OBJTYPE) parameter.
object-type
Specify the object type of the reference object. To see a complete list of object types when prompting this command, position the cursor on the field for this parameter and press F4 (Prompt).

Reference ASP device (REFASPDEV)

Specifies the auxiliary storage pool (ASP) device name where the library that contains the reference object (REFOBJ parameter) is located. If the reference object's library resides in an ASP that is not part of the library name space associated with the job, this parameter must be specified to ensure the correct object is queried for authorities.

*
The ASPs that are currently part of the job's library name space will be searched to locate the reference object. This includes the system ASP (ASP number 1), all defined basic user ASPs (ASP numbers 2-32), and, if the job has an ASP group, all independent ASPs in the ASP group.
*SYSBAS
The system ASP and all basic user ASPs will be searched to locate the reference object. No independent ASPs will be searched, even if the job has an ASP group.
name
Specify the device name of the independent ASP to be searched to locate the reference object. The independent ASP must have been activated (by varying on the ASP device) and have a status of AVAILABLE. The system ASP and basic user ASPs will not be searched.

Replace authority (REPLACE)

Specifies whether the authorities replace the user's current authorities.

*NO
The authorities are given to the user, but no authorities are removed, unless you are granting *EXCLUDE authority.
*YES
The user's current authorities are removed, then the authorities are given to the user.

Examples

Example 1: Granting Authority to All Users

GRTOBJAUT   OBJ(USERLIB/PROGRAM1)  OBJTYPE(*PGM)  USER(*PUBLIC)

This command gives authority to use 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 AUT parameter is not specified, the authority given to all users is change authority. This allows all users to run the program and to debug it.

Example 2: Granting Object Management Authority

GRTOBJAUT   OBJ(ARLIB/PROGRAM2)  OBJTYPE(*PGM)  USER(TMSMITH)
            AUT(*OBJMGT)

This command gives object management authority to user named TMSMITH. This authority allows TMSMITH to grant to others personally possessed authorities for the object named PROGRAM2, which is a program located in the library named ARLIB.

Example 3: Granting Authority to Users on Authorization List

GRTOBJAUT   OBJ(MYLIB/PRGM3)  OBJTYPE(*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.

Error messages

*ESCAPE Messages

CPF22A0
Authority of *AUTL is allowed only with USER(*PUBLIC).
CPF22A1
OBJTYPE(*AUTL) not valid on this command.
CPF22A2
Authority of *AUTL not allowed for object type *USRPRF.
CPF22A3
AUTL parameter not allowed for object type *USRPRF.
CPF22A9
Authority of *AUTL cannot be specified.
CPF22DA
Operation on file &1 in &2 not allowed.
CPF2207
Not authorized to use object &1 in library &3 type *&2.
CPF2208
Object &1 in library &3 type *&2 not found.
CPF2209
Library &1 not found.
CPF2210
Operation not allowed for object type *&1.
CPF2211
Not able to allocate object &1 in &3 type *&2.
CPF2216
Not authorized to use library &1.
CPF2223
Not authorized to give authority to object &1 in &3 type *&2.
CPF2227
One or more errors occurred during processing of command.
CPF2236
AUT input value not supported.
CPF2243
Library name &1 not allowed with OBJ(generic name) or OBJ(*ALL).
CPF2245
Process profile not owner of object &1 in &3 type *&2.
CPF2253
No objects found for &1 in library &2.
CPF2254
No libraries found for &1 request.
CPF2273
Authority may not have been changed for object &1 in &3 type *&2 for user &4.
CPF2283
Authorization list &1 does not exist.
CPF2290
*EXCLUDE cannot be specified with another authority. Start of change
CPF4ACF
Operation failed for object
Operation failed for object &1 in &2 type *&3 due to replication errors.amp;1 in
Operation failed for object &1 in &2 type *&3 due to replication errors.amp;2 type *
Operation failed for object &1 in &2 type *&3 due to replication errors.amp;3 due to replication errors.End of change
CPF9804
Object &2 in library &3 damaged.