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

516 lines
14 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>Open List of Semaphores (QP0ZOLSM) 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. -->
<!-- Direct1 SCRIPT J 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 Feb 02 -->
<!-- This file has undergone html cleanup on 05/01/02 by JET -->
<!--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 Semaphores (QP0ZOLSM) 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">Semaphore set identifier</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">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 Semaphores (QP0ZOLSM) API lets you generate a list of
description information about the semaphores within a semaphore set.</p>
<p>The QP0ZOLSM API places the specified number of list entries in the receiver
variable. You can access additional records by using the Get List Entries
(QGYGTLE) API. On successful completion of the QP0ZOLSM API, a handle is
returned in the list information parameter. You may use this handle on
subsequent calls to the following APIs:</p>
<ul>
<li>Get List Entries (QGYGTLE)<br>
<br>
</li>
<li>Find Entry Number in List (QGYFNDE)<br>
<br>
</li>
<li>Close List (QGYCLST)</li>
</ul>
<p>The records returned by QP0ZOLSM 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>Service special authority (*SERVICE) is needed to call this API.
<p>For additional information on this authority, see the <a href=
"../books/sc415302.pdf" target="_blank">iSeries Security Reference</a> <img
src="wbpdf.gif" alt="Link to PDF"> book.</p>
</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 semaphore information that you
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 semaphores 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>LSEM0100</em></td>
<td align="left" valign="top">This format is described in <a href=
"#HDRLSEM100">LSEM0100 Format</a>.</td>
</tr>
</table>
<br>
<br>
</dd>
<dt><strong>Semaphore set identifier</strong></dt>
<dd>INPUT; BINARY(4)
<p>The semaphore set identifier of the semaphore set whose semaphores you would
like the information about. The semaphore set identifier can be obtained from
calling either the semget(), or QP0ZOLIP API.</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="HDRLSEM100">LSEM0100 Format</a></h3>
<p>This format name is used to return list information for the semaphores in a
semaphore set. The following table shows the information returned in each
record in the receiver variable for the LSEM0100 format. For a detailed
description of each field, see <a href="#HDRRSEMFD">Field Descriptions</a>.</p>
<table border width="80%" cellpadding="5">
<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="bottom">4</td>
<td align="center" valign="bottom">4</td>
<td align="left" valign="bottom">BINARY(4)</td>
<td align="left" valign="bottom">Number</td>
</tr>
<tr>
<td align="center" valign="bottom">8</td>
<td align="center" valign="bottom">8</td>
<td align="left" valign="bottom">BINARY(4)</td>
<td align="left" valign="bottom">Value</td>
</tr>
<tr>
<td align="center" valign="bottom">12</td>
<td align="center" valign="bottom">C</td>
<td align="left" valign="bottom">BINARY(4)</td>
<td align="left" valign="bottom">Displacement to wait values</td>
</tr>
<tr>
<td align="center" valign="bottom">16</td>
<td align="center" valign="bottom">10</td>
<td align="left" valign="bottom">BINARY(4)</td>
<td align="left" valign="bottom">Number of waiters</td>
</tr>
<tr>
<td align="center" valign="bottom">20</td>
<td align="center" valign="bottom">14</td>
<td align="left" valign="bottom">BINARY(4)</td>
<td align="left" valign="bottom">Size of waiting information</td>
</tr>
<tr>
<td align="center" valign="bottom">24</td>
<td align="center" valign="bottom">18</td>
<td align="left" valign="bottom">BINARY(4)</td>
<td align="left" valign="bottom">Waiting for zero</td>
</tr>
<tr>
<td align="center" valign="bottom">28</td>
<td align="center" valign="bottom">1C</td>
<td align="left" valign="bottom">BINARY(4)</td>
<td align="left" valign="bottom">Waiting for positive value</td>
</tr>
<tr>
<td align="center" valign="bottom">32</td>
<td align="center" valign="bottom">20</td>
<td align="left" valign="bottom">CHAR(26)</td>
<td align="left" valign="bottom">Last changed qualified job identifier</td>
</tr>
<tr>
<td align="center" valign="bottom">58</td>
<td align="center" valign="bottom">3A</td>
<td align="left" valign="bottom">CHAR(2)</td>
<td align="left" valign="bottom">Reserved</td>
</tr>
<tr>
<td align="center" valign="bottom">60</td>
<td align="center" valign="bottom">3C</td>
<td align="left" valign="bottom">BINARY(4)</td>
<td align="left" valign="bottom">Process identifier</td>
</tr>
<tr>
<td align="left" valign="top" rowspan="3" colspan="2">These fields repeat for
each waiter on the semaphore value.</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Wait value</td>
</tr>
<tr>
<td align="left" valign="top">CHAR(26)</td>
<td align="left" valign="top">Waiting qualified job identifier</td>
</tr>
<tr>
<td align="left" valign="top">CHAR(2)</td>
<td align="left" valign="top">Reserved</td>
</tr>
</table>
<br>
<br>
<h3><a name="HDRRSEMFD">Field Descriptions</a></h3>
<p><strong>Displacement to wait values.</strong> The offset in characters
(bytes) from the beginning of the semaphore record to the beginning of the
array of wait values.</p>
<p><strong>Last changed qualified job identifier.</strong> The job name, the
job user profile, and the job number of the thread that last changed the value
of the semaphore. The 26 characters are:</p>
<table cellpadding="5">
<!-- cols="15 85" -->
<tr>
<td align="left" valign="top"><em>1-10</em></td>
<td align="left" valign="top">The job name</td>
</tr>
<tr>
<td align="left" valign="top"><em>11-20</em></td>
<td align="left" valign="top">The user profile</td>
</tr>
<tr>
<td align="left" valign="top"><em>21-26</em></td>
<td align="left" valign="top">The job number</td>
</tr>
</table>
<p>These fields will be all blanks if any of the following are true:</p>
<ul>
<li>No thread has changed the semaphore value.<br>
<br>
</li>
<li>The process that changed the semaphore has ended.<br>
<br>
</li>
<li>The process that changed the semaphore has not been initialized for
signals.</li>
</ul>
<p><strong>Length of entry.</strong> The length of this semaphore record in the
list.</p>
<p><strong>Number.</strong> The semaphore number in the semaphore set.</p>
<p><strong>Number of waiters.</strong> The total number of threads that are
waiting for this semaphore to reach a certain value.</p>
<p><strong>Process identifier</strong> The process identifier of the last
thread to change the value of the semaphore. If no thread has changed the
semaphore value, this field will be zero.</p>
<p><strong>Reserved.</strong> An ignored field.</p>
<p><strong>Size of waiting information.</strong> The size, in bytes, of the
record that is used to store information about a thread that is waiting for a
semaphore value.</p>
<p><strong>Value.</strong> The current value of the semaphore.</p>
<p><strong>Wait value.</strong> The value that a thread is waiting for the
semaphore to reach. If the value is zero, the thread is waiting for the
semaphore value to equal zero. If the value is a positive number, the thread is
waiting for the semaphore value to be greater than or equal to this value.</p>
<p><strong>Waiting for positive value.</strong> The number of threads that are
currently waiting for a semaphore value to reach a positive number.</p>
<p><strong>Waiting for zero.</strong> The number of threads that are currently
waiting for the semaphore value to reach zero.</p>
<p><strong>Waiting qualified job identifier.</strong> The job name, the job
user profile, and the job number of the thread that is currently waiting for
the semaphore. The 26 characters are:</p>
<table cellpadding="5">
<!-- cols="15 85" -->
<tr>
<td align="left" valign="top"><em>1-10</em></td>
<td align="left" valign="top">The job name</td>
</tr>
<tr>
<td align="left" valign="top"><em>11-20</em></td>
<td align="left" valign="top">The user profile</td>
</tr>
<tr>
<td align="left" valign="top"><em>21-26</em></td>
<td align="left" valign="top">The job number</td>
</tr>
</table>
<br>
<br>
<h3>Error Messages</h3>
<table width="100%" cellpadding="5">
<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">GUI0002 E</td>
<td width="85%" 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>
<tr>
<td align="left" valign="top">GUI0115 E</td>
<td align="left" valign="top">The list has been marked in error. See the
previous messages.</td>
</tr>
<tr>
<td align="left" valign="top">GUI0118 E</td>
<td align="left" valign="top">Starting record cannot be 0 when records have
been requested.</td>
</tr>
<tr>
<td align="left" valign="top">CPF0F01 E</td>
<td align="left" valign="top">*SERVICE authority is required to run this
program.</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">CPF24B4 E</td>
<td align="left" valign="top">Severe error while addressing parameter
list.</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">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">CPFA988 E</td>
<td align="left" valign="top">IPC object &amp;1 does not exist.</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_Of_Page">Top</a> | <a href=
"unix.htm">UNIX-Type APIs</a> | <a href="aplist.htm">APIs by category</a></td>
</tr>
</table>
</center>
</body>
</html>