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

510 lines
15 KiB
HTML
Raw Normal View History

2024-04-02 14:02:31 +00:00
<!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>Retrieve Authorization List Information (QSYRTVAI) 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. -->
<!-- Sec 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 -->
<!-- Edited by Kersten Jan 02 -->
<!--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 language="Javascript" src="../rzahg/synch.js" type="text/javascript">
</script>
<h2>Retrieve Authorization List Information (QSYRTVAI) 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">Format</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Char(8)</td>
</tr>
<tr>
<td align="center" valign="top">4</td>
<td align="left" valign="top">Authorization list name</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Char(10)</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: *USE<br>
<!-- iddvc RMBR -->
<br>
&nbsp;&nbsp;Threadsafe: Yes<br>
<!-- iddvc RMBR -->
<br>
</div>
<p>The Retrieve Authorization List Information (QSYRTVAI) API returns to
the caller
information about the number of authorization list entries that are in use
for the specified authorization list.
The returned information can be use to determine how full an authorization list
is.
</p>
<p>The normal view of an authorization list (AUTL) is that it is a single
object (structure) with the capacity to secure 2,097,104
objects. However, to successfully manage the fullness of an AUTL, a more comprehensive
view of an AUTL is required.</p>
<p>When an object is secured by an AUTL, each piece of the object
may have to be individually
secured by the AUTL. This means that when an object is secured by an AUTL, multiple
entries in the AUTL may be used by the system to secure all of the parts
of the object. For example, when a database file with multiple members is secured by
an AUTL,
multiple entries in the AUTL will be used.
Because of this, using commands like DSPAUTLOBJ (Display
Authorization List Objects) and APIs like QSYLATLO (List Authorization List
Objects), is not an effective way to determine whether an AUTL is becoming full.
</p>
<p>In addition, the first
time an AUTL is used to secure an object that resides in an independent
auxiliary storage pool (ASP),
the system creates an internal structure in the independent
ASP that is transparently
tied to the AUTL object. This internal structure is called an authorization
list extension. The authorization list extension has entries just like the AUTL
but these entries can only be used to secure objects that reside in the independent
ASP.
An authorization list extension also has a maximum of 2,097,104 entries. These
entries are in addition to the 2,097,104 entries in the base AUTL which are
used to secure objects in the system and basic user auxiliary storage pools
(*SYSBAS). The system can have a maximum of 223 independent
ASPs; therefore, the theoretical combined
limit for an AUTL and its extensions is 469,751,296 entries
(224 multiplied by 2,097,104).
</p>
<p>If an attempt is made to secure an object that resides in an independent
ASP with an
AUTL but all of the entries in the authorization list extension for the object's
independent ASP have
been used; an MCH2804 exception will occur indicating that the storage limit for
the AUTL has been reached. This would happen even if there were unused entries
available for objects that reside in *SYSBAS. Likewise, if an attempt is made to
secure an object that resides in *SYSBAS with an AUTL but all of the AUTL's
*SYSBAS entries have been used; an MCH2804 exception will occur even if there are
unused entries available in authorization list extensions for the AUTL.
</p>
<p>To effectively manage the fullness of an AUTL, a user needs to ensure that
no single set of entries (the *SYSBAS set and the authorization list extension sets)
exceed their individual 2,097,104 entry limit.
</p>
<p>This API returns information about the total number of entries used for
*SYSBAS and all varied on independent
ASPs for the specified
AUTL as well as detailed entry use information for *SYSBAS and each varied on
independent ASP.
</p>
<br>
<h3>Authorities and Locks</h3>
<dl>
<dt><em>Authorization List Authority</em></dt>
<dd>*READ</dd>
</dl>
<br>
<h3>Required Parameter Group</h3>
<dl>
<dt><strong>Receiver variable</strong></dt>
<dd>OUTPUT; CHAR(*)
<p>The variable used to return the information about the AUTL. An
approximation of the
size needed for this receiver variable can be obtained by calling the QSYRTVAI API with
the <em>length of receiver variable</em> set to 8 bytes. The <em>bytes available</em>
value that
is returned in this receiver variable will indicate the approximate size needed for the
receiver variable. The receiver variable format is defined in <a href=
"#HDRRTAI100">RTAI0100 Format</a>.</p>
</dd>
<dt><strong>Length of receiver variable</strong></dt>
<dd>INPUT; BINARY(4)
<p>The length of the receiver variable. This value must be at least 8.
</p>
</dd>
<dt><strong>Format</strong></dt>
<dd>INPUT; CHAR(8)
<p>The name of the format that is used to return the AUTL's information.
</p>
<p>The following value is allowed:</p>
<table cellpadding="5">
<!-- cols="30 70" -->
<tr>
<td align="left" valign="top"><em><a href="#HDRRTAI100">RTAI0100</a></em></td>
<td align="left" valign="top">Authorization list information is returned.</td>
</tr>
</table>
<br>
</dd>
<dt><strong>Authorization list name</strong></dt>
<dd>INPUT; CHAR(10)
<p>The name of the authorization list for which information is to be returned.
The name must be specified in uppercase.</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>Format of Receiver Variable</h3>
<p>The following tables describe the receiver variable that is returned by the
QSYRTVAI API.</p>
<p>For detailed descriptions of the fields in this table, see <a href=
"#HDRRTVAIFD">Field Descriptions</a>.</p>
<br>
<h4><a name="HDRRTAI100">RTAI0100 Format</a></h4>
<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%">BINARY(4)</td>
<td align="left" valign="top" width="60%">Bytes returned</td>
</tr>
<tr>
<td align="center" valign="top">4</td>
<td align="center" valign="top">4</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Bytes available</td>
</tr>
<tr>
<td align="center" valign="top">8</td>
<td align="center" valign="top">8</td>
<td align="left" valign="top">BINARY(8)</td>
<td align="left" valign="top">Total entries used</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">Offset to ASP information sets</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 ASP information sets</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">Length of ASP information set entry</td>
</tr>
<tr>
<td align="center" valign="top">*</td>
<td align="center" valign="top">*</td>
<td align="left" valign="top">Array of CHAR(*)</td>
<td align="left" valign="top">ASP information sets</td>
</tr>
</table>
<br>
<h4><a name="HDRRTIS100">ASP Information Set</a></h4>
<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%">ASP name</td>
</tr>
<tr>
<td align="center" valign="top">10</td>
<td align="center" valign="top">A</td>
<td align="left" valign="top">CHAR(1)</td>
<td align="left" valign="top">AUTL extension indicator</td>
</tr>
<tr>
<td align="center" valign="top">11</td>
<td align="center" valign="top">B</td>
<td align="left" valign="top">CHAR(1)</td>
<td align="left" valign="top">Reserved</td>
</tr>
<tr>
<td align="center" valign="top">12</td>
<td align="center" valign="top">C</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Number of entries used</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">Number entries available</td>
</tr>
</table>
<br>
<br>
<h3><a name="HDRRTVAIFD">Field Descriptions</a></h3>
<p><strong>ASP name.</strong> The name of the ASP whose information is
being returned. The system ASP and basic user ASP information is returned
with an ASP name of <strong>*SYSBAS</strong>. For independent
ASPs, the ASP name is the name
of the varied on device description associated with the independent
ASP.</p>
<p><strong>AUTL extension indicator.</strong> This field indicates whether an
authorization list extension exists for the specified AUTL on the varied on
independent ASP. The possible values for this field are:</p>
<dl>
<dt>Blank</dt>
<dd>This is the value returned for *SYSBAS. AUTL extensions are not applicable
to the base AUTL object that secures objects in *SYSBAS.</dd>
<dt>0</dt>
<dd>An AUTL extension for the specified AUTL does not exist on this
independent ASP.</dd>
<dt>1</dt>
<dd>An AUTL extension for the specified AUTL does exist on this
independent ASP.</dd>
</dl>
<p><strong>Bytes available.</strong> The number of bytes of data available to
be returned to the user.</p>
<p>If the <em>bytes available</em> field is larger than the <em>bytes returned</em>
field, all of the ASP information will not be included in the
receiver variable.</p>
<p><strong>Bytes returned.</strong> The number of bytes of data returned to the
user in the receiver variable.</p>
<p><strong>Length of ASP information set entry.</strong> The length of a single
ASP information set.
<p><strong>Number of ASP information sets.</strong> The number of
ASP information sets. This is the total number of information sets that could
be returned. There is always one ASP information set for
*SYSBAS. Additional ASP information sets are provided for each
varied on independent ASP even if the authorization list does not currently
secure any objects in the independent ASP. The ASP information set for *SYSBAS
is always the first ASP information set returned.
</p>
<p><strong>Number of entries used.</strong> The number of entries used for securing
objects that reside in the ASP. This field can have a value from zero to
2,097,104.</p>
<p><strong>Number entries available.</strong> The number of entries available for
securing additional
objects that reside in the ASP. This field can have a value from zero to
2,097,104.</p>
<p><strong>Offset to ASP information sets.</strong> The offset from the beginning
of the receiver variable to the begining of the ASP information sets.
<p><strong>Reserved.</strong> Reserved space used for boundary alignment.
<p><strong>Total entries used.</strong> The total number of authorization list
entries used for all objects secured by the authorization list that reside in
the system ASP, basic user ASPs, and all varied on independent ASPs. This
field can have a value ranging from zero to the
(number-of-varied-on-independent-ASPs + 1) multiplied by 2,097,104.</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">CPF22F0 E</td>
<td align="left" valign="top">Unexpected errors occurred during processing.</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">CPF3C24 E</td>
<td align="left" valign="top">Length of receiver variable is not valid.</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">CPF8132 E</td>
<td align="left" valign="top">Authorization list &amp;4 damaged.</td>
</tr>
<tr>
<td align="left" valign="top">CPF9801 E</td>
<td align="left" valign="top">Object &amp;2 in library &amp;3 not found.</td>
</tr>
<tr>
<td align="left" valign="top">CPF9802 E</td>
<td align="left" valign="top">Not authorized to object &amp;2 in &amp;3.</td>
</tr>
<tr>
<td align="left" valign="top">CPF9803 E</td>
<td align="left" valign="top">Cannot allocate object &amp;2 in library &amp;3.</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: V5R4
<hr>
<center>
<table cellpadding="2" cellspacing="2">
<tr align="center">
<td valign="middle" align="center"><a href="#Top_Of_Page">Top</a> | <a href=
"sec.htm">Security APIs</a> | <a href="aplist.htm">APIs by category</a></td>
</tr>
</table>
</center>
</body>
</html>