| 1 | Receiver variable | Output | Char(*) |
| 2 | Length of receiver variable | Input | Binary(4) |
| 3 | Format of receiver information | Input | Char(8) |
| 4 | Job or thread identification information | Input | Char(*) |
| 5 | Format of job or thread identification information | Input | Char(8) |
| 6 | Action | Input | Binary(4) |
| 7 | Error code | I/O | Char(*) |
The Control Thread (QTHMCTLT) API holds, releases, or ends the specified thread.
End thread cannot be specified for the initial thread of a job. Hold thread or release thread cannot be specified for the initial thread of a system job.
If the action to be taken is end thread, the caller of the API must be running under a user profile that has service (*SERVICE) special authority or must be authorized to the Thread Control function of the IBM i operating system through System i Navigator's Application Administration support.
The Change Function Usage Information (QSYCHFUI) API, with a function ID of QIBM_SERVICE_THREAD, can be used to change the list of users that are allowed to end, hold, or release a thread.
The job user identity is the name of the user profile by which a job is known to other jobs. It is described in more detail in the Work management topic collection.
The receiver variable that receives the information requested. You can specify the size of the area to be smaller than the format requested as long as you specify the length parameter correctly. As a result, the API returns only the data that the area can hold.
The length of the receiver variable provided. The length of receiver variable parameter may be specified up to the size of the receiver variable specified in the user program. If the length of receiver variable parameter specified is larger than the allocated size of the receiver variable specified in the user program, the results are not predictable. The minimum length is 8 bytes.
The format of the information returned in the receiver variable. The format name is:
| CTLT0100 | See CTLT0100 Format for details on the information returned. |
The information that is used to identify the thread within a job for which an action is to be taken. See Format of Job or Thread Identification Information for details.
The format of the job or thread identification information. The possible format names are:
| JIDF0100 | See JIDF0100 Format for details on the job identification information. |
| JIDF0200 | See JIDF0200 Format for details on the job identification information. |
Note: If the thread handle is available, Format JIDF0200 provides a faster method of accessing a thread that is not the current thread than Format JIDF0100.
The action to be taken against the thread. The following actions are supported:
| 1 | Hold thread |
| 2 | Release thread |
| 3 | End thread |
The end thread, hold thread, and release thread actions are asynchronous operations. A portion of the action is done by the current thread, and the remainder of the action is done by the target thread. When control is returned to the current thread, the action may not have been performed in its entirety. Since some processing must be performed in the target thread, the action could be delayed for some period of time if higher priority threads in this or other jobs prevent the target thread from running.
End thread cannot be specified for the initial thread of a job. Hold thread or release thread cannot be specified for the initial thread of a system job.
The structure in which to return error information. For the format of the structure, see Error code parameter.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Bytes returned |
| 4 | 4 | BINARY(4) | Bytes available |
| 8 | 8 | UNSIGNED BINARY(4) | Hold count |
Bytes available. The number of bytes of data available to be returned. All available data is returned if enough space is provided.
Bytes returned. The number of bytes of data returned.
Hold count. The number of times the thread has been held prior to performing the action. The hold count is the count of fully processed hold operations currently in effect for the thread. The count is incremented by one for every hold operation that is processed for the thread. It is decremented by one for every release operation. If the count is greater than 0, the thread was already held. Hold and release operations that have not completed are not reflected in the count.
The format of the information needed to identify the thread for which the specified action will be taken.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | CHAR(10) | Job name |
| 10 | A | CHAR(10) | User name |
| 20 | 14 | CHAR(6) | Job number |
| 26 | 1A | CHAR(16) | Internal job identifier |
| 42 | 2A | CHAR(2) | Reserved |
| 44 | 2C | BINARY(4) | Thread indicator |
| 48 | 30 | CHAR(8) | Thread identifier |
Internal job identifier. The internal identifier for the job. The List Job (QUSLJOB) API returns this identifier. If you do not specify *INT for the job name parameter, this parameter must contain blanks. With this parameter, the system can locate the job more quickly than with a job name.
Job name. A specific job name or one of the following special values:
| * | The job in which this program is running. The job number and user name must contain blanks. |
| *INT | The internal job identifier locates the job. The job number and user name must contain blanks. |
Job number. A specific job number, or blanks when the job name specified is a special value.
Reserved. An unused field. This field must contain hexadecimal zeros.
Thread identifier. A value that uniquely identifies a thread within a job. If the thread indicator is not 0, this field must contain hexadecimal zeros.
Thread indicator. A value that is used to specify the thread within the job for which the action is to be taken. The following values are supported:
| 0 | Action should be taken for the thread specified in the thread identifier field. |
| 1 | Action should be taken for the thread that this program is running in currently. The combination of the internal job identifier, job name, job number, and user name fields also must identify the job containing the current thread. |
| 2 | Action should be taken for the initial thread of the identified job. |
User name. A specific user profile name, or blanks when the job name specified is a special value.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | CHAR(10) | Job name |
| 10 | A | CHAR(10) | User name |
| 20 | 14 | CHAR(6) | Job number |
| 26 | 1A | CHAR(16) | Internal job identifier |
| 42 | 2A | CHAR(2) | Reserved |
| 44 | 2C | UNSIGNED BINARY(4) | Thread handle |
| 48 | 30 | CHAR(8) | Thread identifier |
Internal job identifier. The internal identifier for the job. The List Job (QUSLJOB) API returns this identifier. If you do not specify *INT for the job name parameter, this parameter must contain blanks. With this parameter, the system can locate the job more quickly than with a job name.
Job name. A specific job name or one of the following special values:
| * | The job in which this program is running. The job number and user name must contain blanks. |
| *INT | The internal job identifier locates the job. The job number and user name must contain blanks. |
Job number. A specific job number, or blanks when the job name specified is a special value.
Reserved. An unused field. This field must contain hexadecimal zeros.
Thread handle. A value that is used to address a particular thread within a job. While the thread identifier uniquely identifies the thread within the job, the thread handle can imporve performance when referencing the thread. A valid thread handle must be specified. The thread handle is returned on several other interfaces.
Thread identifier. A value that uniquely identifies a thread within a job. A valid thread identifier must be specified.
User name. A specific user profile name, or blanks when the job name specified is a special value.
| Message ID | Error Message Text |
|---|---|
| CPF1071 E | No authority to job &3/&2/&1. |
| CPF136A E | Job &3/&2/&1 not active. |
| CPF18BF E | Thread &1 not found. |
| CPF24B4 E | Severe error while addressing parameter list. |
| CPF3CF1 E | Error code parameter not valid. |
| CPF3CF2 E | Error(s) occurred during running of &1 API. |
| CPF3C19 E | Error occurred with receiver variable specified. |
| CPF3C21 E | Format name &1 is not valid. |
| CPF3C24 E | Length of the receiver variable is not valid. |
| CPF3C3B E | Value for parameter &2 for API &1 not valid. |
| CPF3C3C E | Value for parameter &1 not valid. |
| CPF3C51 E | Internal job identifier not valid. |
| CPF3C52 E | Internal job identifier no longer valid. |
| CPF3C53 E | Job &3/&2/&1 not found. |
| CPF3C55 E | Job &3/&2/&1 does not exist. |
| CPF3C58 E | Job name specified is not valid. |
| CPF3C59 E | Internal identifier is not blanks and job name is not *INT. |
| CPF3C90 E | Literal value cannot be changed. |
| CPF9872 E | Program or service program &1 in library &2 ended. Reason code &3. |
| CPFB431 E | Ending the initial thread is not allowed. |
| CPFB438 E | Holding the initial thread of a system job is not allowed. |
| CPFB439 E | Releasing the initial thread of a system job is not allowed. |