Retrieve Authorized Users (QSYRAUTU) API
Required Parameter Group:
| 1 | Receiver variable | Output | Char(*) |
| 2 | Length of receiver variable | Input | Binary(4) |
| 3 | Returned records feedback information | Output | Char(16) |
| 4 | Format name | Input | Char(8) |
| 5 | Selection criteria | Input | Char(10) |
| 6 | Starting profile name | Input | Char(10) |
| 7 | Starting profile option | Input | Char(1) |
| 8 | Group profile name | Input | Char(10) |
| 9 | Error Code | I/O | Char(*) |
Optional Parameter:
| 10 | Ending profile name | Input | Char(10) |
Default Public Authority: *USE
Threadsafe: Yes
The Retrieve Authorized Users (QSYRAUTU) API provides information about the authorized users of the system. It returns a list of authorized user names that meet the selection criteria specified by the caller of the API and information about those users. This API provides information similar to the Display Authorized Users (DSPAUTUSR) command.
Authorities and Locks
- Authority to User Profiles in List of Authorized Users
- *READ 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.
Note: If you are not authorized to the Database Administrator function of the IBM i, only those profiles to which you have *READ authority are returned in the list.
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 specified in the user program. If the length of receiver variable parameter specified is larger than the allocated size of the receiver variable specified in the user program, the results are not predictable.
- Returned records feedback information
- OUTPUT; CHAR(16)
Information about the entries that are returned in the receiver variable.
See Format of Returned Records Feedback Information for details.
- Format name
- INPUT; CHAR(8)
The name of the format that is used to return information about the authorized users.
You can specify these formats:
AUTU0100 Each entry contains the user name, an indicator specifying whether the user is a user profile or a group profile and an indicator specifying whether the user is a group that has members. AUTU0150 Each entry contains the same information as AUTU0100 plus the text description for the user. AUTU0200 Each entry contains the same information as AUTU0100 plus group profiles are returned for users who are members of one or more groups. AUTU0250 Each entry contains the same information as AUTU0200 plus the text description for the user.
- Selection criteria
- INPUT; CHAR(10)
The users that are returned.
Possible values follow:
*ALL All user profile and group profile names are returned. This is the same list of users that is returned by the List Authorized Users (QSYLAUTU) API. *USER User names that are not group profiles are returned. (Users that do not have a GID specified in their user profile.) *GROUP User names that are group profiles are returned. (Users that have a GID specified in their user profile.) *MEMBER User names that are members of the group specified by the group profile name parameter are returned. The users who do not have any group profiles can be retrieved by specifying *NOGROUP for the group profile name. Only user names that are not group profiles are returned. The group profile name parameter must contain a valid group profile name or *NOGROUP when the selection criteria parameter is *MEMBER.
- Starting profile name
- INPUT; CHAR(10)
The profile name at which to start the listing. The profile names are listed alphabetically.
Possible values follow:
*FIRST Profiles are returned starting with the first profile alphabetically. profile name If an exact match for the starting profile name is found, the starting profile option parameter indicates whether that profile name is returned. If an exact match for the starting profile name is not found, the listing begins with the first existing profile name after the specified starting profile name. For example, assume the authorized users are ED, FRANK, and MARY. If F is specified for the starting user profile, the list returned would be FRANK and MARY.
- Starting profile option
- INPUT; CHAR(1)
This parameter indicates whether the starting profile name is returned when an exact match for the starting profile name is found. Possible values follow:
0 Profile names greater than the starting profile are returned. 1 Profile names equal to and greater than the starting profile name are returned.
- Group profile name
- INPUT; CHAR(10)
The group profile whose members are to be returned. The profile that is specified must exist and must be a group profile.
A group profile name or *NOGROUP is required if *MEMBER is specified for the selection criteria parameter. The group profile name must be *NONE if the selection criteria parameter is not *MEMBER.
*NONE No group profile is specified. group name Users who are a member of this group are returned. *NOGROUP Users who are not a member of any group are 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
- Ending profile name
- INPUT; CHAR(10)
The profile name at which to end the listing. Specifying an ending profile name can limit the names that are returned.
If this parameter is not provided, *LAST is used as a default. Possible values are:
*LAST Profiles up to and including the last profile are returned. Profile name The last profile name to be included in the list.
Receiver Variable Description
The following tables describe the order and format of the data returned in the receiver variable for each profile name in the list. For detailed descriptions of the fields in the tables, see Field Descriptions.
AUTU0100 Format
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | CHAR(10) | Profile name |
| 10 | 0A | CHAR(1) | User or group indicator |
| 11 | 0B | CHAR(1) | Group members indicator |
AUTU0150 Format
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | CHAR(10) | Profile name |
| 10 | 0A | CHAR(1) | User or group indicator |
| 11 | 0B | CHAR(1) | Group members indicator |
| 12 | 0C | CHAR(50) | Text description |
AUTU0200 Format
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | CHAR(10) | Profile name |
| 10 | 0A | CHAR(1) | User or group indicator |
| 11 | 0B | CHAR(1) | Group members indicator |
| 12 | 0C | BINARY(4) | Number of group profiles |
| 16 | 10 | ARRAY(16) of CHAR(10) | Group profiles |
AUTU0250 Format
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | CHAR(10) | Profile name |
| 10 | 0A | CHAR(1) | User or group indicator |
| 11 | 0B | CHAR(1) | Group members indicator |
| 12 | 0C | CHAR(50) | Text description |
| 62 | 3E | CHAR(2) | Reserved |
| 64 | 40 | BINARY(4) | Number of group profiles |
| 68 | 44 | ARRAY(16) of CHAR(10) | Group profiles |
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 |
| 4 | 4 | BINARY(4) | Bytes available |
| 8 | 8 | BINARY(4) | Number of profile names |
| 12 | C | BINARY(4) | Entry length for each profile returned |
Field Descriptions
Bytes available.The number of bytes of data available to be returned to the user in the receiver variable. If all data is returned, bytes available is the same as the number of bytes returned. If the receiver variable was not big enough to contain all of the data, this value is estimated based on the total number of authorized users of the system and the format specified.
Bytes returned. The number of bytes of data returned to the user in the receiver variable. This is the lesser of the number of bytes available to be returned or the length of the receiver variable.
Entry length for each profile returned. The entry length, in bytes, of each element in the list of profile names. A value of zero is returned if the list is empty.
Group members indicator. Whether this user is a group that has members. Possible values follow:
| 0 | The user is not a group, or is a group but does not have any members. |
| 1 | The user is a group that has members. |
Group profiles. The array of group profiles for the user. The number of group profiles field indicates how many entries are in the array.
Number of group profiles. The number of group profiles returned in the group profiles field. The number of group profiles will be zero if the user is not a member of any groups.
Number of profile names. The number of complete entries in the list of profile names. A value of zero is returned if the list is empty.
Profile name. The name of an authorized user for whom information is returned.
Reserved. An ignored field.
Text description. The descriptive text for the user profile.
User or group indicator. Whether this user is a user profile or a group profile. Possible values follow:
| 0 | User profile |
| 1 | Group profile |
Error Messages
| Message ID | Error Message Text |
|---|---|
| CPF2225 E | Not able to allocate internal system object. |
| CPF22B4 E | Group profile &1 not found. |
| CPF22B7 E | Profile &1 is not a group profile. |
| CPF22E0 E | Group profile name cannot be *NONE when selection criteria is *MEMBER. |
| CPF22ED E | Group profile name must be *NONE when selection criteria is not *MEMBER. |
| CPF22EE E | Selection criteria is not valid. |
| CPF22EF E | Starting profile option must be 0 or 1. |
| CPF3C19 E | Error occurred with receiver variable specified. |
| CPF3C21 E | Format name &1 is 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: V3R7
[ Back to top | Security APIs | APIs by category ]