Get Profile Handle (QSYGETPH) API


  Required Parameter Group:


  Optional Parameter Group 1:


  Optional Parameter Group 2:


  Default Public Authority: *USE

  Threadsafe: Yes

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.

The QSYGETPH API follows this process:


Authorities and Locks

API Public Authority
*USE
User profile authority, if the password is *NOPWD, *NOPWDCHK or *NOPWDSTS.
*USE
User Profile Lock
*LSRD

Required Parameter Group

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.

You can specify the following special value:


Password
INPUT; CHAR(*)

The password for the user ID or a special value.

Password for the user ID

  • Length of password and CCSID of password are required

Special value

  • Length of password and CCSID of password are not allowed when specifying a special value.
  • A special value must be a 10 character, blank padded value in CCSID 37.
  • Special values allowed are:

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.




Optional Parameter Group 1

This parameter group is required when specifying a password for the password parameter. It is optional when specifying a special value.

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 Group 2

This parameter group is required when specifying a password for the password parameter. It is not allowed when specifying a special value.

Length of password
INPUT; BINARY(4)

The length, in bytes, of the password contained in the user profile password parameter.

The valid values are:

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:


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



API introduced: V2R1

[ Back to top | Security APIs | APIs by category ]