<!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>Retrieve Associated Space (QbnRetrieveAssociatedSpace) 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. --> <!-- QCLRA SCRIPT A converted by B2H R4.1 (346) (CMS) by HOLTJM at --> <!-- RCHVMW2 on 5 Feb 1999 at 14:54:33 --> <!-- Change History: --> <!-- YYMMDD USERID Change description --> <!--File Edited by Kersten Nov 2001 --> <!--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 language="Javascript" src="../rzahg/synch.js" type="text/javascript"> </script> <h2>Retrieve Associated Space (QbnRetrieveAssociatedSpace) API</h2> <div class="box" style="width: 70%;"> <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%">Qualified user space name</td> <td align="left" valign="top" width="20%">Input</td> <td align="left" valign="top" width="20%">Char(20)</td> </tr> <tr> <td align="center" valign="top">2</td> <td align="left" valign="top">Call level</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">Associated space identifier</td> <td align="left" valign="top">Input</td> <td align="left" valign="top">Char(10)</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: *USE<br> <!-- iddvc RMBR --> <br> Service Program: QBNPREPR<br> <!-- iddvc RMBR --> <br> Threadsafe: No<br> <!-- iddvc RMBR --> <br> </div> <p>The Retrieve Associated Space (QbnRetrieveAssociatedSpace) API is used by a run-time routine to retrieve data stored with the QbnAddAssociatedSpaceEntry API. This data will be placed into the specified user space. The format of the data is specified by the user when placed into the associated space of a module using the QbnAddAssociatedSpaceEntry API. This API should be called only by a preprocessor run-time routine.</p> <br> <h3>Authorities and Locks</h3> <dl> <dt><em>User Space Authority</em></dt> <dd>*CHANGE</dd> <dt><em>User Space Library Authority</em></dt> <dd>*USE</dd> <dt><em>ILE Program or Service Program Authority</em></dt> <dd>*EXECUTE</dd> </dl> <br> <h3>Required Parameter Group</h3> <dl> <dt><strong>Qualified user space name</strong></dt> <dd>INPUT; CHAR(20) <p>The qualified name of the user space that is to receive the associated space data. The first 10 characters contain the user space name. It is left-justified and padded with blanks. The second 10 characters contain the name of the library where the user space is located. It is left-justified and padded with blanks. The library name can be specified with the following special values:</p> <table cellpadding="5"> <!-- cols="15 85" --> <tr> <td align="left" valign="top"><em>*CURLIB</em></td> <td align="left" valign="top">The job's current library</td> </tr> <tr> <td align="left" valign="top"><em>*LIBL</em></td> <td align="left" valign="top">The library list</td> </tr> </table> <br> </dd> <dt><strong>Call level</strong></dt> <dd>INPUT; BINARY(4) <p>The call level parameter identifies the location in the call stack of the ILE program or service program, which contains the associated space data.</p> <table cellpadding="5"> <!-- cols="5 95" --> <tr> <td align="left" valign="top"><em>0</em></td> <td align="left" valign="top">The current program in the call stack identifies the associated space of the ILE program or service program.</td> </tr> <tr> <td align="left" valign="top"><em>n</em></td> <td align="left" valign="top">The nth caller up the stack identifies the associated space of the ILE program or service program. This is a positive number.</td> </tr> </table> <br> </dd> <dt><strong>Associated space identifier</strong></dt> <dd>INPUT; CHAR(10) <p>The associated space identifier has the following special value:</p> <table cellpadding="5"> <!-- cols="15 85" --> <tr> <td align="left" valign="top"><em>*PREPROC</em></td> <td align="left" valign="top">The type of data from within the associated space to copy into the user space. The special value must be left-justified and padded with blanks.</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>Error Messages</h3> <table cellpadding="5"> <!-- cols="15 85" --> <tr> <th align="left" valign="top">Message ID</th> <th align="left" valign="top">Error Message Text</th> </tr> <tr> <td width="15%" valign="top">CPF2207 E</td> <td width="85%" valign="top">Not authorized to use object &1 in library &3 type *&2.</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">CPF3C90 E</td> <td align="left" valign="top">Literal value cannot be changed.</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">CPF5CA2 E</td> <td align="left" valign="top">&1 is not a valid associated space identifier parameter.</td> </tr> <tr> <td align="left" valign="top">CPF5CA4 E</td> <td align="left" valign="top">Error occurred while addressing API Parameter.</td> </tr> <tr> <td align="left" valign="top">CPF5D24 E</td> <td align="left" valign="top">Unexpected error occurred during preprocessor processing.</td> </tr> <tr> <td align="left" valign="top">CPF811A E</td> <td align="left" valign="top">User space &4 in &9 damaged.</td> </tr> <tr> <td align="left" valign="top">CPF9801 E</td> <td align="left" valign="top">Object &2 in library &3 not found.</td> </tr> <tr> <td align="left" valign="top">CPF9802 E</td> <td align="left" valign="top">Not authorized to object &2 in &3.</td> </tr> <tr> <td align="left" valign="top">CPF9803 E</td> <td align="left" valign="top">Cannot allocate object &2 in library &3.</td> </tr> <tr> <td align="left" valign="top">CPF9807 E</td> <td align="left" valign="top">One or more libraries in library list deleted.</td> </tr> <tr> <td align="left" valign="top">CPF9808 E</td> <td align="left" valign="top">Cannot allocate one or more libraries on library list.</td> </tr> <tr> <td align="left" valign="top">CPF9810 E</td> <td align="left" valign="top">Library &1 not found.</td> </tr> <tr> <td align="left" valign="top">CPF9820 E</td> <td align="left" valign="top">Not authorized to use library &1.</td> </tr> <tr> <td align="left" valign="top">CPF9830 E</td> <td align="left" valign="top">Cannot assign library &1.</td> </tr> <tr> <td align="left" valign="top">CPF9838 E</td> <td align="left" valign="top">User profile storage limit exceeded.</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: V3R1 <hr> <center> <table cellpadding="2" cellspacing="2"> <tr align="center"> <td valign="middle" align="center"><a href="#Top_Of_Page">Top</a> | <a href= "pgm1.htm">Program and CL Command APIs</a> | <a href="aplist.htm">APIs by category</a></td> </tr> </table> </center> </body> </html>