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

597 lines
17 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 Server Authentication Entries (QSYRTVSE,
QsyRetrieveServerEntries) 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 -->
<!--File Edited April 2001 -->
<!--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 Server Authentication Entries (QSYRTVSE,
QsyRetrieveServerEntries) API</h2>
<div class="box" style="width: 80%;">
<br>
&nbsp;&nbsp;<img src="delta.gif" alt="Start of change">Required Parameter Group for QSYRTVSE:<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">Return records feedback information</td>
<td align="left" valign="top">Output</td>
<td align="left" valign="top">Char(12)</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">Starting server name</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Char(*)</td>
</tr>
<tr>
<td align="center" valign="top">6</td>
<td align="left" valign="top">Length of starting server name</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Binary(4)</td>
</tr>
<tr>
<td align="center" valign="top">7</td>
<td align="left" valign="top">Starting server option</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Char(1)</td>
</tr>
<tr>
<td align="center" valign="top">8</td>
<td align="left" valign="top">User profile</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Char(10)</td>
</tr>
<tr>
<td align="center" valign="top">9</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>
<br>
<div class="box" style="width: 80%;">
<br>
&nbsp;&nbsp;Syntax for QsyRetrieveServerEntries:<br>
<pre>
#include &lt;qsysvrfn.h&gt;
void QsyRetrieveServerEntries
(void *<em>Receiver_variable</em>,
int <em>Length_of_receiver_variable</em>,
Qsy_RSVRE_Feedback_Info_T *<em>Return_records_feedback_information</em>,
char *<em>Format_name</em>,
char *<em>Starting_server_name</em>,
int <em>Length_of_starting_server_name</em>,
char <em>Starting_server_option</em>,
char <em>User_profile</em>[10],
void *<em>Error_code</em>);
</pre>
&nbsp;&nbsp;Service Program: QSYSVRFN<br>
<!-- iddvc RMBR -->
<br>
&nbsp;&nbsp;Default Public Authority: *USE<br>
<!-- iddvc RMBR -->
<br>
&nbsp;&nbsp;Threadsafe: No<img src="deltaend.gif" alt="End of change"><br>
<!-- iddvc RMBR -->
<br>
</div>
<p>The Retrieve Server Authentication Entries (OPM, QSYRTVSE; ILE,
QsyRetrieveServerEntries) API returns a list of server authentication
entries for a user profile.</p>
<br>
<h3>Authorities and Locks</h3>
<dl>
<dt><em>User Profile Authority</em></dt>
<dd><em>*READ</em></dd>
</dl>
<br>
<h3><em>Required Parameter Group</em></h3>
<dl>
<dt><strong>Receiver variable</strong></dt>
<dd>OUTPUT; CHAR(*)
<p>The receiver variable that receives the information requested. You
can specify the size of the area to be smaller than the format requested
as long as you specify the length parameter correctly. As a result, the
API returns only the data that the area can hold.</p>
</dd>
<dt><strong>Length of receiver variable</strong></dt>
<dd>INPUT; BINARY(4)
<p>The length of the receiver variable provided. The length of
receiver variable parameter may be specified up to the size of the
receiver variable specified in the user program. If the length of receiver
variable parameter specified is larger than the allocated size of the
receiver variable specified in the user program, the results are not
predictable.</p>
</dd>
<dt><strong>Returned records feedback information</strong></dt>
<dd>OUTPUT; CHAR(12)
<p>Information about the entries that are returned in the receiver
variable.</p>
<p>See <a href="#HDRRTVSERR">Format of Returned Records Feedback
Information</a> for details.</p>
</dd>
<dt><strong>Format name</strong></dt>
<dd>INPUT; CHAR(8)
<p>The name of the format that is used to retrieve server
authentication entries for the user profile.</p>
<p>You can specify this format:</p>
<table cellpadding="5">
<!-- cols="15 85" -->
<tr>
<td width="15%" valign="top"><em>SVRE0100</em></td>
<td width="85%" valign="top">For a detailed description of this format,
see <a href="#HDRRSVRE10">SVRE0100 Format</a>.</td>
</tr>
</table>
<br>
</dd>
<dt><strong>Starting server name</strong></dt>
<dd>INPUT; CHAR(*)
<p>The server name at which to start listing server authentication
entries. The server authentication entries are listed in hexadecimal sort
sequence by server name.</p>
<p>Possible values follow:</p>
<table cellpadding="5">
<!-- cols="15 85" -->
<tr>
<td width="15%" valign="top"><em>*FIRST</em></td>
<td width="85%" valign="top">Server authentication entries are returned
starting with the server that has the smallest hexadecimal value.</td>
</tr>
<tr>
<td align="left" valign="top"><em>server name</em></td>
<td align="left" valign="top">If an exact match for the starting server name is found,
the starting server option parameter indicates whether that server
authentication entry is returned.</td>
</tr>
<tr>
<td align="left" valign="top"></td>
<td align="left" valign="top">If an exact match for the starting server name is not
found, the listing begins with the first existing server authentication
entry for the server name whose hexadecimal value would follow the
hexadecimal value of the specified starting server name.</td>
</tr>
</table>
<br>
</dd>
<dt><strong>Length of starting server name</strong></dt>
<dd>INPUT; BINARY(4)
<p>The length of the starting server name. The length of the starting
server name may be from 1 to 200.</p>
</dd>
<dt><strong>Starting server option</strong></dt>
<dd>INPUT; CHAR(1)
<p>This parameter indicates whether the starting server authentication
entry is returned when an exact match for the starting server name is
found.</p>
<p>Possible values follow:</p>
<table cellpadding="5">
<!-- cols="5 95" -->
<tr>
<td width="15%" valign="top"><em>0</em></td>
<td width="85%" valign="top">Server authentication entries for server
names whose hexadecimal value is greater than the hexadecimal value for
the starting server name are returned.</td>
</tr>
<tr>
<td align="left" valign="top"><em>1</em></td>
<td align="left" valign="top">Server authentication entries for server names whose
hexadecimal value is equal to or greater than the hexadecimal value for
the starting server name are returned.</td>
</tr>
</table>
<br>
</dd>
<dt><strong>User profile</strong></dt>
<dd>INPUT; CHAR(10)
<p>The name of the user profile for which the server authentication
entries are returned.</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="HDRSYRSVR1">Receiver Variable Description</a></h3>
<p>The following tables describe the order and format of the data returned
in the receiver variable. For detailed descriptions of the fields in the
tables, see <a href="#HDRSYSVRE3">Field Descriptions</a>.</p>
<br>
<h4><a name="HDRRSVRE10">SVRE0100 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%">Length of entry</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">Length of server name</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">CCSID of server name</td>
</tr>
<tr>
<td align="center" valign="top">12</td>
<td align="center" valign="top">C</td>
<td align="left" valign="top">CHAR(200)</td>
<td align="left" valign="top">Server name</td>
</tr>
<tr>
<td align="center" valign="top">212</td>
<td align="center" valign="top">D4</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Displacement to user ID</td>
</tr>
<tr>
<td align="center" valign="top">216</td>
<td align="center" valign="top">D8</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Length of user ID</td>
</tr>
<tr>
<td align="center" valign="top">220</td>
<td align="center" valign="top">DC</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">CCSID of user ID</td>
</tr>
<tr>
<td align="center" valign="top">224</td>
<td align="center" valign="top">E0</td>
<td align="left" valign="top">CHAR(1)</td>
<td align="left" valign="top">Password stored indicator</td>
</tr>
<tr>
<td align="center" valign="top"></td>
<td align="center" valign="top"></td>
<td align="left" valign="top">CHAR(*)</td>
<td align="left" valign="top">User ID</td>
</tr>
</table>
<br>
<br>
<h4><a name="HDRRTVSERR">Format of Returned Records Feedback
Information</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">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(4)</td>
<td align="left" valign="top">Number of server authentication entries</td>
</tr>
</table>
<br>
<br>
<h3><a name="HDRSYSVRE3">Field Descriptions</a></h3>
<p><strong>Bytes available.</strong> The number of bytes of data available
to be returned to the user in the receiver variable. If all data is
returned, bytes available is the same as the number of bytes returned. If
the receiver variable was not large enough to contain all of the data,
this value is estimated based on the total number of server authentication
entries for the user profile and the format specified.</p>
<p><strong>Bytes returned.</strong> The number of bytes of data returned
to the user in the receiver variable. This is the lesser of the number of
bytes available to be returned or the length of the receiver variable.</p>
<p><strong>CCSID of server name.</strong> The CCSID of the server name.
This will be the default job CCSID of the job that added the server
authentication entry.</p>
<p><strong>CCSID of user ID.</strong> The CCSID of the user ID. This will
be the default job CCSID of the job that last changed the user ID field in
the server authentication entry.</p>
<p><strong>Displacement to user ID.</strong> The displacement in the entry
to the start of the user ID.</p>
<p><strong>Format name.</strong> The name of the format that is used to
return server authentication entries for a user profile.</p>
<p><strong>Length of entry.</strong> The length (in bytes) of the current
entry. This length can be used to access the next entry.</p>
<p><strong>Length of server name ID.</strong> The length (in bytes) of the
server name.</p>
<p><strong>Length of user ID.</strong> The length (in bytes) of the user
ID.</p>
<p><strong>Number of server authentication entries.</strong> The number of
complete entries returned in the list of server authentication entries. A
value of zero is returned if the list is empty.</p>
<p><strong>Password specified.</strong> Indicates whether the server
authentication entry has a password associated with it.</p>
<p>Possible values follow:</p>
<table cellpadding="5">
<!-- cols="5 95" -->
<tr>
<td width="15%" valign="top"><em>0</em></td>
<td width="85%" valign="top">The server authentication entry does not have
a password associated with it.</td>
</tr>
<tr>
<td align="left" valign="top"><em>1</em></td>
<td align="left" valign="top">The server authentication entry does have a password
associated with it.</td>
</tr>
</table>
<p><strong>Server name.</strong> The name of the server that the entry is
for.</p>
<p><strong>User ID.</strong> The user ID that is used on requests to the
server.</p>
<p><strong>User profile.</strong> The name of the user profile for which
the list of server authentication entries is returned.</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 width="15%" valign="top">CPFA0AA E</td>
<td width="85%" valign="top">Error occurred while attempting to obtain space.</td>
</tr>
<tr>
<td align="left" valign="top">CPF2204 E</td>
<td align="left" valign="top">User profile &amp;1 not found.</td>
</tr>
<tr>
<td align="left" valign="top">CPF2213 E</td>
<td align="left" valign="top">Not able to allocate user profile &amp;1.</td>
</tr>
<tr>
<td align="left" valign="top">CPF2217 E</td>
<td align="left" valign="top">Not authorized to user profile &amp;1.</td>
</tr>
<tr>
<td align="left" valign="top">CPF2222 E</td>
<td align="left" valign="top">Storage limit is greater than specified for user profile
&amp;1.</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">CPF3C1D E</td>
<td align="left" valign="top">Length specified in parameter &amp;1 not valid.</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">CPF3C3C E</td>
<td align="left" valign="top">Value for parameter &amp;1 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>
<hr>
API introduced: V4R2
<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>
<br>
</body>
</html>