Add Job Watcher Definition (ADDJWDFN)
| 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:
- To use this command, you must have service (*SERVICE) special authority, or be authorized to the Job Watcher function of the operating system. The Change Function Usage (CHGFCNUSG) command, with a function ID of QIBM_SERVICE_JOB_WATCHER, can be used to change the list of users that are allowed to use this command.
| Top |
Parameters
| 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 |
Definition (DFN)
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.
- name
- Specify the name of the new Job Watcher definition.
| Top |
Text 'description' (TEXT)
The text description of the Job Watcher definition to be added.
- *BLANK
- The Job Watcher definition will have no text description.
- character-value
- Specify a text description for the Job Watcher definition. The description should be no more that 50 characters of text, enclosed in apostrophes.
| Top |
Collection interval (COLITV)
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.
- 10
- The delay between the collection of interval data will be 10 seconds.
- *NODELAY
- Data will be collected as fast as possible, with no delay between the collection of interval data.
- 0.1-3600.0
- Specify the number of seconds to delay between the collection of interval data. If a value is specified on this parameter it will override the value in the Job Watcher definition.
| Top |
Additional data categories (ADDDTACGY)
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
- *NONE
- Only standard data will be included in this collection. Standard data collected includes: run information (QAPYJWRUNI), interval information (QAPYJWINTI), TDE and process data (QAPYJWSTS, QAPYJWTDE, and QAPYJWPRC), wait bucket mapping (QAPYJWBKT), Classic Java virtual machine data (QAPYJWJVM), and Classic Java thread data (QAPYJWJVTH).
- *ALL
- This collection will include standard data and all optional data categories.
Other values (up to 10 repetitions)
Element 1: Category
Specifies the additional types of data to collect.
- *ACTGRPDTL
- This data type will collect detailed activation group data. This data type will write activation group data to the database files QAPYJWAIGP, QAPYJWAIHP, and QAPYJWAIPA.
- *ACTGRPSUM
- This data type will collect summary data for activation groups. This summary data will be written to the file QAPYJWPRC in the fields CURNUMACTG and CURNUMACT.
- *SQLCURSTMT
- This data type will collect "in progress" SQL statement and host variable data. SQL current statement data will be written to the files QAPYJWSQL and QAPYJWSQLH.
- *SQLSTMT
- This data type will collect "in progress" or "last completed" SQL statement and host variable data. SQL statement data will be written to the files QAPYJWSQL and QAPYJWSQLH.
- *SQLDTL
- This data type will collect detailed SQL data which includes "in progress" or "last completed" SQL statement, host variable, open cursor list, and prepared statement area data. Detailed SQL data will be written to the files QAPYJWSQL, QAPYJWSQLH, QAPYJWSQLO, and QAPYJWSQLP.
- *CALLSTK
- This data type will collect call stacks for each TDE included in the collection. Call stack data will be written to the files QAPYJWSTK and QAPYJWPROC.
- *SCKTCP
- This data type will collect socket and TCP data. Socket and TCP data will be written to the file QAPYJWSKTC.
- *SCKJOB
- This data type will collect the same data collected by the *SCKTCP data type and will additionally collect information regarding the jobs using each socket. Data collected for this data type will be written to the files QAPYJWSKTC and QAPYJWSKJB.
- *JAVA
- This data type will collect IBM Technology for Java VM and thread data. Data collected for this data type will be written to the files QAPYJWIJVM and QAPYJWIJVT.
- *JAVASTACK
- This data type will collect call stacks for IBM Technology for Java threads included in the collection. Data collected for this data type will be written to the file QAPYJWIJVS.
Element 2: Interval frequency
Specifies how frequently (in intervals) each type of data should be collected.
- *ALWAYS
- Data for the corresponding category will be collected in every interval.
- integer
- Specify the interval frequency in intervals. For example, if 5 is entered in this parameter, data for the corresponding category will be collected in intervals 5, 10, 15, 20, etc.
| Top |
Wait-based call stack data (WAITSTK)
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
- *NONE
- No wait-based call stacks will be included in the collection.
Other values (up to 2 repetitions)
Element 1: Category
Specifies the type of wait for which call stacks will be collected.
- *ABNWAIT
- This category will collect call stacks which are in an abnormal wait. Abnormal waits are those that only occur in problem situations. These are either waits that rarely occur or waits that are taking a longer amount of time than normal to complete.
- *CONFLICT
- This category will collect call stacks which are in a conflict wait. Conflict waits occur when a job or task is either in a seize condition or is waiting for a lock, mutex, or gate that is being held by another job or task.
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.
- 10000
- A minimum duration value of 10,000 microseconds is used.
- integer
- Specify the number of microseconds that the job or task must be in the wait state.
| Top |
Job name (JOB)
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
- *ALL
- All jobs on the system are included.
- *NONE
- None of the jobs on the system are included.
Other values (up to 20 repetitions)
Qualifier 1: Job name
- name
- Specify the name of the job to include in the Job Watcher collection.
- generic-name
- Specify the generic name of the job to be included. A generic name is a character string of one or more characters followed by an asterisk (*). A generic name specifies all items that have names with the same prefix as the generic name.
Qualifier 2: User
- *ALL
- All jobs that match the specified job name are included.
- name
- Specify the name of the user of the job to be included.
- generic-name
- Specify the generic user name of the jobs to be included.
Qualifier 3: Number
- *ALL
- All jobs that match the specified job name and user name are included.
- number
- Specify the job number to further qualify the job name and user name.
| Top |
Task name (TASKNAME)
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
- *ALL
- All tasks on the system will be included in the collection.
- *NONE
- None of the tasks on the system will be included in the collection.
Other values (up to 20 repetitions)
- name
- Specify the name of the tasks(s) which will be included in the collection.
| Top |
TDE number (TDENBR)
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.
- number
- The TDE number of the TDE(s) which will be included in the collection.
| Top |
Current user profile (CURUSRPRF)
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.
- name
- The current user profile name of the jobs which will be included in the collection. Only jobs which are running under the specified current user profile during the interval will be included in the collection.
| Top |
Subsystem (SBS)
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.
- name
- The name of the subsystem of the jobs which will be included in the collection. Only jobs which are running in the specified subsystem at the time data is gathered will be included in the collection.
| Top |
Current storage pool (CURPOOL)
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.
- 1-64
- The current pool number of the jobs and/or tasks which will be included in the collection. Only jobs and/or tasks which are running in the specified pool at the time data is gathered will be included in the collection.
| Top |
Force record write (FRCRCD)
Specifies when data records will be written to the Job Watcher database files.
- *ITVEND
- Collected data will be written to the database files at the end of each interval.
- *CALC
- Collected data will be written to the files at a time determined by the system. Data will always be available in the files after data collection is ended.
| Top |
Include inactive jobs/tasks (INCALLFST)
Specifies whether detailed data for all jobs and tasks, including inactive jobs and tasks, will be collected for the first interval.
- *NO
- Inactive jobs and tasks will not be collected on the first interval.
- *YES
- Inactive jobs and tasks will be collected on the first interval. This option will provide detailed information about the jobs and tasks that are waiting at the time the collection started. This information would otherwise not be available until an interval in which the job or task becomes active. Collecting this additional information may cause the duration of the first interval to be significantly larger than the rest of the collection.
| Top |
To file ASP threshold (TOASPTHLD)
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.
- *SYSTEM
- The threshold which is configured on the system for this ASP. This value is a percentage which is configured using the Change Storage Threshold function of the Start System Service Tools (STRSST) command. Data collection will be forced to end if this percentage of the ASP storage is consumed.
- 1-99
- The percentage of the database files' ASP which may be used before data collection will be forced to end. For example, if you specify 80, data collection will be forced to end if more than 80% of the ASP storage is consumed. A value specified on this parameter will override the threshold which is configured on the system.
| Top |
System ASP threshold (SYSASPTHLD)
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.
- *SYSTEM
- The threshold which is configured on the system for the system ASP. This value is a percentage which is configured using the Change Storage Threshold function of the Start System Service Tools (STRSST) command. Data collection will be forced to end if this percentage of the system ASP storage is consumed.
- 1-99
- The percentage of the system ASP which may be used before data collection will be forced to end. For example, if you specify 80, data collection will be forced to end if more than 80% of the system ASP storage is consumed. A value specified on this parameter will override the threshold which is configured on the system.
| Top |
Condition control file (CONDCTLF)
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
- *NONE
- No condition will be specified for the Job Watcher collection.
Qualifier 1: File
- name
- Specify the name of the file which contains the condition information.
Qualifier 2: Library
- name
- Specify the name of the library which contains the condition control file.
| Top |
Condition control member (CONDCTLMBR)
Specifies the file member which contains the condition information.
- *FIRST
- The first member in the file will be used.
- name
- Specify the name of the member which contains the condition information.
| Top |
Condition type (CONDTYPE)
Specifies the type of conditional collection.
- *PERITV
- The specified condition will be checked in every interval. In this type of collection, data will only be written to the database files for intervals in which the condition was satisfied. If an exit program is specified on the on the User exit program (EXITPGM) parameter it will be called in each interval where the condition was satisfied.
- *TRIGGER
- The specified condition will be checked in each interval until the condition is satisfied. Once the condition has been met, data will be unconditionally written to the database files for the remainder of the collection. If an exit program is specified on the on the User exit program (EXITPGM) parameter it will be called one time in the interval where the condition was satisfied.
- *UNTILMET
- Data will be unconditionally written to the database files until the condition is satisfied. Once the condition has been met, the collection will end. If an exit program is specified on the on the User exit program (EXITPGM) parameter it will be called one time before the collection ends.
| Top |
Timeout option (TIMEOUT)
Specifies how long the collection should run without writing any data to the database files.
Single values
- *NONE
- The collection will not time out.
Element 1: Option
- *NBRSEC
- The collection will time out after the number of seconds specified in element 2 of this parameter has elapsed without the condition being met.
- *NBRITV
- The collection will time out after the number of intervals specified in element 2 of this parameter have been collected without the condition being met.
Element 2: Value
- integer
- Specify the number of seconds (for *NBRSEC) or the number of intervals (for *NBRITV) to use as the timeout criteria for the conditional collection.
| Top |
Consecutive occurrence count (OCCURS)
Specifies number of consecutive intervals in which the specified condition must occur before it is considered satisfied.
- 1
- The condition must occur in one interval to be considered satisfied.
- integer
- Specify the number of consecutive intervals in which the condition must occur.
| Top |
History size (HSTSIZE)
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.
- 0
- No history data will be buffered.
- integer
- Specify the number of intervals which should be buffered as history.
| Top |
User exit program (EXITPGM)
Specifies the user exit program which will be called at the time the condition is satisfied.
Single values.
- *NONE
- No exit program will be called.
Qualifier 1: User exit program
- name
- Specify the name of the user exit program.
Qualifier 2: Library
- name
- Specify the name of the library where the user exit program is located.
| Top |
Exit program data (EXITPGMDTA)
Specifies any data which should be passed to the user exit program specified on the User exit program (EXITPGM) parameter.
- *NONE
- No data will be passed to the user exit program.
- character-value
- Specify any data which should be passed to the user exit program.
| Top |
Examples
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 |
Error messages
*ESCAPE Messages
- CPFAF10
- Definition or filter already exists.
- CPFB518
- The user does not have the required authority.
| Top |