Join Trace (QSCJOINT) API

When *START is specified for the set value parameter, the Join Trace (QSCJOINT) API verifies if the job passed in the job identifier parameter is being traced with JOINTRC(*YES) specified on the Start Trace (STRTRC) command. If so, the trace characteristics of the specified job are used to modify the current job.

When *END is specified for the set value parameter, this API cleans the trace characteristics that were previously set.

Authorities and Locks

Authority to use the API

To use this API, you must have service (*SERVICE) special authority or must be authorized to the Service Watch function of the IBM^® i operating system through System i™ Navigator's Application Administration support. The Change Function Usage (CHGFCNUSG) command, with a function ID of QIBM_SERVICE_TRACE, can also be used to change the list of users that are allowed to perform trace operations.

Required Parameter Group

Set value

INPUT; CHAR(10)

The value passed to specify if the trace characteristics of the job passed in the job identifier parameter will be set or cleared in the current job.

Special value	Description
*START	If the job passed in the job identifier parameter is being traced with JOINTRC(*YES) specified on the Start Trace (STRTRC) command, the trace characteristics of the specified job are used to modify the current job.
*END	Clear the trace characteristics of the current job.

Job identifier

INPUT; CHAR(40)

The identifier of the job for which the trace environment is going to be verified if it was specified to set its trace characteristics in a related job or thread. If *END was specified in the set value parameter, this parameter must be set to hexadecimal zeros ('00'X). If *START was specified in the set value parameter, the information must be in the following 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(2)	Reserved
28	1C	BINARY(4)	Thread indicator
32	20	CHAR(8)	Thread identifier

Field Descriptions

Job name. The name of the job for which the trace environment is to be checked.

Job number. The number of the job for which the trace environment is to be checked.

Reserved. Must be set to hexadecimal zeros ('00'X).

Thread identifier. The identifier of a thread within a job for which the trace environment is to be checked. This field must be set to hexadecimal zeros ('00'X) if thread indicator is set to 1.

Thread indicator. The value that is used to specify the thread within the job for which the trace environment is to be checked. The following values are supported:

0	Use the thread specified in the thread identifier field.
1	Use the initial thread of the identified job.

User name. The name of the user of the job for which the trace environment is to be checked.

Return code

OUTPUT; BINARY(4)

The variable that receives the information requested.

Special value	Description
0	Indicates the job passed in the job identifier parameter is being traced with JOINTRC(*YES) specified on the Start Trace (STRTRC) command, therefore the trace characteristics of the specified job were used to modify the current job.
1	Indicates the job passed in the job identifier parameter is not being traced with JOINTRC(*YES) specified on the Start Trace (STRTRC) command, therefore the trace characteristics of the specified job were not used to modify the current job.

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

The following messages may be sent from this function:

[ Back to top | Problem Management APIs | APIs by category ]