Control statement keywords1
The following table lists the keywords you can code on the GLBL, SETUP, and SPACE control statements, along with their valid and default values.
The use of many of these keywords depends on the value you specify for the TYPE keyword. You can use the keyword if the TYPE value is set as indicated.
Table 1. PCPSPACE control statement keywords
Keyword Panel field | Valid value | Initial default | GLBL | SETUP TYPE | SPACE TYPE | Reference |
|---|---|---|---|---|---|---|
BITMAP | Y N | N | NA | NA | CAPTURE | |
CAPTURE | Y N | N | NA | CHANGE | NA | |
DBD | dbdname (1-8 characters; wildcards valid) | None | NA | ADD CHANGE DELETE | CAPTURE REPORT PURGE | |
DBRC | Y N | N | NA | ADD CHANGE | NA | |
DSN | data.set.name (up to 44 characters) | None | NA | ADD CHANGE | NA | |
IMSID | imsid (1-4 characters; wildcards valid with TYPE(CHANGE) and TYPE(DELETE) only) | None | Available | ADD CHANGE DELETE | CAPTURE REPORT PURGE | |
KEEPDAYS | nnnn (1- 9999) | 10 | NA | ADD CHANGE | PURGE | |
KEEPSETS | nnnn (1- 9999) | 10 | NA | ADD CHANGE | PURGE | |
REPORTS | keyword(value) ... keyword(value) | See the other REPORTS keywords | NA | NA | CAPTURE REPORT | |
REPORTS ALLOC | Y N | N | NA | NA | REPORT | |
REPORTS SETUP | Y N | N | NA | NA | REPORT | |
REPORTS TREND | Y N | N | NA | NA | REPORT | |
REPORTS USAGE | A Y or L N | Y if you omit REPORTS keyword; N if you include REPORTS keyword | NA | NA | CAPTURE REPORT | |
SCAN | Y N | N | NA | ADD CHANGE DELETE | NA | |
THRESH | keyword(value) ... keyword(value) | See the other THRESH keywords | NA | ADD CHANGE | NA | |
THRESH AVAILEXT | 0 (do not monitor) nn (where nn is 1-16) | 0 | NA | ADD CHANGE | NA | |
THRESH CASPLIT % CA Split | 0 (do not monitor) nn (where nn is 1-99) | 0 | NA | ADD CHANGE | NA | |
THRESH CISPLIT % CI Split | 0 (do not monitor) nn (where nn is 1-99) | 0 | NA | ADD CHANGE | NA | |
THRESH LASTEXT Warn on Last Extent | Y N | N | NA | ADD CHANGE | NA | |
THRESH SPACEUSE % Space Used | 0 (do not monitor) nn (where nn is 1-99) | 0 | NA | ADD CHANGE | NA | |
THRESH USEDEXT Used Extents | 0 (do not monitor) nn (where nn is 1-16) | 0 | NA | ADD CHANGE | NA | |
TYPE | ADD CHANGE DELETE CAPTURE REPORT PURGE | None | Available | ADD CHANGE DELETE | CAPTURE REPORT PURGE | |
USERID | userid, ... userid | None | Available | NA | NA | |
VOLUME | N Y,print (where print is NONE, ALL, EX, STAT) | N | Available | NA | NA |
BITMAP
Optional on the SPACE control statement with TYPE(CAPTURE).
Use the BITMAP keyword to control the production of the Bitmap report when capturing current data set space usage statistics for the database(s) being processed. PCPSPACE writes this report to the data set described by the BITMAP DD statement. See Bitmap-Detail-report for information about this report. To produce the Bitmap report, PCPSPACE uses the DBD; you must provide the IMS DD statement to describe the DBD library. The following values are valid:
Y
Produce the Bitmap Report.
N
Do not produce the report.
The default value is N.
CAPTURE
Optional on the SETUP control statement with TYPE(CHANGE).
Use the CAPTURE keyword to control the capture of current data set space usage statistics when you change threshold setup for the database(s). The following values are valid:
Y
Capture new statistics.
N
Do not capture new statistics.
The default value is N. However, PCPSPACE always captures statistics if you are changing the threshold set to add a new data set group or if a data set name changes.
DBD
Required on the SETUP control statement.
Optional on the SPACE control statement; if you omit it, PCPSPACE selects all databases registered for space monitoring in the PDX data set. Provide the DBD name of the database(s) to be processed. This name can be a specific DBD name, or it can be a generic name you create with the wildcard character asterisk (*) and/or the masking character plus sign (+):
*
Multiple position wildcard value. Matches any number of characters (0-8) in the DBD name. For example, to select all DBD names, specify DBD(*). To select all DBD names that start with A and end with B, specify DBD(A*B).
+
Single position masking value. Allows any value at the corresponding position in the DBD name. For example, to select all five-character DBD names, specify DBD(+++++). To select any DBD names in which the first character is A and the fourth (and last) character is B, specify DBD(A++B).
You can combine use of the wildcard and masking characters. For example, to select any DBD name in which the third (but not necessarily last) character is A, specify DBD(++A*).
DBRC
Optional on the SETUP control statement with TYPE(ADD) and TYPE(CHANGE).
Use the DBRC keyword to control whether PCPSPACE attempts to resolve the data set names from the RECON data sets, as described in Building-data-set-names. The default value is N.
Y
Use the RECON data sets to resolve data set names.
N
Do not use the RECON data sets.
DSN
Optional on the SETUP control statement with TYPE(ADD) and TYPE(CHANGE).
Use the DSN keyword to provide the data set name that PCPSPACE will use if it cannot determine data set name from any other source, as described in Building-data-set-names. The data set name you provide can contain up to 44 characters, including periods. You can include the following variables where appropriate, and PCPSPACE will substitute the current value of the variable:
&DBD
PCPSPACE replaces &DBD with the DBD name.
&DD
PCPSPACE replaces &DD with the ddname.
For example, if you code DSN(IMSVS.V13.&DBD.&DD) on the SETUP control statement, the current DBD name is HDAMDB, and the ddname is HDAMDD1, PCPSPACE sets the data set name in the record to IMSVS.V13.HDAMDB.HDAMDD1.
IMSID
Required (however, you only need to provide the IMSID keyword once on either the GLBL, SETUP, or SPACE control statement).
Provide the IMSID (1-4 characters) associated with the space monitor records to process. If the value of the TYPE keyword is CHANGE, DELETE, CAPTURE, REPORT, or PURGE, you can provide a specific IMSID, or you can select multiple IMSIDs by using the wild card character asterisk (*) and/or the masking character plus sign (+):
*
Multiple position wild card value. Matches any number of characters (0-4) in the IMSID. For example, to select all IMSIDs, specify IMSID(*). To select all IMSIDs that start with A and end with B, specify IMSID(A*B).
+
Single position masking value. Allows any value at the corresponding position in the IMSID. For example, to select all four-character IMSIDs, specify IMSID(++++). To select any IMS ID in which the first character is A and the fourth (and last) character is B, specify IMSID(A++B).
You can combine use of the wild card and masking characters. For example, to select any IMSID in which the second (but not necessarily last) character is A, specify IMSID(+A*).
If the value of the TYPE keyword is ADD, you cannot use wild card characters in the value of the IMSID keyword.
KEEPSETS
Optional on the SETUP statement with TYPE(ADD) and TYPE(CHANGE).
Also optional on the SPACE statement with TYPE(PURGE). Use the KEEPSETS keyword to specify the total number of sets of statistics you want to keep. (A set of statistics is the data that was captured at a particular date and time for a particular DBD.) When a pointer checking function or the PCPSPACE program adds a new set of statistics and the total number of sets for the IMSID/DBD exceeds the specified number, PCP deletes the oldest set of statistics. The value of the KEEPSETS keyword can be an integer in the range 1-9999 inclusive.
You cannot code the KEEPDAYS and KEEPSETS keywords on the same control statement. If you code neither the KEEPSETS nor KEEPDAYS keyword on a control statement that contains TYPE(ADD), the default value is 10 sets.
KEEPDAYS
Optional on the SETUP statement with TYPE(ADD) and TYPE(CHANGE).
Also optional on the SPACE statement with TYPE(PURGE). Use the KEEPDAYS keyword to specify the number of days to keep a set of statistics. After this length of time has elapsed, PCP deletes the outdated statistic set for the IMSID/DBD when a new set is created by a pointer checking function or the PCPSPACE program. The value of the KEEPDAYS keyword can be an integer in the range 1-9999 inclusive.
You cannot code the KEEPDAYS and KEEPSETS keywords on the same control statement. If you code neither the KEEPSETS nor KEEPDAYS keyword on a control statement that contains TYPE(ADD), the default value is 10 sets.
REPORTS
Optional on the SPACE statement.
Use this keyword with one or more of the following keywords to control reporting from the PCPSPACE process:
- ALLOC
- SETUP
- TREND
- USAGE
Code these keywords and their values in parentheses as the value of the REPORTS keyword, as the following example illustrates:
The following sections describe the REPORTS keywords and values.
REPORTS ALLOC
Optional on the SPACE statement with TYPE(REPORT).
Use the REPORTS ALLOC keyword to control the printing of space allocation information for each data set for the selected DBD(s). The statistics reflect information from last capture. The following values are valid:
Y
Print the space allocation report.
N
Do not print the space allocation report.
The default value is N.
REPORTS SETUP
Optional on the SPACE statement with TYPE(REPORT).
Use the REPORTS SETUP keyword to control the printing of a report showing how the selected PDX members are defined (set up). The following values are valid:
Y
Print the report.
N
Do not print report.
The default value is N.
REPORTS TREND
Optional on the SPACE statement with TYPE(REPORT).
Use the REPORTS TREND keyword to request a report showing changes in space usage and allocation information for each data set for the selected DBD(s). The following values are valid:
Y
Print the report.
N
Do not print report.
The default value is N.
REPORTS USAGE
Optional on the SPACE statement with TYPE(CAPTURE) and TYPE(REPORT).
Use the REPORTS USAGE keyword to control the printing of a report showing the space usage information for each data set for the selected DBD(s). The information displayed on the report depends on the value of the keyword. The following values are valid:
A
Report all captured space data for each data set.
N
Do not report space usage information.
Y or L
Report only the most recently captured space data for each data set.
The default is N. However, if you do not include this keyword with TYPE(REPORT), PCPSPACE produces the space usage information.
SCAN
Optional on the SETUP statement.
Use the SCAN keyword to review the results of the batch space setup process before actually updating the PDX data set. The following values are valid:
Y
PCPSPACE performs the requested processes, but it does not update the PDX.
N
PCPSPACE performs the requested processes and updates the PDX.
The default value is N.
THRESH
Optional on the SETUP statement with TYPE(ADD) and TYPE(CHANGE).
Use this keyword with one or more of the following keywords to set space monitoring threshold values:
- AVAILEXT
- CASPLIT
- CISPLIT
- LASTEXT
- SPACEUSE
- USEDEXT
Code these keywords and their values in parentheses as the value of the THRESH keyword, as the following example illustrates:
The following sections describe the THRESH keywords and values.
THRESH AVAILEXT
Optional on the SETUP statement.
Use the THRESH AVAILEXT keyword to control the monitoring of available extents. The following values are valid:
nn
Monitor available extents, and flag an exception when the number of available extents for the data set falls below the threshold (nn), where nn is the threshold number (1-16). You can set a higher value for VSAM data sets through the ISPF interface.
PCP calculates the available extents by examining the free extents on all candidate volumes and determining how many extents can be allocated by the data set before reaching the extent limit (16 for OSAM, 119 for VSAM) or the 4 Gb limit. For VSAM, values from 119 to 123 are treated as 119 because VSAM will not start a new secondary extent after 119 extents are used.
If the 4 GB limit is reached before the maximum number of extents, PCP issues the following message:
** WARNING ** EXTENTS AVAILABLE LIMITED TO 4 GIGABYTES
0
Do not monitor this item.
The default value is 0.
THRESH CASPLIT
Optional on the SETUP statement.
Use the THRESH CASPLIT keyword to control the monitoring of control area (CA) splits. The following values are valid:
nn
Monitor CA splits, and flag an exception when the number of CA splits exceeds nn% of the used control areas, where nn is the percentage (1-99).
0
Do not monitor this item.
The default value is 0.
THRESH CISPLIT
Optional on the SETUP statement.
Use the THRESH CISPLIT keyword to control the monitoring of control interval (CI) splits. The following values are valid:
nn
Monitor CI splits, and flag an exception when the number of CI splits exceeds nn% of the used control intervals, where nn is the percentage (1-99).
0
Do not monitor this item.
The default value is 0.
THRESH LASTEXT
Optional on the SETUP statement.
Use the THRESH LASTEXT keyword to control whether PCP issues a warning when it determines that the data set is using its last extent (no more extents are available). The following values are valid:
Y
Issue a warning on the last extent.
N
Do not issue a warning on the last extent.
The default value is N.
THRESH SPACEUSE
Optional on the SETUP statement. Use the THRESH SPACEUSE keyword to control the monitoring of used space. You must monitor used space to obtain volume monitoring information. The following values are valid:
nn
Monitor used space, and flag an exception when the number of used space exceeds nn% of the allocated space, where nn is the percentage (1-99).
0
Do not monitor this item.
The default value is 0.
THRESH USEDEXT
Optional on the SETUP statement. Optional on the SETUP statement. Use the THRESH USEDEXT keyword to control the monitoring of used extents. The following values are valid:
nn
Monitor used extents, and flag an exception when the number of extents allocated for the data set exceeds the threshold ( nn), where nn is the threshold number (1-16). You can set a higher value for VSAM data sets through the ISPF interface.
0
Do not monitor this item.
The default value is 0.
TYPE
Required (however, you only need to provide the TYPE keyword once on either the GLBL or SETUP statement, or on the GLBL or SPACE control statement). The value of the TYPE keyword determines whether the process adds, changes, or deletes the space monitoring setup record(s) and whether it captures, reports, or purges space monitoring statistics. The following values are valid:
ADD
Add a space monitor record for each DBD in the DBDLIB that matches the mask specified on the DBD keyword and that does not have an existing member. This value is valid on the GLBL and SETUP statements.
CHANGE
Change all space monitor records for which the IMSID and DBD name match the values of the IMSID and DBD keywords. This function allows attributes of the data set to change without deleting captured data. However, if the BLKSIZE or CISIZE is being changed, the previously captured space data will not be displayed correctly. This value is valid on the GLBL and SETUP statements.
DELETE
Delete all space monitor records in which the IMSID and DBD name match the values of the IMSID and DBD keywords. This value is valid on the GLBL and SETUP statements.
CAPTURE
Capture the data set space usage information from either a VSAM CATALOG or OSAM DSCB. The captured information is stored in the PDX specified by the PDX DD statement. This value is valid on the GLBL and SPACE statements.
REPORT
Extract and report space usage information from the PDX data set. The reports are written to the data set described by the SYSPRINT DD statement. This value is valid on the GLBL and SPACE statements.
PURGE
Delete data from the PDX data set, according to the KEEPDAYS or KEEPSETS keyword. This value is valid on the GLBL and SPACE statements.
USERID
Optional on the GLBL statement with TYPE(CAPTURE) or VOLUME(Y). Use the USERID keyword to notify the specified TSO user IDs if the PCPSPACE discovers any space or volume exceptions. PCPSPACE sends notification of exceptions to the specified TSO user ID. It does not validate the TSO user ID, and all messages sent to an invalid TSO user ID will be lost.
Support for the USERID keyword depends on the version of TSO and MVS you have installed:
TSO Version 1.4 or later
If you are running under TSO Version 1.4 or later, you must have the DBUSS installed and started to send monitoring messages to a TSO user ID.
MVS/370 SP Version 1.3.5 or earlier
PCP does not support sending messages to a TSO user ID when running under MVS/370 SP Version 1.3.5 or earlier.
As the value of the USERID keyword, specify a list of TSO user IDs. Separate the entries in the list with a comma. You can use a maximum of 99 characters (including commas).
VOLUME
Optional on the GLBL statement. Use the VOLUME keyword to control the generation of space reports for disk volumes. When PCPSPACE generates volume reports, it forces the capture of statistics for all databases that are registered for space monitoring. However, it uses the statistics that are being captured in the current execution of PCPSPACE with TYPE(CAPTURE).
Therefore, for wise resource usage, combine the generation of volume reports with the capture of space statistics. See Using-volume-monitoring-reports for more information about how PCPSPACE produces the volume reports.
The following values are valid for the VOLUME keyword:
Y, print
Generate volume reports and save them in the PDX data set. The print value controls the printing of these volume reports during the PCPSPACE execution. The following values are valid for print:
NONE
Do not print any volume reports.
ALL
Print both volume reports.
EX
Print volume exception reports.
STAT
Print volume status reports.
N
Do not produce volume reports.
The default is N. If you specify Y without the print value, the default print value is ALL.