| Where allowed to run: All environments (*ALL) Threadsafe: No |
Parameters Examples Error messages |
The Add Job Watcher Definition (ADDJWDFN) command adds a new Job Watcher definition to the system. A Job Watcher definition identifies the performance data that is to be collected during a Job Watcher collection. A session can be started using the Start Job Watcher (STRJW) command. A definition is required when starting a new Job Watcher collection.
Restrictions:
| Top |
| Keyword | Description | Choices | Notes |
|---|---|---|---|
| DFN | Definition | Name | Required, Positional 1 |
| TEXT | Text 'description' | Character value, *BLANK | Optional |
| COLITV | Collection interval | 0.1-3600.0, 10, *NODELAY | Optional |
| ADDDTACGY | Additional data categories | Single values: *NONE, *ALL Other values (up to 8 repetitions): Element list |
Optional |
| Element 1: Category | *ACTGRPDTL, *ACTGRPSUM, *SQLSTMT, *SQLCURSTMT, *SQLDETAIL, *CALLSTACK, *SOCKETTCP, *SOCKETJOBS, *JAVA, *JAVASTACK | ||
| Element 2: Interval frequency | Integer, *ALWAYS | ||
| WAITSTK | Wait-based call stack data | Single values: *NONE Other values (up to 2 repetitions): Element list |
Optional |
| Element 1: Category | *CONFLICT, *ABNWAIT | ||
| Element 2: Minimum duration (microsecs) | Integer, 10000 | ||
| JOB | Job name | Single values: *ALL, *NONE Other values (up to 20 repetitions): Qualified job name |
Optional |
| Qualifier 1: Job name | Generic name, name | ||
| Qualifier 2: User | Generic name, name, *ALL | ||
| Qualifier 3: Number | 000000-999999, *ALL | ||
| TASKNAME | Task name | Single values: *ALL, *NONE Other values (up to 20 repetitions): Character value |
Optional |
| TDENBR | TDE number | Values (up to 20 repetitions): Hexadecimal value | Optional |
| CURUSRPRF | Current user profile | Values (up to 20 repetitions): Name | Optional |
| SBS | Subsystem | Values (up to 20 repetitions): Name | Optional |
| CURPOOL | Current storage pool | Values (up to 20 repetitions): 1-64 | Optional |
| FRCRCD | Force record write | *ITVEND, *CALC | Optional |
| INCALLFST | Include inactive jobs/tasks | *NO, *YES | Optional |
| TOASPTHLD | To file ASP threshold | 1-99, *SYSTEM | Optional |
| SYSASPTHLD | System ASP threshold | 1-99, *SYSTEM | Optional |
| CONDCTLF | Condition control file | Single values: *NONE Other values: Qualified object name |
Optional |
| Qualifier 1: Condition control file | Name | ||
| Qualifier 2: Library | Name | ||
| CONDCTLMBR | Condition control member | Name, *FIRST | Optional |
| CONDTYPE | Condition type | *PERITV, *TRIGGER, *UNTILMET | Optional |
| TIMEOUT | Timeout option | Single values: *NONE Other values: Element list |
Optional |
| Element 1: Option | *NBRSEC, *NBRITV | ||
| Element 2: Value | Integer | ||
| OCCURS | Consecutive occurrence count | Integer, 1 | Optional |
| HSTSIZE | History size | Integer, 0 | Optional |
| EXITPGM | User exit program | Single values: *NONE Other values: Qualified object name |
Optional |
| Qualifier 1: User exit program | Name | ||
| Qualifier 2: Library | Name | ||
| EXITPGMDTA | Exit program data | Character value, *NONE | Optional |
| Top |
Specifies the name of the Job Watcher definition being added. If the specified definition already exists an error condition will occur. This is a required parameter.
| Top |
The text description of the Job Watcher definition to be added.
| Top |
Specifies the interval between retrieval of job/task data. Job/task data is collected from the system on a sampling basis. This value specifies the amount of time that will elapse between the collection of each sample.
| Top |
Specifies additional types of data to include in the collection. Data types selected on this parameter will be collected in addition to the standard data collected by the Job Watcher function.
Single values
Other values (up to 10 repetitions)
Element 1: Category
Specifies the additional types of data to collect.
Element 2: Interval frequency
Specifies how frequently (in intervals) each type of data should be collected.
| Top |
Specifies a special case where call stacks can be collected for certain jobs and/or tasks which have been in an abnormal type of wait state on the system.
Single values
Other values (up to 2 repetitions)
Element 1: Category
Specifies the type of wait for which call stacks will be collected.
Element 2: Minimum duration (microsecs)
Specifies the minimum duration which the job or task must be in the abnormal or conflict wait state before call stacks will be collected.
| Top |
Specifies the jobs that will be included in the Job Watcher collection. Job(s) selected on this parameter will be collected in addition to any jobs or tasks specified on the Task name (TASKNAME), TDE number (TDENBR), Current user profile (CURUSRPRF), Subsystem (SBS), or Current storage pool (CURPOOL) parameters.
Single values
Other values (up to 20 repetitions)
Qualifier 1: Job name
Qualifier 2: User
Qualifier 3: Number
| Top |
Specifies the name of the task(s) which will be included in the Job Watcher collection. Task(s) selected on this parameter will be collected in addition to any jobs or tasks specified on the Job name (JOB), TDE number (TDENBR), Current user profile (CURUSRPRF), Subsystem (SBS), or Current storage pool (CURPOOL) parameters.
Single values
Other values (up to 20 repetitions)
| Top |
Specifies the Task Dispatching Element (TDE) number of the TDE(s) which will be included in the Job Watcher collection. The TDE number is a unique identifier assigned to each job, thread, and task running in the system. The TDE number may be found by using the Display list of tasks option in the Display/Alter/Dump function of Start System Service Tools (STRSST). TDE(s) selected on this parameter will be collected in addition to any jobs or tasks specified on the Job name (JOB), Task name (TASKNAME), Current user profile (CURUSRPRF), Subsystem (SBS), or Current storage pool (CURPOOL) parameters.
You can specify twenty values for this parameter.
| Top |
Specifies the current user profile of the jobs which will be included in the collection. Jobs selected on this parameter will be collected in addition to any jobs or tasks specified on the Job name (JOB), Task name (TASKNAME), TDE number (TDENBR), Subsystem (SBS), or Current storage pool (CURPOOL) parameters.
You can specify twenty values for this parameter.
| Top |
Specifies the subsystem of the jobs which will be included in the Job Watcher collection. Jobs selected on this parameter will be collected in addition to any jobs or tasks specified on the Job name (JOB), Task name (TASKNAME), TDE number (TDENBR), Current user profile (CURUSRPRF), or Current storage pool (CURPOOL) parameters.
You can specify twenty values for this parameter.
| Top |
Specifies the current system pool of the jobs and/or tasks which will be included in the Job Watcher collection. Jobs and/or tasks selected on this parameter will be collected in addition to any jobs or tasks specified on the Job name (JOB), Task name (TASKNAME), TDE number (TDENBR), Current user profile (CURUSRPRF), or Subsystem (SBS) parameters.
You can specify twenty values for this parameter.
| Top |
Specifies when data records will be written to the Job Watcher database files.
| Top |
Specifies whether detailed data for all jobs and tasks, including inactive jobs and tasks, will be collected for the first interval.
| Top |
Specifies the percentage of the auxiliary storage pool (ASP) that contains the Job Watcher database files which can be used before the collection is forced to end. Because the amount of data collected can be very large, this parameter allows you to limit how much of the ASP is consumed. If the database files exist in the system ASP and values are specified in both this parameter and the System ASP threshold (SYSASPTHLD), the SYSASPTHLD parameter will override the value specified here.
| Top |
Specifies the percentage of the system auxiliary storage pool (ASP) which can be used before the collection is forced to end. Because Job Watcher allocates temporary storage and the amount of data collected can be very large, this parameter allows you to limit how much of the system ASP is consumed. If the database files exist in the system ASP and values are specified in both this parameter and the To file ASP threshold (TOASPTHLD) parameter, the value specified here will take precedence.
| Top |
Specifies the name of the condition control file. This file must be a source physical file and may be used to specify conditions that Job Watcher will use to limit data collection. If a file is specified on this parameter, the data collected will be compared against the conditions defined in the file.
Conditions must be specified in a specific format. A description of valid conditions and formats follows:
Direct field comparison
Syntax: FIELDNAME.COMPARAND.VALUE
Example 1: The condition will be met when more than 75 synchronous database writes occur in the interval
SYNDBWRT.GT.75
Example 2: The condition will be met when the wait time in bucket 6 is between 30 and 80 microseconds.
QTIME06.GE.30.AND.QTIME06.LE.80
Rate condition
Syntax: RATE(FIELDNAME).COMPARAND.VALUE
Example: The condition will be met when the rate of synchronous database writes is greater than 10 per second
RATE(SYNDBWRT).GT.10
Percent condition (applies to time spent in a particular wait bucket)
Syntax: PERCENT(FIELDNAME).COMPARAND.VALUE
Example: The condition will be met when more than 10 percent of time spent waiting was counted in bucket 9
PERCENT(QTIME09).GT.10
Average condition
Syntax: AVERAGE(FIELDNAME1,FIELDNAME2).COMPARAND.VALUE where FIELDNAME1 is a time and FIELDNAME2 is a corresponding count
Note: At this time the only time/count combinations reported in Job Watcher are the wait bucket times and counts reported in the QAPYJWTDE file.
Example: The condition will be met when the average wait time for a wait counted in bucket 5 is greater than 50 microseconds
AVERAGE(QTIME05,QCOUNT05).GT.50
Single values
Qualifier 1: File
Qualifier 2: Library
| Top |
Specifies the file member which contains the condition information.
| Top |
Specifies the type of conditional collection.
| Top |
Specifies how long the collection should run without writing any data to the database files.
Single values
Element 1: Option
Element 2: Value
| Top |
Specifies number of consecutive intervals in which the specified condition must occur before it is considered satisfied.
| Top |
Specifies the amount of data (in intervals) that should be buffered as history during the conditional collection. The specified amount of data will be maintained until the condition has been satisfied, at which time all buffered data will be written to the database files along with the data from the current interval.
| Top |
Specifies the user exit program which will be called at the time the condition is satisfied.
Single values.
Qualifier 1: User exit program
Qualifier 2: Library
| Top |
Specifies any data which should be passed to the user exit program specified on the User exit program (EXITPGM) parameter.
| Top |
Example 1: Add a Job Watcher Definition which will Collect Data for a Specific Job with No Delay Between Samples
ADDJWDFN DFN(MYJOB) COLITV(*NODELAY)
JOB(123456/MYUSER/MYJOB) TASKNAME(*NONE)
This command will add a Job Watcher definition which will collect data for job 123456/MYUSER/MYJOB. Data will be collected as fast as possible, with no delay between intervals. To collect Job Watcher data using this definition use the Start Job Watcher (STRJW) command with MYJOB specified for the Definition (DFN) parameter.
Example 2: Add a Job Watcher Definition which will Collect Data for a Generic Job, Collecting SQL Data
ADDJWDFN DFN(GENJOB) COLITV(5) ADDDTACGY((*SQLDETAIL))
JOB(*ALL/*ALL/QPADEV*) TASKNAME(*NONE)
This command will add a Job Watcher definition which will collect data for all jobs with names which begin with 'QPADEV'. Data will be collected with a delay of 5 seconds between intervals. Standard data and SQL data will be collected. To collect Job Watcher data using this definition use the Start Job Watcher (STRJW) command with GENJOB specified for the Definition (DFN) parameter.
Example 3: Add a Job Watcher Definition which will Collect Data for All Jobs and Tasks, Collecting Call Stacks for those in Conflict Waits
ADDJWDFN DFN(CONFLICT) WAITSTK((*CONFLICT 100))
This command will add a Job Watcher definition which will collect data for all jobs and tasks on the system. Data will be collected at the default interval of 10 seconds. Data collected with this definition will include standard data, as well as call stacks for any job or task which was in a conflict wait for 100 microseconds or longer. To collect Job Watcher data using this definition use the Start Job Watcher (STRJW) command with CONFLICT specified for the Definition (DFN) parameter.
Example 4: Add a Job Watcher Definition which will Conditionally Collect Data for a Generic Job Name
ADDJWDFN DFN(COND) JOB(*ALL/*ALL/QSQ*)
TASKNAME(*NONE) CONDCTLF(MYLIB/MYCTLFILE)
CONDCTLMBR(MYCTLMBR) CONDTYPE(*TRIGGER)
TIMEOUT(1000/*NBRITV) HSTSIZE(5)
This command will add a Job Watcher definition which will conditionally collect data for all jobs with names which begin with 'QSQ'. The file/member which specifies the condition to evaluate is MYCTLFILE/MYCTLMBR and this file exists in library MYLIB. No data will be written to the Job Watcher database files until the specified condition has been satisfied. At the time the condition is met, the 5 previous intervals of history data will be written to the database files. If data collection continues for 1000 intervals and the condition is not satisfied in any interval, the collection will end without writing any data to the database files. To collect Job Watcher data using this definition use the Start Job Watcher (STRJW) command with COND specified for the Definition (DFN) parameter.
| Top |
*ESCAPE Messages
| Top |