378 lines
13 KiB
HTML
378 lines
13 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>Allocation Strategy Type (CEE4ALC)</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. -->
|
|
<!-- Change History: -->
|
|
<!-- YYMMDD USERID Change description -->
|
|
<!-- ILE8A SCRIPT A converted by B2H R4.1 (346) (CMS) by NLJONES at -->
|
|
<!-- RCHVMX on 25 Feb 1999 at 15:15:15 -->
|
|
<!-- 041006 AARONA Mark PAG field as deprecated -->
|
|
<!--Edited by Kersten Nov 2001 -->
|
|
<!-- End Header Records -->
|
|
<link rel="stylesheet" type="text/css" href="../rzahg/ic.css">
|
|
</head>
|
|
<body>
|
|
<!--Java sync-link-->
|
|
<script type="text/javascript" language="Javascript" src="../rzahg/synch.js">
|
|
</script>
|
|
|
|
<a name="Top_Of_Page"></a>
|
|
|
|
<h2>Allocation Strategy Type (CEE4ALC)</h2>
|
|
|
|
<p>The CEE4ALC allocation strategy type contains attributes that are used to
|
|
define the characteristics of the storage allocated for heaps. ILE C defines
|
|
the attributes as shown in <a href="#FIGALCC">CEE4ALC Definition for ILE C</a>. ILE COBOL defines
|
|
the attributes as shown in <a href="#FIGALCCOB">CEE4ALC Definition for ILE COBOL</a>, and ILE RPG
|
|
defines the attributes as shown in <a href="#FIGALCRPG">CEE4ALC Definition for ILE RPG</a>.</p>
|
|
|
|
<br>
|
|
<h3><a name="HDRDEFHP">User-Defined Allocation Strategy</a></h3>
|
|
|
|
<p>You can define an allocation strategy by altering the attributes of the
|
|
CEE4ALC allocation strategy type. You do this with the Define Heap Allocation
|
|
Strategy (CEE4DAS) API. Then, when you use the Create Heap (CEECRHP) API, you
|
|
can specify the allocation strategy that you defined for the heap attributes
|
|
you require.</p>
|
|
|
|
<p>If you use the CEECRHP API, but did not define an allocation strategy, a
|
|
default allocation strategy provides the heap attributes. See <a href=
|
|
"#HDRDEFEHP">The Default Heap</a> for a description of the default allocation
|
|
strategy.</p>
|
|
|
|
<p><strong>Note:</strong> The creation size and extension size values of
|
|
CEE4ALC may be overridden. You do this by specifying values for the
|
|
initial_size parameter and the increment parameter on the CEECRHP bindable
|
|
API.</p>
|
|
|
|
<p>For ILE C the CEE4ALC allocation strategy type is defined as follows:</p>
|
|
|
|
<p><strong><a name="FIGALCC">CEE4ALC Definition for ILE
|
|
C</a></strong><br>
|
|
</p>
|
|
|
|
<img src="delta.gif" alt="Start of change"><pre>
|
|
struct _CEE4ALC {
|
|
_INT4 max_sngl_alloc; /* maximum size of a single allocation */
|
|
_INT4 min_ddy; /* minimum boundary alignment of any allocation */
|
|
_INT4 crt_size; /* initial creation size of the heap */
|
|
_INT4 ext_size; /* the extension size of the heap */
|
|
_INT2 reserved1; /* must be binary 0 */
|
|
_BITS alloc_strat:1; /* a choice for allocation strategy */
|
|
_BITS no_mark:1; /* a group deallocation choice */
|
|
_BITS blk_xfer:1; /* a choice for block transfer of a heap */
|
|
_BITS PAG:1; /* a choice for heap creation in a PAG */
|
|
/* The PAG option is ignored in i5/OS */
|
|
/* version 5 release 4 and later releases */
|
|
_BITS alloc_init:1; /* a choice for allocation initialization */
|
|
_UCHAR init_value; /* initialization value */
|
|
_BITS reserved2:3; /* must be binary 0 */
|
|
_BITS reserved3:32; /* must be binary 0 */
|
|
};
|
|
</pre><img src="deltaend.gif" alt="End of change">
|
|
|
|
<p>For ILE COBOL the CEE4ALC allocation strategy type is defined as
|
|
follows:</p>
|
|
|
|
<p><strong><a name="FIGALCCOB">CEE4ALC Definition for ILE
|
|
COBOL</a></strong><br>
|
|
</p>
|
|
|
|
<img src="delta.gif" alt="Start of change"><pre>
|
|
01 CEE4ALC-my-own.
|
|
05 max-sngl-alloc pic 9(9) BINARY.
|
|
05 min-bdy pic 9(9) BINARY.
|
|
05 crt-size pic 9(9) BINARY.
|
|
05 ext-size pic 9(9) BINARY.
|
|
05 reserved1 pic 9(4) BINARY VALUE 0.
|
|
05 my-bits pic x VALUE X"E8".
|
|
* Using initial value of X"E8" , alloc_strat, no_mark,
|
|
* blk_xfer, and alloc_init are set to TRUE
|
|
05 init-value pic x.
|
|
05 my-reserved2 pic x(5).
|
|
05 my-reserved3 pic x(5).
|
|
</pre><img src="deltaend.gif" alt="End of change">
|
|
|
|
|
|
<p>For ILE RPG the CEE4ALC allocation strategy type is defined as follows:</p>
|
|
|
|
<p><strong><a name="FIGALCRPG">CEE4ALC Definition for ILE
|
|
RPG</a></strong>
|
|
</p>
|
|
|
|
<pre>
|
|
D CEE4ALC DS
|
|
D MaxSglAloc 10I 0
|
|
D MinBdy 10I 0
|
|
D CrtSiz 10I 0
|
|
D ExtSiz 10I 0
|
|
D res1 5I 0
|
|
D AllocBits 1A
|
|
D InitValue 1A
|
|
D res2 5A
|
|
* Use BITON to set on the appropriate bit.
|
|
* For example BITON AllocInit AllocBits
|
|
D AllocStrat C '0'
|
|
D NoMark C '1'
|
|
D BlkXfer C '2'
|
|
D PAG C '3'
|
|
D AllocInit C '4'
|
|
</pre>
|
|
|
|
<br>
|
|
<dl>
|
|
<dt><strong>max_sngl_alloc</strong></dt>
|
|
|
|
<dd>The maximum allocation size, in bytes, of any single allocation from the
|
|
heap. This attribute is useful for controlling the use of the heap. The minimum
|
|
value for this attribute is 4 bytes, and the maximum value is 16MB minus 64KB.
|
|
If 0 is specified, the default value of 16MB minus 64KB is used.<br>
|
|
<br>
|
|
</dd>
|
|
|
|
<dt><strong>min_bdy</strong></dt>
|
|
|
|
<dd>The minimum boundary alignment, in bytes, associated with any allocation
|
|
from the heap. The minimum value for a boundary alignment is 4 bytes, and
|
|
maximum value is 512 bytes. To allow valid pointers to be stored in a storage
|
|
allocation with the heap, a minimum boundary alignment of 16 bytes is required.
|
|
If zero is specified, a default value of 16 bytes is used for the boundary
|
|
alignment. The minimum boundary alignment is rounded up to a power of 2.<br>
|
|
<br>
|
|
</dd>
|
|
|
|
<dt><strong>crt_size</strong></dt>
|
|
|
|
<dd>The creation size, in bytes, of the heap. The minimum value for the size of
|
|
the heap is 512 bytes and the maximum value is 16MB minus 1KB. If 0 is
|
|
specified, the system computes a default value. The value is rounded up to a
|
|
512-byte boundary.
|
|
|
|
<p><strong>Note:</strong> If system resources are constrained, the system may
|
|
override the value specified.</p>
|
|
</dd>
|
|
|
|
<dt><strong>ext_size</strong></dt>
|
|
|
|
<dd>The extension size of the heap in bytes. The minimum value for extension
|
|
size is 512 bytes and the maximum value is 16MB minus 1KB. If 0 is specified
|
|
the system computes a default value. The value is rounded up to a 512-byte
|
|
boundary.
|
|
|
|
|
|
<p><strong>Note:</strong> If system resources are constrained, the system may
|
|
override the value specified.</p>
|
|
</dd>
|
|
|
|
<dt><strong>reserved1</strong></dt>
|
|
|
|
<dd>Must be binary 0.<br><br></dd>
|
|
|
|
<dt><strong>alloc_strat</strong></dt>
|
|
|
|
<dd>Allows a choice between:
|
|
|
|
<table cellpadding="5">
|
|
<!-- cols="15 85" -->
|
|
<tr>
|
|
<td align="left" valign="top"><em>0</em></td>
|
|
<td align="left" valign="top">Normal allocation strategy.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>1</em></td>
|
|
<td align="left" valign="top">Create a process space on each allocation.</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<p><strong>Note:</strong> This option should be used only in unusual
|
|
situations, such as in debugging application problems caused by references past
|
|
the end of an allocation.</p>
|
|
</dd>
|
|
|
|
<dt><strong>no_mark</strong></dt>
|
|
|
|
<dd>Allows a choice between:
|
|
|
|
<table cellpadding="5">
|
|
<!-- cols="15 85" -->
|
|
<tr>
|
|
<td align="left" valign="top"><em>0</em></td>
|
|
<td align="left" valign="top">Allow the use of the CEEMKHP and CEERLHP
|
|
APIs.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>1</em></td>
|
|
<td align="left" valign="top">Do not allow the use of the CEEMKHP and CEERLHP
|
|
APIs.</td>
|
|
</tr>
|
|
</table><br>
|
|
</dd>
|
|
|
|
<dt><strong>blk_xfer</strong></dt>
|
|
|
|
<dd><img src="delta.gif" alt="Start of change">Used to increase the
|
|
performance of a heap based on prior knowledge of how the heap is used.
|
|
The values are:<img src="deltaend.gif" alt="End of change">
|
|
|
|
|
|
|
|
<table cellpadding="5">
|
|
<!-- cols="15 85" -->
|
|
<tr>
|
|
<td align="left" valign="top"><em>0</em></td>
|
|
<td align="left" valign="top">Transfer the minimum storage transfer size (that
|
|
is, 1 storage unit).</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>1</em></td>
|
|
<td align="left" valign="top">Transfer the machine default storage transfer
|
|
size (that is, 8 storage units).</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<p><strong>Note:</strong> On the reduced instruction set computer (RISC)
|
|
hardware, this parameter has no effect. Regardless of whether 0 or 1 is
|
|
specified for blk_xfer, the machine default storage transfer size will always
|
|
be transferred.</p>
|
|
</dd>
|
|
|
|
<dt><strong>PAG</strong></dt>
|
|
|
|
<dd>A heap can be created as a process access group (PAG) member. The values
|
|
are:
|
|
|
|
<table cellpadding="5">
|
|
<!-- cols="15 85" -->
|
|
<tr>
|
|
<td align="left" valign="top"><em>0</em></td>
|
|
<td align="left" valign="top">Do not create the heap in the PAG.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>1</em></td>
|
|
<td align="left" valign="top">Create the heap in the PAG.</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<p><strong>Note:</strong> It is possible for the PAG to overflow, at which
|
|
point any requested PAG heap creations or extensions will not reside in the
|
|
PAG. Therefore, the system may ignore the request to create the heap in the
|
|
PAG.</p>
|
|
<p><img src="delta.gif" alt="Start of change"><strong>Note:</strong>
|
|
The PAG option is ignored in i5/OS version 5 release 4 and later releases.
|
|
<img src="deltaend.gif" alt="End of change"></p>
|
|
</dd>
|
|
|
|
<dt><strong>alloc_init</strong></dt>
|
|
|
|
<dd>Allows the user to specify if all storage allocations from the heap being
|
|
created will be initialized to the initialization value. The values are:
|
|
|
|
<table cellpadding="5">
|
|
<!-- cols="15 85" -->
|
|
<tr>
|
|
<td align="left" valign="top"><em>0</em></td>
|
|
<td align="left" valign="top">Do not initialize the heap with Init_Value.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>1</em></td>
|
|
<td align="left" valign="top">Initialize the heap with Init_Value.</td>
|
|
</tr>
|
|
</table><br>
|
|
</dd>
|
|
|
|
<dt><strong>init_value</strong></dt>
|
|
|
|
<dd>The value used to initialize the storage allocations. This value is not
|
|
used if <em>alloc_value</em> is 0.<br><br></dd>
|
|
|
|
<dt><strong>reserved2</strong></dt>
|
|
|
|
<dd>Must be binary 0.<br><br></dd>
|
|
|
|
<dt><strong>reserved3</strong></dt>
|
|
|
|
<dd>Must be binary 0.</dd>
|
|
</dl>
|
|
<br>
|
|
<h3><a name="HDRDEFEHP">The Default Heap</a></h3>
|
|
|
|
<p>From the programmer's viewpoint, a default heap is always available in the
|
|
activation group. In fact, the first request to allocate storage results in the
|
|
creation of the default heap from which the storage allocation takes place.</p>
|
|
|
|
<p>The attributes of the default heap are defined by the system through a
|
|
default allocation strategy. You cannot change this default allocation
|
|
strategy. Following is an example of the default allocation strategy:</p>
|
|
|
|
<pre>
|
|
Max_Sngl_Alloc = 16MB - 64KB
|
|
Min_Bdy = 16
|
|
Crt_Size = 4KB
|
|
Ext_Size = 4KB
|
|
Alloc_Strat = 0
|
|
No_Mark = 1
|
|
Blk_Xfer = 0
|
|
PAG = 0
|
|
Alloc_Init = 0
|
|
Init_Value = 0x00 /* This value is not used */
|
|
/* if Alloc_Init is 0 */
|
|
</pre>
|
|
|
|
<p>In addition, the default heap in an activation group has the following
|
|
special characteristics:</p>
|
|
|
|
<ul>
|
|
<li>It may not be discarded by CEEDSHP (discard a heap); it is guaranteed to be
|
|
present for the life of the activation group.</li>
|
|
|
|
<li>It is referred to with a heap identifier of 0.</li>
|
|
</ul>
|
|
|
|
<p>Languages that do not have an intrinsic multiple-heap storage model (such as
|
|
ILE C) use the default heap. This heap cannot be discarded and is immune to the
|
|
Mark Heap (CEEMKHP) and Release Heap (CEERLHP) APIs. Storage allocated within
|
|
the default heap can be freed only by explicit free operations or when the
|
|
owning activation group ends.</p>
|
|
|
|
<p>This implementation ensures that the storage is not inadvertently released
|
|
in mixed-language applications. Release heap and discard heap operations are
|
|
considered insecure for the following reasons:</p>
|
|
|
|
<ul>
|
|
<li>Large applications that re-use existing code with potentially different
|
|
storage models.</li>
|
|
|
|
<li>The programmer is not completely familiar with the internals of each
|
|
procedure.</li>
|
|
</ul>
|
|
|
|
<p>If release heap operations were valid for the default heap, then procedures
|
|
that correctly use different storage management capabilities separately might
|
|
fail when used in combination.</p>
|
|
|
|
|
|
<hr>
|
|
<center>
|
|
<table cellpadding="2""" cellspacing="2">
|
|
<tr align="center">
|
|
<td valign="middle" align="center"><a href="#Top_Of_Page">Top</a> | <a href=
|
|
"ile1a1.htm">ILE CEE APIs</a>| <a href="aplist.htm">APIs by category</a></td>
|
|
</tr>
|
|
</table>
|
|
</center>
|
|
</body>
|
|
</html>
|
|
|