Add Disk Watcher Definition (ADDDWDFN)
| Where allowed to run: All environments (*ALL) Threadsafe: No |
Parameters Examples Error messages |
The Add Disk Watcher Definition (ADDDWDFN) command adds a new Disk Watcher definition to the system. A Disk Watcher definition identifies the performance data that is to be collected during a Disk Watcher collection. A session can be started using the Start Disk Watcher (STRDW) command. A definition is required when starting a new Disk Watcher collection.
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.
| Top |
Parameters
| Keyword | Description | Choices | Notes |
|---|---|---|---|
| DFN | Definition | Name | Required, Positional 1 |
| TEXT | Text 'description' | Character value, *BLANK | Optional |
| COLITV | Collection interval | 1-3600, *DYN | Optional |
| ASP | ASP number | Single values: *ALL, *ASPDEV Other values (up to 10 repetitions): 1-255, *SYS |
Optional |
| ASPDEV | ASP device | Name | Optional |
| DSKUNIT | Disk unit identifier | Single values: *ALL Other values (up to 10 repetitions): 1-6047 |
Optional |
| POOLID | Storage pool identifier | 1-64, *ALL | Optional |
| TYPE | Type | *STATS, *ALL, *TRACE | Optional |
| IOTYPE | I/O type | *ALL, *READ, *WRITE | Optional |
| OBJINF | Object information | *NONE, *ALL, *RESIDENT | Optional |
| COLCOND | Collection condition | Single values: *NONE Other values: Element list |
Optional |
| Element 1: Data type | *RESPTIME, *QTIME, *SERVTIME | ||
| Element 2: Relational operator | *LT, *GT, *LE, *GE | ||
| Element 3: Value | Integer | ||
| COLRNG | Collection range | Single values: *NONE Other values: Element list |
Optional |
| Element 1: Data type | *RESPTIME, *QTIME, *SERVTIME | ||
| Element 2: Lower value | Integer | ||
| Element 3: Upper value | Integer | ||
| FRCRCD | Force record write | *ITVEND, *CALC | Optional |
| TOASPTHLD | To file ASP threshold | 1-99, *SYSTEM | Optional |
| SYSASPTHLD | System ASP threshold | 1-99, *SYSTEM | Optional |
| Top |
Definition (DFN)
Specifies the name of the Disk 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 Disk Watcher definition.
| Top |
Text 'description' (TEXT)
The text description of the Disk Watcher definition to be added.
- *BLANK
- The Disk Watcher definition will have no text description.
- character-value
- Specify the text description for this Disk 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 disk I/O data.
Note: Disk data is collected from a wrapping flight recorder. If the value specified for this parameter is too large, I/O operations may be missed. The record format for Disk Watcher database file QAPYDWINTI includes a field ('Data missed') which indicates whether I/O operations were missed during the interval.
- *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 |
ASP number (ASP)
Specifies the auxiliary storage pools for which disk I/O information will be collected. Selected ASPs must be varied on in order for data collection to occur.
Single values
- *ALL
- Disk I/O information will be collected for all ASPs on the system.
- *ASPDEV
- Disk I/O information will be collected for the independent ASP specified for the ASP device (ASPDEV) parameter.
Note: A value must be specified for the ASPDEV parameter if this value is specified.
Other values (up to 10 repetitions)
- *SYS
- Disk I/O information will be collected for only the system ASP (ASP 1).
- 1-255
- Specify the ASP number for which disk I/O information will be collected.
| Top |
ASP device (ASPDEV)
Specifies the independent auxiliary storage pool (ASP) device for which disk I/O information should be collected.
Note: A value must be specified for this parameter if *ASPDEV is specified for the ASP number (ASP) parameter.
- name
- Specify the name of the independent ASP device for which disk I/O information should be collected. The device description associated with the independent ASP must be varied on and have a status of 'Available' in order for data collection to occur.
| Top |
Disk unit identifier (DSKUNIT)
Specifies the disk units for which I/O information should be collected. Disk unit identifiers from 4001 through 6047 are reserved for independent auxiliary storage pools.
Single values
- *ALL
- Disk I/O information will be collected for all disk units in the auxiliary storage pools specified by the ASP number (ASP) or ASP device (ASPDEV) parameter.
Other values (up to 10 repetitions)
- 1-6047
- Specify the numeric identifier of each disk unit for which disk I/O information will be collected.
| Top |
Storage pool identifier (POOLID)
Specifies the main memory storage pool for which disk I/O information should be collected as data is read from disk into memory or written from memory back to disk. This parameter is a value ranging from 1 through 64, where pool 1 is the machine pool, and pool 2 is the base pool. This value also corresponds to the identifier shown on the Work with System Status (WRKSYSSTS) display.
Single values
- *ALL
- Disk I/O information will be collected for all storage pools.
Other values
- 1-64
- Specify the pool number of the storage pool for which disk I/O information will be collected.
| Top |
Type (TYPE)
Specifies the type of disk I/O collection to be performed. This determines the detail level of the data which will be collected.
Note: Disk data is collected from a wrapping flight recorder. If the value specified for the Collection interval (COLITV) parameter is too large, I/O operations may be missed. The record format for Disk Watcher database file QAPYDWINTI includes a field ('Data missed') which indicates whether I/O operations were missed during the interval.
- *STATS
- A statistics collection will be performed. This type of collection will summarize the I/O data into a set of counters based on the type of I/O operation. A statistics collection will always include all I/O operations on the system. This means that the I/O operations included in the statistics data will not be limited by values specified for the Collection condition (COLCOND) or Collection range (COLRNG) parameters.
Data for a statistics collection is written to database files QAPYDWRUNI, QAPYDWINTI, and QAPYDWSTAT in the library specified for the Library (LIB) parameter.
- *ALL
- Both statistics and trace data will be collected and written to the Disk Watcher database files.
- *TRACE
- A trace collection will be performed. This type of collection will gather data for every I/O which occurred on the specified ASP or disk unit(s). The trace data collected with this option may be limited to I/O operations which meet a certain condition. To collect a limited set of trace data, either specify a condition on the Collection condition (COLCOND) parameter or a range on the Collection range (COLRNG) parameter.
Data for a trace collection is written to the database files QAPYDWRUNI, QAPYDWINTI, QAPYDWTRC, and QAPYDWTDER in the library specified for the Library (LIB) parameter. Additionally, data will be written to the database files QAPYDWPGMR and QAPYDWOBJR if *ALL or *RESIDENT is specified for the Object information (OBJINF) parameter.
| Top |
I/O type (IOTYPE)
Specifies whether the I/O trace data collected should be limited to a particular type of I/O operation.
Note: This parameter will only limit the collection of I/O trace data. Statistics data will always include all I/O operations.
- *ALL
- All types of disk I/O operations will be included in the disk I/O trace data.
- *READ
- Only operations that read data from disk storage will be included in the disk I/O trace data.
- *WRITE
- Only operations that write data to disk storage will be included in the disk I/O trace data.
| Top |
Object information (OBJINF)
Specifies whether Disk Watcher will gather object and program information, such as the object name and program name, and whether this data collection will be limited to objects and programs which are in resident storage.
During *TRACE collections, Disk Watcher collects information related to the object on which the I/O operation was performed. When this object is in resident storage, the time required to gather the data is relatively small. However, if the object is not in resident storage, there will be a more significant performance impact associated with gathering this information. The same is true when collecting information related to the program or procedure which initiated the I/O operation.
- *NONE
- Object and program information will not be collected for any objects or programs.
- *ALL
- Object and program information will be collected for all objects and programs. This includes data for objects and programs which are not in resident storage.
- *RESIDENT
- Object and program information will only be collected for objects and programs which are in resident storage.
| Top |
Collection condition (COLCOND)
Specifies whether the I/O trace data collected should be limited to I/O operations which meet a specified condition.
Note: This parameter will only limit the collection of I/O trace data. Statistics data will always include all I/O operations.
Note: Either a single limiting value may be specified for this parameter or a range may be specified for the COLRNG parameter. You cannot specify values for both parameters.
Single values
- *NONE
- No limiting condition is specified.
Element 1: Data type
- *RESPTIME
- The conditional trace data collection will be based on the total response time of the I/O operation.
- *QTIME
- The conditional trace data collection will be based on the queue (wait) time of the I/O operation.
- *SERVTIME
- The conditional trace data collection will be based on the service time of the I/O operation.
Element 2: Relational operator
- *LT
- Collect trace records for disk I/O operations that took less than the number of microseconds specified for element 3 of this parameter.
- *GT
- Collect trace records for disk I/O operations that took more than the number of microseconds specified for element 3 of this parameter.
- *LE
- Collect trace records for disk I/O operations that took not more than the number of microseconds specified for element 3 of this parameter.
- *GE
- Collect trace records for disk I/O operations that took not less than the number of microseconds specified for element 3 of this parameter.
Element 3: Value
- integer
- Specify the number of microseconds to use to limit trace record collection.
| Top |
Collection range (COLRNG)
Specifies whether the I/O trace data collected should be limited to I/O operations which are within a range of time values.
Note: This parameter will only limit the collection of I/O trace data. Statistics data will always include all I/O operations.
Note: Either a single limiting value may be specified for the Collection condition (COLCOND) parameter or a range may be specified for this parameter. You cannot specify values for both parameters.
Single values
- *NONE
- No limiting range is specified.
Element 1: Data type
- *RESPTIME
- The conditional trace data collection will be based on the total response time of the I/O operation.
- *QTIME
- The conditional trace data collection will be based on the queue (wait) time of the I/O operation.
- *SERVTIME
- The conditional trace data collection will be based on the service time of the I/O operation.
Element 2: Lower value
- integer
- Specify the lower limit of a range to determine which I/O operations will be included in the trace collection.
Element 3: Upper value
- integer
- Specify the upper limit of a range to determine which I/O operations will be included in the trace collection.
| Top |
Force record write (FRCRCD)
Specifies when disk I/O data records will be written to the Disk 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 disk I/O data collection is ended.
| Top |
To file ASP threshold (TOASPTHLD)
Specifies the percentage of the auxiliary storage pool (ASP) that contains the Disk 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
- Specify the percentage of the database files' ASP which may be used before disk I/O 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 Disk 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
- Specify the percentage of the system ASP which may be used before disk I/O 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 |
Examples
Example 1: Add a Disk Watcher Definition Which Collects Data for Specific ASPs
ADDDWDFN DFN(ASPNBR) ASP(2 16) TYPE(*STATS) COLITV(5)
This command will create a Disk Watcher definition called ASPNBR. This definition will collect summarized statistics data for auxiliary storage pool (ASP) 2 and ASP 16. Data will be collected at an interval of 5 seconds and will include all I/O operations which occur in the specified ASPs. To collect Disk Watcher data using this definition use the Start Disk Watcher (STRDW) command with ASPNBR specified for the Definition (DFN) parameter.
Example 2: Add a Disk Watcher Definition Which Collects Data for a Specific Disk Unit
ADDDWDFN DFN(DSKNBR) ASP(*SYS) DSKUNIT(12) TYPE(*ALL)
This command will create a Disk Watcher definition called DSKNBR. This definition will collect data for disk unit 12 in the system auxiliary storage pool (ASP). Both detailed trace data and summarized statistics data will be collected. To collect Disk Watcher data using this definition use the Start Disk Watcher (STRDW) command with DSKNBR specified for the Definition (DFN) parameter.
Example 3: Add a Disk Watcher Definition Which Traces Only I/O Operations Which Meet a Collection Condition
ADDDWDFN DFN(RESPTIME) COLTYPE(*TRACE)
COLCOND(*RESPTIME *GT 100)
In this example, a Disk Watcher definition called RESPTIME will be created. This definition will collect data for all ASPs on the system and only trace data will be collected. The I/O operation data collected for the trace will include only those disk operations whose total response time was greater than 100 microseconds. To collect Disk Watcher data using this definition use the Start Disk Watcher (STRDW) command with RESPTIME specified for the Definition (DFN) parameter.
Example 4: Add a Disk Watcher Definition Which Traces Only I/O Write Operations
ADDDWDFN DFN(WRITEOPS) TYPE(*TRACE) IOTYPE(*WRITE)
In this example, a Disk Watcher definition called WRITEOPS will be created. This definition will collect data for all ASPs on the system. Only trace data for I/O operations which write disk data to storage will be collected. To collect Disk Watcher data using this definition use the Start Disk Watcher (STRDW) command with WRITEOPS specified for the Definition (DFN) parameter.
| Top |
Error messages
*ESCAPE Messages
- CPF0001
- Error found on &1 command.
- CPFAF10
- Definition or filter already exists.
- CPFB513
- The user does not have the required authority.
- CPFB51C
- Error on Add Disk Watcher Definition (ADDDWDFN) command.
| Top |