ibm-information-center/dist/eclipse/plugins/i5OS.ic.apis_5.4.0.1/QSYCHGPW.htm

631 lines
18 KiB
HTML
Raw Permalink Normal View History

2024-04-02 14:02:31 +00:00
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<meta name="Copyright" content="Copyright (c) 2006 by IBM Corporation">
<title>Change User Password (QSYCHGPW) API</title>
<!-- Begin Header Records ========================================== -->
<!-- All rights reserved. Licensed Materials Property of IBM -->
<!-- US Government Users Restricted Rights -->
<!-- Use, duplication or disclosure restricted by -->
<!-- GSA ADP Schedule Contract with IBM Corp. -->
<!-- Sec SCRIPT A converted by B2H R4.1 (346) (CMS) by V2KEA304 -->
<!-- at RCHVMW2 on 17 Feb 1999 at 11:05:09 -->
<!-- Change History: -->
<!-- YYMMDD USERID Change description -->
<!--File Edited by Kersten Dec 2001 -->
<!--End Header Records -->
<link rel="stylesheet" type="text/css" href="../rzahg/ic.css">
</head>
<body>
<a name="Top_Of_Page"></a>
<!-- Java sync-link -->
<script language="Javascript" src="../rzahg/synch.js" type="text/javascript">
</script>
<h2>Change User Password (QSYCHGPW) API</h2>
<div class="box" style="width: 70%;">
<br>
&nbsp;&nbsp;Required Parameter Group:<br>
<!-- iddvc RMBR -->
<br>
<table width="100%">
<tr>
<td align="center" valign="top" width="10%">1</td>
<td align="left" valign="top" width="50%">User ID</td>
<td align="left" valign="top" width="20%">Input</td>
<td align="left" valign="top" width="20%">Char(10)</td>
</tr>
<tr>
<td align="center" valign="top">2</td>
<td align="left" valign="top">Current password</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Char(*)</td>
</tr>
<tr>
<td align="center" valign="top">3</td>
<td align="left" valign="top">New password</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Char(*)</td>
</tr>
<tr>
<td align="center" valign="top">4</td>
<td align="left" valign="top">Error code</td>
<td align="left" valign="top">I/O</td>
<td align="left" valign="top">Char(*)</td>
</tr>
</table>
<br>
&nbsp;&nbsp;Optional Parameter Group:<br>
<!-- iddvc RMBR -->
<br>
<table width="100%">
<tr>
<td align="center" valign="top" width="10%">5</td>
<td align="left" valign="top" width="50%">Length of current password</td>
<td align="left" valign="top" width="20%">Input</td>
<td align="left" valign="top" width="20%">Bin(4)</td>
</tr>
<tr>
<td align="center" valign="top">6</td>
<td align="left" valign="top">CCSID of current password</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Bin(4)</td>
</tr>
<tr>
<td align="center" valign="top">7</td>
<td align="left" valign="top">Length of new password</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Bin(4)</td>
</tr>
<tr>
<td align="center" valign="top">8</td>
<td align="left" valign="top">CCSID of new password</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Bin(4)</td>
</tr>
</table>
<br>
&nbsp;&nbsp;Default Public Authority: *USE<br>
<!-- iddvc RMBR -->
<br>
&nbsp;&nbsp;Threadsafe: No<br>
<!-- iddvc RMBR -->
<br>
</div>
<p>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.</p>
<p>This API provides support similar to the Change Password (CHGPWD)
command.</p>
<br>
<h3>Authorities and Locks</h3>
<p>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.</p>
<br>
<h3>Required Parameter Group</h3>
<dl>
<dt><strong>User ID</strong></dt>
<dd>INPUT; CHAR(10)
<p>The name of the user whose password is being changed.</p>
<p>You can specify the following special value:</p>
<table cellpadding="5">
<!-- cols="15 85" -->
<tr>
<td align="left" valign="top"><em>*CURRENT</em></td>
<td align="left" valign="top">The password of the user currently running is
changed.</td>
</tr>
</table>
<br>
</dd>
<dt><strong>Current password</strong></dt>
<dd>INPUT; CHAR(*)
<p>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.</p>
<p>You can specify the following special values:</p>
<table cellpadding="5">
<!-- cols="15 85" -->
<tr>
<td align="left" valign="top"><em>*NONE</em></td>
<td align="left" valign="top">The user currently does not have a password or
the password is not managed locally.</td>
</tr>
<tr>
<td align="left" valign="top"><em>*NOPWD</em></td>
<td align="left" valign="top">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.</td>
</tr>
</table>
<br>
</dd>
<dt><strong>New password</strong></dt>
<dd>INPUT; CHAR(*)
<p>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.</p>
<p>You can specify the following special value:</p>
<table cellpadding="5">
<!-- cols="15 85" -->
<tr>
<td align="left" valign="top"><em>*NONE</em></td>
<td align="left" valign="top">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.</td>
</tr>
</table>
<p>If the local password management (LCLPWDMGT) value for the user profile
specified on the user ID parameter is set to *NO, then the local i5/OS
password will be set to *NONE. The password value specified in this
parameter will be sent to other IBM products that do password synchronization
(for example, iSeries Integration for Windows Server).</p>
<br>
</dd>
<dt><strong>Error code</strong></dt>
<dd>I/O; CHAR(*)
<p>The structure in which to return error information. For the format of the
structure, see <a href="../apiref/error.htm#hdrerrcod">Error Code Parameter</a>.</p>
</dd>
</dl>
<br>
<h3>Optional Parameter Group</h3>
<dl>
<dt><strong>Length of current password</strong></dt>
<dd>INPUT; BINARY(4)
<p>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.</p>
<p>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.</p>
</dd>
<dt><strong>CCSID of current password</strong></dt>
<dd>INPUT; BINARY(4)
<p>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 <a href="../nls/rbagsglobalmain.htm">Globalization</a> topic in the
iSeries Information Center.</p>
<p>The valid values are:</p>
<table cellpadding="5">
<!-- cols="15 85" -->
<tr>
<td align="left" valign="top"><em>0</em></td>
<td align="left" valign="top">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.</td>
</tr>
<tr>
<td align="left" valign="top" nowrap><em>1-65533</em></td>
<td align="left" valign="top">A valid CCSID in this range.</td>
</tr>
<tr>
<td align="left" valign="top"><em>65535</em></td>
<td align="left" valign="top">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.</td>
</tr>
</table>
<br>
</dd>
<dt><strong>Length of new password</strong></dt>
<dd>INPUT; BINARY(4)
<p>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.</p>
<p>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.</p>
</dd>
<dt><strong>CCSID of new password</strong></dt>
<dd>INPUT; BINARY(4)
<p>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 <a href="../nls/rbagsglobalmain.htm">Globalization</a> topic in the
iSeries Information Center.</p>
<p>The valid values are:</p>
<table cellpadding="5">
<!-- cols="15 85" -->
<tr>
<td align="left" valign="top"><em>0</em></td>
<td align="left" valign="top">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.</td>
</tr>
<tr>
<td align="left" valign="top" nowrap><em>1-65533</em></td>
<td align="left" valign="top">A valid CCSID in this range.</td>
</tr>
<tr>
<td align="left" valign="top"><em>65535</em></td>
<td align="left" valign="top">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.</td>
</tr>
</table>
</dd>
</dl>
<br>
<h3>Usage Notes</h3>
<p>If the caller of the API:</p>
<ul>
<li>Enters the wrong password for the user, and</li>
<li>Exceeds the maximum number of times allowed by the system value QMAXSIGN,
and</li>
<li>The system value QMAXSGNACN is set to disable user profiles,</li>
</ul>
<p>then the user profile specified on the user parameter is disabled.</p>
<p>You cannot specify the following user ID profile names for the user
parameter:</p>
<pre>
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
</pre>
<p>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.</p>
<p>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.</p>
<p>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.</p>
<p>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.</p>
<p>You cannot specify a password length greater than 10 unless the system is
operating at a password level of 2 or 3.</p>
<br>
<h3>Error Messages</h3>
<table cellpadding="5">
<!-- cols="15 85" -->
<tr>
<th align="left" valign="top">Message ID</th>
<th align="left" valign="top">Error Message Text</th>
</tr>
<tr>
<td width="15%" valign="top">CPD2201 E</td>
<td width="85%" valign="top">System user profile cannot be changed.</td>
</tr>
<tr>
<td align="left" valign="top">CPD2356 E</td>
<td align="left" valign="top">New password cannot be same as current
password.</td>
</tr>
<tr>
<td align="left" valign="top">CPF0001 E</td>
<td align="left" valign="top">Error found on &amp;1 command.</td>
</tr>
<tr>
<td align="left" valign="top">CPF22C0 E</td>
<td align="left" valign="top">Password does not meet password rules. Return
code &amp;1.</td>
</tr>
<tr>
<td align="left" valign="top">CPF22C2 E</td>
<td align="left" valign="top">Password less than &amp;1 characters.</td>
</tr>
<tr>
<td align="left" valign="top">CPF22C3 E</td>
<td align="left" valign="top">Password longer than &amp;1 characters.</td>
</tr>
<tr>
<td align="left" valign="top">CPF22C4 E</td>
<td align="left" valign="top">Password matches one of 32 previous
passwords.</td>
</tr>
<tr>
<td align="left" valign="top">CPF22C5 E</td>
<td align="left" valign="top">Password contains one of the following:
&amp;1.</td>
</tr>
<tr>
<td align="left" valign="top">CPF22C6 E</td>
<td align="left" valign="top">Password contains two numbers next to each
other.</td>
</tr>
<tr>
<td align="left" valign="top">CPF22C7 E</td>
<td align="left" valign="top">Password contains a character used more than
once.</td>
</tr>
<tr>
<td align="left" valign="top">CPF22C8 E</td>
<td align="left" valign="top">Same character in same position as previous
password.</td>
</tr>
<tr>
<td align="left" valign="top">CPF22C9 E</td>
<td align="left" valign="top">Password must contain a number.</td>
</tr>
<tr>
<td align="left" valign="top">CPF22D0 E</td>
<td align="left" valign="top">Password contains a character repeated
consecutively.</td>
</tr>
<tr>
<td align="left" valign="top">CPF22D1 E</td>
<td align="left" valign="top">Password cannot be same as user ID.</td>
</tr>
<tr>
<td align="left" valign="top">CPF22D2 E</td>
<td align="left" valign="top">Password approval program &amp;1 not found.</td>
</tr>
<tr>
<td align="left" valign="top">CPF22D3 E</td>
<td align="left" valign="top">Password approval program signaled an error.</td>
</tr>
<tr>
<td align="left" valign="top">CPF22D4 E</td>
<td align="left" valign="top">Not allowed to use password approval
program.</td>
</tr>
<tr>
<td align="left" valign="top">CPF22D5 E</td>
<td align="left" valign="top">Parameters in password approval program not
correct.</td>
</tr>
<tr>
<td align="left" valign="top">CPF22E2 E</td>
<td align="left" valign="top">Password not correct for user profile
&amp;1.</td>
</tr>
<tr>
<td align="left" valign="top">CPF22E3 E</td>
<td align="left" valign="top">User profile &amp;1 is disabled.</td>
</tr>
<tr>
<td align="left" valign="top">CPF22F5 E</td>
<td align="left" valign="top">Value &amp;1 for new password not allowed.</td>
</tr>
<tr>
<td align="left" valign="top">CPF22F6 E</td>
<td align="left" valign="top">New password cannot be *NONE.</td>
</tr>
<tr>
<td align="left" valign="top">CPF2203 E</td>
<td align="left" valign="top">User profile &amp;1 not correct.</td>
</tr>
<tr>
<td align="left" valign="top">CPF2213 E</td>
<td align="left" valign="top">Not able to allocate user profile &amp;1.</td>
</tr>
<tr>
<td align="left" valign="top">CPF222E E</td>
<td align="left" valign="top">&amp;1 special authority is required.</td>
</tr>
<tr>
<td align="left" valign="top">CPF2225 E</td>
<td align="left" valign="top">Not able to allocate internal system object.</td>
</tr>
<tr>
<td align="left" valign="top">CPF2292 E</td>
<td align="left" valign="top">*SECADM required to create or change user
profiles.</td>
</tr>
<tr>
<td align="left" valign="top">CPF3BC7 E</td>
<td align="left" valign="top">CCSID &amp;1 outside of valid range.</td>
</tr>
<tr>
<td align="left" valign="top">CPF3C1D E</td>
<td align="left" valign="top">Length specified in parameter &amp;1 not
valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPF3C36 E</td>
<td align="left" valign="top">Number of parameters, &amp;1, entered for this
API was not valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPF3C90 E</td>
<td align="left" valign="top">Literal value cannot be changed.</td>
</tr>
<tr>
<td align="left" valign="top">CPF3CF1 E</td>
<td align="left" valign="top">Error code parameter not valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPF9801 E</td>
<td align="left" valign="top">Object &amp;2 in library &amp;3 not found.</td>
</tr>
<tr>
<td align="left" valign="top">CPF9802 E</td>
<td align="left" valign="top">Not authorized to object &amp;2 in &amp;3.</td>
</tr>
<tr>
<td align="left" valign="top">CPF9803 E</td>
<td align="left" valign="top">Cannot allocate object &amp;2 in library
&amp;3.</td>
</tr>
<tr>
<td align="left" valign="top">CPF9820 E</td>
<td align="left" valign="top">Not authorized to use library &amp;1.</td>
</tr>
<tr>
<td align="left" valign="top">CPF9830 E</td>
<td align="left" valign="top">Cannot assign library &amp;1.</td>
</tr>
<tr>
<td align="left" valign="top">CPF9872 E</td>
<td align="left" valign="top">Program or service program &amp;1 in library
&amp;2 ended. Reason code &amp;3.</td>
</tr>
</table>
<br>
<hr>
API introduced: V2R2
<hr>
<center>
<table cellpadding="2" cellspacing="2">
<tr align="center">
<td valign="middle" align="center"><a href="#Top_Of_Page">Top</a> | <a href=
"sec.htm">Security APIs</a> | <a href="aplist.htm">APIs by category</a></td>
</tr>
</table>
</center>
</body>
</html>