Start Disk Watcher (STRDW)
| Where allowed to run: All environments (*ALL) Threadsafe: No |
Parameters Examples Error messages |
The Start Disk Watcher (STRDW) command starts the collection of disk performance data. It allows the user to obtain data including counts and durations of input/output (I/O) operations to disk units. In addition, it provides useful run-time data regarding which objects are being read from disk or written to disk, and which jobs, threads, or LIC tasks are causing the operations. The collected data is written to a set of database files. The file names all begin with the letters 'QAPYDW'.
Restrictions:
- To use this command, you must have service (*SERVICE) special authority, or be authorized to the Disk Watcher function of the operating system. The Change Function Usage (CHGFCNUSG) command, with a function ID of QIBM_SERVICE_DISK_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 | 1-3600, *DFN, *DYN | Optional |
| ENDCOL | End collection | Values (up to 3 repetitions): Element list | Optional |
| Element 1: Option | *NBRSEC, *DASDMB, *NBRITV | ||
| Element 2: Value | Integer, 60 | ||
| HDWF | Hardware file | *YES, *NO | Optional |
| Top |
Definition (DFN)
Specifies the Disk Watcher definition to use when starting a new Disk Watcher collection. The definition identifies the disk I/O data to be collected. A new Disk Watcher definition can be created using the Add Disk Watcher Definition (ADDDWDFN) command.
- *SELECT
- The user will be prompted to select from a list of existing Disk Watcher definitions.
- name
- Specify the name of the Disk 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 is to be written. If a member by this name does not exist in each Disk 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 STRDW command was run. 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 disk I/O data collection was started.
- name
- Specify the name of the collection.
| Top |
Library (LIB)
Specifies the library where the database files for the Disk Watcher data are to 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 Disk Watcher database files associated with the collection.
- *DFN
- Disk Watcher database file members will have the same text description as the Disk Watcher definition that was selected on the Definition (DFN) parameter.
- *BLANK
- Disk Watcher database file members will have no text description.
- character-value
- Specify the text description for this set of Disk 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 Disk Watcher database file members should be replaced with a new set of members with the same name.
- *NO
- The existing Disk Watcher database file members will not be replaced. A new Disk Watcher collection will not begin if the specified member already exists.
- *YES
- The existing Disk Watcher database file members will be replaced with data from the new collection.
| Top |
Collection interval (COLITV)
Specifies the interval between retrieval of disk I/O data.
- *DFN
- The collection interval specified in the Disk Watcher definition will be used for this collection.
- *DYN
- The time interval between samples is dynamic. This indicates that the interval seconds will be adjusted to the optimal value and may change during the collection. The optimal value is the largest interval time that can be used without missing data.
- 1-3600
- Specify the number of seconds between intervals.
| 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 ending criteria is specified, disk I/O data collection will end the first time any one of specified criteria has been met.
You can specify 3 values for this parameter.
Element 1: Option
- *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 have been written to the Disk Watcher database files. Specify the megabyte limit in element 2 of this parameter.
- *NBRITV
- End the collection when a number of collection intervals have 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 disk I/O 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 disk I/O data collection.
| Top |
Hardware file (HDWF)
Specifies whether data will be written to the QAPYDWHDWR file for this collection. This file contains storage device resource information provided by the Display Hardware Resources (DSPHDWRSC) command.
- *YES
- Storage device resource information will be written to the QAPYDWHDWR file for this collection. The name of the QAPYDWHDWR file member will be the name specified on the Collection (COL) parameter.
- *NO
- Storage device resource information will not be written to the QAPYDWHDWR file for this collection.
| Top |
Examples
Example 1: Start a Disk Watcher Collection
STRDW DFN(MYDFN) COL(TEST) LIB(MYLIB)
This command will start Disk Watcher using definition MYDFN to determine which data should 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 Disk Watcher database files in library MYLIB in member TEST. The Disk Watcher database file names all begin with 'QAPYDW'.
Example 2: Start Disk Watcher Using a Collection Interval
STRDW DFN(MYDFN) COLITV(5) ENDCOL((*NBRITV 200))
This command will start Disk 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 Disk Watcher database files in library QPFRDATA in a member name which will be generated by Disk Watcher based on the date and time the collection started.
Example 3: Start Disk Watcher, Prompting to Select a Definition
STRDW DFN(*SELECT) COL(TEST) LIB(MYLIB)
ENDCOL((*DASDMB 100))
This command will open a prompt panel listing all Disk 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 Disk 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.
- CPFB511
- Disk Watcher could not start due to reason code &1.
- CPFB512
- Start Disk Watcher did not complete successfully.
- CPFB513
- The user does not have the required authority.
- CPFB514
- Member already exists.
- CPFB515
- Not enough storage in machine pool.
- CPFB51B
- Option *SELECT is only valid if the command is being run interactively.
| Top |