ibm-information-center/dist/eclipse/plugins/i5OS.ic.apis_5.4.0.1/qwcchgtn.htm

708 lines
22 KiB
HTML

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<meta name="Copyright" content="Copyright (c) 2006 by IBM Corporation">
<title>Change Pool Tuning Information (QWCCHGTN) API</title>
<!-- Begin Header Records ========================================= -->
<!-- All rights reserved. Licensed Materials Property of IBM -->
<!-- US Government Users Restricted Rights -->
<!-- Use, duplication or disclosure restricted by -->
<!-- GSA ADP Schedule Contract with IBM Corp. -->
<!-- WM SCRIPT A converted by B2H R4.1 (346) (CMS) by V2KEA304 -->
<!-- at RCHVMW2 on 17 Feb 1999 at 11:05:09 -->
<!-- Change History: -->
<!-- YYMMDD USERID Change description -->
<!-- File cleanup completed Nov 2001 by v2cdijab -->
<!-- End Header Records -->
<link rel="stylesheet" type="text/css" href="../rzahg/ic.css">
</head>
<body>
<a name="Top_Of_Page"></a>
<!-- Java sync-link -->
<script type="text/javascript" language="Javascript" src="../rzahg/synch.js">
</script>
<h2>Change Pool Tuning Information (QWCCHGTN) API</h2>
<div class="box" style="width: 80%;">
<br>
&nbsp;&nbsp;Required Parameter Group:<br>
<!-- iddvc RMBR -->
<br>
<table width="100%">
<tr>
<td align="center" valign="top" width="10%">1</td>
<td align="left" valign="top" width="50%">System pool identifier</td>
<td align="left" valign="top" width="20%">Input</td>
<td align="left" valign="top" width="20%">Binary(4)</td>
</tr>
<tr>
<td align="center" valign="top">2</td>
<td align="left" valign="top">Change request</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Char(*)</td>
</tr>
<tr>
<td align="center" valign="top">3</td>
<td align="left" valign="top">Length of change request</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Binary(4)</td>
</tr>
<tr>
<td align="center" valign="top">4</td>
<td align="left" valign="top">Format name</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Char(8)</td>
</tr>
<tr>
<td align="center" valign="top">5</td>
<td align="left" valign="top">Error code</td>
<td align="left" valign="top">I/O</td>
<td align="left" valign="top">Char(*)</td>
</tr>
</table>
<br>
&nbsp;&nbsp;Default Public Authority: *EXCLUDE<br>
<!-- iddvc RMBR -->
<br>
&nbsp;&nbsp;Threadsafe: No<br>
<!-- iddvc RMBR -->
<br>
</div>
<p>The Change Pool Tuning Information (QWCCHGTN) API changes information about
tuning being performed by the system for the different storage pools. The
Materialize Resource Management Data (MATRMD) machine interface (MI)
instruction can be used to retrieve the current setting of the tuning
parameters.</p>
<br>
<!-- Please NOTE: DO NOT DELETE THIS SECTION if this API has no authorities and locks. -->
<!-- Instead, use the commented out coding below to indicate NONE. -->
<h3>Authorities and Locks</h3>
<!-- Use this if there are no authorities and locks. -->
<p>None.</p>
<br>
<h3>Required Parameter Group</h3>
<dl>
<dt><strong>System pool identifier</strong></dt>
<dd>INPUT; BINARY(4)
<p>The pool is to be changed. This number corresponds to the number returned on
option 9 of the Materialize Resource Management Data (MATRMD) MI instruction.
This also corresponds to the identifier shown on the Work with System Status
display. This parameter is a value ranging from 2 through 64, where pool 2 is
the base pool.</p>
</dd>
<dt><strong>Change request</strong></dt>
<dd>INPUT; CHAR(*)
<p>The variable containing the new tuning information. See <a href="#HDRTUNI1">
TUNI0100 Format</a> for the definition of the fields for this parameter.</p>
</dd>
<dt><strong>Length of change request</strong></dt>
<dd>INPUT; BINARY(4)
<p>The length of the change request list. This area must be as large as the
format specified.</p>
</dd>
<dt><strong>Format name</strong></dt>
<dd>INPUT; CHAR(8)
<p>The format of the information to be changed. The valid values are:</p>
<table cellpadding="5">
<!-- cols="15 85" -->
<tr>
<td align="left" valign="top"><em>TUNI0100</em></td>
<td align="left" valign="top">Tuning information for a storage pool.</td>
</tr>
</table>
<br>
</dd>
<dt><strong>Error code</strong></dt>
<dd>I/O; CHAR(*)
<p>The structure in which to return error information. For the format of the
structure, see <a href="../apiref/error.htm#hdrerrcod">Error Code Parameter</a>.</p>
</dd>
</dl>
<br>
<h3><a name="HDRTUNI1">TUNI0100 Format</a></h3>
<p>The following table shows the information that must be specified in the
change request parameter when format TUNI0100 is specified. For a detailed
description of each field, see <a href="#HDRTUNI1D">Field Descriptions</a>.</p>
<table border width="80%">
<tr>
<th align="center" valign="bottom" colspan="2">Offset</th>
<th align="left" valign="bottom" rowspan="2">Type</th>
<th align="left" valign="bottom" rowspan="2">Field</th>
</tr>
<tr>
<th align="center" valign="bottom">Dec</th>
<th align="center" valign="bottom">Hex</th>
</tr>
<tr>
<td align="center" valign="top" width="10%">0</td>
<td align="center" valign="top" width="10%">0</td>
<td align="left" valign="top" width="20%">CHAR(1)</td>
<td align="left" valign="top" width="60%">Type of tuning</td>
</tr>
<tr>
<td align="center" valign="top">1</td>
<td align="center" valign="top">1</td>
<td align="left" valign="top">CHAR(1)</td>
<td align="left" valign="top">Change page handling</td>
</tr>
<tr>
<td align="center" valign="top">2</td>
<td align="center" valign="top">2</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Blocking factor for nondatabase objects</td>
</tr>
<tr>
<td align="center" valign="top">6</td>
<td align="center" valign="top">6</td>
<td align="left" valign="top">CHAR(1)</td>
<td align="left" valign="top">Allow exchange operations (for class 1 objects in
pool)</td>
</tr>
<tr>
<td align="center" valign="top">7</td>
<td align="center" valign="top">7</td>
<td align="left" valign="top">CHAR(1)</td>
<td align="left" valign="top">Type of transfer from main storage to auxiliary
storage (for class 1 objects in pool)</td>
</tr>
<tr>
<td align="center" valign="top">8</td>
<td align="center" valign="top">8</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Blocking factor for database (class 1)
objects</td>
</tr>
<tr>
<td align="center" valign="top">12</td>
<td align="center" valign="top">C</td>
<td align="left" valign="top">CHAR(1)</td>
<td align="left" valign="top">Allow exchange operations (for class 2 objects in
pool)</td>
</tr>
<tr>
<td align="center" valign="top">13</td>
<td align="center" valign="top">D</td>
<td align="left" valign="top">CHAR(1)</td>
<td align="left" valign="top">Type of transfer from main storage to auxiliary
storage (for class 2 objects in pool)</td>
</tr>
<tr>
<td align="center" valign="top">14</td>
<td align="center" valign="top">E</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Blocking factor for database (class 2)
objects</td>
</tr>
<tr>
<td align="center" valign="top">18</td>
<td align="center" valign="top">12</td>
<td align="left" valign="top">CHAR(1)</td>
<td align="left" valign="top">Allow exchange operations (for class 3 objects in
pool)</td>
</tr>
<tr>
<td align="center" valign="top">19</td>
<td align="center" valign="top">13</td>
<td align="left" valign="top">CHAR(1)</td>
<td align="left" valign="top">Type of transfer from main storage to auxiliary
storage (for class 3 objects in pool)</td>
</tr>
<tr>
<td align="center" valign="top">20</td>
<td align="center" valign="top">14</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Blocking factor for database (class 3)
objects</td>
</tr>
<tr>
<td align="center" valign="top">24</td>
<td align="center" valign="top">18</td>
<td align="left" valign="top">CHAR(1)</td>
<td align="left" valign="top">Allow exchange operations (for class 4 objects in
pool)</td>
</tr>
<tr>
<td align="center" valign="top">25</td>
<td align="center" valign="top">19</td>
<td align="left" valign="top">CHAR(1)</td>
<td align="left" valign="top">Type of transfer from main storage (for class 4
objects in pool) to auxiliary storage</td>
</tr>
<tr>
<td align="center" valign="top">26</td>
<td align="center" valign="top">1A</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Blocking factor for database (class 4)
objects</td>
</tr>
</table>
<p>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:</p>
<table cellpadding="5">
<!-- cols="15 85" -->
<tr>
<td align="left" valign="top" width="10%"><em>Class 1</em></td>
<td align="left" valign="top" width="90%">Object access appears to be random. A disk access
is required for nearly each record that is accessed.</td>
</tr>
<tr>
<td align="left" valign="top"><em>Class 2</em></td>
<td align="left" valign="top">Locality of reference detected. Several records
are being accessed per disk access.</td>
</tr>
<tr>
<td align="left" valign="top"><em>Class 3</em></td>
<td align="left" valign="top">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.</td>
</tr>
<tr>
<td align="left" valign="top"><em>Class 4</em></td>
<td align="left" valign="top">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.</td>
</tr>
</table>
<p>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.</p>
<p><strong>Note:</strong> 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.</p>
<br>
<h3><a name="HDRTUNI1D">Field Descriptions</a></h3>
<p><strong>Allow exchange operations.</strong> 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:</p>
<table cellpadding="5">
<!-- cols="5 95" -->
<tr>
<td align="left" valign="top"><em>0</em></td>
<td align="left" valign="top">Use the system default, which is 1 (allow
exchange operations)</td>
</tr>
<tr>
<td align="left" valign="top"><em>1</em></td>
<td align="left" valign="top">Allow exchange operations</td>
</tr>
<tr>
<td align="left" valign="top"><em>2</em></td>
<td align="left" valign="top">Disable exchange operations</td>
</tr>
<tr>
<td align="left" valign="top"><em>3</em></td>
<td align="left" valign="top">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.)</td>
</tr>
</table>
<p>The value specified for this field is ignored unless static tuning is
specified for the type of tuning field.</p>
<p><strong>Blocking factor for database objects.</strong> 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:</p>
<table cellpadding="5">
<!-- cols="5 95" -->
<tr>
<td align="left" valign="top"><em>0</em></td>
<td align="left" valign="top">Use the system default, which is 4 (transfer data
into main storage in 4KB blocks)</td>
</tr>
<tr>
<td align="left" valign="top"><em>4</em></td>
<td align="left" valign="top">Transfer data into main storage in 4KB
blocks</td>
</tr>
<tr>
<td align="left" valign="top"><em>8</em></td>
<td align="left" valign="top">Transfer data into main storage in 8KB
blocks</td>
</tr>
<tr>
<td align="left" valign="top"><em>16</em></td>
<td align="left" valign="top">Transfer data into main storage in 16KB
blocks</td>
</tr>
<tr>
<td align="left" valign="top"><em>32</em></td>
<td align="left" valign="top">Transfer data into main storage in 32KB
blocks</td>
</tr>
<tr>
<td align="left" valign="top"><em>64</em></td>
<td align="left" valign="top">Transfer data into main storage in 64KB
blocks</td>
</tr>
<tr>
<td align="left" valign="top"><em>128</em></td>
<td align="left" valign="top">Transfer data into main storage in 128KB
blocks</td>
</tr>
</table>
<p>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.</p>
<p><strong>Blocking factor for nondatabase objects.</strong> 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:</p>
<table cellpadding="5">
<!-- cols="5 95" -->
<tr>
<td align="left" valign="top"><em>0</em></td>
<td align="left" valign="top">Use the system default, which is 4 (transfer data
into main storage in 4KB blocks)</td>
</tr>
<tr>
<td align="left" valign="top"><em>4</em></td>
<td align="left" valign="top">Transfer data into main storage in 4KB
blocks</td>
</tr>
<tr>
<td align="left" valign="top"><em>8</em></td>
<td align="left" valign="top">Transfer data into main storage in 8KB
blocks</td>
</tr>
<tr>
<td align="left" valign="top"><em>16</em></td>
<td align="left" valign="top">Transfer data into main storage in 16KB
blocks</td>
</tr>
<tr>
<td align="left" valign="top"><em>32</em></td>
<td align="left" valign="top">Transfer data into main storage in 32KB
blocks</td>
</tr>
</table>
<p>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.</p>
<p><strong>Change page handling.</strong> The method the system uses to
determine when to write changed pages to auxiliary storage. The values for this
field are:</p>
<table cellpadding="5">
<!-- cols="5 95" -->
<tr>
<td align="left" valign="top"><em>0</em></td>
<td align="left" valign="top">Use the system default, which is 1 (Changed pages
should be written to auxiliary storage when there is a demand for pages in a
storage pool.)</td>
</tr>
<tr>
<td align="left" valign="top"><em>1</em></td>
<td align="left" valign="top">Changed pages should be written to auxiliary
storage when there is a demand for pages in a storage pool</td>
</tr>
<tr>
<td align="left" valign="top"><em>2</em></td>
<td align="left" valign="top">In addition to writing changed pages on demand,
periodically write changed pages to auxiliary storage</td>
</tr>
</table>
<p><strong>Type of transfer from main storage to auxiliary storage.</strong>
The method the system uses to process a request to write an object to auxiliary
storage. The values for this field are:</p>
<table cellpadding="5">
<!-- cols="5 95" -->
<tr>
<td align="left" valign="top"><em>0</em></td>
<td align="left" valign="top">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.)</td>
</tr>
<tr>
<td align="left" valign="top"><em>1</em></td>
<td align="left" valign="top">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.</td>
</tr>
<tr>
<td align="left" valign="top"><em>2</em></td>
<td align="left" valign="top">When objects are changed, write the changes to
auxiliary storage.</td>
</tr>
<tr>
<td align="left" valign="top"><em>3</em></td>
<td align="left" valign="top">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.</td>
</tr>
<tr>
<td align="left" valign="top"><em>4</em></td>
<td align="left" valign="top">Do not immediately write the changes to auxiliary
storage.</td>
</tr>
</table>
<p>The value specified for this field is ignored unless static tuning is
specified for the type of tuning field.</p>
<p><strong>Type of tuning.</strong> The method used by the system to tune the
storage pool. The values for this field are:</p>
<table cellpadding="5">
<!-- cols="5 95" -->
<tr>
<td align="left" valign="top"><em>0</em></td>
<td align="left" valign="top">No tuning is being performed for this pool.
<p>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.</p>
</td>
</tr>
<tr>
<td align="left" valign="top"><em>1</em></td>
<td align="left" valign="top">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.
<p>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.</p>
</td>
</tr>
<tr>
<td align="left" valign="top"><em>2</em></td>
<td align="left" valign="top">Dynamic tuning of transfers into main storage is
being performed. This indicates that the system is dynamically adjusting the
blocking factor and exchange operations.
<p>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.</p>
</td>
</tr>
<tr>
<td align="left" valign="top"><em>3</em></td>
<td align="left" valign="top">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.
<p>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.</p>
</td>
</tr>
</table>
<br>
<h3>Error Messages</h3>
<table width="100%" cellpadding="5">
<!-- cols="15 85" -->
<tr>
<th align="left" valign="top">Message ID</th>
<th align="left" valign="top">Error Message Text</th>
</tr>
<tr>
<td align="left" valign="top" width="15%">CPF1001 E</td>
<td align="left" valign="top" width="85%">Wait time expired for system
response.</td>
</tr>
<tr>
<td align="left" valign="top">CPF1870 E</td>
<td align="left" valign="top">Value &amp;1 for type of tuning not valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPF1871 E</td>
<td align="left" valign="top">Value &amp;1 for change page handling not
valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPF1872 E</td>
<td align="left" valign="top">Value &amp;1 for blocking factor not valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPF1873 E</td>
<td align="left" valign="top">Value &amp;1 for exchange operation not
valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPF1874 E</td>
<td align="left" valign="top">Value &amp;1 for transfer to auxiliary storage
not valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPF1875 E</td>
<td align="left" valign="top">Value &amp;1 for change request length not
valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPF1876 E</td>
<td align="left" valign="top">Value &amp;1 for pool number not valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPF24B4 E</td>
<td align="left" valign="top">Severe error while addressing parameter
list.</td>
</tr>
<tr>
<td align="left" valign="top">CPF3CF1 E</td>
<td align="left" valign="top">Error code parameter not valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPF3CF2 E</td>
<td align="left" valign="top">Error(s) occurred during running of &amp;1
API.</td>
</tr>
<tr>
<td align="left" valign="top">CPF3C21 E</td>
<td align="left" valign="top">Format name &amp;1 is not valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPF3C90 E</td>
<td align="left" valign="top">Literal value cannot be changed.</td>
</tr>
<tr>
<td align="left" valign="top">CPF9872 E</td>
<td align="left" valign="top">Program or service program &amp;1 in library
&amp;2 ended. Reason code &amp;3.</td>
</tr>
</table>
<br>
<hr>
API introduced: V2R3
<hr>
<center>
<table cellpadding="2" cellspacing="2">
<tr align="center">
<td valign="middle" align="center"><a href="#Top">Top</a> | <a href="wm1.htm">
Work Management APIs</a> | <a href="aplist.htm">APIs by category</a></td>
</tr>
</table>
</center>
</body>
</html>