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

703 lines
20 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>Open List of Activation Group Attributes (QWVOLAGP) 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 -->
<!-- File cleanup completed Nov 2001 by v2cdijab -->
<!-- Change history: -->
<!-- 021205 AARONA: V5R3 Support 64-bit marks, XPF DCR 99214 -->
<!-- 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>Open List of Activation Group Attributes (QWVOLAGP) 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%">Receiver variable</td>
<td align="left" valign="top" width="20%">Output</td>
<td align="left" valign="top" width="20%">Char(*)</td>
</tr>
<tr>
<td align="center" valign="top">2</td>
<td align="left" valign="top">Length of receiver variable</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Binary(4)</td>
</tr>
<tr>
<td align="center" valign="top">3</td>
<td align="left" valign="top">List information</td>
<td align="left" valign="top">Output</td>
<td align="left" valign="top">Char(80)</td>
</tr>
<tr>
<td align="center" valign="top">4</td>
<td align="left" valign="top">Number of records to return</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Binary(4)</td>
</tr>
<tr>
<td align="center" valign="top">5</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">6</td>
<td align="left" valign="top">Qualified job name</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Char(26)</td>
</tr>
<tr>
<td align="center" valign="top">7</td>
<td align="left" valign="top">Internal job identifier</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Char(16)</td>
</tr>
<tr>
<td align="center" valign="top">8</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: *USE<br>
<!-- iddvc RMBR -->
<br>
&nbsp;&nbsp;Threadsafe: No<br>
<!-- iddvc RMBR -->
<br>
</div>
<p>The Open List of Activation Group Attributes (QWVOLAGP) API generates a list
of all the activation groups that are associated with a given job and their
attributes. The QWVOLAGP API places the list into a receiver variable. You can
access additional records by using the Get List Entries (QGYGTLE) API. On
successful completion of the QWVOLAGP API, a handle is returned in the list
information parameter. You may use this handle on subsequent calls to the
following APIs:</p>
<dl>
<dd>Get List Entries (QGYGTLE)</dd>
<dd>Find Entry Number in List (QGYFNDE)</dd>
<dd>Close List (QGYCLST)</dd>
</dl>
<p>The records returned by the QWVOLAGP API include an information status field
that describes the completeness and validity of the information. Be sure to
check the information status field before using any other information
returned.</p>
<br>
<h3>Authorities and Locks</h3>
<dl>
<dt><em>Job Authority</em></dt>
<dd>
<ul>
<li>*JOBCTL if the job for which activation group attributes are being
retrieved has a user profile different from that of the job that calls the
QWVOLAGP API.</li>
</ul>
For additional information on these authorities, see the <a href=
"../books/sc415302.pdf" target="_blank">iSeries Security Reference</a> <img
src="wbpdf.gif" alt="Link to PDF"> book.</dd>
</dl>
<br>
<h3>Required Parameter Group</h3>
<dl>
<dt><strong>Receiver variable</strong></dt>
<dd>OUTPUT; CHAR(*)
<p>The variable that is used to return the activation group attributes that was
requested.</p>
</dd>
<dt><strong>Length of receiver variable</strong></dt>
<dd>INPUT; BINARY(4)
<p>The length of the receiver variable.</p>
</dd>
<dt><strong>List information</strong></dt>
<dd>OUTPUT; CHAR(80)
<p>Information about the list of activation group attributes that were opened.
For a description of the layout of this parameter, see <a href="../apiref/oli.htm">Format
of Open List Information</a>.</p>
</dd>
<dt><strong>Number of records to return</strong></dt>
<dd>INPUT; BINARY(4)
<p>The number of records in the list to put into the receiver variable.</p>
</dd>
<dt><strong>Format name</strong></dt>
<dd>INPUT; CHAR(8)
<p>The format of the information to be returned in the receiver variable. You
must use the following format name:</p>
<table cellpadding="5">
<!-- cols="15 85" -->
<tr>
<td align="left" valign="top"><em>RAGA0100</em></td>
<td align="left" valign="top">This format is described in <a href=
"#HDRRAGA100">RAGA0100 Format</a>.</td>
</tr>
</table>
<br>
</dd>
<dt><strong>Qualified job name</strong></dt>
<dd>INPUT; CHAR(26)
<p>The job name, the job user profile, and the job number of the job for which
you want to return activation group attributes.</p>
<table cellpadding="5">
<!-- cols="15 85" -->
<tr>
<td align="left" valign="top"><em>CHAR 1-10</em></td>
<td align="left" valign="top">The job name</td>
</tr>
<tr>
<td align="left" valign="top"><em>CHAR 11-20</em></td>
<td align="left" valign="top">The user profile</td>
</tr>
<tr>
<td align="left" valign="top"><em>CHAR 21-26</em></td>
<td align="left" valign="top">The job number</td>
</tr>
</table>
<p>You can use these special values for the qualified job name:</p>
<table cellpadding="5">
<!-- cols="10 90" -->
<tr>
<td align="left" valign="top"><em>*</em></td>
<td align="left" valign="top">The job in which this program is running. The
rest of the qualified job name parameter must be blank.</td>
</tr>
<tr>
<td align="left" valign="top"><em>*INT</em></td>
<td align="left" valign="top">The internal job identifier locates the job. The
rest of the qualified job name parameter must be blank.</td>
</tr>
</table>
<br>
</dd>
<dt><strong>Internal job identifier</strong></dt>
<dd>INPUT; CHAR(16)
<p>The internal name for the job. The List Job (QUSLJOB) API creates this
identifier. If you do not specify *INT for the qualified job name parameter,
this parameter must contain blanks.</p>
<p>If your application already has this information available from the List Job
(QUSLJOB) API, the QWVOLAGP API can locate the job more quickly with this
information than with a job name. However, if you call QUSLJOB solely to obtain
this parameter for use by QWVOLAGP, you would get poorer performance than by
using a job name in calling QWVOLAGP.</p>
</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="HDRRAGA100">RAGA0100 Format</a></h3>
<p>The following table shows the information returned in the list data section
of the receiver variable for the RAGA0100 format. For a detailed description of
each field, see <a href="#HDRRAGAFD">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(10)</td>
<td align="left" valign="top" width="60%">Activation group name</td>
</tr>
<tr>
<td align="center" valign="top">10</td>
<td align="center" valign="top">A</td>
<td align="left" valign="top">CHAR(6)</td>
<td align="left" valign="top">Reserved</td>
</tr>
<tr>
<td align="center" valign="top">16</td>
<td align="center" valign="top">10</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Activation group number</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">Number of activations</td>
</tr>
<tr>
<td align="center" valign="top">24</td>
<td align="center" valign="top">18</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Number of heaps</td>
</tr>
<tr>
<td align="center" valign="top">28</td>
<td align="center" valign="top">1C</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Static storage size</td>
</tr>
<tr>
<td align="center" valign="top">32</td>
<td align="center" valign="top">20</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Heap storage size</td>
</tr>
<tr>
<td align="center" valign="top">36</td>
<td align="center" valign="top">24</td>
<td align="left" valign="top">CHAR(10)</td>
<td align="left" valign="top">Root program name</td>
</tr>
<tr>
<td align="center" valign="top">46</td>
<td align="center" valign="top">2E</td>
<td align="left" valign="top">CHAR(10)</td>
<td align="left" valign="top">Root program library</td>
</tr>
<tr>
<td align="center" valign="top">56</td>
<td align="center" valign="top">38</td>
<td align="left" valign="top">CHAR(1)</td>
<td align="left" valign="top">Root program type</td>
</tr>
<tr>
<td align="center" valign="top">57</td>
<td align="center" valign="top">39</td>
<td align="left" valign="top">CHAR(1)</td>
<td align="left" valign="top">Activation group state</td>
</tr>
<tr>
<td align="center" valign="top">58</td>
<td align="center" valign="top">3A</td>
<td align="left" valign="top">CHAR(1)</td>
<td align="left" valign="top">Shared activation group indication</td>
</tr>
<tr>
<td align="center" valign="top">59</td>
<td align="center" valign="top">3B</td>
<td align="left" valign="top">CHAR(1)</td>
<td align="left" valign="top">In-use indicator</td>
</tr>
<tr>
<td align="center" valign="top">60</td>
<td align="center" valign="top">3C</td>
<td align="left" valign="top">CHAR(4)</td>
<td align="left" valign="top">Reserved</td>
</tr>
<tr>
<td align="center" valign="top">64</td>
<td align="center" valign="top">40</td>
<td align="left" valign="top">BINARY(8)</td>
<td align="left" valign="top">Activation group number long</td>
</tr>
<tr>
<td align="center" valign="top">72</td>
<td align="center" valign="top">48</td>
<td align="left" valign="top">CHAR(8)</td>
<td align="left" valign="top">Reserved</td>
</tr>
</table>
<br>
<br>
<h3><a name="HDRRAGAFD">Field Descriptions</a></h3>
<p><strong>Activation group name.</strong> The name of the activation group
that contains the attributes listed. Possible values follow:</p>
<table cellpadding="5">
<!-- cols="15 85" -->
<tr>
<td align="left" valign="top"><em>*DFTACTGRP</em></td>
<td align="left" valign="top">The activation group is one of the default
activation groups.</td>
</tr>
<tr>
<td align="left" valign="top"><em>*UNNAMED</em></td>
<td align="left" valign="top">The activation group does not have a name.</td>
</tr>
</table>
<p><strong>Activation group number.</strong> The activation group number of the
activation group listed. This is the last 32 bits of a 64 bit internal number
that uniquely identifies the activation group within the job. The full 64 bit
value can be retrieved using the "Activation group number long" field.</p>
<p><strong>Activation group number long.</strong> The 64 bit activation
group number of the activation group listed. This is an internal number that
uniquely identifies the activation group within the job.</p>
<p><strong>Activation group state.</strong> The state of the activation group.
Possible values follow:</p>
<table cellpadding="5">
<!-- cols="5 95" -->
<tr>
<td align="left" valign="top"><em>0</em></td>
<td align="left" valign="top">The activation group is in user state.</td>
</tr>
<tr>
<td align="left" valign="top"><em>1</em></td>
<td align="left" valign="top">The activation group is in system state.</td>
</tr>
</table>
<p><strong>Heap storage size.</strong> The total amount of heap storage that is
allocated to the activation group in bytes.</p>
<p><strong>In-use indicator.</strong> Whether the activation group is eligible
to be reclaimed. An activation group can be reclaimed by the Reclaim Activation
Group (RCLACTGRP) command. Possible values follow:</p>
<table cellpadding="5">
<!-- cols="5 95" -->
<tr>
<td align="left" valign="top"><em>0</em></td>
<td align="left" valign="top">The activation group is not in use and is
eligible to be reclaimed.</td>
</tr>
<tr>
<td align="left" valign="top"><em>1</em></td>
<td align="left" valign="top">The activation group is in use and cannot be
reclaimed.</td>
</tr>
</table>
<p><strong>Note:</strong> It is not recommended to reclaim eligible activation
groups if you are not familiar with that activation group. Other activation
groups may have references to the activation group that you are reclaiming. For
example, a program of one activation group could be bound to a service program
that belongs to another activation group. If you reclaim the service program's
activation group and then call the program, you will get a destroyed object
error when the service program is referred to.</p>
<p><strong>Number of activations.</strong> The total number of program
activations in this activation group.</p>
<p><strong>Number of heaps.</strong> The total number of heaps that are
allocated by this activation group.</p>
<p><strong>Reserved.</strong> An ignored field.</p>
<p><strong>Root program library.</strong> The name of the library that contains
the program that caused this activation group to be created. The possible value
follows:</p>
<table cellpadding="5">
<!-- cols="5 95" -->
<tr>
<td align="left" valign="top"><em>*N</em></td>
<td align="left" valign="top">The program no longer exists in the system.</td>
</tr>
</table>
<p><strong>Note:</strong> When the activation group is the default activation
group, there is no root program. Blanks are returned in this case.</p>
<p><strong>Root program name.</strong> The name of the program that caused this
activation group to be created. The possible value follows:</p>
<table cellpadding="5">
<!-- cols="5 95" -->
<tr>
<td align="left" valign="top"><em>*N</em></td>
<td align="left" valign="top">The program no longer exists in the system.</td>
</tr>
</table>
<p><strong>Note:</strong> When the activation group is the default activation
group, there is no root program. Blanks are returned in this case.</p>
<p><strong>Root program type.</strong> The type of program that caused this
activation group to be created. Possible values follow:</p>
<table cellpadding="5">
<!-- cols="5 95" -->
<tr>
<td align="left" valign="top"><em>N</em></td>
<td align="left" valign="top">The program no longer exists in the system.</td>
</tr>
<tr>
<td align="left" valign="top"><em>0</em></td>
<td align="left" valign="top">The type is a program or *PGM.</td>
</tr>
<tr>
<td align="left" valign="top"><em>1</em></td>
<td align="left" valign="top">The type is a service program or *SRVPGM.</td>
</tr>
<tr>
<td align="left" valign="top"><em>2</em></td>
<td align="left" valign="top">The type is a Java program.</td>
</tr>
</table>
<p><strong>Note:</strong> When the activation group is the default activation
group, there is no root program. A blank is returned in this case.</p>
<p><strong>Shared activation group indication.</strong> Whether the activation
group is shared or not. A shared activation group is an activation group that
belongs to more than one job at the same time. Possible values follow:</p>
<table cellpadding="5">
<!-- cols="5 95" -->
<tr>
<td align="left" valign="top"><em>0</em></td>
<td align="left" valign="top">The activation group is not shared with other
jobs.</td>
</tr>
<tr>
<td align="left" valign="top"><em>1</em></td>
<td align="left" valign="top">The activation group is shared with other
jobs.</td>
</tr>
</table>
<p><strong>Static storage size.</strong> The total amount of static storage
allocated to the activation group in bytes.</p>
<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%">CPF0941 E</td>
<td align="left" valign="top" width="85%">Job &amp;3/&amp;2/&amp;1 no longer in
system.</td>
</tr>
<tr>
<td align="left" valign="top">CPF1071 E</td>
<td align="left" valign="top">No authority to job &amp;3/&amp;2/&amp;1.</td>
</tr>
<tr>
<td align="left" valign="top">CPF136A E</td>
<td align="left" valign="top">Job &amp;3/&amp;2/&amp;1 not active.</td>
</tr>
<tr>
<td align="left" valign="top">CPF136B E</td>
<td align="left" valign="top">Job &amp;3/&amp;2/&amp;1 in use.</td>
</tr>
<tr>
<td align="left" valign="top">CPF136C E</td>
<td align="left" valign="top">Value &amp;2 for activation group 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">CPF2401 E</td>
<td align="left" valign="top">Not authorized to library &amp;1.</td>
</tr>
<tr>
<td align="left" valign="top">CPF3C19 E</td>
<td align="left" valign="top">Error occurred with receiver variable
specified.</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">CPF3C51 E</td>
<td align="left" valign="top">Internal job identifier not valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPF3C52 E</td>
<td align="left" valign="top">Internal job identifier no longer valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPF3C53 E</td>
<td align="left" valign="top">Job &amp;3/&amp;2/&amp;1 not found.</td>
</tr>
<tr>
<td align="left" valign="top">CPF3C58 E</td>
<td align="left" valign="top">Job name specified is not valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPF3C59 E</td>
<td align="left" valign="top">Internal identifier is not blanks and job name is
not *INT.</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">CPF3CF1 E</td>
<td align="left" valign="top">Error code parameter not valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPF9830 E</td>
<td align="left" valign="top">Cannot assign library &amp;1.</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>
<tr>
<td align="left" valign="top">GUI0002 E</td>
<td align="left" valign="top">&amp;2 is not valid for length of receiver
variable.</td>
</tr>
<tr>
<td align="left" valign="top">GUI0027 E</td>
<td align="left" valign="top">&amp;1 is not valid for number of records to
return.</td>
</tr>
</table>
<br>
<hr>
API introduced: V4R2
<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>