101 lines
7.4 KiB
HTML
101 lines
7.4 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="concept" />
|
||
|
|
<meta name="DC.Title" content="Receiver variables" />
|
||
|
|
<meta name="abstract" content="A receiver variable is a program variable that is used as an output field to contain information that is returned from an API." />
|
||
|
|
<meta name="description" content="A receiver variable is a program variable that is used as an output field to contain information that is returned from an API." />
|
||
|
|
<meta name="DC.Relation" scheme="URI" content="conUSRV.htm" />
|
||
|
|
<meta name="DC.Relation" scheme="URI" content="receiverbytes.htm" />
|
||
|
|
<meta name="DC.Relation" scheme="URI" content="receiverkeyed.htm" />
|
||
|
|
<meta name="DC.Relation" scheme="URI" content="receiverusr.htm" />
|
||
|
|
<meta name="DC.Relation" scheme="URI" content="usf.htm" />
|
||
|
|
<meta name="DC.Relation" scheme="URI" content="cmnCommon.htm" />
|
||
|
|
<meta name="DC.Relation" scheme="URI" content="../apis/ileReceiver.htm" />
|
||
|
|
<meta name="DC.Relation" scheme="URI" content="../apis/ileKeyed.htm" />
|
||
|
|
<meta name="DC.Relation" scheme="URI" content="pgmerr_bytea.htm" />
|
||
|
|
<meta name="DC.Relation" scheme="URI" content="cmnKeysRPG.htm" />
|
||
|
|
<meta name="DC.Relation" scheme="URI" content="usf.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="conReceiver" />
|
||
|
|
<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>Receiver variables</title>
|
||
|
|
</head>
|
||
|
|
<body id="conReceiver"><a name="conReceiver"><!-- --></a>
|
||
|
|
<!-- Java sync-link --><script language="Javascript" src="../rzahg/synch.js" type="text/javascript"></script>
|
||
|
|
<h1 class="topictitle1">Receiver variables</h1>
|
||
|
|
<div><p>A receiver variable is a program variable that is used as an output
|
||
|
|
field to contain information that is returned from an API.</p>
|
||
|
|
<p>Retrieve APIs use receiver variables to place returned information. For
|
||
|
|
example, instead of using a user space to return the information, the information
|
||
|
|
is placed in a receiver variable. A retrieve API requires only addressability
|
||
|
|
to storage of fixed size (typically a field or structure defined in your program),
|
||
|
|
whereas a list API requires a user space because the amount of information
|
||
|
|
returned by a list API may be large and not of a predictable size.</p>
|
||
|
|
<p>Retrieve APIs that return information to a receiver variable use the storage
|
||
|
|
provided for the receiver variable parameter. The returned information is
|
||
|
|
in a specific format. The format name is usually a parameter on the call to
|
||
|
|
the API, and the format indicates to the API the information that you want
|
||
|
|
returned. On the return from the call to the API, the caller parses through
|
||
|
|
the receiver variable and extracts the information that is needed. The caller
|
||
|
|
knows how the information is returned by the documented format of the information.
|
||
|
|
An API may have one or many formats that give you the flexibility to choose
|
||
|
|
the information that you need. To see examples of using receiver variables,
|
||
|
|
see Scenario: Original Program Model (OPM) API.</p>
|
||
|
|
<p>Some formats have variable-length fields, some only fixed-length fields,
|
||
|
|
and yet others have repeating entries. To move through the information, some
|
||
|
|
formats use offsets, some use lengths, and some use displacements. When the
|
||
|
|
field is defined as an offset, the offset is always the number of bytes from
|
||
|
|
the beginning of the receiver variable. When a length or displacement is used
|
||
|
|
to move through the receiver variable entries, the length is always added
|
||
|
|
to the current position within the receiver variable. For examples of repeating
|
||
|
|
entry types and the various ways to move through receiver variable entries,
|
||
|
|
see Example: Receiver variables using ILE APIs.</p>
|
||
|
|
<p>Offsets and displacements are not the same. An <em>offset</em> is relative
|
||
|
|
to the beginning of a receiver variable or the beginning of a user space,
|
||
|
|
whereas a <em>displacement</em> is relative to the current position of the pointer
|
||
|
|
plus the value within the displacement field. If a format uses a displacement,
|
||
|
|
you will see the word displacement in the Field column of the API description.</p>
|
||
|
|
</div>
|
||
|
|
<div>
|
||
|
|
<ul class="ullinks">
|
||
|
|
<li class="ulchildlink"><strong><a href="receiverbytes.htm">Bytes available and bytes returned fields</a></strong><br />
|
||
|
|
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.</li>
|
||
|
|
<li class="ulchildlink"><strong><a href="receiverkeyed.htm">Keyed interface</a></strong><br />
|
||
|
|
Some APIs have a keyed interface for selecting what information
|
||
|
|
you want returned. A <em>keyed interface</em> allows the user of the API to
|
||
|
|
provide information to the API through the use of keys.</li>
|
||
|
|
<li class="ulchildlink"><strong><a href="receiverusr.htm">User space alternative</a></strong><br />
|
||
|
|
Although a receiver variable is usually used for returning information from a retrieve API, sometimes a user space should be used instead.</li>
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
<div class="familylinks">
|
||
|
|
<div class="parentlink"><strong>Parent topic:</strong> <a href="conUSRV.htm" title="APIs that return information to a caller generally return the information in a user space (used by list APIs) or a receiver variable (used by retrieve APIs).">User spaces and receiver variables</a></div>
|
||
|
|
</div>
|
||
|
|
<div class="relconcepts"><strong>Related concepts</strong><br />
|
||
|
|
<div><a href="cmnCommon.htm" title="API names contain verbs that are similar to the i5/OS licensed program: change, create, remove, and retrieve.">API information format</a></div>
|
||
|
|
</div>
|
||
|
|
<div class="relref"><strong>Related reference</strong><br />
|
||
|
|
<div><a href="usf.htm" title="List APIs require a user space for returning information. A user space is an object consisting of a collection of bytes that can be used for storing any user-defined information.">User spaces</a></div>
|
||
|
|
<div><a href="../apis/ileReceiver.htm">Example: Receiver variables using ILE APIs</a></div>
|
||
|
|
<div><a href="../apis/ileKeyed.htm">Example: Keyed interface using ILE APIs</a></div>
|
||
|
|
<div><a href="pgmerr_bytea.htm" title="Correct byte alignment ensures that data used with an API is correct. Byte alignment is also essential when APIs are used to retrieve and then print or display data.">Define byte alignment</a></div>
|
||
|
|
<div><a href="cmnKeysRPG.htm" title="This example shows the steps necessary to process keyed output from an API.">Example in OPM RPG: Using keys with List Spooled Files API</a></div>
|
||
|
|
</div>
|
||
|
|
</div>
|
||
|
|
</body>
|
||
|
|
</html>
|