Control Thread (QTHMCTLT) API
Required Parameter Group:
| 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(*) |
Default Public Authority: *USE
Threadsafe: Yes
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.
Authorities and Locks
- Job Authority
- If the action to be taken is hold thread or release thread, the caller of
the API must be running under a user profile that is the same as the job user
identity of the job containing the thread for which the specified action is to
be taken. Otherwise, the caller of the API must be running under a user profile that
has job control (*JOBCTL) 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.
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.
Required Parameter Group
- Receiver variable
- OUTPUT; CHAR(*)
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.
- Length of receiver variable
- INPUT; BINARY(4)
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.
- Format of receiver information
- INPUT; CHAR(8)
The format of the information returned in the receiver variable. The format name is:
CTLT0100 See CTLT0100 Format for details on the information returned.
- Job or thread identification information
- INPUT; CHAR(*)
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.
- Format of job or thread identification information
- INPUT; CHAR(8)
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.
- Action
- INPUT; BINARY(4)
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.
- Error code
- I/O; CHAR(*)
The structure in which to return error information. For the format of the structure, see Error code parameter.
CTLT0100 Format
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Bytes returned |
| 4 | 4 | BINARY(4) | Bytes available |
| 8 | 8 | UNSIGNED BINARY(4) | Hold count |
Field Descriptions for CTLT0100 Format
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.
Format of Job or Thread Identification Information
The format of the information needed to identify the thread for which the specified action will be taken.
JIDF0100 Format
| 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 |
Field Descriptions for JIDF0100 Format
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.
JIDF0200 Format
| 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 |
Field Descriptions for JIDF0200 Format
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.
Error Messages
| 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. |
API introduced: V5R2