friedkiwi/ibm-information-center
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
8826eae394
ibm-information-center/dist/eclipse/plugins/i5OS.ic.cli_5.4.0.1/rzadpfndatas.htm

262 lines
16 KiB
HTML
Raw Blame History

<?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="SQLDataSources - Get list of data sources" />
<meta name="DC.Relation" scheme="URI" content="rzadphdapi.htm" />
<meta name="DC.Relation" scheme="URI" content="rzadprestrictions.htm" />
<meta name="copyright" content="(C) Copyright IBM Corporation 1999, 2006" />
<meta name="DC.Rights.Owner" content="(C) Copyright IBM Corporation 1999, 2006" />
<meta name="DC.Format" content="XHTML" />
<meta name="DC.Identifier" content="rzadpfndatas" />
<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>SQLDataSources</title>
</head>
<body id="rzadpfndatas"><a name="rzadpfndatas"><!-- --></a>
<!-- Java sync-link --><script language="Javascript" src="../rzahg/synch.js" type="text/javascript"></script>
<h1 class="topictitle1">SQLDataSources - Get list of data sources</h1>
<div><div class="section"><h4 class="sectiontitle">Purpose</h4> <p><samp class="codeph">SQLDataSources()</samp> returns
a list of target databases available, one at a time. A database must be cataloged
to be available. For more information about cataloging, refer to the usage
notes for <samp class="codeph">SQLConnect()</samp> or see the online help for the Work
with Relational Database (RDB) Directory Entries (WRKRDBDIRE) command.</p>
<p><samp class="codeph">SQLDataSources()</samp> is
typically called before a connection is made, to determine the databases that
are available to connect to.</p>
<p>If you are running DB2<sup>®</sup> UDB CLI in SQL server mode, some restrictions
apply when you use <samp class="codeph">SQLDataSources()</samp>. </p>
</div>
<div class="section"><h4 class="sectiontitle">Syntax</h4><pre>SQLRETURN SQLDataSources (SQLHENV EnvironmentHandle,
SQLSMALLINT Direction,
SQLCHAR *ServerName,
SQLSMALLINT BufferLength1,
SQLSMALLINT *NameLength1Ptr,
SQLCHAR *Description,
SQLSMALLINT BufferLength2,
SQLSMALLINT *NameLength2Ptr);</pre>
</div>
<div class="section"><h4 class="sectiontitle">Function arguments</h4>
<div class="tablenoborder"><table cellpadding="4" cellspacing="0" summary="" width="100%" frame="hsides" border="1" rules="all"><caption>Table 1. SQLDataSources arguments</caption><thead align="left"><tr><th align="left" valign="bottom" width="17.59259259259259%" id="d0e65">Data type</th>
<th align="left" valign="bottom" width="23.51851851851852%" id="d0e67">Argument </th>
<th align="left" valign="bottom" width="11.851851851851853%" id="d0e69">Use </th>
<th align="left" valign="bottom" width="47.03703703703704%" id="d0e71">Description </th>
</tr>
</thead>
<tbody><tr><td align="left" valign="top" width="17.59259259259259%" headers="d0e65 ">SQLCHAR *</td>
<td align="left" valign="top" width="23.51851851851852%" headers="d0e67 "><span class="synph"><span class="var">Description</span></span> </td>
<td align="left" valign="top" width="11.851851851851853%" headers="d0e69 ">Output </td>
<td align="left" valign="top" width="47.03703703703704%" headers="d0e71 ">Pointer to buffer where the description of
the data source is returned. DB2 UDB CLI returns the <strong><em>Comment</em></strong> field associated
with the database catalogued to the Database Management System (DBMS).</td>
</tr>
<tr><td align="left" valign="top" width="17.59259259259259%" headers="d0e65 ">SQLCHAR *</td>
<td align="left" valign="top" width="23.51851851851852%" headers="d0e67 "><span class="synph"><span class="var">ServerName</span></span></td>
<td align="left" valign="top" width="11.851851851851853%" headers="d0e69 ">Output </td>
<td align="left" valign="top" width="47.03703703703704%" headers="d0e71 ">Pointer to buffer to hold the data source
name retrieved.</td>
</tr>
<tr><td align="left" valign="top" width="17.59259259259259%" headers="d0e65 ">SQLHENV </td>
<td align="left" valign="top" width="23.51851851851852%" headers="d0e67 "><span class="synph"><span class="var">EnvironmentHandle</span></span> </td>
<td align="left" valign="top" width="11.851851851851853%" headers="d0e69 ">Input </td>
<td align="left" valign="top" width="47.03703703703704%" headers="d0e71 ">Environment handle.</td>
</tr>
<tr><td align="left" valign="top" width="17.59259259259259%" headers="d0e65 ">SQLSMALLINT </td>
<td align="left" valign="top" width="23.51851851851852%" headers="d0e67 "><span class="synph"><span class="var">Direction</span></span> </td>
<td align="left" valign="top" width="11.851851851851853%" headers="d0e69 ">Input </td>
<td align="left" valign="top" width="47.03703703703704%" headers="d0e71 ">Used by application to request the first
data source name in the list or the next one in the list. <span class="synph"><span class="var">Direction</span></span> can
take on only the following values: <ul><li>SQL_FETCH_FIRST </li>
<li>SQL_FETCH_NEXT </li>
</ul>
</td>
</tr>
<tr><td align="left" valign="top" width="17.59259259259259%" headers="d0e65 ">SQLSMALLINT *</td>
<td align="left" valign="top" width="23.51851851851852%" headers="d0e67 "><span class="synph"><span class="var">NameLength1Ptr</span></span> </td>
<td align="left" valign="top" width="11.851851851851853%" headers="d0e69 ">Output </td>
<td align="left" valign="top" width="47.03703703703704%" headers="d0e71 ">Pointer to location where the maximum number
of bytes available to return in the <span class="synph"><span class="var">ServerName</span></span> is
stored.</td>
</tr>
<tr><td align="left" valign="top" width="17.59259259259259%" headers="d0e65 ">SQLSMALLINT *</td>
<td align="left" valign="top" width="23.51851851851852%" headers="d0e67 "><span class="synph"><span class="var">NameLength2Ptr</span></span> </td>
<td align="left" valign="top" width="11.851851851851853%" headers="d0e69 ">Output </td>
<td align="left" valign="top" width="47.03703703703704%" headers="d0e71 ">Pointer to location where this function returns
the actual number of bytes available to return for the description of the
data source.</td>
</tr>
<tr><td align="left" valign="top" width="17.59259259259259%" headers="d0e65 ">SQLSMALLINT </td>
<td align="left" valign="top" width="23.51851851851852%" headers="d0e67 "><span class="synph"><span class="var">BufferLength1</span></span> </td>
<td align="left" valign="top" width="11.851851851851853%" headers="d0e69 ">Input </td>
<td align="left" valign="top" width="47.03703703703704%" headers="d0e71 ">Maximum length of the buffer pointed to by <span class="synph"><span class="var">ServerName</span></span>.
This should be less than or equal to SQL_MAX_DSN_LENGTH + 1.</td>
</tr>
<tr><td align="left" valign="top" width="17.59259259259259%" headers="d0e65 ">SQLSMALLINT </td>
<td align="left" valign="top" width="23.51851851851852%" headers="d0e67 "><span class="synph"><span class="var">BufferLength2</span></span> </td>
<td align="left" valign="top" width="11.851851851851853%" headers="d0e69 ">Input </td>
<td align="left" valign="top" width="47.03703703703704%" headers="d0e71 ">Maximum length of the <span class="synph"><span class="var">Description</span></span> buffer.</td>
</tr>
</tbody>
</table>
</div>
</div>
<div class="section"><h4 class="sectiontitle">Usage</h4><p>The application can call this function any
time by setting <span class="synph"><span class="var">Direction</span></span> to either SQL_FETCH_FIRST
or SQL_FETCH_NEXT.</p>
<p>If SQL_FETCH_FIRST is specified, the first database
in the list is always returned.</p>
<div class="p">If SQL_FETCH_NEXT is specified: <ul><li>Directly following the SQL_FETCH_FIRST call, the second database in the
list is returned</li>
<li>Before any other <samp class="codeph">SQLDataSources()</samp> call, the first database
in the list is returned</li>
<li>When there are no more databases in the list, SQL_NO_DATA_FOUND is returned.
If the function is called again, the first database is returned.</li>
<li>Any other time, the next database in the list is returned.</li>
</ul>
</div>
</div>
<div class="section"><h4 class="sectiontitle">Return codes</h4><ul><li>SQL_SUCCESS </li>
<li>SQL_SUCCESS_WITH_INFO </li>
<li>SQL_ERROR </li>
<li>SQL_INVALID_HANDLE </li>
<li>SQL_NO_DATA_FOUND </li>
</ul>
</div>
<div class="section"><h4 class="sectiontitle">Error conditions</h4>
<div class="tablenoborder"><table cellpadding="4" cellspacing="0" summary="" width="100%" frame="hsides" border="1" rules="rows"><caption>Table 2. SQLDataSources SQLSTATEs</caption><thead align="left"><tr><th align="left" valign="bottom" width="12.962962962962962%" id="d0e253">SQLSTATE </th>
<th align="left" valign="bottom" width="29.074074074074076%" id="d0e255">Description </th>
<th align="left" valign="bottom" width="57.96296296296296%" id="d0e257">Explanation </th>
</tr>
</thead>
<tbody><tr><td align="left" valign="top" width="12.962962962962962%" headers="d0e253 "><strong>01</strong>004 </td>
<td align="left" valign="top" width="29.074074074074076%" headers="d0e255 ">Data truncated</td>
<td align="left" valign="top" width="57.96296296296296%" headers="d0e257 ">The data source name returned in the argument <span class="synph"><span class="var">ServerName</span></span> is
longer than the value specified in the argument <span class="synph"><span class="var">BufferLength1</span></span>.
The argument <span class="synph"><span class="var">NameLength1Ptr</span></span> contains the length
of the full data source name. (Function returns SQL_SUCCESS_WITH_INFO.) <p>The
data source name returned in the argument <span class="synph"><span class="var">Description</span></span> is
longer than the value specified in the argument <span class="synph"><span class="var">BufferLength2</span></span>.
The argument <span class="synph"><span class="var">NameLength2Ptr</span></span> contains the length
of the full data source description. (Function returns SQL_SUCCESS_WITH_INFO.)</p>
</td>
</tr>
<tr><td align="left" valign="top" width="12.962962962962962%" headers="d0e253 "><strong>58</strong>004</td>
<td align="left" valign="top" width="29.074074074074076%" headers="d0e255 ">Unexpected system failure</td>
<td align="left" valign="top" width="57.96296296296296%" headers="d0e257 ">Unrecoverable system error.</td>
</tr>
<tr><td align="left" valign="top" width="12.962962962962962%" headers="d0e253 "><strong>HY</strong>000 </td>
<td align="left" valign="top" width="29.074074074074076%" headers="d0e255 ">General error</td>
<td align="left" valign="top" width="57.96296296296296%" headers="d0e257 ">An error occurred for which there is no specific
SQLSTATE and for which no specific SQLSTATE is defined. The error message
returned by <samp class="codeph">SQLError()</samp> in the argument <span class="synph"><span class="var">ErrorMsg</span></span> describes
the error and its cause.</td>
</tr>
<tr><td align="left" valign="top" width="12.962962962962962%" headers="d0e253 "><strong>HY</strong>001 </td>
<td align="left" valign="top" width="29.074074074074076%" headers="d0e255 ">Memory allocation failure</td>
<td align="left" valign="top" width="57.96296296296296%" headers="d0e257 ">DB2 UDB CLI is unable to allocate memory
required to support the processing or completion of the function.</td>
</tr>
<tr><td align="left" valign="top" width="12.962962962962962%" headers="d0e253 "><strong>HY</strong>009</td>
<td valign="top" width="29.074074074074076%" headers="d0e255 ">Argument value that is not valid </td>
<td align="left" valign="top" width="57.96296296296296%" headers="d0e257 ">The argument <em>ServerName</em>, <em>NameLength1Ptr</em>, <em>Description</em>,
or <em>NameLength2Ptr</em> is a null pointer. <p>Value for the direction that
is not valid.</p>
</td>
</tr>
<tr><td align="left" valign="top" width="12.962962962962962%" headers="d0e253 "><strong>HY</strong>013</td>
<td align="left" valign="top" width="29.074074074074076%" headers="d0e255 ">Unexpected memory handling error</td>
<td align="left" valign="top" width="57.96296296296296%" headers="d0e257 ">DB2 UDB CLI is unable to access memory required
to support the processing or completion of the function.</td>
</tr>
<tr><td align="left" valign="top" width="12.962962962962962%" headers="d0e253 "><strong>HY</strong>103 </td>
<td align="left" valign="top" width="29.074074074074076%" headers="d0e255 ">Direction option out of range</td>
<td align="left" valign="top" width="57.96296296296296%" headers="d0e257 ">The value specified for the argument <span class="synph"><span class="var">Direction</span></span> is
not equal to SQL_FETCH_FIRST or SQL_FETCH_NEXT.</td>
</tr>
</tbody>
</table>
</div>
</div>
<div class="section"><h4 class="sectiontitle">Authorization</h4><p>None. </p>
</div>
<div class="section"><h4 class="sectiontitle">Example</h4></div>
<div class="example" id="rzadpfndatas__xmdatas"><a name="rzadpfndatas__xmdatas"><!-- --></a><div class="p"><div class="note"><span class="notetitle">Note:</span> By using the code examples, you
agree to the terms of the <a href="codedisclaimer.htm">Code license and disclaimer information</a>.</div>
<pre>/* From CLI sample datasour.c */
/* ... */
#include &lt;stdio.h&gt;
#include &lt;stdlib.h&gt;
#include &lt;sqlcli1.h&gt;
#include "samputil.h" /* Header file for CLI sample code */
/* ... */
/*******************************************************************
** main
** - initialize
** - terminate
*******************************************************************/
int main() {
SQLHANDLE henv ;
SQLRETURN rc ;
SQLCHAR source[SQL_MAX_DSN_LENGTH + 1], description[255] ;
SQLSMALLINT buffl, desl ;
/* ... */
/* allocate an environment handle */
rc = SQLAllocHandle( SQL_HANDLE_ENV, SQL_NULL_HANDLE, &amp;henv ) ;
if ( rc != SQL_SUCCESS ) return( terminate( henv, rc ) ) ;
/* list the available data sources (servers) */
printf( "The following data sources are available:\n" ) ;
printf( "ALIAS NAME Comment(Description)\n" ) ;
printf( "----------------------------------------------------\n" ) ;
while ( ( rc = SQLDataSources( henv,
SQL_FETCH_NEXT,
source,
SQL_MAX_DSN_LENGTH + 1,
&amp;buffl,
description,
255,
&amp;desl
)
) != SQL_NO_DATA_FOUND
) printf( "%-30s %s\n", source, description ) ;
rc = SQLFreeHandle( SQL_HANDLE_ENV, henv ) ;
if ( rc != SQL_SUCCESS ) return( terminate( henv, rc ) ) ;
return( SQL_SUCCESS ) ;
}</pre>
</div>
</div>
<div class="section"><h4 class="sectiontitle">References</h4><p>None. </p>
</div>
</div>
<div>
<div class="familylinks">
<div class="parentlink"><strong>Parent topic:</strong> <a href="rzadphdapi.htm" title="This topic provides a description of each CLI function.">DB2 UDB CLI functions</a></div>
</div>
<div class="relconcepts"><strong>Related concepts</strong><br />
<div><a href="rzadprestrictions.htm">Restrictions for running DB2 UDB CLI in server mode</a></div>
</div>
</div>
</body>
</html>
Reference in New Issue View Git Blame Copy Permalink