Change Pool Attributes (QUSCHGPA) API
Required Parameter Group:
| 1 |
System pool identifier |
Input |
Binary(4) |
| 2 |
New pool size |
Input |
Binary(4) |
| 3 |
New pool activity level |
Input |
Binary(4) |
Optional Parameter Group 1:
| 4 |
Message logging |
Input |
Char(1) |
| 5 |
Error code |
I/O |
Char(*) |
Optional Parameter Group 2:
| 6 |
Paging option |
Input |
Char(10) |
Optional Parameter Group 3:
Note: Group 3 is valid for shared pools
only.
| 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) |
Optional Parameter Group 4:
Note: Group 4 is valid for shared pools
only.
| 13 |
Minimum activity level |
Input |
Binary(4) |
| 14 |
Maximum activity level |
Input |
Binary(4) |
Default Public Authority: *USE
Threadsafe: No
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.
Authorities and Locks
- Subsystem Description Authority
- *OBJOPR, *OBJMGT, and *READ
- Subsystem Description Library Authority
- *EXECUTE
Required Parameter Group
- System pool identifier
- INPUT; BINARY(4)
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.
- New pool size
- INPUT; BINARY(4)
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.
- New pool activity level
- INPUT; BINARY(4)
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.
Optional Parameter Group 1
- Message logging
- INPUT; CHAR(1)
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.
- Error code
- I/O; CHAR(*)
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.
Optional Parameter Group 2
- Paging option
- INPUT; CHAR(10)
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.
Optional Parameter Group 3
Note: Group 3 is valid for shared pools
only.
- Priority
- INPUT; BINARY(4)
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.
- Minimum pool size %
- INPUT; BINARY(4)
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.
- Maximum pool size %
- INPUT; BINARY(4)
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.
- Minimum faults
- INPUT; BINARY(4)
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.
- Per-thread faults
- INPUT; BINARY(4)
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.
- Maximum faults
- INPUT; BINARY(4)
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.
Optional Parameter Group 4
Note: Group 4 is valid for shared pools
only.
- Minimum activity level
- INPUT; BINARY(4)
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.
- Maximum activity level
- INPUT; BINARY(4)
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.
Error Messages
| 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. |
Example: Changing System Storage Pool Attributes
See Code disclaimer information
for information pertaining to code examples.
The following is an example of how to change system storage pool attributes
using the QUSCHGPA API:
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
.
.
.
API introduced: V1R3