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.

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