<!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>Create Handle (QRZCRTH) 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. --> <!-- GSA ADP Schedule Contract with IBM Corp. --> <!-- Change History: --> <!-- YYMMDD USERID Change description --> <!-- This file has undergone html cleanup on 1/14/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>Create Handle (QRZCRTH) API</h2> <div class="box" style="width: 80%;"> <br> 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 name</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">Error code</td> <td align="left" valign="top">I/O</td> <td align="left" valign="top">Char(*)</td> </tr> </table> <br> Default Public Authority: *EXCLUDE<br> <!-- iddvc RMBR --> <br> Threadsafe: No<br> <!-- iddvc RMBR --> <br> </div> <p>The Create Handle (QRZCRTH) API creates a handle that is used as a placeholder when possible list items are involved. Use this API to create a handle before calling a hardware resource API that has a handle parameter defined.</p> <ul> <li><strong>Handle supplied to an API.</strong> The handle allows repeated calls to obtain more than one list item. While retrieving possible list items, a handle should be supplied when a first call attempt is used that is followed by subsequent (next) call attempts.<br> <br> </li> <li><strong>Handle not supplied to an API.</strong> While retrieving information, if an attempt is made only for the first call, a handle may be set to hexadecimal 0. If a subsequent (next) call is attempted by an API to retrieve information, the API is unable to determine if more information meets the supplied criteria unless the initial call is repeated through the use of a handle.</li> </ul> <p><strong>Note:</strong> The repeated API calls must have the same criteria and must involve the same API. Handles cannot be shared across different APIs or within the same API with different criteria.</p> <p>You are required to delete any handles created by the Create Handle (QRZCRTH) API. See <a href="qrzdlth.htm">Delete Handle (QRZDLTH) API</a> for more information.</p> <br> <h3>Authorities and Locks</h3> <dl> <dt><em>API Public Authority</em></dt> <dd>*EXCLUDE</dd> </dl> <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 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. The minimum length is 8 bytes.</p> </dd> <dt><strong>Format name</strong></dt> <dd>INPUT; CHAR(8) <p> The content and format of the information returned. The possible format name is as follows:</p> <table cellpadding="5"> <!-- cols="15 85" --> <tr> <td align="left" valign="top"><em>HNDL0100</em></td> <td align="left" valign="top">A handle that is 16 bytes in length is returned. See <a href="#HDRCRTP100">HNDL0100 Format</a> for details of this format.</td> </tr> </table> <br> </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="HDRCRTP100">HNDL0100 Format</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">CHAR(16)</td> <td align="left" valign="top">Handle</td> </tr> </table> <br> <br> <h3><a name="HDRCRTPFD">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.</p> <p><strong>Handle.</strong> The returned handle value to be used on subsequent API calls when a handle parameter is required.</p> <br> <h3>Error Messages</h3> <table width="100%" cellpadding="5"> <!-- cols="15 85" --> <tr> <th align="left" valign="top" nowrap>Message ID</th> <th align="left" valign="top">Error Message Text</th> </tr> <tr> <td align="left" valign="top">CPF0B31 E</td> <td align="left" valign="top">A handle failed to create.</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">CPF3CF1 E</td> <td align="left" valign="top">Error code parameter not valid.</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 &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">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 &1 in library &2 ended. Reason code &3.</td> </tr> </table> <br> <hr> API introduced: V3R6 <hr> <table align="center" cellpadding="2" cellspacing="2"> <tr align="center"> <td valign="middle" align="center"><a href="#Top_Of_Page">Top</a> | <a href= "config.htm">Configuration APIs</a> | <a href="aplist.htm">API by category</a></td> </tr> </table> </body> </html>