Retrieve User Authority to Object (QSYRUSRA) API
Required Parameter Group:
| 1 | Receiver variable | Output | Char(*) |
| 2 | Receiver variable length | Input | Binary(4) |
| 3 | Format name | Input | Char(8) |
| 4 | User profile name | Input | Char(10) |
| 5 | Qualified object name | Input | Char(20) |
| 6 | Object type | Input | Char(10) |
| 7 | Error code | I/O | Char(*) |
Optional Parameter Group 1:
| 8 | ASP device | Input | Char(10) |
| 9 | Path name | Input | Char(*) |
| 10 | Length of Path name | Input | Binary(4) |
Default Public Authority: *USE
Threadsafe: Yes
The Retrieve User Authority to Object (QSYRUSRA) API returns a specific user's authority for an object to the caller.
Authorities and Locks
The following authorities are required for the user calling this API, unless the user profile specified is *CURRENT, the caller owns the object, or the object is an authorization list:
- *OBJMGT authority to the object specified.
- *READ authority to the user profile specified (unless *PUBLIC is specified).
- *USE authority to the Auxiliary Storage Pool Device.
If previous programs in the program stack adopt their owner's authority, the adopted authority for the current program is the accumulated adopted authority from all other programs in the program stack that adopt authority. Adopted authority is only valid when the user specified is *CURRENT. If a path name is specified, adopted authority is not used when accessing the path object.
If a path name is specified, *X authority is required for each directory in the path.
If a path name is specified, adopted authority is not used to locate the object but adopted authority will be used when authority information is retrieved for the object.
Required Parameter Group
- Receiver variable
- OUTPUT; CHAR(*)
The variable used to return the user's authority to the object. This variable must be at least 8 bytes long.
- Receiver variable length
- INPUT; BINARY(4)
The length of the receiver variable. The variable must be at least 8 bytes long.
- Format name
- INPUT; CHAR(8)
The name of the format used to return the authority information.
You can specify the following special value:
USRA0100 All authority information is returned.
- User profile name
- INPUT; CHAR(10)
The name of the user whose object authority is returned.
You can specify the following special values:
*CURRENT The authority of the user currently running to the specified object is returned. *PUBLIC The public authority for the object is returned.
- Qualified object name
- INPUT; CHAR(20)
The name of the object whose authority is returned. The first 10 characters specify the object name, and the second 10 characters specify the library.
If you want to use a path name instead of a qualified object name, then use this special value for the object name:
*OBJPATH Use the optional parameters, path name and path name length, to specify the object name. When this special value is specified, the library name must be blanks. 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 authority information is returned. The object type must be blank if *OBJPATH is specified for the qualified object name.
- 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 1
- 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. If *OBJPATH is specifed for the qualifed object name, the ASP device must be *.
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 *.
Optional Parameter Group 2
- Path name
- INPUT; CHAR(*)
The object name, specified as a path name. This parameter is assumed to be 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 path 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 path name
- INPUT; BINARY(4)
The length of the path name in bytes. If the length is -1, the path name parameter is assumed to be a Qlg_Path_name_T structure. This value must be zero if no path name is specified.
Receiver Variable Description
The following tables describe the order and format of the data returned in the receiver variable. For detailed descriptions of the fields in the tables, see Field Descriptions.
USRA0100 Format
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Bytes returned |
| 4 | 4 | BINARY(4) | Bytes available |
| 8 | 8 | CHAR(10) | Object authority / Data authority |
| 18 | 12 | CHAR(1) | Authorization list management |
| 19 | 13 | CHAR(1) | Object operational |
| 20 | 14 | CHAR(1) | Object management |
| 21 | 15 | CHAR(1) | Object existence |
| 22 | 16 | CHAR(1) | Data read |
| 23 | 17 | CHAR(1) | Data add |
| 24 | 18 | CHAR(1) | Data update |
| 25 | 19 | CHAR(1) | Data delete |
| 26 | 1A | CHAR(10) | Authorization list |
| 36 | 24 | CHAR(2) | Authority source |
| 38 | 26 | CHAR(1) | Some adopted authority |
| 39 | 27 | CHAR(10) | Adopted object authority |
| 49 | 31 | CHAR(1) | Adopted authorization list management |
| 50 | 32 | CHAR(1) | Adopted object operational |
| 51 | 33 | CHAR(1) | Adopted object management |
| 52 | 34 | CHAR(1) | Adopted object existence |
| 53 | 35 | CHAR(1) | Adopted data read |
| 54 | 36 | CHAR(1) | Adopted data add |
| 55 | 37 | CHAR(1) | Adopted data update |
| 56 | 38 | CHAR(1) | Adopted data delete |
| 57 | 39 | CHAR(1) | Adopted data execute |
| 58 | 3A | CHAR(10) | Reserved |
| 68 | 44 | CHAR(1) | Adopted object alter |
| 69 | 45 | CHAR(1) | Adopted object reference |
| 70 | 46 | CHAR(10) | Reserved |
| 80 | 50 | CHAR(1) | Data execute |
| 81 | 51 | CHAR(10) | Reserved |
| 91 | 5B | CHAR(1) | Object alter |
| 92 | 5C | CHAR(1) | Object reference |
| 93 | 5D | CHAR(10) | ASP device name of library |
| 103 | 67 | CHAR(10) | ASP device name of object |
| 113 | 71 | CHAR(3) | Reserved |
| 116 | 74 | BINARY(4) | Offset to group information table |
| 120 | 78 | BINARY(4) | Number of group table entries returned |
| * | * | Char(*) | Group information table repeated for each of the user's groups |
Field Descriptions
Adopted authorization list management. Whether the user has adopted this authority to the object. If the user adopted the authority, this field is Y. If not, this field is N.
Adopted data add. Whether the user has adopted this authority to the object. If the user has adopted the authority, this field is Y. If not, this field is N.
Adopted data delete. Whether the user has adopted this authority to the object. If the user has adopted the authority, this field is Y. If not, this field is N.
Adopted data execute. Whether the user has adopted this authority to the object. If the user adopted the authority, this field is Y. If not, this field is N.
Adopted data read. Whether the user has adopted this authority to the object. If the user has adopted the authority, this field is Y. If not, this field is N.
Adopted data update. Whether the user has adopted this authority to the object. If the user has adopted the authority, this field is Y. If not, this field is N.
Adopted object alter. Whether the user has adopted this authority to the object. If the user adopted the authority, this field is Y. If not, this field is N.
Adopted object authority. The user's adopted authority to the object. This field is only valid if some of the user's authority is adopted. If the user does not adopt authority, this field will be blank.
If a qualified object name is specified, the possible values are:
| *ALL | The user adopted all object (operational, management, existence, alter, and reference) and data (read, add, update, delete, and execute) authorities to the object. |
| *CHANGE | The user adopted object operational and all data authorities to the object. |
| *USE | The user adopted object operational and data read and execute authorities to the object. |
| USER DEF | The user adopted 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 adopted to the object. |
If a path name is specified, the possible values are:
| *RWX | The user has object operational and all data authorities. |
| *RW | The user has object operational and data read, data add, data update, and data delete authorities. |
| *RX | The user has object operational, data read, and data execute authorities |
| *WX | The user has object operational and data add, data update, data delete, and data execute authorities. |
| *R | The user has object operational and data read authorities. |
| *W | The user has object operational and data add, data update, and data delete authorities. |
| *X | The user has object operational and data execute authorities. |
| *EXCLUDE | The user has exclude authority. |
| *NONE | The user does not have object operational or any data authorities. |
| 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. |
Note: If *OBJPATH is specified for the qualified object name parameter, be aware that adopted authority is not used by most commands and APIs that accept path names as input.
Adopted object existence. Whether the user adopted this authority to the object. If the user adopted the authority, this field is Y. If not, this field is N.
Adopted object management. Whether the user has adopted this authority to the object. If the user has adopted the authority, this field is Y. If not, this field is N.
Adopted object operational. Whether the user has adopted this authority to the object. If the user has adopted the authority, this field is Y. If not, this field is N.
Adopted object reference. Whether the user has adopted this authority to the object. If the user adopted the authority, this field is Y. If not, this field is N.
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 source. Indicates where the authority that the user has to the object initially came from. The authority may be a combination of authority from this source plus adopted authority.
This field contains one of the following special values:
| UA | The user has *ALLOBJ special authority. |
| UO | The user is privately authorized to the object. |
| UL | The user is privately authorized to the authorization list securing the object. |
| GA | The user's groups have *ALLOBJ special authority. |
| GO | The user's groups are privately authorized to the object. |
| GL | The user's groups are privately authorized to the authorization list securing the object. |
| GC | The user's groups have a combination of private authority to the object and private authority to the authorization list securing the object. |
| PO | The user accesses the object through the public authority. |
| PL | The user accesses the object through the public authority on the authorization list securing the object. |
| AD | All of the authority that the user has comes from adopted authority. This value is only returned if the user is *CURRENT. |
Authorization list. The name of the authorization list securing the object.
This field can contain one of the following special values:
| *NONE | There is no authorization list securing the object. |
| *DAMAGED | The authorization list securing the object is damaged. |
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.
Bytes available. The number of bytes of data available to be returned to the user. If all data is returned, this is the same as the number of bytes returned. If the receiver variable was not big enough to contain all of the data, this is the number of bytes that can be returned.
Bytes returned. The number of bytes of data returned to the user. This is the lesser of the number of bytes available to be returned or the length of the receiver variable.
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.
Group information table. A list of the user's group authorities to the object.
Number of group table entries returned. Number of group table entries returned in the receiver variable.
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 authority / Data authority. If a qualified object name is specifed, this is a special value indicating the user's total authority to the object including adopted authority (if the user is *CURRENT). If a path name is specified, this is a special value indicating the user's data authority to the object and includes any adopted authority (if the user is *CURRENT).
If a qualified object name is specified, the possible values are:
| *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, data read, and data execute authorities to the object. |
| *EXCLUDE | The user has exclude authority to the object. |
| 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. |
If a path name is specified, the possible values are:
| *RWX | The user has object operational and all data authorities. |
| *RW | The user has object operational and data read, data add, data update, and data delete authorities. |
| *RX | The user has object operational, data read, and data execute authorities |
| *WX | The user has object operational and data add, data update, data delete, and data execute authorities. |
| *R | The user has object operational and data read authorities. |
| *W | The user has object operational and data add, data update, and data delete authorities. |
| *X | The user has object operational and data execute authorities. |
| *EXCLUDE | The user has exclude authority. |
| *NONE | The user does not have object operational or any data authorities. |
| 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. |
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 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.
Offset to group information table. Offset from the beginning of the receiver variable to the first group table entry.
Reserved. An ignored field set to hexadecimal zeros.
Some adopted authority. Whether some of the authority that the user has to the object comes from adopted authority. If some of the authority is adopted, this field is Y. If not, this field is N. This field can only contain Y if the user is *CURRENT.
Group Information Table
This table holds information about the authorities a group has to the object.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Displacement to next group entry |
| 4 | 4 | CHAR(10) | Group profile |
| 14 | E | CHAR(10) | Object authority / Data authority |
| 24 | 18 | CHAR(1) | Authority source |
| 25 | 19 | CHAR(1) | Authorization List Management |
| 26 | 1A | CHAR(1) | Object operational |
| 27 | 1B | CHAR(1) | Object management |
| 28 | 1C | CHAR(1) | Object existence |
| 29 | 1D | CHAR(1) | Object alter |
| 30 | 1E | CHAR(1) | Object reference |
| 31 | 1F | CHAR(10) | Reserved |
| 41 | 29 | CHAR(1) | Data read |
| 42 | 2A | CHAR(1) | Data add |
| 43 | 2B | CHAR(1) | Data update |
| 44 | 2C | CHAR(1) | Data delete |
| 45 | 2D | CHAR(1) | Data execute |
| 46 | 2E | CHAR(2) | Reserved |
Field Descriptions
Authority source. Where the group's authority comes from. The value of this field is one of these special values:
| A | The group has *ALLOBJ special authority. |
| O | The group authority comes from private authority to the object. |
| L | The group authority comes from the authorization list securing the object. |
| blank | There is no authority source for the group. |
Authorization List Management. Whether the group has this authority to the object. If the group has the authority, this field is Y. If not, this field is N.
Data add. Whether the group has this authority to the object. If the group has the authority, this field is Y. If not, this field is N.
Data delete. Whether the group has this authority to the object. If the group has the authority, this field is Y. If not, this field is N.
Data execute. Whether the group has this authority to the object. If the group has the authority, this field is Y. If not, this field is N.
Data read. Whether the group has this authority to the object. If the group has the authority, this field is Y. If not, this field is N.
Data update. Whether the group has this authority to the object. If the group has the authority, this field is Y. If not, this field is N.
Displacement to next group entry. Displacement to the next group entry. This field is 0 if there is not another group entry.
Group profile. Name of a group in the user's profile.
Object alter. Whether the group has this authority to the object. If the group has the authority, this field is Y. If not, this field is N.
Object authority / Data authority. If a qualified object name is specified, this is a special value indicating the group's authority to the object. If a path name is specified, this is a special values indications the group's data authority to the object.
If a qualified object name is specified, this is one of the following values:
| *ALL | The group has all object (operational, management, existence, alter and reference) and data (read, add, update, delete, and execute) authorities to the object. |
| *CHANGE | The group has object operational and all data authorities to the object. |
| *USE | The group has object operational, data read, and data execute authorities to the object. |
| *EXCLUDE | The group has exclude authority to the object, or authorization list management authority. |
| USER DEF | The group has some combination of object and data authorities that do not relate to a special value. The individual authorities for the group should be checked to determine what authority the group has to the object. |
If a path name is specified, this is one of the following values:
| *RWX | The user has object operational and all data authorities. |
| *RW | The user has object operational and read, add, update, and delete data authorities. |
| *RX | The user has object operational, data read, and data execute authorities |
| *WX | The user has object operational and add, update, delete, and execute data authorities. |
| *R | The user has object operational and data read authorities. |
| *W | The user has object operational and add, update, and delete data authorities. |
| *X | The user has object operational and data execute authorities. |
| *EXCLUDE | The user has exclude authority. |
| *NONE | The user does not have object operational or any data authorities. |
| USER DEF | The group has some combination of object and data authorities that do not relate to a special value. The individual authorities for the group should be checked to determine what authority the group has to the object. |
Object existence. Whether the group has this authority to the object. If the group has the authority, this field is Y. If not, this field is N.
Object management. Whether the group has this authority to the object. If the group has the authority, this field is Y. If not, this field is N.
Object operational. Whether the group has this authority to the object. If the group has the authority, this field is Y. If not, this field is N.
Object reference. Whether the group has this authority to the object. If the group has the authority, this field is Y. If not, this field is N.
Error Messages
| Message ID | Error Message Text |
|---|---|
| CPF18A2 D | Path name parameters not specified. |
| CPF2203 E | User profile &1 not correct. |
| CPF2225 E | Not able to allocate internal system object. |
| CPF3CF1 E | Error code parameter not valid. |
| CPF3C19 E | Error occurred with receiver variable specified. |
| CPF3C21 E | Format name &1 is not valid. |
| CPF3C24 E | Length of the receiver variable is not valid. |
| CPF3C31 E | Object type &1 is not valid. |
| CPF3C3A E | Value for parameter &2 for API &1 not valid. |
| CPF3C90 E | Literal value cannot be changed. |
| CPF8122 E | &8 damage on library &4. |
| 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. |
| CPF9811 E | Program &1 in library &2 not found. |
| CPF9812 E | File &1 in library &2 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. |
| CPF9872 E | Program or service program &1 in library &2 ended. Reason code &3. |
| CPF9873 E | ASP status is preventing access to object. |
| CPFA09C E | Not authorized to object. |
| CPFA09E E | Object in use. Object is &1. |
| CPFA0A3 E | Path name resolution causes looping. |
| CPFA0A7 E | Path name too long. |
| CPFA0A9 E | Object not found. |
| CPFA0AB E | Operation failed for object. Object is &1. |
| CPFA0AD E | Function not supported by file system. |
API Introduced: V2R2
[ Back to top | Security APIs | APIs by category ]