List Users Authorized to Object (QSYLUSRA) API
Required Parameter Group:
| 1 | Qualified user space name | Input | Char(20) |
| 2 | Format name | Input | Char(8) |
| 3 | Qualified object name | Input | Char(20) |
| 4 | Object type | Input | Char(10) |
| 5 | Error code | I/O | Char(*) |
Optional Parameter Group:
| 6 | ASP device | Input | Char(10) |
Default Public Authority: *USE
Threadsafe: Yes
The List Users Authorized to Object (QSYLUSRA) API puts a list of users privately authorized to an object, including an authorization list, into a user space. The information returned is the authority as it exists for the object. Any authority the process has to the object through its group or adopted authority is not included. *PUBLIC authority to the object is also returned in the first list entry of the user space.
If the object is a database file, an indication of whether the file has field authorities is returned.
This API provides information similar to that provided by the Display Authorization List (DSPAUTL) command or the Display Object Authority (DSPOBJAUT) command.
Authorities and Locks
- User Space Authority
- *CHANGE
- Authority to Library Containing User Space
- *EXECUTE
- Specified Object or Authorization List Authority
- *OBJMGT or be authorized to the Database Security 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.
- Auxiliary Storage Pool Device Authority
- *USE or 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.
Required Parameter Group
- Qualified user space name
- INPUT; CHAR(20)
The name of the existing user space used to return the list of authorized users to the object. The first 10 characters specify the user space name, and the second 10 characters specify the library.
You can use these special values for the library name:
*CURLIB The current library is used to locate the user space. If there is no current library, QGPL (general purpose library) is used. *LIBL The library list is used to locate the user space.
- Format name
- INPUT; CHAR(8)
The name of the format used to list authorized users.
You can specify this format:
USRA0100 Each entry contains the user name and authority values.
- Qualified object name
- INPUT; CHAR(20)
The name of the object for which the list of authorized users is returned. The first 10 characters specify the object name, and the second 10 characters specify the library.
You can use these special values for the library name:
*CURLIB The current library is used to locate the object. If there is no current library, QGPL (general purpose library) is used. *LIBL The library list is used to locate the object.
- Object type
- INPUT; CHAR(10)
The type of object for which the list of authorized users is returned.
- 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
- ASP device
- INPUT; CHAR(10)
The name of the auxiliary storage pool (ASP) device in which to search for the library that contains the object.
The valid values are:
* All ASPs associated with the job will be searched. This is the default value if the parameter is not specified. *SYSBAS The system ASP and all basic user ASPs will be searched. *ALL All ASPs that are currently available will be searched. ASP device name The specified ASP will be searched. If *CURLIB or *LIBL is specified for the library then the ASP device parameter must be specified as *.
User Space Variables
The following tables describe the order and format of the data returned in the user space. For detailed descriptions of the fields in the tables, see Field Descriptions.
Input Parameter Section
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | CHAR(10) | User space name specified |
| 10 | 0A | CHAR(10) | Library name specified |
| 20 | 14 | CHAR(8) | Format name |
| 28 | 1C | CHAR(10) | Object name |
| 38 | 26 | CHAR(10) | Library name specified |
| 48 | 30 | CHAR(10) | Object type |
| 58 | 3A | CHAR(10) | ASP device |
Header Section
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | CHAR(10) | Object name |
| 10 | 0A | CHAR(10) | Library name specified |
| 20 | 14 | CHAR(10) | Object type |
| 30 | 1E | CHAR(10) | Owner name |
| 40 | 28 | CHAR(10) | Authorization list |
| 50 | 32 | CHAR(10) | Primary group |
| 60 | 3C | CHAR(1) | Field authorities |
| 61 | 3D | CHAR(10) | ASP device name of library |
| 71 | 47 | CHAR(10) | ASP device name of object |
| 81 | 51 | CHAR(1) | Row or column access control |
USRA0100 Format
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | CHAR(10) | User profile name |
| 10 | 0A | CHAR(10) | Authority value |
| 20 | 14 | CHAR(1) | Authorization list management |
| 21 | 15 | CHAR(1) | Object operational |
| 22 | 16 | CHAR(1) | Object management |
| 23 | 17 | CHAR(1) | Object existence |
| 24 | 18 | CHAR(1) | Data read |
| 25 | 19 | CHAR(1) | Data add |
| 26 | 1A | CHAR(1) | Data update |
| 27 | 1B | CHAR(1) | Data delete |
| 28 | 1C | CHAR(1) | Data execute |
| 29 | 1D | CHAR(10) | Reserved |
| 39 | 27 | CHAR(1) | Object alter |
| 40 | 28 | CHAR(1) | Object reference |
Field Descriptions
ASP device name of library. The auxiliary storage pool (ASP) device name where the object's library is stored. If the object's library is in the system ASP or one of the basic user ASPs, this field contains *SYSBAS.
ASP device name of object. The auxiliary storage pool (ASP) device name where the object is stored. If the object is in the system ASP or one of the basic user ASPs, this field contains *SYSBAS.
Authority value. The user's authority to the object.
This field contains one of the following values:
| *ALL | The user has all object (operational, management, existence, alter, and reference) and data (read, add, update, delete, and execute) authorities to the object. |
| *CHANGE | The user has object operational and all data authorities to the object. |
| *USE | The user has object operational and data read and execute authorities to the object. |
| *EXCLUDE | The user has none of the object or data authorities to the object, or authorization list management authority to the authorization list. |
| *AUTL | The public authority for the object comes from the public authority on the authorization list securing the object. This value can only be returned if there is an authorization list securing the object and the authorized user is *PUBLIC. |
| USER DEF | The user has some combination of object and data authorities that do not relate to a special value. The individual authorities for the user should be checked to determine what authority the user has to the object. |
Authorization list. The name of the authorization list securing the object. If there is no authorization list securing the object, this field is *NONE.
Authorization list management. Whether the user has this authority to the object. If the user has the authority, this field is Y. If not, this field is N. This field is only valid if the object type is *AUTL.
Data add. Whether the user has this authority to the object. If the user has the authority, this field is Y. If not, this field is N.
Data delete. Whether the user has this authority to the object. If the user has the authority, this field is Y. If not, this field is N.
Data execute. Whether the user has this authority to the object. If the user has the authority, this field is Y. If not, this field is N.
Data read. Whether the user has this authority to the object. If the user has the authority, this field is Y. If not, this field is N.
Data update. Whether the user has this authority to the object. If the user has the authority, this field is Y. If not, this field is N.
Field authorities. Whether the object has field authorities. If the object is a database file and it has field authorities, this field is Y. If not, this field is N. This field is only valid if the object type is *FILE. To see the field authorities for a database file, do DSPOBJAUT OBJ(your_lib/your_dbfile) OBJTYPE(*FILE) AUTTYPE(*FIELD).
Format name. The name of the format used to list users authorized to the object.
Library name specified. The name of the library the object containing the authorization list is in.
Primary group. The name of the user that is the primary group for the object. If there is not a primary group for the object, the field will contain *NONE.
Object alter. Whether the user has this authority to the object. If the user has the authority, this field is Y. If not, this field is N.
Object existence. Whether the user has this authority to the object. If the user has the authority, this field is Y. If not, this field is N.
Object management. Whether the user has this authority to the object. If the user has the authority, this field is Y. If not, this field is N.
Object name. The name of the object for which the list of authorized users is returned.
Object operational. Whether the user has this authority to the object. If the user has the authority, this field is Y. If not, this field is N.
Object reference. Whether the user has this authority to the object. If the user has the authority, this field is Y. If not, this field is N.
Object type. The type of object for which the list of authorized users is returned.
Owner. The name of the owner of the object. If all authority for the owner is removed, no list entry is returned for the owner.
Reserved. An ignored field set to hexadecimal zeros.
Row or column access control. Whether row or column access control is active on the object. If row or column access control is active on the object this field is Y. If not, this field is blank.
User profile name. The name of the user authorized to the object.
This field can contain the following special value:
| *PUBLIC | Public authority (authority used by users not privately authorized) to the object. This is the first entry in the list data section. |
User space name specified. The name of the user space used to return the list of users authorized to the object.
Error Messages
| Message ID | Error Message Text |
|---|---|
| CPF3CAA E | List is too large for user space &1. |
| CPF3CF1 E | Error code parameter not valid. |
| CPF3C21 E | Format name &1 is not valid. |
| CPF3C31 E | Object type &1 is not valid. |
| CPF3C90 E | Literal value cannot be changed. |
| CPF811A E | User space &4 in &9 damaged. |
| CPF980B E | Object &1 in library &2 not available. |
| CPF9801 E | Object &2 in library &3 not found. |
| CPF9802 E | Not authorized to object &2 in &3. |
| CPF9803 E | Cannot allocate object &2 in library &3. |
| CPF9807 E | One or more libraries in library list deleted. |
| CPF9808 E | Cannot allocate one or more libraries on library list. |
| CPF9810 E | Library &1 not found. |
| CPF9814 E | Device &1 not found. |
| CPF9820 E | Not authorized to use library &1. |
| CPF9825 E | Not authorized to device &1. |
| CPF9830 E | Cannot assign library &1. |
| CPF9838 E | User profile storage limit exceeded. |
| CPF9872 E | Program or service program &1 in library &2 ended. Reason code &3. |
| CPF9873 E | ASP status is preventing access to object. |
API introduced: V4R2
[ Back to top | Security APIs | APIs by category ]