Retrieve Users Authorized to an Object (QSYRTVUA) API
Required Parameter Group:
| 1 | Receiver variable | Output | Char(*) |
| 2 | Length of receiver variable | Input | Binary(4) |
| 3 | Returned records feedback information | Output | Char(*) |
| 4 | Length of returned records feedback information | Input | Binary(4) |
| 5 | Format name | Input | Char(8) |
| 6 | Object name | Input | Char(*) |
| 7 | Length of object name | Input | Binary(4) |
| 8 | Error code | I/O | Char(*) |
| 9 | Symbolic link | Input | Char(10) |
Default Public Authority: *USE
Threadsafe: No
The Retrieve Users Authorized to an Object (QSYRTVUA) API provides information about the users who are authorized to an object. The API returns the following information:
- A list of users who have a private authority to the object and the authority that the users have
- The public authority for the object
- Other authority information for the object, such as the name of the owner, the primary group, and the authorization list securing the object
- For objects in the QDLS file system, the sensitivity level of the object
This API provides information that is similar to the Display Authority (DSPAUT) command.
Authorities and Locks
To use this API, you must have the authorities listed below or must be authorized to the Database Administrator function of the IBM i through System i™ Navigator's Application Administration support. The Change Function Usage (CHGFCNUSG) command, with a function ID of QIBM_DB_SECADM, can also be used to change the list of users allowed to use the function.
*X is required for all directories in the path.
- Authority to Object
- *OBJMGT
- Authority to Object (QSYS.LIB *AUTL object)
- No authority is required
- Authority to Object (QDLS file system)
- *ALL
- Authority to Object (QOPT file system)
- *USE
Required Parameter Group
- Receiver variable
- OUTPUT; CHAR(*)
The receiver variable that receives the information requested. You can specify the size of the area to be smaller than the format requested as long as you specify the length parameter correctly. As a result, the API returns only the data that the area can hold.
- Length of receiver variable
- INPUT; BINARY(4)
The length of the receiver variable provided. The length of receiver variable parameter may be specified up to the size of the receiver variable that is specified in the user program. If the length of receiver variable parameter that is specified is larger than the allocated size of the receiver variable that is specified in the user program, the results are not predictable.
- Returned records feedback information
- OUTPUT; CHAR(*)
Information about the object and information about the entries that are returned in the receiver variable.
See Format of Returned Records Feedback Information for details.
- Length of returned records feedback information
- INPUT; BINARY(4)
The length of the returned records feedback information provided. The length of the returned records feedback information parameter may be specified up to the size of the returned records feedback information variable specified in the user program. If the length of the returned records feedback information parameter specified is larger than the allocated size of the returned records feedback information variable that is specified in the user program, the results are not predictable. The minimum length is 16 bytes.
- Format name
- INPUT; CHAR(8)
The name of the format that is used to return information about the users who are authorized to the object.
You can specify this format:
RTUA0100 Each entry contains the name of the profile that is authorized to the object, whether the profile is a user profile or a group profile, and the profile's authority to the object.
- Object name
- INPUT; CHAR(*)
The object name.
If the length of the object name is greater than 0, then this parameter is assumed to be a path name represented in the coded character set identifier (CCSID) currently in effect for the job. If the CCSID of the job is 65535, this parameter is assumed to be represented in the default CCSID of the job.
If the length of the object name is -1, then this parameter is assumed to be a Qlg_Path_Name_T structure that contains a path name or a pointer to a path name. For more information on the Qlg_Path_Name_T structure, see Path name format.
- Length of object name
- INPUT; BINARY(4)
The length of the object name. If the length is -1, the object name parameter is assumed to be a Qlg_Path_Name_T structure.
- Error code
- I/O; CHAR(*)
The structure in which to return error information. For the format of the structure, see Error code parameter.
Optional Parameter Group
- Symbolic link
- INPUT; CHAR(10)
If the last component in the path name is a symbolic link, specifies whether or not to retrieve users authorized to the symbolic link or users authorized to the object pointed to by the symbolic link.
The valid values are:
*NO The users authorized to the symbolic link object are not retrieved. The users authorized to the object pointed to by the symbolic link are retrieved. This is the default value when the Symbolic link parameter is not specified
*YES If the object is a symbolic link, the users authorized to the symbolic link object are retrieved. The users authorized to the object pointed to by the symbolic link are not retrieved.
Receiver Variable Description
The following table describes the order and format of the data that is returned in the receiver variable for each user that is authorized to the object. For detailed descriptions of the fields in the table, see Field Descriptions.
RTUA0100 Format
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | CHAR(10) | Profile name |
| 10 | 0A | CHAR(1) | User or group indicator |
| 11 | 0B | CHAR(10) | Data authority |
| 21 | 15 | CHAR(1) | Authorization list management |
| 22 | 16 | CHAR(1) | Object management |
| 23 | 17 | CHAR(1) | Object existence |
| 24 | 18 | CHAR(1) | Object alter |
| 25 | 19 | CHAR(1) | Object reference |
| 26 | 1A | CHAR(10) | Reserved |
| 36 | 24 | CHAR(1) | Object operational |
| 37 | 25 | CHAR(1) | Data read |
| 38 | 26 | CHAR(1) | Data add |
| 39 | 27 | CHAR(1) | Data update |
| 40 | 28 | CHAR(1) | Data delete |
| 41 | 29 | CHAR(1) | Data execute |
| 42 | 2A | CHAR(10) | Reserved |
Format of Returned Records Feedback Information
For a description of the fields in this format, see Field Descriptions.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Bytes returned in the returned records feedback information |
| 4 | 4 | BINARY(4) | Bytes available in the returned records feedback information |
| 8 | 8 | BINARY(4) | Bytes returned in the receiver variable |
| 12 | C | BINARY(4) | Bytes available in the receiver variable |
| 16 | 10 | BINARY(4) | Number of authorized users |
| 20 | 14 | BINARY(4) | Entry length for each authorized user returned |
| 24 | 18 | CHAR(10) | Owner |
| 34 | 22 | CHAR(10) | Primary group |
| 44 | 2C | CHAR(10) | Authorization list |
| 54 | 36 | CHAR(1) | Sensitivity level |
Field Descriptions
Authorization list. The name of the authorization list that is securing the object. If there is no authorization list that secures the object, this field is *NONE.
Authorization list management. Whether the user has this authority to the object. This field is only valid if the object is an authorization list.
This field contains one of the following values:
| 0 | The user does not have this authority. |
| 1 | The user has this authority. |
Bytes available in the receiver variable. The number of bytes of data that is available to be returned to the user in the receiver variable. All available data is returned if enough space is provided.
Bytes available in the returned records feedback information. The number of bytes of data available to be returned to the user in the returned records feedback information. All available data is returned if enough space is provided.
Bytes returned in the receiver variable. The number of bytes of data that is returned to the user in the receiver variable.
Bytes returned in the returned records feedback information. The number of bytes of data returned to the user in the returned records feedback information.
Data add. Whether the user has this authority to the object.
This field contains one of the following values:
| 0 | The user does not have this authority. |
| 1 | The user has this authority. |
Data authority. The data authority that the authorized user has to the object.
This field contains one of the following values:
| *RWX | The user has object operational, read, add, update, delete, and execute authorities to the object. |
| *RW | The user has object operational, read, add, update, and delete authorities to the object. |
| *RX | The user has object operational, read, and execute authorities to the object. |
| *WX | The user has object operational, add, update, delete, and execute authorities to the object. |
| *R | The user has object operational and read authorities to the object. |
| *W | The user has object operational, add, update, and delete authorities to the object. |
| *X | The user has object operational and execute authorities to the object. |
| *EXCLUDE | The user has no authority to the object. |
| *AUTL | The public authority to the object comes from the public authority on the authorization list that secures the object. This value can be returned only if there is an authorization list that secures the object and the authorized user is *PUBLIC. |
| USER DEF | The user has some combination of data rights that do not relate to a special value. The API user should check the individual authorities for the user to determine what authority the user has to the object. |
Data delete. Whether the user has this authority to the object.
This field contains one of the following values:
| 0 | The user does not have this authority. |
| 1 | The user has this authority. |
Data execute. Whether the user has this authority to the object.
This field contains one of the following values:
| 0 | The user does not have this authority. |
| 1 | The user has this authority. |
Data read. Whether the user has this authority to the object.
This field contains one of the following values:
| 0 | The user does not have this authority. |
| 1 | The user has this authority. |
Data update. Whether the user has this authority to the object.
This field contains one of the following values:
| 0 | The user does not have this authority. |
| 1 | The user has this authority. |
Entry length for each authorized user returned. The entry length, in bytes, of each entry in the list of users who are authorized to the object.
Number of authorized users. The number of complete entries in the list of users who are authorized to the object. A value of zero is returned if the list is empty.
Object alter. Whether the user has this authority to the object.
This field contains one of the following values:
| 0 | The user does not have this authority. |
| 1 | The user has this authority. |
Object existence. Whether the user has this authority to the object.
This field contains one of the following values:
| 0 | The user does not have this authority. |
| 1 | The user has this authority. |
Object management. Whether the user has this authority to the object.
This field contains one of the following values:
| 0 | The user does not have this authority. |
| 1 | The user has this authority. |
Object operational. Whether the user has this authority to the object.
This field contains one of the following values:
| 0 | The user does not have this authority. |
| 1 | The user has this authority. |
Object reference. Whether the user has this authority to the object.
This field contains one of the following values:
| 0 | The user does not have this authority. |
| 1 | The user has this authority. |
Owner. The name of the owner of the object. If the owner has no authority, no authorized user entry is returned for the owner.
This field can contain the following special value:
| *NOUSRPRF | The user profile that owns this object does not exist on this system. |
Primary group. The name of the primary group for the object. If the primary group has no authority, no authorized user entry is returned for the primary group.
This field can contain the following special value:
| *NONE | There is no primary group for the object. |
| *NOUSRPRF | The user profile that is the primary group for this object does not exist on this system. |
Profile name. The name of the user profile that is authorized to the object.
This field can contain the following special values:
| *PUBLIC | Public authority (the authority used by users who are not privately authorized) to the object. This is the first entry that is returned. |
| *NOUSRPRF | The user profile that is authorized to this object does not exist on this system. |
| *NTWIRF | This value is not longer supported. |
| *NTWEFF | This value is not longer supported. |
Reserved. An ignored field.
Sensitivity level. The sensitivity level of a QDLS object. For all other objects, this field contains 0.
This field contains one of the following values:
| 0 | This value does not apply to this object. |
| 1 | (None) The object has no sensitivity restrictions. |
| 2 | (Personal) The object contains information intended for the user as an individual. |
| 3 | (Private) The object contains information that should be accessed only by the owner. |
| 4 | (Confidential) The object contains information that should be handled according to company procedures. |
User or group indicator. Whether this user is a user profile or a group profile.
This field contains one of the following values:
| 0 | This user is not a user or a group. This value is returned for special values such as *PUBLIC. |
| 1 | This user is a user profile. |
| 2 | This user is a group profile. |
Error Messages
| Message ID | Error Message Text |
|---|---|
| CPFA0A9 E | Object not found. Object is &1. |
| CPFA0CE E | Error occurred with path name parameter specified. |
| CPFA09C E | Not authorized to object. Object is &1. |
| CPF3C1D E | Length specified in parameter &1 not valid. |
| CPF3C21 E | Format name &1 is not valid. |
| CPF3C3A E | Value for parameter &2 for API &1 not valid. |
| CPF3C36 E | Number of parameters, &1, entered for this API was not valid. |
| CPF3C90 E | Literal value cannot be changed. |
| CPF3CF1 E | Error code parameter not valid. |
| CPF9872 E | Program or service program &1 in library &2 ended. Reason code &3. |
API introduced: V2R2
[ Back to top | Security APIs | APIs by category ]