95 lines
6.6 KiB
HTML
95 lines
6.6 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="User spaces for list APIs" />
|
||
|
|
<meta name="abstract" content="The list APIs require a user space for returning information." />
|
||
|
|
<meta name="description" content="The list APIs require a user space for returning information." />
|
||
|
|
<meta name="DC.Relation" scheme="URI" content="listOverview.htm" />
|
||
|
|
<meta name="DC.Relation" scheme="URI" content="listLogicFlow.htm" />
|
||
|
|
<meta name="DC.Relation" scheme="URI" content="listUserPointer.htm" />
|
||
|
|
<meta name="DC.Relation" scheme="URI" content="listUserWOPointer.htm" />
|
||
|
|
<meta name="DC.Relation" scheme="URI" content="listChangeUser.htm" />
|
||
|
|
<meta name="DC.Relation" scheme="URI" content="listAdditionalinfo.htm" />
|
||
|
|
<meta name="DC.Relation" scheme="URI" content="listDBFileMembers.htm" />
|
||
|
|
<meta name="DC.Relation" scheme="URI" content="usf.htm" />
|
||
|
|
<meta name="DC.Relation" scheme="URI" content="usf.htm" />
|
||
|
|
<meta name="DC.Relation" scheme="URI" content="lang.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="listUserSpace" />
|
||
|
|
<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>User spaces for list APIs</title>
|
||
|
|
</head>
|
||
|
|
<body id="listUserSpace"><a name="listUserSpace"><!-- --></a>
|
||
|
|
<!-- Java sync-link --><script language="Javascript" src="../rzahg/synch.js" type="text/javascript"></script>
|
||
|
|
<h1 class="topictitle1">User spaces for list APIs</h1>
|
||
|
|
<div><p>The list APIs require a user space for returning information.</p>
|
||
|
|
<p>A user space is an object type that is created by the Create User Space
|
||
|
|
(QUSCRTUS) API. Generally, a user space is used when information about more
|
||
|
|
than one object is being requested.</p>
|
||
|
|
<p>Most lists returned by APIs are made up of a series of entries where each
|
||
|
|
entry is a data structure. Special fields are placed in the user space at
|
||
|
|
consistent locations that describe:</p>
|
||
|
|
<ul><li>Where the list begins.</li>
|
||
|
|
<li>The number of entries. Logic flow of processing a list of entries shows
|
||
|
|
the logic for processing a list of entries.</li>
|
||
|
|
<li>The length of each entry.</li>
|
||
|
|
</ul>
|
||
|
|
<p>User spaces are used for such functions as returning either a list of members
|
||
|
|
in a file or objects in a library. When you use one of the list APIs, the
|
||
|
|
parameter list requires that you name the user space that will be used.</p>
|
||
|
|
<p>User spaces can be processed in two ways:</p>
|
||
|
|
<ul><li>If your language supports pointers, you can access or change the information
|
||
|
|
directly. Language selection considerations describes each supported language
|
||
|
|
and whether it supports pointers. Generally, pointer access is faster than
|
||
|
|
API access. </li>
|
||
|
|
<li>For languages that do not support pointers, you can use APIs to access
|
||
|
|
or change the data in a user space. For example, the data in a user space
|
||
|
|
can be accessed by the Retrieve User Space (QUSRTVUS) API. The API identifies
|
||
|
|
a receiver variable that receives a number of bytes of information from the
|
||
|
|
user space.</li>
|
||
|
|
</ul>
|
||
|
|
<p>You can pass the user space as a parameter to a program. You do need to
|
||
|
|
use a language that has pointer support to be able to pass the address of
|
||
|
|
the first byte of the user space as a parameter to the processing program.</p>
|
||
|
|
</div>
|
||
|
|
<div>
|
||
|
|
<ul class="ullinks">
|
||
|
|
<li class="ulchildlink"><strong><a href="listLogicFlow.htm">Logic flow of processing a list of entries</a></strong><br />
|
||
|
|
This topic shows you what a logic flow looks like when you process a list containing multiple entries.</li>
|
||
|
|
<li class="ulchildlink"><strong><a href="listUserPointer.htm">Manipulating a user space with pointers</a></strong><br />
|
||
|
|
Some languages, such as ILE C, Visual Age for C++, ILE COBOL, ILE RPG, COBOL, Pascal, and PL/I, support pointers. Pointers allow you to manipulate information more rapidly from the user space.</li>
|
||
|
|
<li class="ulchildlink"><strong><a href="listUserWOPointer.htm">Manipulate a user space without pointers</a></strong><br />
|
||
|
|
When programming in a language that does not support pointers, you can use the Change user space (QUSCHGUS) and Retrieve user space (QUSRTVUS) APIs to manipulate data. However, you must first understand how to use positions and lengths with these APIs.</li>
|
||
|
|
<li class="ulchildlink"><strong><a href="listChangeUser.htm">Examples: Change a user space</a></strong><br />
|
||
|
|
These examples illustrate how a user space can be changed.</li>
|
||
|
|
<li class="ulchildlink"><strong><a href="listAdditionalinfo.htm">Additional information about list APIs and a user space</a></strong><br />
|
||
|
|
Before you can use a list API to create a list, the *USRSPC object must exist.</li>
|
||
|
|
<li class="ulchildlink"><strong><a href="listDBFileMembers.htm">Example: List database file members with a CL program</a></strong><br />
|
||
|
|
This program generates a list of members that start with M, and places the list into a user space named example in Library QGPL.</li>
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
<div class="familylinks">
|
||
|
|
<div class="parentlink"><strong>Parent topic:</strong> <a href="listOverview.htm" title="List APIs return a list unique to a given API. The section discusses the characteristics of a list API and provides information that you should be aware of when you use list APIs.">List APIs overview</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="lang.htm" title="You can use APIs with all the languages available on iSeries business computing systems, except for the ILE APIs.">Language selection considerations</a></div>
|
||
|
|
</div>
|
||
|
|
</div>
|
||
|
|
</body>
|
||
|
|
</html>
|