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

573 lines
15 KiB
HTML
Raw 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>Get Profile Handle (QSYGETPH) 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 April 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 type="text/javascript" language="Javascript" src="../rzahg/synch.js">
</script>
<h2>Get Profile Handle (QSYGETPH) API</h2>
<div class="box" style="width: 65%;">
<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">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">Profile handle</td>
<td align="left" valign="top">Output</td>
<td align="left" valign="top">Char(12)</td>
</tr>
</table>
<br>
&nbsp;&nbsp;Optional Parameter Group 1:<br>
<!-- iddvc RMBR -->
<br>
<table width="100%">
<tr>
<td align="center" valign="top" width="10%">4</td>
<td align="left" valign="top" width="50%">Error code</td>
<td align="left" valign="top" width="20%">I/O</td>
<td align="left" valign="top" width="20%">Char(*)</td>
</tr>
</table>
<br>
&nbsp;&nbsp;Optional Parameter Group 2:<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 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 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: Yes<br>
<!-- iddvc RMBR -->
<br>
</div>
<p>The Get Profile Handle (QSYGETPH) 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.
</p>
<p>The QSYGETPH API follows this process:</p>
<ul>
<li>Verifies that the user ID and password are correct. Incorrect passwords and
special cases are handled as follows:<br>
<br>
<ul>
<li>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 disable the user ID. This
keeps applications from methodically determining user passwords.<br>
<br>
</li>
<li>To obtain a profile handle for a profile that does not have a password,
specify *NOPWD, *NOPWDCHK or *NOPWDSTS for the password parameter.
<p>You cannot obtain a
profile handle for the following system-supplied user profiles:</p>
<pre>
QAUTPROF QDLFM QMSF QSNADS QTSTRQS
QCLUMGT QDOC QNETSPLF QSPL
QCOLSRV QDSNX QNFSANON QSPLJOB
QDBSHR QFNC QNTP QSRVAGT
QDBSHRDO QGATE QPEX QSYS
QDFTOWN QLPAUTO QPM400 QTCP
QDIRSRV QLPINSTALL QRJE QTFTP
</pre>
</li>
<li>To obtain a profile handle for a profile that is disabled,
specify *NOPWDCHK for the password parameter.
<br>
<br>
</li>
<li>To obtain a profile handle when the password is expired,
specify *NOPWDCHK or *NOPWDSTS for the password parameter.
<br>
</li>
</ul>
</li>
<li>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.
<p>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 QSYGETPH stops generating
profile handles.</p>
<p>Be sure to keep track of the profile handles created in the calling
application. If the application calls QSYGETPH twice with the same user profile
and password, QSYGETPH returns two different profile handles. Either handle can
be used, but generating and using just one is more efficient.</p>
</li>
<li>Updates the last-used date for the user and group profiles.<br>
<br>
</li>
<li>Resets the signon attempts not valid count to zero.<br>
<br>
</li>
<li>If security-related events are being audited, adds an entry to the QAUDJRN
audit journal to indicate that a profile handle is created.</li>
</ul>
<br>
<h3>Authorities and Locks</h3>
<dl>
<dt><em>API Public Authority</em></dt>
<dd>*USE</dd>
<dt><em>User profile authority, if the password is *NOPWD, *NOPWDCHK or *NOPWDSTS.</em></dt>
<dd>*USE</dd>
<dt><em>User Profile Lock</em></dt>
<dd>*LSRD</dd>
</dl>
<br>
<h3>Required Parameter Group</h3>
<dl>
<dt><strong>User ID</strong></dt>
<dd>INPUT; CHAR(10)
<p>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.</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">A handle is generated with the current thread information.
<p>When specifying *CURRENT, <em> password</em> is ignored
and <em>length of password</em> and <em>CCSID of password</em> are not allowed.</p>
</td>
</tr>
</table>
<br>
</dd>
<dt><strong>Password</strong></dt>
<dd>INPUT; CHAR(*)
<p>The password for the user ID or a special value.</p>
<p><strong>Password for the user ID</strong></p>
<ul>
<li><em>Length of password</em> and <em>CCSID of password</em> are required
</li>
</ul>
<p><strong>Special value</strong></p>
<ul>
<li><em>Length of password</em> and <em>CCSID of password</em> are not allowed
when specifying a special value.
</li>
<li>A special value must be a 10 character,
blank padded value in CCSID 37.
</li>
<li>Special values allowed are:<br>
<br>
<table cellpadding="5">
<!-- cols="15 85" -->
<tr>
<td align="left" valign="top"><em>*NOPWD</em></td>
<td align="left" valign="top">The user requesting the profile
handle must have *USE authority to the user profile.
<p>A profile handle does not get created for a disabled user profile.</p>
<p>A profile handle does not get created for a user profile with an expired password.</p>
</td>
</tr>
<tr>
<td align="left" valign="top"><em>*NOPWDCHK</em></td>
<td align="left" valign="top">The user requesting the profile
handle must have *USE authority to the user profile.
<p>If the profile is disabled,
the user requesting the profile
handle must have *ALLOBJ and
*SECADM special authorities
to get a handle.</p>
<p>If the password is expired,
the user requesting the profile
handle must have *ALLOBJ and
*SECADM special authorities
to get a handle.</p>
</td>
</tr>
<tr>
<td align="left" valign="top"><em>*NOPWDSTS</em></td>
<td align="left" valign="top">The user requesting the profile
handle must have *USE authority to the user profile.
<p>A profile handle does not get created for a disabled user profile.
</p>
<p>If the password is expired,
the user requesting the profile
handle must have *ALLOBJ and
*SECADM special authorities
to get a handle.</p>
</td>
</tr>
</table>
</li>
</ul>
</dd>
<dt><strong>Profile handle</strong></dt>
<dd>OUTPUT; CHAR(12)
<p>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.</p>
<br>
<br>
</dd>
</dl>
<br>
<h3>Optional Parameter Group 1</h3>
<p>This parameter group is required when specifying a password for the <em>password</em>
parameter. It is optional when specifying a special value.</p>
<dl>
<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 2</h3>
<p>This parameter group is required when specifying a password for the <em>password</em>
parameter. It is not allowed when specifying a special value.</p>
<dl>
<dt><strong>Length of password</strong></dt>
<dd>INPUT; BINARY(4)
<p>The length, in bytes, of the password contained in the user profile password
parameter.</p>
<p>The valid values are:</p>
<table cellpadding="5">
<!-- cols="10 90" -->
<tr>
<td align="left" valign="top" nowrap><em>1-512</em></td>
<td align="left" valign="top">The length of the password in the password parameter. </td>
</tr>
</table>
</dd>
<dt><strong>CCSID of password</strong></dt>
<dd>INPUT; BINARY(4)
<p>The CCSID of the password parameter.
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="10 90" -->
<tr>
<td align="left" valign="top"><em>-1</em></td>
<td align="left" valign="top">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.
</td>
</tr>
<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>
</table>
</dd>
</dl>
<br>
<h3>Usage Notes</h3>
<p>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.</p>
<p>
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.</p>
<br>
<h3>Error Messages</h3>
<table width="100%">
<!-- cols="15 85" -->
<tr>
<th align="left" valign="top">Message ID</th>
<th align="left" valign="top">Error Message Text</th>
</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">CPF2204 E</td>
<td align="left" valign="top">User profile &amp;1 not found.</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">CPF2225 E</td>
<td align="left" valign="top">Not able to allocate internal system object.</td>
</tr>
<tr>
<td width="15%" valign="top">CPF22E2 E</td>
<td width="85%" 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">CPF22E4 E</td>
<td align="left" valign="top">Password for user profile &amp;1 has
expired.</td>
</tr>
<tr>
<td align="left" valign="top">CPF22E5 E</td>
<td align="left" valign="top">No password associated with user profile
&amp;1.</td>
</tr>
<tr>
<td align="left" valign="top">CPF22E6 E</td>
<td align="left" valign="top">Maximum number of profile handles have been
generated.</td>
</tr>
<tr>
<td align="left" valign="top">CPF22E9 E</td>
<td align="left" valign="top">*USE authority to user profile &amp;1
required.</td>
</tr>
<tr>
<td align="left" valign="top">CPF24B4 E</td>
<td align="left" valign="top">Severe error while addressing parameter list.</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">CPF3BDE E</td>
<td align="left" valign="top">CCSID &amp;1 not supported by API.</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">CPF3C3C E</td>
<td align="left" valign="top">Value for 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">CPF4AB8 E</td>
<td align="left" valign="top">Insufficient authority for user profile &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: V2R1
<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>