Start Job Watcher (STRJW)
| Where allowed to run: All environments (*ALL) Threadsafe: No |
Parameters Examples Error messages |
The Start Job Watcher (STRJW) command starts the collection of detailed job performance data. It allows the user to obtain detailed data related to a selected set of jobs or tasks on the system. Job Watcher collects data on a sampling basis and writes the collected data to a set of database files. The file names all begin with the letters 'QAPYJW'. In addition to basic job information the user may optionally request SQL, activation group, sockets and TCP, and call stack data.
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.
- You must have execute (*EXECUTE) authority to the library specified in the Library (LIB) parameter.
| Top |
Parameters
| Keyword | Description | Choices | Notes |
|---|---|---|---|
| DFN | Definition | Name, *SELECT | Optional |
| COL | Collection | Name, *GEN | Optional |
| LIB | Library | Name, QPFRDATA | Optional |
| TEXT | Text 'description' | Character value, *DFN, *BLANK | Optional |
| RPLDTA | Replace data | *NO, *YES | Optional |
| COLITV | Collection interval | 0.1-3600.0, *DFN, *NODELAY | Optional |
| ENDCOL | End collection | Single values: *NOITVDTA Other values (up to 3 repetitions): Element list |
Optional |
| Element 1: Option | *NBRSEC, *DASDMB, *NBRITV | ||
| Element 2: Value | Integer, 60 | ||
| JOB | Job name | Single values: *DFN, *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: *DFN, *ALL, *NONE Other values (up to 20 repetitions): Character value |
Optional |
| TDENBR | TDE number | Single values: *DFN Other values (up to 20 repetitions): Hexadecimal value |
Optional |
| Top |
Definition (DFN)
Specifies the Job Watcher definition to use when starting a new Job Watcher collection. The definition identifies the parameters to use when starting a Job Watcher collection. A new Job Watcher definition can be created using the Add Job Watcher Definition (ADDJWDFN) command.
- *SELECT
- The user will be prompted to select from a list of existing Job Watcher definitions. This value is not valid when the STRJW command is submitted to batch and will result in an error.
- name
- Specify the name of the Job Watcher definition to use for this collection.
| Top |
Collection (COL)
Specifies the name of the collection. The name of the collection is the name of the database file member to which the output data will be written. If a member by this name does not exist in each Job Watcher database file, one will be created with the specified name. If a member by this name already exists, you must specify *YES on the Replace data (RPLDTA) parameter in order to write over the data in the existing member.
- *GEN
- The collection name will be generated based on when the STRJW command was called. The format of the collection name will be Qdddhhmmss where ddd is the Julian day (001-366) and hhmmss is the hour (01-24), minute (00-59) and second (00-59) the collection was started.
- name
- Specify the name of the collection.
| Top |
Library (LIB)
Specifies the library where the database files for the Job Watcher data will exist. Each file that is not found in the specified library is automatically created in that library.
- QPFRDATA
- The database files will be located in library QPFRDATA.
- name
- Specify the name of the library where the database files will be located.
| Top |
Text 'description' (TEXT)
Specifies the text to be used for each member across the set of Job Watcher database files associated with the collection.
- *DFN
- Job Watcher database file members will have the same text description as the Job Watcher definition that was selected on the Definition (DFN) parameter.
- *BLANK
- Job Watcher database file members will have no text description.
- character-value
- Specify a text description for this set of Job Watcher database file members. The description should be no more that 50 characters of text, enclosed in apostrophes.
| Top |
Replace data (RPLDTA)
Specifies whether an existing set of Job Watcher database file members should be replaced with a new set of members with the same name.
- *NO
- The existing Job Watcher database file members will not be replaced. A new Job Watcher collection will not begin if the specified member already exists.
- *YES
- The existing Job Watcher database file members will be replaced with data from the new collection.
| 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.
- *DFN
- The collection interval specified in the Job Watcher definition will be used for this collection.
- *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 |
End collection (ENDCOL)
Specifies the criteria which will end the collection. This parameter allows you to specify multiple conditions which will end the collection of data. If more than one end option is specified, the Job Watcher collection will end the first time any one of the specified criteria has been met.
You can specify 3 values for this parameter.
Element 1: Option
Single values
- *NOITVDTA
- End the collection after the first interval in which no records were collected.
Other values
- *NBRSEC
- End the collection after a number of seconds has elapsed. Specify the time limit in element 2 of this parameter.
- *DASDMB
- End the collection when a number of megabytes of data has been written to the Job Watcher database files. Specify the megabyte limit in element 2 of this parameter.
- *NBRITV
- End the collection when a number of collection intervals has occurred. Specify the number of intervals in element 2 of this parameter.
Element 2: Value
- 60
- If the default of *NBRSEC is used for element 1 of this parameter, the collection will end after sixty seconds of data is collected.
- integer
- Specify the number of seconds (for *NBRSEC) or the number of megabytes (for *DASDMB) or the number of intervals (for *NBRITV) to use as the ending criteria for the collection.
| Top |
Job name (JOB)
Specifies the jobs that will be included in the Job Watcher collection. If a value is specified on this parameter it will override the value in the Job Watcher definition.
Single values
- *DFN
- The jobs specified in the Job Watcher definition will be used for this collection.
- *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. If a value is specified on this parameter it will override the value in the Job Watcher definition.
Single values
- *DFN
- The tasks specified in the Job Watcher definition will be used for this collection.
- *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 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). If a value is specified on this parameter it will override the value in the Job Watcher definition.
Single values
- *DFN
- The TDE numbers specified in the Job Watcher definition will be used for this collection.
Other values (up to 20 repetitions)
- number
- The TDE number of the TDEs which will be included in the collection.
| Top |
Examples
Example 1: Start Job Watcher Using a Definition
STRJW DFN(MYDFN) COL(TEST) LIB(MYLIB)
This command will start a Job Watcher collection using the definition called MYDFN to determine which data will be collected. Assuming the shipped default of ENDCOL(*NBRSEC 60) is used, data collection will end after 60 seconds. Collected data will be written to the Job Watcher database files in library MYLIB in member TEST. The Job Watcher database file names all begin with 'QAPYJW'.
Example 2: Start Job Watcher Using a Collection Interval
STRJW DFN(MYDFN) COLITV(5) ENDCOL((*NBRITV 200))
This command will start Job Watcher to collect data using the definition called MYDFN. Data will be collected at an interval of 5 seconds, overriding the interval specified in the definition. Data collection will end after 200 intervals have been collected. Data will be written to the Job Watcher database files in library QPFRDATA in a member name which will be generated by Job Watcher based on the date and time the collection started.
Example 3: Start Job Watcher, Prompting to Select a Definition
STRJW DFN(*SELECT) COL(TEST) LIB(MYLIB)
ENDCOL((*DASDMB 100))
This command will open a prompt panel listing all Job Watcher definitions which currently exist on the system. The definition selected on this panel will be used to determine what data will be collected. Data collection will end after 100 megabytes of data have been written to the Job Watcher database files in library MYLIB in member TEST.
| Top |
Error messages
*ESCAPE Messages
- CPF2401
- Not authorized to library &1.
- CPF9810
- Library &1 not found.
- CPFB514
- Member already exists.
- CPFB517
- Unexpected error in Job Watcher.
- CPFB518
- The user does not have the required authority.
- CPFB519
- Error detected in Job Watcher condition control file.
- CPFB51A
- Start Job Watcher did not complete successfully.
- CPFB51B
- Option *SELECT is only valid if the command is being run interactively.
| Top |