Set To Profile Token (QSYSETPT, QsySetToPrfTkn) API

Start of change


  Required Parameter Group for QSYSETPT:

1 Profile token Input Char(32)
2 Error code I/O Char(*)

  Default Public Authority: *USE

  Threadsafe: Yes



  Syntax for QsySetToPrfTkn:
 #include <qsyptkn.h>

 void QsySetToPrfTkn
        (unsigned char  *Profile_token,
         void           *Error_code);

  Service Program: QSYPTKN

  Default Public Authority: *USE

  Threadsafe: Yes

End of change

The Set To Profile Token (OPM, QSYSETPT; ILE, QsySetToPrfTkn) API validates the profile token and changes the current thread to run under the user and group profiles represented by the profile token.

The qualified job name does not change to reflect the new user profile. Any object, however, 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 token is not valid, this API signals the message CPF2274 and puts an AF-W audit entry 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 spooled file under a QPRTJOB job. Any spooled file command that references the spooled file with the job special value * will access only those files that were created before the profiles were swapped.


QPRTJOB

A QPRTJOB job is the name of a job under which files are spooled when the current job's user name is not the same as the user profile running currently. For example, if you use this API 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 that 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

API Public Authority
*USE

Required Parameter Group

Profile token
INPUT; CHAR(32)

The profile token returned by the Generate Profile Token (QSYGENPT, QsyGenPrfTkn)API or Generate Profile Token From Profile Token (QSYGENFT, QsyGenPrfTknFromPrfTkn) API that represents the user profile to which to switch.


Error code
I/O; CHAR(*)

The structure in which to return error information. For the format of the structure, see Error Code Parameter.


Error Messages

Message ID Error Message Text
CPF18A8 E Error occured during set profile to profile token.
CPF2225 E Not able to allocate internal system object.
CPF2274 E Profile token is not valid.
CPF3CF1 E Error code parameter not valid.
CPF3C36 E Number of parameters, &1, entered for this API was not valid.
CPF3C90 E Literal value cannot be changed.
CPF9872 E Program or service program &1 in library &2 ended. Reason code &3.

Usage Notes

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:



API introduced: V4R5
Top | Security APIs | APIs by category