| 1 | User ID | Input | Char(10) |
| 2 | Current password | Input | Char(*) |
| 3 | New password | Input | Char(*) |
| 4 | Error code | I/O | Char(*) |
| 5 | Length of current password | Input | Bin(4) |
| 6 | CCSID of current password | Input | Bin(4) |
| 7 | Length of new password | Input | Bin(4) |
| 8 | CCSID of new password | Input | Bin(4) |
The Change User Password (QSYCHGPW) API changes a user's password. You must know the existing password that you want to change, unless you have *SECADM special authority and *OBJMGT and *USE authority to the user profile being changed.
This API provides support similar to the Change Password (CHGPWD) command.
If the user ID parameter is not *CURRENT or the user ID of the user that is currently running, the caller of the API must have *SECADM special authority and *OBJMGT and *USE authorities to the user profile being changed to change the password. If the current password parameter is *NOPWD, the caller of the API must have *SECADM special authority and *OBJMGT and *USE authorities to the user profile being changed.
The name of the user whose password is being changed.
You can specify the following special value:
| *CURRENT | The password of the user currently running is changed. |
The current password for the user. Verification is done to ensure this is the correct password for the user before the password is changed, unless *NOPWD is specified. All trailing blank and null characters are removed from the current password before it is verified.
You can specify the following special values:
| *NONE | The user currently does not have a password or the password is not managed locally. |
| *NOPWD | The current password for the user is not verified before changing the password. The caller of the API must have *SECADM special authority and *OBJMGT and *USE authorities to the user profile being changed to specify this value. |
The new password for the user. Verification is done to ensure the new password meets the password composition rules of the system. All trailing blank and null characters are removed from the new password before it is verified.
You can specify the following special value:
| *NONE | The user is changed to not have a password. This value is not allowed if *CURRENT, the user ID of the user that is currently running, or QSECOFR is specified on the user ID parameter. |
If the local password management (LCLPWDMGT) value for the user profile specified on the user ID parameter is set to *NO, then the local IBM i password will be set to *NONE. The password value specified in this parameter will be sent to other IBM® products that do password synchronization.
The structure in which to return error information. For the format of the structure, see Error code parameter.
The length, in bytes, of the password contained in the current password parameter. If the optional parameter group is not specified, a default of 10 is used. The current password parameter should be padded with trailing blank characters, if necessary, to the size specified by this parameter.
This parameter accepts values from 1 to 512; however, values greater than 128 should only be used if multi-byte characters are specified for the current password. The number of characters, as interpreted by the CCSID of the current password parameter, cannot exceed 128.
The CCSID of the current password parameter. If the optional parameter group is not specified and the system is operating at password level 0 or 1, CCSID 37 is used. If the optional parameter group is not specified and the system is operating at password level 2 or 3, the default CCSID of the job is used to determine the CCSID of the data to be converted. For a list of valid CCSIDs, see the IBM i globalization topic collection.
The valid values are:
| 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. |
| 65535 | When the system is operating at password level 0 or 1, CCSID 37 is used. When the system is operating at password level 2 or 3, this value is rejected. |
The length, in bytes, of the password contained in the new password parameter. If the optional parameter group is not specified, a default of 10 is used. The new password parameter should be padded with trailing blank characters, if necessary, to the size specified by this parameter.
This parameter accepts values from 1 to 512; however, values greater than 128 should only be used if multi-byte characters are specified for the new password. The number of characters, as interpreted by the CCSID of the new password parameter, cannot exceed 128.
The CCSID of the new password parameter. If the optional parameter group is not specified and the system is operating at password level 0 or 1, CCSID 37 is used. If the optional parameter group is not specified and the system is operating at password level 2 or 3, the default CCSID of the job is used to determine the CCSID of the data to be converted. For a list of valid CCSIDs, see the IBM i globalization topic collection.
The valid values are:
| 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. |
| 65535 | When the system is operating at password level 0 or 1, CCSID 37 is used. When the system is operating at password level 2 or 3, this value is rejected. |
If the caller of the API:
then the user profile specified on the user parameter is disabled.
You cannot specify the following user ID profile names for the user parameter:
QAUTPROF QCLUMGT QCLUSTER QCOLSRV
QDBSHR QDBSHRDO QDIRSRV QDFTOWN
QDLFM QDOC QDSNX QFNC
QGATE QIPP QLPAUTO QLPINSTALL
QMGTC QMSF QNFSANON QNETSPLF
QNTP QPEX QPM400 QSNADS
QSPL QSPLJOB QSRVAGT QSYS
QTCM QTCP QTFTP QTMHHTP1
QTSTRQS QYCMCIMOM QYPSJSVR
When the new password is checked to ensure it meets the password composition rules for the system, only one error is returned per API call. Therefore, if the new password fails more than one of the rules, multiple calls to the API are needed to determine a correct new password.
If *NOPWD is specified for the current password, then the QPWDPOSDIF (Limit password character positions) system value cannot be checked. This system value determines whether the characters in the same position in the current and new password must be different. This value cannot be checked without the current password value.
You should avoid calling this API from a command line. If this API is called from CL and CL commands are being logged for the job or CL program, the call parameters for the API are logged in the job log. This means the passwords appear in the job log.
If the optional parameter group is not specified, the current and new password lengths default to 10 and the CCSID of the current and new passwords default to 37. These are the values that were used by the QSYCHGPW API prior to the addition of the optional parameter group.
You cannot specify a password length greater than 10 unless the system is operating at a password level of 2 or 3.
| Message ID | Error Message Text |
|---|---|
| CPD2201 E | System user profile cannot be changed. |
| CPD2356 E | New password cannot be same as current password. |
| CPF0001 E | Error found on &1 command. |
| CPF22C0 E | Password does not meet password rules. Return code &1. |
| CPF22C2 E | Password less than &1 characters. |
| CPF22C3 E | Password longer than &1 characters. |
| CPF22C4 E | Password matches one of 32 previous passwords. |
| CPF22C5 E | Password contains one of the following: &1. |
| CPF22C6 E | Password contains two numbers next to each other. |
| CPF22C7 E | Password contains a character used more than once. |
| CPF22C8 E | Same character in same position as previous password. |
| CPF22C9 E | Password must contain a number. |
| CPF22D0 E | Password contains a character repeated consecutively. |
| CPF22D1 E | Password cannot be same as user ID. |
| CPF22D2 E | Password approval program &1 not found. |
| CPF22D3 E | Password approval program signaled an error. |
| CPF22D4 E | Not allowed to use password approval program. |
| CPF22D5 E | Parameters in password approval program not correct. |
| CPF22E2 E | Password not correct for user profile &1. |
| CPF22E3 E | User profile &1 is disabled. |
| CPF22F5 E | Value &1 for new password not allowed. |
| CPF22F6 E | New password cannot be *NONE. |
| CPF2203 E | User profile &1 not correct. |
| CPF2213 E | Not able to allocate user profile &1. |
| CPF222E E | &1 special authority is required. |
| CPF2225 E | Not able to allocate internal system object. |
| CPF2292 E | *SECADM required to create or change user profiles. |
| CPF3BC7 E | CCSID &1 outside of valid range. |
| CPF3C1D E | Length specified in parameter &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. |
| CPF4AA6 E | Password change not allowed at this time. |
| CPF4AA7 E | Password value not valid. Reason code &1. |
| 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. |
| CPF9820 E | Not authorized to use library &1. |
| CPF9830 E | Cannot assign library &1. |
| CPF9872 E | Program or service program &1 in library &2 ended. Reason code &3. |
[ Back to top | Security APIs | APIs by category ]