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

560 lines
16 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 Lock Request Information (QWCRLRQI) 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. -->
<!-- API created for V5R2 by Lance Holmes -->
<!-- Change History: -->
<!-- YYMMDD USERID Change description -->
<!-- File tagging cleanup completed Nov 2001 by v2cdijab -->
<!-- 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>Retrieve Lock Request Information (QWCRLRQI) 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 of lock request information</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">Lock request handle</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Char(64)</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 Lock Request Information (QWCRLRQI) API takes as input a
lock request handle that was returned in other APIs and returns information
about the program that requested the lock. This API must be called from the
same thread that called the API that returned the lock request handle.</p>
<p> The handle is a temporary value. A storage limitation will allow a thread
to create up to 1 million valid handles. Once the storage limit has been
reached the oldest handle information will be overwritten. This can cause a
handle to no longer be valid.</p>
<br>
<h3>Authorities and Locks</h3>
<p>None.</p>
<br>
<h3>Required Parameter Group</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 the receiver
variable parameter may be specified up to the size of the receiver variable
specified in the user program. If the length of the receiver variable specified
is larger then the allocated size of the receiver variable specified in the
user program, the results are not predictable. The minimum length is 8
bytes.</p>
</dd>
<dt><strong>Format of lock request information</strong></dt>
<dd>INPUT; CHAR(8)
<p> The format of the information returned in the receiver variable. The
possible format names are:</p>
<table cellpadding="5">
<!-- cols="15 85" -->
<tr>
<td align="left" valign="top"><em>LRQI0100</em></td>
<td align="left" valign="top">Lock request information. See <a href=
"#lrqi0100">Format LRQI0100</a> for details.</td>
</tr>
</table>
<br>
</dd>
<dt><strong>Lock request handle</strong></dt>
<dd>INPUT; CHAR(64)
<p>This contains the handle that will be used to locate the lock request
information. This value is created by a previous call to another lock API. The
previous lock API call must have been made by the current thread. This value is
a temporary value and may become invalid.</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="lrqi0100">Format LRQI0100</a></h3>
<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(4)</td>
<td align="left" valign="top">Offset to statement identifiers</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 of statement identifiers returned</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">Offset to procedure name</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 procedure name</td>
</tr>
<tr>
<td align="center" valign="top">28</td>
<td align="center" valign="top">1C</td>
<td align="left" valign="top">CHAR(10)</td>
<td align="left" valign="top">Program name</td>
</tr>
<tr>
<td align="center" valign="top">38</td>
<td align="center" valign="top">26</td>
<td align="left" valign="top">CHAR(10)</td>
<td align="left" valign="top">Program library name</td>
</tr>
<tr>
<td align="center" valign="top">48</td>
<td align="center" valign="top">30</td>
<td align="left" valign="top">CHAR(10)</td>
<td align="left" valign="top">Program ASP name</td>
</tr>
<tr>
<td align="center" valign="top">58</td>
<td align="center" valign="top">3A</td>
<td align="left" valign="top">CHAR(10)</td>
<td align="left" valign="top">Program library ASP name</td>
</tr>
<tr>
<td align="center" valign="top">68</td>
<td align="center" valign="top">44</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Program ASP number</td>
</tr>
<tr>
<td align="center" valign="top">72</td>
<td align="center" valign="top">48</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Program library ASP number</td>
</tr>
<tr>
<td align="center" valign="top">76</td>
<td align="center" valign="top">4C</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">MI instruction number</td>
</tr>
<tr>
<td align="center" valign="top">80</td>
<td align="center" valign="top">50</td>
<td align="left" valign="top">CHAR(10)</td>
<td align="left" valign="top">Module name</td>
</tr>
<tr>
<td align="center" valign="top">90</td>
<td align="center" valign="top">5A</td>
<td align="left" valign="top">CHAR(10)</td>
<td align="left" valign="top">Module library name</td>
</tr>
<tr>
<td align="center" valign="top">*</td>
<td align="center" valign="top">*</td>
<td align="left" valign="top">ARRAY OF CHAR(10)</td>
<td align="left" valign="top">Statement identifiers</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">Procedure name</td>
</tr>
</table>
<br>
<br>
<h3><a name="HDRJBLK0100">Field Descriptions</a></h3>
<p><strong>Bytes available.</strong> The number of bytes of data available to
be returned. All available data is returned if enough space is provided.</p>
<p><strong>Bytes returned.</strong> The number of bytes of data returned. Only
complete fields are returned.</p>
<p><strong>Length of procedure name.</strong> The length of the procedure name
in bytes. This field is zero if the program is not an ILE program.</p>
<p><strong>MI instruction number.</strong> The current machine instruction
number in the program. This field is not meaningful for integrated language
environment (ILE) procedures. A zero is returned for ILE procedures.</p>
<p> <strong>Module library name.</strong> The name of the library in which the
module is located. The following special values may be returned:</p>
<table cellpadding="5">
<!-- cols="10 90" -->
<tr>
<td align="left" valign="top"><em>*N</em></td>
<td align="left" valign="top">The module library name is unavailable. Either
the program has been destroyed or the library containing the program is
locked.</td>
</tr>
<tr>
<td align="left" valign="top"><em>blanks</em></td>
<td align="left" valign="top">The program is not an ILE program.</td>
</tr>
</table>
<p><strong>Module name.</strong> The module containing the integrated language
environment (ILE) procedure. The following special values may be returned:</p>
<table cellpadding="5">
<!-- cols="10 90" -->
<tr>
<td align="left" valign="top"><em>*N</em></td>
<td align="left" valign="top">The module name is unavailable. Either the
program has been destroyed or the library containing the program is
locked.</td>
</tr>
<tr>
<td align="left" valign="top"><em>blanks</em></td>
<td align="left" valign="top">The program is not an ILE program.</td>
</tr>
</table>
<p><strong>Number of statement identifiers returned.</strong> The actual number
of statement identifiers returned.</p>
<p><strong>Offset to procedure name.</strong> The offset in bytes from the
beginning of the receiver variable to the procedure name. This value will be
zero if the program is not an ILE program.</p>
<p><strong>Offset to statement identifiers.</strong> The offset in bytes from
the beginning of the receiver variable to the statement identifiers. This value
will be zero if no statement identifiers are returned.</p>
<p><strong>Procedure name.</strong> The name of the procedure.</p>
<p><strong>Program ASP name.</strong> The name of the auxiliary storage pool
(ASP) device in which the program is located. The following special values may
also be returned:</p>
<table cellpadding="5">
<!-- cols="15 85" -->
<tr>
<td align="left" valign="top"><em>*SYSBAS</em></td>
<td align="left" valign="top">The program is located in the system ASP or a
basic user ASP.</td>
</tr>
<tr>
<td align="left" valign="top"><em>*N</em></td>
<td align="left" valign="top">The name of the ASP cannot be determined.</td>
</tr>
</table>
<p><strong>Program ASP number.</strong> The numeric identifier of the ASP
containing the program. The following values may be returned:</p>
<table cellpadding="5">
<!-- cols="10 90" -->
<tr>
<td align="left" valign="top"><em>1</em></td>
<td align="left" valign="top">The library is located in the system ASP.</td>
</tr>
<tr>
<td align="left" valign="top"><em>2-32</em></td>
<td align="left" valign="top">The library is located in a basic user ASP.</td>
</tr>
<tr>
<td align="left" valign="top"><em>33-255</em></td>
<td align="left" valign="top">The library is located in an independent
ASP.</td>
</tr>
<tr>
<td align="left" valign="top"><em>-1</em></td>
<td align="left" valign="top">The ASP device cannot be determined.</td>
</tr>
</table>
<p><strong>Program library ASP name.</strong> The name of the ASP in which the
program library is located. The following special values may also be
returned:</p>
<table cellpadding="5">
<!-- cols="10 90" -->
<tr>
<td align="left" valign="top"><em>*SYSBAS</em></td>
<td align="left" valign="top">The program library is located in the system ASP
or a basic user ASP.</td>
</tr>
<tr>
<td align="left" valign="top"><em>*N</em></td>
<td align="left" valign="top">The name of the ASP cannot be determined.</td>
</tr>
</table>
<p><strong>Program library ASP number.</strong> The numeric identifier of the
ASP containing the program library. The following values may be returned:</p>
<table cellpadding="5">
<!-- cols="10 90" -->
<tr>
<td align="left" valign="top"><em>1</em></td>
<td align="left" valign="top">The library is located in the system ASP or in a
basic user ASP.</td>
</tr>
<tr>
<td align="left" valign="top"><em>2-32</em></td>
<td align="left" valign="top">The library is located in a basic user ASP.</td>
</tr>
<tr>
<td align="left" valign="top"><em>33-255</em></td>
<td align="left" valign="top">The library is located in an independent
ASP.</td>
</tr>
<tr>
<td align="left" valign="top"><em>-1</em></td>
<td align="left" valign="top">The ASP device cannot be determined.</td>
</tr>
</table>
<p><strong>Program library name.</strong> The name of the library in which the
program is located. The following special value may be returned:</p>
<table cellpadding="5">
<!-- cols="5 95" -->
<tr>
<td align="left" valign="top"><em>*N</em></td>
<td align="left" valign="top">The program library name is unavailable. The
library containing the program has been destroyed or is locked.</td>
</tr>
</table>
<p><strong>Program name.</strong> The name of the program. This can be any type
of program object, including objects of type *PGM and *SRVPGM. The following
special value may be returned:</p>
<table cellpadding="5">
<!-- cols="5 95" -->
<tr>
<td align="left" valign="top"><em>*N</em></td>
<td align="left" valign="top">The program is unavailable. Either the program
has been destroyed or the library containing the program is locked.</td>
</tr>
</table>
<p><strong>Statement identifiers.</strong> The high-level language statement
identifier. If this field contains the character representation of a number,
the number is right-adjusted in the field and padded on the left with zeros
(for example, '0000000246'). If the lock is for an integrated language
environment (ILE) procedure, more than one statement identifier may exist
because of the compilers used for ILE languages.</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%">CPF18C2 E</td>
<td align="left" valign="top" width="85%">Object lock handle or lock request handle 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">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 the receiver variable 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">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 occured during running of &amp;1 API.</td>
</tr>
</table>
<br>
<br>
<hr>
API introduced: V5R2
<hr>
<center>
<table cellpadding="2" cellspacing="2">
<tr align="center">
<td valign="middle" align="center"><a href="#Top_Of_Page">Top</a> | <a href=
"wm1.htm">Work Management APIs</a> | <a href="aplist.htm">APIs by
category</a></td>
</tr>
</table>
</center>
</body>
</html>