Get Profile Handle (QsyGetProfileHandle) API
Syntax for QsyGetProfileHandle:
#include <qsyphandle.h> void QsyGetProfileHandle (unsigned char *Profile_handle, char *User_ID, char *Password, int Length_of_password, unsigned int CCSID_of_password, void *Error_code);Service Program: QSYPHANDLE
Default Public Authority: *USE
Threadsafe: Yes
The Get Profile Handle (QsyGetProfileHandle) API validates user IDs and passwords and creates a profile handle, for use in jobs that run under more than one user profile. The profile handle is temporary; you can use it only in the job that created it.
This API requires the password for the user ID to be specified. If you need to create a profile handle for a user ID without specifying the password, see the Get Profile Handle No Password (QsyGetProfileHandleNoPwd) API.
The Get Profile Handle API follows this process:
- Verifies that the user ID and password are correct. Incorrect passwords and
special cases are handled as follows:
- If the password is not correct, the incorrect password count is increased.
(The QMAXSIGN system value contains the maximum number of incorrect attempts to
sign on.) If the QMAXSGNACN system value is set to disable the user profile,
repeated attempts to validate an incorrect password disables the user ID. This
keeps applications from methodically determining user passwords.
-
To obtain a profile handle for *CURRENT user,
use the Get Profile Handle No Password (QsyGetProfileHandleNoPwd) API.
- To obtain a profile handle for a profile that does not have a password, use the Get Profile Handle No Password (QsyGetProfileHandleNoPwd) API.
- If the password is not correct, the incorrect password count is increased.
(The QMAXSIGN system value contains the maximum number of incorrect attempts to
sign on.) If the QMAXSGNACN system value is set to disable the user profile,
repeated attempts to validate an incorrect password disables the user ID. This
keeps applications from methodically determining user passwords.
-
To obtain a profile handle for a profile that is disabled,
use the Get Profile Handle No Password (QsyGetProfileHandleNoPwd) API.
-
To obtain a profile handle when the password is expired,
use the Get Profile Handle No Password (QsyGetProfileHandleNoPwd) API.
- Generates the profile handle, a 12-character random string designating the
user's authorities. This string, not the user's password, supplies the Set
Profile Handle (QWTSETP, QsySetProfileHandle) and the Release Profile Handle
(QSYRLSPH, QsyReleaseHandle) APIs.
The maximum number of profile handles that can be created is approximately 20,000 per job; after that, the space to store them is full. Message CPF22E6 is sent to the application, and Get Profile Handle stops generating profile handles.
Be sure to keep track of the profile handles created in the calling application. If the application calls Get Profile Handle twice with the same user profile and password, Get Profile Handle returns two different profile handles. Either handle can be used, but generating and using just one is more efficient.
- Updates the last-used date for the user and group profiles.
- Resets the signon attempts not valid count to zero.
- If security-related events are being audited, adds an entry to the QAUDJRN
audit journal to indicate that a profile handle is created.
Authorities and Locks
- API Public Authority
- *USE
- User Profile Lock
- *LSRD
Required Parameter Group
- Profile handle
- OUTPUT; CHAR(12)
A unique string or handle designating the user profile to use as input to other routines. The handle is temporary; you can use it only in the job that created it.
- User ID
- INPUT; CHAR(10)
The user ID of the profile for which the handle is being created.
A user ID must be a 10 character, blank padded value in CCSID 37. - Password
- INPUT; CHAR(*)
The password for the user ID.
Special values are not allowed for this parameter.
- Length of password
- INPUT; BINARY(4)
The length, in bytes, of the password contained in the user profile password parameter.
The valid values are:
1-512 The length of the password in the password parameter. - CCSID of password
- INPUT; BINARY(4)
The CCSID of the password parameter. For a list of valid CCSIDs, see the IBM i globalization topic collection.
The valid values are:
-1 The current password level for the system is used to determine the CCSID of the password data. When calling this API on password level 0 or 1, CCSID 37 is used. When calling this API on password level 2 or 3, the default CCSID (DFTCCSID) job attribute is used. See usage notes for more details. 0 The CCSID of the job is used to determine the CCSID of the data to be converted. If the job CCSID is 65535, the CCSID from the default CCSID (DFTCCSID) job attribute is used. 1-65533 A valid CCSID in this range.
- Error code
- I/O; CHAR(*)
The structure in which to return error information. For the format of the structure, see Error code parameter.
Usage Notes
Profile handles are a limited resource; it is possible to run out of handles. To guarantee that you always have a profile handle to switch back to, it is recommended that you get a profile handle for both the current thread and the user profile to which you plan to switch. If for some reason you cannot do this, and if you cannot get a profile handle that will allow you to switch back, then it probably is safest to end the thread or job.
The CCSID parameter on this API can lead to potential problems if coded with inconsistent CCSID values. Passwords created using the CRTUSRPRF, CHGUSRPRF, and CHGPWD CL commands, as well as the QSYCHGPW API (when called without passing the CCSID parameter), while the system is running password level 0 or 1 are created using CCSID 37. Passwords created using these CL commands and the QSYCHGPW API (without the CCSID parameter specified) when running password level 2 or 3 are created using the default job CCSID. Using variant characters $, @ and #, as well as other variant characters, in a user password may result in inconsistencies when converting from one CCSID to another. When calling this API on password level 0 or 1, CCSID 37 should be specified unless the password string is in a known CCSID. When calling this API on password level 2 or 3, pass the default job CCSID unless the password string is in a known CCSID.
Error Messages
Message ID | Error Message Text |
---|---|
CPF2203 E | User profile &1 not correct. |
CPF2204 E | User profile &1 not found. |
CPF2213 E | Not able to allocate user profile &1. |
CPF2225 E | Not able to allocate internal system object. |
CPF22E2 E | Password not correct for user profile &1. |
CPF22E3 E | User profile &1 is disabled. |
CPF22E4 E | Password for user profile &1 has expired. |
CPF22E5 E | No password associated with user profile &1. |
CPF22E6 E | Maximum number of profile handles have been generated. |
CPF22E9 E | *USE authority to user profile &1 required. |
CPF3BC7 E | CCSID &1 outside of valid range. |
CPF3BDE E | CCSID &1 not supported by API. |
CPF3C1D E | Length specified in parameter &1 not valid. |
CPF3C3C E | Value for parameter &1 not valid. |
CPF3C90 E | Literal value cannot be changed. |
CPF3CF1 E | Error code parameter not valid. |
CPF4AB8 E | Insufficient authority for user profile &1. |
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 ]