218 lines
14 KiB
HTML
218 lines
14 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="List Object API general data structure" />
|
||
|
|
<meta name="abstract" content="Describes some of the more important fields that comprise the general data structure." />
|
||
|
|
<meta name="description" content="Describes some of the more important fields that comprise the general data structure." />
|
||
|
|
<meta name="DC.Relation" scheme="URI" content="listOverview.htm" />
|
||
|
|
<meta name="DC.Relation" scheme="URI" content="../apis/qsylobjp.htm" />
|
||
|
|
<meta name="DC.Relation" scheme="URI" content="cmnFormat.htm" />
|
||
|
|
<meta name="DC.Relation" scheme="URI" content="cmnExtract.htm" />
|
||
|
|
<meta name="DC.Relation" scheme="URI" content="listRPG.htm" />
|
||
|
|
<meta name="DC.Relation" scheme="URI" content="conContinuation.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="listGeneral" />
|
||
|
|
<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>List Object API general data structure</title>
|
||
|
|
</head>
|
||
|
|
<body id="listGeneral"><a name="listGeneral"><!-- --></a>
|
||
|
|
<!-- Java sync-link --><script language="Javascript" src="../rzahg/synch.js" type="text/javascript"></script>
|
||
|
|
<h1 class="topictitle1">List Object API general data structure</h1>
|
||
|
|
<div><p>Describes some of the more important fields that comprise the general
|
||
|
|
data structure.</p>
|
||
|
|
<div class="section"><p>The following structure shows the common fields that list APIs
|
||
|
|
use. All list APIs have an input parameter section, a header section, and
|
||
|
|
a list data section.</p>
|
||
|
|
</div>
|
||
|
|
<div class="section" id="listGeneral__general"><a name="listGeneral__general"><!-- --></a><h4 class="sectiontitle">General data structure</h4><pre> Header
|
||
|
|
*------------------------------------* *-------------------------*
|
||
|
|
+00| | | |
|
||
|
|
| 64-Byte User Area | | |
|
||
|
|
| | | |
|
||
|
|
*------------------------------------* *--->| Input Parameter Section |
|
||
|
|
+40| Size of Generic Header | | | |
|
||
|
|
*------------------------------------* | . .
|
||
|
|
| | | . .
|
||
|
|
| Generic Header | | *-------------------------*
|
||
|
|
| | | | |
|
||
|
|
| | |
|
||
|
|
+6C| Offset to Input Parameter Section -+----*
|
||
|
|
| | | |
|
||
|
|
+70| Input Parameter Section Size | *-------------------------*
|
||
|
|
| | | |
|
||
|
|
+74| Offset to Header Section-----------+-------->| Header Section |
|
||
|
|
| | | |
|
||
|
|
+78| Header Section Size | | |
|
||
|
|
| | | |
|
||
|
|
+7C| Offset to List Data Section--------+----* | |
|
||
|
|
| | | | |
|
||
|
|
+80| List Data Section Size | | | |
|
||
|
|
| | | . .
|
||
|
|
+84| Number of List Entries | | . .
|
||
|
|
| | | | |
|
||
|
|
+88| Size of Each Entry | | *-------------------------*
|
||
|
|
| | | | |
|
||
|
|
+8C| CCSID of data in the user space | |
|
||
|
|
| | |
|
||
|
|
+90| Country ID | | | |
|
||
|
|
| | | | List Data Section |
|
||
|
|
+93| Language ID | | |-------------------------*
|
||
|
|
| | *--->| Entry 1 |
|
||
|
|
+95| Subsetted list indicator | |-------------------------*
|
||
|
|
| | | Entry 2 |
|
||
|
|
+C0| API entry point name | |-------------------------*
|
||
|
|
| | | Entry 3 |
|
||
|
|
| | | |
|
||
|
|
*------------------------------------* . .
|
||
|
|
. .
|
||
|
|
| |
|
||
|
|
|-------------------------*
|
||
|
|
| Last Entry |
|
||
|
|
|-------------------------*
|
||
|
|
| |
|
||
|
|
</pre>
|
||
|
|
</div>
|
||
|
|
<div class="section" id="listGeneral__user_area"><a name="listGeneral__user_area"><!-- --></a><h4 class="sectiontitle">User area</h4><p>The first field in the
|
||
|
|
general data structure is called the user area. This is a 64-byte field that
|
||
|
|
is not used or changed by the system. Whatever information you place in this
|
||
|
|
field remains there. For example, you may specify the date last used, include
|
||
|
|
comments about the list, and so forth.</p>
|
||
|
|
</div>
|
||
|
|
<div class="section" id="listGeneral__size_generic"><a name="listGeneral__size_generic"><!-- --></a><h4 class="sectiontitle">Size of generic header</h4><p>The size
|
||
|
|
of the generic header does not include the size of the user area. All sections
|
||
|
|
have a size, which may differ for each API.</p>
|
||
|
|
<p>Some fields may be added
|
||
|
|
to the generic header from release to release. Because fields may be added,
|
||
|
|
you may want to check the size of this field. If your application works across
|
||
|
|
multiple releases, it is recommended that you check the size of this field
|
||
|
|
to determine which fields are applicable.</p>
|
||
|
|
</div>
|
||
|
|
<div class="section" id="listGeneral__offset_input"><a name="listGeneral__offset_input"><!-- --></a><h4 class="sectiontitle">Offset to input parameter section</h4><p>The
|
||
|
|
offset to input parameter section is an offset to the start of the input parameter
|
||
|
|
section. The input parameter section may contain a copy of the input parameters
|
||
|
|
that you pass to the list API. The QSYLOBJP API's input parameter section
|
||
|
|
is shown in Input Parameter Section.</p>
|
||
|
|
<p>The input parameter section contains
|
||
|
|
a copy of the continuation handle value that you passed as the continuation
|
||
|
|
handle parameter to the API. <a href="#listGeneral__HDRGHOTHER">Other fields of generic header</a> discusses
|
||
|
|
continuation handles further.</p>
|
||
|
|
</div>
|
||
|
|
<div class="section" id="listGeneral__offset_header"><a name="listGeneral__offset_header"><!-- --></a><h4 class="sectiontitle">Offset to header section</h4><p>The
|
||
|
|
header section includes an offset to where the header section starts and the
|
||
|
|
size of the header section. This section is needed in the event any input
|
||
|
|
parameters have a special value. The fields in the header section tell what
|
||
|
|
the special value resolved to. For example, the special value *CURRENT for
|
||
|
|
the user name parameter would resolve to the user profile name for the job
|
||
|
|
that called the API.</p>
|
||
|
|
<p>This section is also sometimes used for API-specific
|
||
|
|
control information that is not related to a particular list entry.</p>
|
||
|
|
<p>The
|
||
|
|
QSYLOBJP API's header section is shown in Header section.</p>
|
||
|
|
</div>
|
||
|
|
<div class="section" id="listGeneral__offset_list"><a name="listGeneral__offset_list"><!-- --></a><h4 class="sectiontitle">Offset to list data section</h4><p>The
|
||
|
|
offset to the list data section is the offset to the start of the format.
|
||
|
|
The specific format that the API uses is determined by the name you specify
|
||
|
|
for the format name parameter. The specific format that you use determines
|
||
|
|
what information is returned in the user space.</p>
|
||
|
|
<p>The number of list entries
|
||
|
|
field tells how many entries have been returned to you.</p>
|
||
|
|
<p>The size of
|
||
|
|
each entry field within the list data section tells how large each entry is.
|
||
|
|
In the list data section, each entry is of the same length for a given list.
|
||
|
|
If the size of each entry field is <samp class="codeph">0</samp>, the entries have different
|
||
|
|
lengths and the format tells the length of each entry.</p>
|
||
|
|
<p>The list data
|
||
|
|
sections for the QSYLOBJP API are shown in the OBJP0100 Format, OBJP0110 Format,
|
||
|
|
and the OBJP0200 Format. This API has three possible formats.</p>
|
||
|
|
<p>For more
|
||
|
|
information about formats and how to extract a field from a format, see Format
|
||
|
|
and Extracting a field from the format.</p>
|
||
|
|
</div>
|
||
|
|
<div class="section" id="listGeneral__HDRGHOTHER"><a name="listGeneral__HDRGHOTHER"><!-- --></a><h4 class="sectiontitle">Other fields of generic header</h4><p>The
|
||
|
|
field called structure's release and level is part of the generic header.
|
||
|
|
This field tells the layout of the generic header. For an original program
|
||
|
|
model (OPM) layout, this value should be 0100. For an Integrated Language
|
||
|
|
Environment<sup>®</sup> (ILE) model layout, the value should be 0300.</p>
|
||
|
|
<p>The information
|
||
|
|
status field tells you whether the information in the user space is complete
|
||
|
|
and accurate, or partial. You need to check the value of this field before
|
||
|
|
you do anything with the information in the user space, shown at (1) in the
|
||
|
|
RPG example program. Possible values for this field follow:</p>
|
||
|
|
|
||
|
|
<div class="tablenoborder"><table cellpadding="4" cellspacing="0" summary="" frame="border" border="1" rules="all"><thead align="left"><tr valign="bottom"><th valign="bottom" id="d0e86">Status value</th>
|
||
|
|
<th valign="bottom" id="d0e88">Description</th>
|
||
|
|
</tr>
|
||
|
|
</thead>
|
||
|
|
<tbody><tr><td valign="top" headers="d0e86 "><em>C</em></td>
|
||
|
|
<td valign="top" headers="d0e88 ">Complete and accurate.</td>
|
||
|
|
</tr>
|
||
|
|
<tr><td valign="top" headers="d0e86 "><em>I</em></td>
|
||
|
|
<td valign="top" headers="d0e88 ">Incomplete. The information you received is not accurate or complete.</td>
|
||
|
|
</tr>
|
||
|
|
<tr><td valign="top" headers="d0e86 "><em>P</em></td>
|
||
|
|
<td valign="top" headers="d0e88 ">Partial but accurate. The information you received is accurate, but
|
||
|
|
the API had more information to return than the user space could hold.</td>
|
||
|
|
</tr>
|
||
|
|
</tbody>
|
||
|
|
</table>
|
||
|
|
</div>
|
||
|
|
<p>If the value is <tt class="sysout">P</tt>, the API has more
|
||
|
|
information to return than what could fit in the user space. If you received
|
||
|
|
the value <tt class="sysout">P</tt>, you need to process the current
|
||
|
|
information in the user space before you get the remaining information. The
|
||
|
|
API returns a continuation handle usually in the form of a parameter. You
|
||
|
|
can use this continuation handle value to have the remaining information placed
|
||
|
|
in the user space. You specify the continuation handle value that the API
|
||
|
|
returned as the value of the continuation handle input parameter on your next
|
||
|
|
call to the API.</p>
|
||
|
|
<p>The QSYLOBJP API provides a continuation handle in
|
||
|
|
the header section to return the remaining information to the user space,
|
||
|
|
as shown at (2) in the RPG example program. The user then passes this value
|
||
|
|
back to the API as an input parameter so that the API can locate the remaining
|
||
|
|
information and place it in the user space, as shown at (3) in the RPG example
|
||
|
|
program.</p>
|
||
|
|
<p>If the API does not have a continuation handle and the information
|
||
|
|
status field value is <tt class="sysout">P</tt>, you must further qualify
|
||
|
|
what you want in the list. In other words, you must be more specific on the
|
||
|
|
parameter values that you pass to the API. For example, the QUSLOBJ API asked
|
||
|
|
to get a list of objects; however, all of the objects on the system would
|
||
|
|
not fit in the user space. To further qualify or limit the number of objects
|
||
|
|
returned, the user might specify all libraries that start with a specific
|
||
|
|
letter.</p>
|
||
|
|
<p>For more information about continuation handles and how to use
|
||
|
|
them, see Continuation handle.</p>
|
||
|
|
</div>
|
||
|
|
</div>
|
||
|
|
<div>
|
||
|
|
<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="relconcepts"><strong>Related concepts</strong><br />
|
||
|
|
<div><a href="cmnFormat.htm" title="The format section in API information describes a format name.">API format</a></div>
|
||
|
|
<div><a href="cmnExtract.htm" title="The format section describes where the field that you want is located within the receiver variable.">Extracting a field from the format</a></div>
|
||
|
|
</div>
|
||
|
|
<div class="reltasks"><strong>Related tasks</strong><br />
|
||
|
|
<div><a href="conContinuation.htm" title="Some APIs that return information offer a continuation handle.">Continuation handle</a></div>
|
||
|
|
</div>
|
||
|
|
<div class="relref"><strong>Related reference</strong><br />
|
||
|
|
<div><a href="../apis/qsylobjp.htm">Input Parameter Section</a></div>
|
||
|
|
<div><a href="listRPG.htm" title="This example program prints a report that shows all objects that adopt owner authority.">Example in RPG: List Object API</a></div>
|
||
|
|
</div>
|
||
|
|
</div>
|
||
|
|
</body>
|
||
|
|
</html>
|