262 lines
16 KiB
HTML
262 lines
16 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="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 <stdio.h>
|
||
|
|
#include <stdlib.h>
|
||
|
|
#include <sqlcli1.h>
|
||
|
|
#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, &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,
|
||
|
|
&buffl,
|
||
|
|
description,
|
||
|
|
255,
|
||
|
|
&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>
|