GRTOBJAUT (Grant Object Authority)

GRTOBJAUT Command syntax diagram

 

Purpose

The Grant Object Authority (GRTOBJAUT) command is used by one user to grant specific authority for the object named in this 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. User profiles cannot be secured by an authorization list (*AUTL).

This command can be used by an object's owner or by a user with object management authority for the specified object. A user with object management authority can grant to other users any authority that user has, except object management authority. 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.

 

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

 

Required Parameters

OBJ
Specifies the qualified name of the objects for which specific authorities are given to one or more users or to an authorization list. A specific object name or a generic object name can be qualified by a library name. More information on this parameter is in commonly used parameters.

The name of the object can be qualified by one of the following library values:

*LIBL: All libraries in the job's library list are searched until the first match is found.

*CURLIB: The current library for the job is searched. If no library is specified as the current library for the job, the QGPL library is used.

*USRLIBL: Only the libraries in the user portion of the job's library list are searched.

*ALL: All libraries in the auxiliary storage pools (ASPs) specified by the ASPDEV parameter are searched.>

*ALLUSR: All user libraries in the ASPs specified by the ASPDEV parameter are searched. > All libraries with names that do not begin with the letter Q are searched except for the following:

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

Although the following Qxxx libraries are provided by IBM, they typically contain user data that changes frequently. Therefore, these libraries are also considered user libraries and are also searched:

QDSNX
QGPL
QGPL38
QMPGDATA
QMQMDATA
QMQMPROC
QPFRDATA
QRCL

QRCLnnnnnEnd of change

 QS36F
QUSER38
QUSRADSM
QUSRBRM
QUSRDIRCL
QUSRDIRDB
QUSRIJS
QUSRINFSKR
QUSRNOTES		 QUSROND
QUSRPOSGS
QUSRPOSSA
QUSRPYMSVR
QUSRRDARS
QUSRSYS
QUSRVI
QUSRVxRxMx

 

Notes

  1. "nnnnn" is the number of a primary auxiliary storage pool.

  2. A different library name, of the form QUSRVxRxMx, can be created by the user for each release that IBM supports. VxRxMx is the version, release, and modification level of the library.

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

library-name: Specify the name of the library to be searched.

*ALL: All objects of the specified type (OBJTYPE) found in the search have specific authorities granted. A specific library name must be specified.

object-name: Specify the name of the object for which specific authorities are given to one or more users.

generic*-object-name: Specify the generic name of the object. A generic name is a character string of one or more characters followed by an asterisk (*); for example, ABC*. The asterisk substitutes for any valid characters. A generic name specifies all objects with names that begin with the generic prefix for which the user has authority. If an asterisk is not included with the generic (prefix) name, the system assumes it to be the complete object name. If the complete object name is specified, and multiple libraries are searched, multiple objects can be granted only if *ALL, *ALLUSR, *ALLAVL, or *ALLUSRAVL> library values can be specified for the name. For more information on the use of generic names, refer to generic names.

OBJTYPE
Specifies the object type of the object for which specific authorities are given to the specified users or to an authorization list. More information on this parameter is in commonly used parameters.

*ALL: Specific authorities for all object types (except *AUTL) are given to the specified users or to the authorization list.

object-type: Specify the specific object type of the object for which specific authorities are given to the specified users.

USER
Specifies the user names of one or more users to whom authorities for the named object are being given. If user names are specified, the authorities are given specifically to those users. Authority given by this command can be revoked specifically by the Revoke Object Authority (RVKOBJAUT) command.

*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 not 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.

user-profile-name: Specify the user names of one or more users to have specific authority for the object. Up to 50 user profile names can be specified.

AUTL
Specifies the name of the authorization list whose users are given authority for the object specified in the OBJ parameter.

*NONE: The object specified on the OBJ parameter will no longer be secured by an authorization list. If public authority to the object is *AUTL, it is changed to *EXCLUDE.

authorization-list-name: Specify the name of the authorization list whose users are given authority for the object specified on the OBJ parameter.

REFOBJ
Specifies the name of the object being queried to obtain authorization information. Those authorizations are given to the object specified by the OBJ parameter. Users authorized to the referenced object are authorized in the same manner to the object for which authority is being given. If the referenced object is secured by an authorization list, that authorization list secures the object specified in the OBJ parameter. Specify the name of the object.

The name of the reference object can be qualified by one of the following library values:

*LIBL: All libraries in the job's library list are searched until the first match is found.

*CURLIB: The current library for the job is searched. If no library is specified as the current library for the job, the QGPL library is used.

library-name: Specify the name of the library to be searched.

 

Optional Parameters

AUT
Specifies the authority given to users specified on the USER parameter. Users must have *AUTLMGT authority to manage the authorization list. More information on this parameter is in commonly used parameters.

*CHANGE: The user can perform all operations on the object except those limited to the owner or controlled by object existence authority and object management authority. The user can change and perform basic functions on the object. Change authority provides object operational authority and all data authority.

*ALL: The user can perform all operations except those limited to the owner or controlled by authorization list management 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 run a program or display the contents of a file. The user is prevented from changing the object. Use authority provides object operational authority, read authority, and execute authority.

*EXCLUDE: The user cannot access the object.

*AUTL: The public authority of the authorization list specified in the AUTL parameter is used for the public authority for the object.

A maximum of ten of the following values can be specified:

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

*OBJEXIST: Object existence authority provides the authority to control the object's existence and ownership. This authority is necessary for users who want to delete the object, free storage of the object, perform save and restore operations for the object or transfer ownership of an object. (If a user has special save system authority (*SAVSYS), object existence authority is not required.) Object existence authority is required to create an object that has been named by an authority holder.

*OBJMGT: Object management authority provides the authority to specify the security for the object, move or rename the object, and add members to database files.

*OBJOPR: Object operational authority provides authority to look at the description of an object and use the object as determined by the data authorities 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.

*ADD: Add authority provides the authority to add entries to an object (for example, job entries to a queue or records to a file).

*DLT: Delete authority allows the user to remove entries from an object, for example, remove messages from a message queue or records from a file.

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

*UPD: Update authority provides the authority needed to change the entries in an object.

REFOBJTYPE
Specifies the object type of the referenced object (REFOBJ parameter).

*OBJTYPE: The object type of the referenced object is the same type as the object being given authority (OBJTYPE parameter).

object-type: Specify the type of the object. Any one of the operating system object types can be specified.

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.

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 the grant 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.

auxiliary-storage-pool-device-name: 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.

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 user basic ASPs will be searched to locate the reference object. No independent ASPs will be searched, even if the job has an ASP group.

auxiliary-storage-pool-device-name: 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.>

Examples for GRTOBJAUT

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 for GRTOBJAUT

*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.
CPF22F0
Unexpected errors occurred during processing.>
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.
CPF980B
Object &1 in library &2 not available.>
CPF9804
Object &2 in library &3 damaged.
CPF9814
Device &1 not found.
CPF9825
Not authorized to device &1.
CPF9873
ASP status is preventing access to object.>