72 lines
4.7 KiB
HTML
72 lines
4.7 KiB
HTML
|
<?xml version="1.0" encoding="UTF-8"?>
|
||
|
|
<!DOCTYPE html
|
||
|
|
PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
||
|
|
<html lang="en-us" xml:lang="en-us">
|
||
|
|
<head>
|
||
|
|
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
|
||
|
|
<meta name="security" content="public" />
|
||
|
|
<meta name="Robots" content="index,follow" />
|
||
|
|
<meta http-equiv="PICS-Label" content='(PICS-1.1 "http://www.icra.org/ratingsv02.html" l gen true r (cz 1 lz 1 nz 1 oz 1 vz 1) "http://www.rsac.org/ratingsv01.html" l gen true r (n 0 s 0 v 0 l 0) "http://www.classify.org/safesurf/" l gen true r (SS~~000 1))' />
|
||
|
|
<meta name="DC.Type" content="reference" />
|
||
|
|
<meta name="DC.Title" content="Bytes available and bytes returned fields" />
|
||
|
|
<meta name="abstract" content="Most formats used by retrieve APIs have a bytes available field and a bytes returned field. The bytes available field contains the length in bytes of all the data available to be returned to the user. The bytes returned field contains the length in bytes of all the data that is actually returned to the user." />
|
||
|
|
<meta name="description" content="Most formats used by retrieve APIs have a bytes available field and a bytes returned field. The bytes available field contains the length in bytes of all the data available to be returned to the user. The bytes returned field contains the length in bytes of all the data that is actually returned to the user." />
|
||
|
|
<meta name="DC.Relation" scheme="URI" content="conReceiver.htm" />
|
||
|
|
<meta name="copyright" content="(C) Copyright IBM Corporation 1998, 2006" />
|
||
|
|
<meta name="DC.Rights.Owner" content="(C) Copyright IBM Corporation 1998, 2006" />
|
||
|
|
<meta name="DC.Format" content="XHTML" />
|
||
|
|
<meta name="DC.Identifier" content="receiverbytes" />
|
||
|
|
<meta name="DC.Language" content="en-us" />
|
||
|
|
<!-- 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. -->
|
||
|
|
<link rel="stylesheet" type="text/css" href="./ibmdita.css" />
|
||
|
|
<link rel="stylesheet" type="text/css" href="./ic.css" />
|
||
|
|
<title>Bytes available and bytes returned fields</title>
|
||
|
|
</head>
|
||
|
|
<body id="receiverbytes"><a name="receiverbytes"><!-- --></a>
|
||
|
|
<!-- Java sync-link --><script language="Javascript" src="../rzahg/synch.js" type="text/javascript"></script>
|
||
|
|
<h1 class="topictitle1">Bytes available and bytes returned fields</h1>
|
||
|
|
<div><p>Most formats used by retrieve APIs have a bytes available field
|
||
|
|
and a bytes returned field. The bytes available field contains the length
|
||
|
|
in bytes of all the data available to be returned to the user. The bytes returned
|
||
|
|
field contains the length in bytes of all the data that is actually returned
|
||
|
|
to the user.</p>
|
||
|
|
<div class="section"><p>All available data is returned if enough space is
|
||
|
|
provided in the receiver variable. If the size of the receiver variable is
|
||
|
|
at least large enough to contain all of the data, the bytes returned field
|
||
|
|
equals the bytes available field. If the receiver variable is not large enough
|
||
|
|
to contain all of the data, the bytes available field contains the number
|
||
|
|
of bytes that can be returned.</p>
|
||
|
|
<p>Your code could check the values for
|
||
|
|
both the bytes available and bytes returned fields. If the bytes available
|
||
|
|
field is greater than the bytes returned field, the API had more information
|
||
|
|
to return than what would fit in the receiver variable. This could occur,
|
||
|
|
over time, because the APIs that you use may be enhanced with new releases.
|
||
|
|
The API may also have more information to return if the receiver variable
|
||
|
|
is being used to return a variable-length field (or array) and a very large
|
||
|
|
value was returned on this API call. If both values are the same, the API
|
||
|
|
returned all the information.</p>
|
||
|
|
<p>Depending on the capabilities of your
|
||
|
|
high-level language, some API users take advantage of the following technique
|
||
|
|
to avoid guessing the appropriate size for the receiver variable:</p>
|
||
|
|
<ol><li>Call the API with a receiver variable length of 8 bytes (that is, just
|
||
|
|
enough for the bytes available and the bytes returned fields).</li>
|
||
|
|
<li>Dynamically allocate an amount of storage equivalent to the bytes available.</li>
|
||
|
|
<li>Set the length of receiver variable parameter to the amount of storage
|
||
|
|
allocated.</li>
|
||
|
|
<li>Pass the address of the storage allocated in step 2 by using pass by value
|
||
|
|
(directly).</li>
|
||
|
|
</ol>
|
||
|
|
<p>This technique provides for highly flexible use of APIs that can return
|
||
|
|
variable amounts of data.</p>
|
||
|
|
</div>
|
||
|
|
</div>
|
||
|
|
<div>
|
||
|
|
<div class="familylinks">
|
||
|
|
<div class="parentlink"><strong>Parent topic:</strong> <a href="conReceiver.htm" title="A receiver variable is a program variable that is used as an output field to contain information that is returned from an API.">Receiver variables</a></div>
|
||
|
|
</div>
|
||
|
|
</div>
|
||
|
|
</body>
|
||
|
|
</html>
|