Set Profile Handle (QWTSETP, QsySetToProfileHandle) API

  #include <qsyphandle.h>

  void QsySetToProfileHandle
             (unsigned char  *Profile_handle,        
              void           *Error_code);                 

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.

Output Queue Considerations

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.

Auditing Considerations

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).

• UserA - *JOBDTA or *JOBCHGUSR user profile action auditing is active.
• UserB - *JOBDTA and *JOBCHGUSR user profile action auditing are not active.

Example 1 - Thread profile (UserA) has *JOBDTA or *JOBCHGUSR user profile action auditing active.

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.

Example 2 - Thread profile (UserB) does not have *JOBDTA or *JOBCHGUSR user profile 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.

Authorities and Locks

None.

Required Parameter

Profile handle

INPUT; CHAR(12)

The profile handle returned by the QSYGETPH API or QsyGetProfileHandle API for the user profile to switch the thread to.

Optional Parameter

Error code

I/O; CHAR(*)

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.

Considerations for Scope and Thread Safety

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:

• The design of threads is for every thread in the job to share the same resources. With threads, programs share the same static and heap storage, and by passing pointers, they can get at each other's automatic storage. They also share open files and other resources, such as the same QTEMP library and the profile handles used by the Set Profile Handle API.
• Assume two users are allowed to run their own commands or programs in different threads of a single job. One of the users may be able to read or write data of the other user. This access may occur without the system doing an authority check or even auditing the fact that they read or modified that data.

Error Messages

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