Get Profile Handle No Password (QsyGetProfileHandleNoPwd) API

Syntax for QsyGetProfileHandleNoPwd:

 #include <qsyphandle.h>

 void QsyGetProfileHandleNoPwd
        (unsigned char  *Profile_handle,
         char           *User_ID,
         char           *Password_value,
         void           *Error_code);

  Service Program: QSYPHANDLE

  Default Public Authority: *USE

  Threadsafe: Yes

The Get Profile Handle No Password (QsyGetProfileHandleNoPwd) API validates user IDs 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 a special value to be specified for the password value parameter. If you need to validate a user password, see the Get Profile Handle (QsyGetProfileHandle) API.

The Get Profile Handle No Password API follows this process:

Verifies that the user ID and password value are correct. Incorrect password values and special cases are handled as follows:
- To obtain a profile handle for a profile that does not have a password, specify *NOPWD, *NOPWDCHK or *NOPWDSTS for the password parameter.
  You cannot obtain a profile handle for the following system-supplied user profiles:
```
  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  
```
- To obtain a profile handle for a profile that is disabled, specify *NOPWDCHK for the password parameter.
- To obtain a profile handle when the password is expired, specify *NOPWDCHK or *NOPWDSTS for the password parameter.
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 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.

You can specify the following special value:

*CURRENT

A handle is generated with the current thread information.

Password value

INPUT; CHAR(10)

The password value for the user ID.

Only special values are allowed for this parameter. A special value must be a 10 character, blank padded value in CCSID 37.

You must specify one of the following special values:

*NOPWD

The user requesting the profile handle must have *USE authority to the user profile.

A profile handle does not get created for a disabled user profile.

A profile handle does not get created for a user profile with an expired password.

*NOPWDCHK

The user requesting the profile handle must have *USE authority to the user profile.

If the profile is disabled, the user requesting the profile handle must have *ALLOBJ and *SECADM special authorities to get a handle.

If the password is expired, the user requesting the profile handle must have *ALLOBJ and *SECADM special authorities to get a handle.

*NOPWDSTS

The user requesting the profile handle must have *USE authority to the user profile.

A profile handle does not get created for a disabled user profile.

If the password is expired, the user requesting the profile handle must have *ALLOBJ and *SECADM special authorities to get a handle.

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. Therefore, to guarantee that you will 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 you plan to switch to. 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 is probably safest to just end the thread or job.

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.
CPF22E3 E	User profile &1 is disabled.
CPF22E4 E	Password for user profile &1 has expired.
CPF22E6 E	Maximum number of profile handles have been generated.
CPF22E9 E	*USE authority to user profile &1 required.
CPF3C90 E	Literal value cannot be changed.
CPF3C3C E	Value for parameter &1 not valid.
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: V5R3

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