Change Pools (QWCCHGPL) API
Required Parameter Group:
| 1 | Change request | Output | Char(*) |
| 2 | Length of change request | Input | Binary(4) |
| 3 | Format name | Input | Char(8) |
| 4 | Wait time | Input | Binary(4) |
| 5 | Return value | Output | Binary(4) |
| 6 | Error Code | I/O | Char(*) |
Default Public Authority: *EXCLUDE
Threadsafe: No
The Change Pools (QWCCHGPL) API changes how the system's memory is divided into storage pools. The Materialize Resource Management Data (MATRMD) machine interface instruction (options X'14', X'16', and X'2D' can be used to retrieve the current setting of this information. The Change Pool Attributes (QUSCHGPA) API can be used to change a single pool.
Authorities and Locks
None.
Required Parameter Group
- Change request
- INPUT; CHAR(*)
The variable containing the new pool information. See the formats for the definition of the fields for this parameter (POOL0100, POOL0200, POOL0300, and POOL0400).
- Length of change request
- INPUT; BINARY(4)
The length of the change request list. This area must be as large as the format specified.
- Format name
- INPUT; CHAR(8)
The format of the change request. You must use one of the following format names:
POOL0100 Adjust full pool information for 64 system storage pools. Use this format to change size, activity level, and tuning values for all active pools. POOL0200 Adjust pool size and activity level for 64 system storage pools. Use this format to change size and activity level for all active pools. POOL0300 Allocate system pool. Use this format to allocate a system pool. POOL0400 Deallocate system pool. Use this format to deallocate a system pool that was previously allocated with this API. For more information about these formats, see Format of Information to be Changed.
- Wait time
- INPUT; BINARY(4)
The time, in seconds, that the API will wait for a response from the system indicating that the pool changes requested could be made. A value of -1 indicates the process default wait time should be used. A value of 0 indicates the API should not wait for a response. A minimum of 30 seconds should be used when the POOL0300 format is used to allocate a pool. If the system could not complete pool changes during this wait time message CPF1001 is issued. The change may or may not complete.
- Format return value
- OUTPUT; BINARY(4)
The resulting return value for the request. Format POOL0300 returns the system pool identifier for the allocated system pool request, or no value if an error occurs. For the other formats no value is returned. See Format Return Values.
- 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.
Format of Information to be Changed
The variable containing the new pool information must use one of the following formats.
POOL0100 Format
The following table shows the information that must be specified in the change request parameter when POOL0100 is specified. The total length of the change request is 3328 for this format. For a detailed description of each field, see Field Descriptions.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| Offsets vary. These fields repeat, in the order listed, for 64 pools. The position in the information corresponds to the system pool identifier. | BINARY(8) | Pool size | |
| BINARY(4) | Maximum active threads | ||
| CHAR(1) | Type of tuning | ||
| CHAR(1) | Change page handling | ||
| CHAR(2) | Reserved | ||
| BINARY(4) | Blocking factor for nondatabase objects | ||
| CHAR(1) | Allow exchange operations (for class 1 objects in pool) | ||
| CHAR(1) | Type of transfer from main storage to auxiliary storage (for class 1 objects in pool) | ||
| CHAR(2) | Reserved | ||
| BINARY(4) | Blocking factor for database (class 1) objects | ||
| CHAR(1) | Allow exchange operations (for class 2 objects in pool) | ||
| CHAR(1) | Type of transfer from main storage to auxiliary storage (for class 2 objects in pool) | ||
| CHAR(2) | Reserved | ||
| BINARY(4) | Blocking factor for database (class 2) objects | ||
| CHAR(1) | Allow exchange operations (for class 3 objects in pool) | ||
| CHAR(1) | Type of transfer from main storage to auxiliary storage (for class 3 objects in pool) | ||
| CHAR(2) | Reserved | ||
| BINARY(4) | Blocking factor for database (class 3) objects | ||
| CHAR(1) | Allow exchange operations (for class 4 objects in pool) | ||
| CHAR(1) | Type of transfer from main storage (for class 4 objects in pool) to auxiliary storage | ||
| CHAR(2) | Reserved | ||
| BINARY(4) | Blocking factor for database (class 4) objects | ||
When tuning is requested (values 1, 2, or 3 for the type of tuning field), the system periodically categorizes database objects into four different performance classes. The classes are:
| Class 1 | Object access appears to be random. A disk access is required for nearly each record that is accessed. |
| Class 2 | Locality of reference detected. Several records are being accessed per disk access. |
| Class 3 | High locality of reference detected. The object is being processed in a sequential manner; references are highly clustered and large portions of the object are resident in main storage. |
| Class 4 | The class of a database object is adjusted if the object's size is small in comparison to the available storage in the storage pool. This class adjustment involves adding 1 to the class number; therefore, a class 3 database object (as defined above) would be treated as a class 4 if it were small in comparison to the available storage in the storage pool. |
Reference information for determining an object's class is collected periodically. It is collected by storage pool because an object's class varies over time and by storage pool.
Note: When a new system pool is created as a result of starting a subsystem, the type of tuning and change page handling attributes for the new system pool are initialized based on the type of storage pool being created. For shared storage pools, the type of tuning and change page handling attributes are set based on the paging option defined for the shared storage pool. For private storage pools, the type of tuning attribute is set to indicate no tuning should be done and the change page handling attribute is set to the system default value. The type of tuning and change page handling cannot be changed for the machine pool (system pool 1).
POOL0200 Format
The following table shows the information that must be specified in the change request parameter when POOL0200 is specified. This format can be used when the size and maximum active threads are being changed. The total length of the change request is 768 for this format. For a detailed description of each field, see Field Descriptions.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| Offsets vary. These fields repeat, in the order listed, for 64 pools. The position in the information corresponds to the system pool identifier. | BINARY(8) | Pool size | |
| BINARY(4) | Maximum active threads | ||
POOL0300 Format
The following table shows the information that must be specified in the change request parameter when POOL0300 is specified. This format can be used to allocate a pool that is not associated with a subsystem. The length of the change request is 40 when allocating a shared pool. (The size and maximum active threads values specified on the Change Shared Pool command are used.) The length of the change request is 52 when allocating a private pool. For a detailed description of each field, see Field Descriptions.
If the pool allocation identifier is already associated with an active pool, that system pool number will be returned instead of allocating another system pool.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | CHAR(10) | Pool name |
| 10 | A | CHAR(30) | Pool allocation identifier |
| 40 | 28 | BINARY(8) | Pool size |
| 48 | 30 | BINARY(4) | Maximum active threads |
POOL0400 Format
The following table shows the information that must be specified in the change request parameter when POOL0400 is specified. This format can be used to deallocate a pool that was allocated with this API. The total length of the change request is 34 for this format. For a detailed description of each field, see Field Descriptions.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | System pool identifier |
| 4 | 4 | CHAR(30) | Pool allocation identifier |
Field Descriptions
Allow exchange operations. The exchange operation used to reduce the working set size. This is done by overlaying data that is already in main storage with new data this is being brought into main storage. The values for this field are:
| 0 | Use the system default, which is 1 (allow exchange operations) |
| 1 | Allow exchange operations |
| 2 | Disable exchange operations |
| 3 | Disable exchange operations (The data that already exists in main storage should be a good candidate to be replaced when additional storage is needed in the storage pool.) |
The value specified for this field is ignored unless static tuning is specified for the type of tuning field.
Blocking factor for database objects. The amount of data that should be brought into main storage when a request is made to read database objects from auxiliary storage. The values for this field are:
| 0 | Use the system default, which is currently 4 (transfer data into main storage in 4KB blocks) |
| 4 | Transfer data into main storage in 4KB blocks |
| 8 | Transfer data into main storage in 8KB blocks |
| 16 | Transfer data into main storage in 16KB blocks |
| 32 | Transfer data into main storage in 32KB blocks |
| 64 | Transfer data into main storage in 64KB blocks |
| 128 | Transfer data into main storage in 128KB blocks |
The system may need to issue multiple I/O operations to bring the data into main storage. The value specified for the blocking factor for database objects field is ignored unless static tuning is specified for the type of tuning field.
Blocking factor for nondatabase objects. The amount of data that should be brought into main storage when a request is made to read nondatabase objects from auxiliary storage. The possible values for this field are:
| 0 | Use the system default, which is currently 4 (transfer data into main storage in 4KB blocks) |
| 4 | Transfer data into main storage in 4KB blocks |
| 8 | Transfer data into main storage in 8KB blocks |
| 16 | Transfer data into main storage in 16KB blocks |
| 32 | Transfer data into main storage in 32KB blocks |
The system may need to issue multiple I/O operations to bring the data into main storage. The value specified for the blocking factor for nondatabase objects is ignored unless static tuning is specified for the type of tuning field.
Change page handling. The method the system uses to determine when to write changed pages to auxiliary storage. The values for this field are:
| 0 | Use the system default, which is currently 1 (Changed pages should be written to auxiliary storage when there is a demand for pages in a storage pool.) |
| 1 | Changed pages should be written to auxiliary storage when there is a demand for pages in a storage pool |
| 2 | In addition to writing changed pages on demand, periodically write changed pages to auxiliary storage |
Maximum active threads. The requested activity level for the pool. This is the maximum number of threads in the pool that can use the processor at the same time. A maximum active threads of 0 for a shared pool with a size greater than 0 indicates the shared pool is defined as a data pool.
Pool allocation identifier. Identifier used to allocate and deallocate a pool. This can be any unique 30 character value. The same identifier that was used to allocate the pool must be used to deallocate it. Do not use identifiers starting with QIBM.
Pool name. Name of the shared pool (*SHRPOOL1 - *SHRPOOL60). For a private pool any 10-character name can be used.
Pool size. The requested size for the pool in pages. To determine the current page size use the machine minimum transfer size of MATRMD option X'09'.
Reserved. An ignored field.
System pool identifier. A number from 1 to 64 representing a memory pool that has main storage allocated to it. This is the same number shown on the Work with System Status (WRKSYSSTS) display and returned in Format return value for format POOL0300.
Type of transfer from main storage to auxiliary storage. The method the system uses to process a request to write an object to auxiliary storage. The values for this field are:
| 0 | Use the system default, which is 1 (When objects are changed, write the changes to auxiliary storage. Indicate that the portion of the object that was written to auxiliary storage should be a good candidate to be replaced when additional storage is needed in the storage pool.) |
| 1 | When objects are changed, write the changes to auxiliary storage. Indicate that the portion of the object that was written to auxiliary storage should be a good candidate to be replaced when additional storage is needed in the storage pool. |
| 2 | When objects are changed, write the changes to auxiliary storage. |
| 3 | Do not immediately write the changes to auxiliary storage. Indicate that the portion of the object that was changed should be a good candidate to be replaced when additional storage is needed in the storage pool. |
| 4 | Do not immediately write the changes to auxiliary storage. |
The value specified for this field is ignored unless static tuning is specified for the type of tuning field.
Type of tuning. The method used by the system to tune the storage pool. The values for this field are:
| 0 | No tuning is being performed for this pool.
All values specified for the blocking factor, the allow exchange operations, and the type of transfer from main storage to auxiliary storage fields are ignored. The system default values are used for all these fields. |
| 1 | Static tuning is being performed for this pool.
Static tuning implies that the values specified for blocking factor, exchange
operation, and transfers to auxiliary storage are not dynamically adjusted by
the system.
Values must be specified for the blocking factor, allow exchange operations, and type of transfer from main storage to auxiliary storage for the storage pools. |
| 2 | Dynamic tuning of transfers into main storage is
being performed. This indicates that the system is dynamically adjusting the
blocking factor and exchange operations.
Because the values for blocking factor and allow exchange operations are dynamically adjusted, the values specified on the API are ignored. The value used for the transfer to auxiliary storage field is set to ensure that requests to write data to auxiliary storage are processed immediately. |
| 3 | Dynamic tuning of transfers into main storage and
to auxiliary storage is being performed. This indicates that the system is
dynamically adjusting the blocking factor, exchange operations, and transfers
to auxiliary storage.
Because the values for the blocking factor, allow exchange operations, and transfers to auxiliary storage are dynamically adjusted, the values specified on the API are ignored. |
Format Return Values
For format POOL0300:
| Return Value | Explanation |
|---|---|
| 3 - 64 | Value is system pool identifier of allocated pool. |
For formats POOL0100, POOL0200, and POOL0400:
| Return Value | Explanation |
|---|---|
| Return value not used with this format. |
Error Messages
| Message ID | Error Message Text |
|---|---|
| CPF1001 E | Wait time expired for system response |
| CPF116A E | Pool &2 not allocated. |
| CPF116C E | Pool attributes not changed. |
| CPF116D E | System pool &2 not deallocated. |
| CPF1875 E | Value &1 for change request length not valid. |
| CPF24B4 E | Severe error while addressing parameter list. |
| CPF3CA3 E | Pool &1 is not in use. |
| CPF3CF1 E | Error code parameter not valid. |
| CPF3C21 E | Format name &1 is not valid. |
| CPF3C3B E | Value for parameter &2 for API &1 not valid. |
| CPF3C90 E | Literal value cannot be changed. |
| CPF980A E | &1 routine in &2 module detected an exception. The exception return code was &3. |
| CPF9872 E | Program or service program &1 in library &2 ended. Reason code &3. |
API introduced: V6R1