#include <qsyphandle.h> void QsySetToProfileHandle (unsigned char *Profile_handle, void *Error_code);Service Program: QSYPHANDLE
The Set Profile Handle (OPM, QWTSETP; ILE, QsySetToProfileHandle) API validates the profile handle, locks the user profile, and changes the current thread to run under the user and group profiles represented by the profile handle. Once the change has been made, any open files and objects allocated by the original profile are accessible to the new profile.
No other attributes associated with the user or group profile are replaced. The qualified job name does not change to reflect the new user profile. However, any object created by the thread while running under the new profile is owned by the new profile or its group profile. If the job is running single threaded and the job user identity has not been explicitly set by an API, the job user identity is changed to the name of the new profile. If the job is running multithreaded, the job user identity does not change.
If the profile handle is not valid, the Set Profile Handle API, adds an exception to the job log, and enters a security violation in the QAUDJRN audit journal.
If you use this API to begin running under a specific profile, any spooled files created are, by default, owned by that profile. This is controlled by the spool file owner (SPLFOWN) parameter on the CRTPRTF command and is done by putting the file under a QPRTJOB job. Any spooled file command that references the spooled file with the job special value * will only access those files that were created before the profiles were swapped.
A QPRTJOB job is the name of a job that files are spooled under when the current job's user name is not the same as the user profile currently running. For example, if you use Set Profile Handle to set the profile to user JOE and create a spooled file, the file is spooled under job nnnnnn/JOE/QPRTJOB. This ensures that user JOE owns the spooled file and if that user uses the WRKSPLF command, the file is displayed.
The output queue a spooled file is placed in may be different after using this API. If the application using this API produces spooled output that needs to be on a secure output queue or the application is expecting the spooled output to be found on a particular output queue, configuration changes may be required. See the Printing topic for information about which output queue contains the spooled output.
The Job Change for modify profile or group profile (JS-M) audit records are written by this API to the security audit journal when *JOBDTA or *JOBCHGUSR action auditing is active. There are special auditing considerations when *JOBDTA and *JOBCHGUSR are not specified as part of the action auditing system values QAUDLVL and QAUDLVL2 but have been specified as part of the user action auditing for one of the profiles involved in the set profile handle operation. The determination of whether a JS-M audit record is written to the security audit journal is made after this API has changed the current thread to run under the user profile represented by the profile handle. *JOBDTA or *JOBCHGUSR user action auditing must be active for the user profile represented by the profile handle in order for a JS-M audit record to be written. The following examples describe when JS-M audit records are written.
In these examples, it is assumed that system wide auditing of *JOBDTA and *JOBCHGUSR is not active (system values QAUDLVL and QAUDLVL2 do not contain *JOBDTA or *JOBCHGUSR).
If UserA is the thread profile and uses this API to run under profile UserB, then there will not be a JS-M audit record written to the security audit journal. An audit record is not written because when the API makes the determination of whether an audit record should be written, the thread is running as UserB who does not have *JOBDTA or *JOBCHGUSR user action auditing active.
If UserB is the thread profile and uses this API to run under profile UserA, then there will be a JS-M audit record written to the security audit journal. An audit record is written because when the API makes the determination of whether an audit record should be written, the thread is running as UserA who has *JOBDTA or *JOBCHGUSR user action auditing active.
The profile handle returned by the QSYGETPH API or QsyGetProfileHandle API for the user profile to switch the thread to.
The structure in which to return error information. For the format of the structure, see Error code parameter. This parameter is optional for the QWTSETP API and is omissable for the QsySetToProfileHandle API.
This API sets the user profile for the thread in which it is called. Thus if the API is called while running multithreaded, it will result in different threads in the same process simultaneously running under different user profiles.
While this API itself is threadsafe, it should only be used in a job that is running multithreaded when all code running in the job is known to be trusted and operating in a coordinated manner. Some considerations when running multiple threads under different user profiles are:
|Message ID||Error Message Text|
|CPF22AD E||Group profile for user not found.|
|CPF22E7 E||Profile handle is not valid.|
|CPF2204 E||User profile &1 not found.|
|CPF2213 E||Not able to allocate user profile &1.|
|CPF2217 E||Not authorized to user profile &1.|
|CPF2225 E||Not able to allocate internal system object.|
|CPF3C90 E||Literal value cannot be changed.|
|CPF3CF1 E||Error code parameter not valid.|
|CPF9872 E||Program or service program &1 in library &2 ended. Reason code &3.|
[ Back to top | Security APIs | APIs by category ]