| 1 | System pool identifier | Input | Binary(4) |
| 2 | New pool size | Input | Binary(4) |
| 3 | New pool activity level | Input | Binary(4) |
| 4 | Message logging | Input | Char(1) |
| 5 | Error code | I/O | Char(*) |
| 6 | Paging option | Input | Char(10) |
| 7 | Priority | Input | Binary(4) |
| 8 | Minimum pool size % | Input | Binary(4) |
| 9 | Maximum pool size % | Input | Binary(4) |
| 10 | Minimum faults | Input | Binary(4) |
| 11 | Per-thread faults | Input | Binary(4) |
| 12 | Maximum faults | Input | Binary(4) |
| 13 | Minimum activity level | Input | Binary(4) |
| 14 | Maximum activity level | Input | Binary(4) |
The Change Pool Attributes (QUSCHGPA) API changes the size, activity level, and paging options of any system storage pool. In addition, QUSCHGPA changes the tuning parameters for system storage pools that are also shared pools. A system storage pool identifier is returned with the Materialize Resource Management Data (MATRMD) machine interface (MI) or Retrieve System Status (QWCRSSTS) API. (Note that system pool identifiers differ from subsystem pool identifiers.) Depending on whether the base pool, shared pool, or private subsystem pool is to be changed, the QUSCHGPA API determines the appropriate command to use and then issues that command. This is similar to the function provided on the System Status display, where you can change the system storage pool size and paging options interactively.
You can use the QUSCHGPA API to tune storage pools without having to know which subsystem monitor allocated the pool. In addition, you do not have to determine whether or not a pool is a shared storage pool, unless parameter group 3 or 4 is specified. The Work with System Status (WRKSYSSTS), the Work with Subsystems (WRKSBS), and the Work with Shared Pools (WRKSHRPOOL) commands provide similar functions.
This identifies which pool is to be changed. This number corresponds to the number returned on option nine of the MATRMD MI instruction. This also corresponds to the identifier shown on the Work with System Status display. This parameter is a value ranging from 1 through 64, where pool 1 is the machine pool, and pool 2 is the base pool.
The size of the pool in kilobytes, where one kilobyte is 1024 bytes. If you do not want the pool size to be changed, you must specify a value of -1 for this parameter. The minimum value is 256 kilobytes.
Note: For compatibility with previous releases, a pool size of 32 through 255 kilobytes can be specified. However, since the minimum pool size is 256 kilobytes, the pool will not be changed when a size of 32 through 255 kilobytes is specified.
The activity level for the pool. If you do not want the activity level to be changed, you must specify a value of -1 for this parameter. You cannot change the activity level of the machine pool.
Whether messages reporting that a change was made are written to the current job's job log and to the QHST message log. This affects the logging of change-related messages only; it does not affect the logging of error messages. Valid values are:
| Y | Log change messages. |
| N | Do not log change messages. |
If this parameter is omitted, Y is used and change messages are logged.
The structure in which to return error information. For the format of the structure, see Error code parameter. If this parameter is omitted, diagnostic and escape messages are issued to the application.
Whether the system should dynamically adjust the paging characteristics of the storage pool for optimum performance. Valid values are:
| *SAME | The paging option for the storage pool is not changed. |
| *FIXED | The system will not dynamically adjust the paging characteristics; system default values are used. |
| *CALC | The system will dynamically adjust the paging characteristics. |
If this parameter is omitted, the paging option is not changed.
Note: Group 3 is valid for shared pools only.
The priority of this pool relative to the priority of the other storage pools. Valid values are 1 through 14. The priority for the *MACHINE pool must be 1. This value is used by the system if the performance adjustment (QPFRADJ) system value is set to 2 or 3. If this parameter is omitted, the priority value is not changed. If you want the system to calculate the priority, you must specify -2 for this parameter. If you do not want this value to change, you may specify -1 for this parameter.
The minimum amount of storage to allocate to this storage pool (as a percentage of total main storage), specified in hundredths. That is, a value of 1234 means 12.34 percent. This value cannot be greater than the maximum pool size % parameter value. This value is used by the system if the QPFRADJ system value is set to 2 or 3. If this parameter is omitted, the minimum size value is not changed. If you want the system to calculate the minimum size, you must specify -2 for this parameter. If you do not want this value to change, you may specify -1 for this parameter.
The maximum amount of storage to allocate to this storage pool (as a percentage of total main storage), specified in hundredths. That is, a value of 1234 means 12.34 percent. This value cannot be less than the minimum pool size % parameter value. This value is used by the system if the QPFRADJ system value is set to 2 or 3. If this parameter is omitted, the maximum size value is not changed. If you want the system to calculate the maximum size, you must specify -2 for this parameter. If you do not want this value to change, you may specify -1 for this parameter.
The minimum faults-per-second guideline to use for this storage pool, specified in hundredths. That is, a value of 1234 means 12.34. This value is used by the system if the QPFRADJ system value is set to 2 or 3. If this parameter is omitted, the minimum faults value is not changed. If you want the system to calculate minimum faults, you must specify -2 for this parameter. If you do not want this value to change, you may specify -1 for this parameter.
The faults per second for each active thread in this storage pool, specified in hundredths. That is, a value of 1234 means 12.34. Each job is comprised of one or more threads. The system multiplies this number by the number of active threads that it finds in the pool. This result is added to the minimum faults parameter to calculate the faults-per-second guideline to use for this pool. This value is used by the system if the QPFRADJ system value is set to 2 or 3. If this parameter is omitted, the per-thread faults value is not changed. If you want the system to calculate per-thread faults, you must specify -2 for this parameter. If you do not want this value to change, you may specify -1 for this parameter.
The maximum faults-per-second guideline to use for this storage pool, specified in hundredths. That is, a value of 1234 means 12.34. The sum of minimum faults and per-thread faults must be less than the value of the maximum faults parameter. This value is used by the system if the QPFRADJ system value is set to 2 or 3. If this parameter is omitted, the maximum faults value is not changed. If you want the system to calculate maximum faults, you must specify -2 for this parameter. If you do not want this value to change, you may specify -1 for this parameter.
Note: Group 4 is valid for shared pools only.
The minimum value that this pool's activity level can be set to by the performance adjuster when the QPFRADJ system value is set to 2 or 3. Valid values are 1 through 32767. This value cannot be greater than the maximum activity level parameter value. You cannot change the minimum activity level for the machine pool. If this parameter is omitted, the minimum activity level is not changed. If you want the system to calculate the minimum activity level, you must specify -2 for this parameter. If you do not want this value to change, you may specify -1 for this parameter.
The maximum value that this pool's activity level can be set to by the performance adjuster when the QPFRADJ system value is set to 2 or 3. Valid values are 5 through 32767. This value cannot be less than the minimum activity level parameter value. You cannot change the maximum activity level for the machine pool. If this parameter is omitted, the maximum activity level is not changed. If you want the system to calculate the maximum activity level, you must specify -2 for this parameter. If you do not want this value to change, you may specify -1 for this parameter.
The following table summarizes the values you can specify for the system pool identifier, the new pool size, and the new pool activity level.
| System Pool Identifier | New Pool Size | New Pool Activity Level |
|---|---|---|
| 1 (Machine pool) | -1 or >= 256 | -1 |
| 2 (Base pool) | -1 or >= 256 1 | -1 or 1 through 32 767 |
| 3 to 64 |
>= 256 1 | 1 through 32 767 |
| 1 For compatibility with previous releases, a pool size of 32 through 255 kilobytes can be specified. Since the minimum pool size is 256 kilobytes, however, the pool will not be changed when a size of 32 through 255 kilobytes is specified. | ||
For pools 3 through 64, both size and pool activity level must be specified.
In some cases, pool size changes do not take effect immediately. For example, a save or restore operation might be using some of the storage allocated to a pool, or the system might be using some of the storage allocated to the base pool. The size is changed only when the storage being used is free again.
The base pool holds all unused main storage on the system that is not allocated to other shared or private pools. As subsystems are started and allocate storage for their shared and private storage pools, that storage comes from the base pool. The base pool (pool number 2) size is what is left after pool 1 and pools 3 through 64 are subtracted from the total main storage. The QBASPOOL system value is a minimum size, and it is not the actual size of the base pool. At this minimum size, the system does not allow additional storage requests. For this reason, you must calculate the storage requirements for all pools on the system, including the base pool, and then run this API.
| Message ID | Error Message Text |
|---|---|
| CPF1001 E | Wait time expired for system response. |
| CPF1076 E | Specified value not allowed for system value &1. |
| CPF1078 E | System value &1 not changed. |
| CPF113A E | Sum of MINFAULT and JOBFAULT parameters exceeds MAXFAULT parameter. |
| CPF113B E | Minimum size percentage exceeds maximum size percentage. |
| CPF113C E | Parameter not valid for private pool. |
| CPF113E E | Range of parameter &2 does not include &4. |
| CPF1165 E | Specified parameter not allowed for *MACHINE pool. |
| CPF1619 E | Subsystem description &1 in library &2 damaged. |
| CPF1691 E | Active subsystem description may or may not have changed. |
| CPF1697 E | Subsystem description &1 not changed. |
| CPF1879 E | Paging option &1 not valid. |
| CPF1880 E | Machine pool paging option cannot be changed. |
| CPF1881 E | Changing private pool paging option not allowed. |
| CPF24B4 E | Severe error while addressing parameter list. |
| CPF3CA0 E | System pool &1 does not exist. |
| CPF3CA1 E | Pool size &1 is not valid. |
| CPF3CA2 E | Activity level &1 is not valid. |
| CPF3CA3 E | Pool &1 is not in use. |
| CPF3CA4 E | Changing machine pool activity level is not allowed. |
| CPF3CA5 E | Both pool size and activity level are required. |
| CPF3CA6 E | Message logging value &1 not valid. |
| CPF3CF1 E | Error code parameter not valid. |
| CPF3CF2 E | Error(s) occurred during running of &1 API. |
| CPF3C36 E | Number of parameters, &1, entered for this API was not valid. |
| CPF3C3C E | Value for parameter &1 not valid. |
| CPF3C90 E | Literal value cannot be changed. |
| CPF9872 E | Program or service program &1 in library &2 ended. Reason code &3. |
The following example shows how to change system storage pool attributes using the QUSCHGPA API.
Note: By using the code examples, you agree to the terms of the Code license and disclaimer information.
Pseudocode
.
.
.
MATRMD (OPERAND1, OPERAND2);
DO /* Do loop for each pool in use */
.
. /* Calculate the desired pool size
and activity level */
.
END
DO /* Do loop for each pool in use */
CALL QUSCHGPA (POOLID, POOLSIZE, POOLACTLVL);
/* Change pool attributes */
END
.
.
.