296 lines
18 KiB
HTML
296 lines
18 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="SQLColumns - Get column information for a table" />
|
|
<meta name="DC.Relation" scheme="URI" content="rzadphdapi.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="rzadpfncoln" />
|
|
<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>SQLColumns - Get column information for a table</title>
|
|
</head>
|
|
<body id="rzadpfncoln"><a name="rzadpfncoln"><!-- --></a>
|
|
<!-- Java sync-link --><script language="Javascript" src="../rzahg/synch.js" type="text/javascript"></script>
|
|
<h1 class="topictitle1">SQLColumns - Get column information for a table</h1>
|
|
<div><div class="section"></div>
|
|
<div class="section"><h4 class="sectiontitle">Purpose</h4> <p><samp class="codeph">SQLColumns()</samp> returns
|
|
a list of columns in the specified tables. The information is returned in
|
|
an SQL result set, which can be retrieved using the same functions that are
|
|
used to fetch a result set generated by a SELECT statement.</p>
|
|
</div>
|
|
<div class="section"><h4 class="sectiontitle">Syntax</h4><pre>SQLRETURN SQLColumns (SQLHSTMT hstmt,
|
|
SQLCHAR *szCatalogName,
|
|
SQLSMALLINT cbCatalogName,
|
|
SQLCHAR *szSchemaName,
|
|
SQLSMALLINT cbSchemaName,
|
|
SQLCHAR *szTableName,
|
|
SQLSMALLINT cbTableName,
|
|
SQLCHAR *szColumnName,
|
|
SQLSMALLINT cbColumnName);</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. SQLColumns arguments</caption><thead align="left"><tr><th align="left" valign="bottom" width="20%" id="d0e45">Data type</th>
|
|
<th align="left" valign="bottom" width="20%" id="d0e47">Argument</th>
|
|
<th align="left" valign="bottom" width="20%" id="d0e49">Use</th>
|
|
<th align="left" valign="bottom" width="40%" id="d0e51">Description</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody><tr><td align="left" valign="top" width="20%" headers="d0e45 ">SQLHSTMT</td>
|
|
<td align="left" valign="top" width="20%" headers="d0e47 "><em>hstmt</em></td>
|
|
<td align="left" valign="top" width="20%" headers="d0e49 ">Input</td>
|
|
<td align="left" valign="top" width="40%" headers="d0e51 ">Statement handle.</td>
|
|
</tr>
|
|
<tr><td align="left" valign="top" width="20%" headers="d0e45 ">SQLCHAR *</td>
|
|
<td align="left" valign="top" width="20%" headers="d0e47 "><em>szCatalogName</em></td>
|
|
<td align="left" valign="top" width="20%" headers="d0e49 ">Input</td>
|
|
<td align="left" valign="top" width="40%" headers="d0e51 ">Buffer that might contain a <cite>pattern-value</cite> to
|
|
qualify the result set. <cite>Catalog</cite> is the first part of a three-part
|
|
table name. <p>This must be a NULL pointer or a zero length string.</p>
|
|
</td>
|
|
</tr>
|
|
<tr><td align="left" valign="top" width="20%" headers="d0e45 ">SQLSMALLINT</td>
|
|
<td align="left" valign="top" width="20%" headers="d0e47 "><em>cbCatalogName</em></td>
|
|
<td align="left" valign="top" width="20%" headers="d0e49 ">Input</td>
|
|
<td align="left" valign="top" width="40%" headers="d0e51 ">Length of <em>szCatalogName</em>. This must
|
|
be set to 0.</td>
|
|
</tr>
|
|
<tr><td align="left" valign="top" width="20%" headers="d0e45 ">SQLCHAR *</td>
|
|
<td align="left" valign="top" width="20%" headers="d0e47 "><em>szSchemaName</em></td>
|
|
<td align="left" valign="top" width="20%" headers="d0e49 ">Input</td>
|
|
<td align="left" valign="top" width="40%" headers="d0e51 ">Buffer that might contain a <em>pattern-value</em> to
|
|
qualify the result set by schema name.</td>
|
|
</tr>
|
|
<tr><td align="left" valign="top" width="20%" headers="d0e45 ">SQLSMALLINT</td>
|
|
<td align="left" valign="top" width="20%" headers="d0e47 "><em>cbSchemaName</em></td>
|
|
<td align="left" valign="top" width="20%" headers="d0e49 ">Input</td>
|
|
<td align="left" valign="top" width="40%" headers="d0e51 ">Length of <em>szSchemaName</em></td>
|
|
</tr>
|
|
<tr><td align="left" valign="top" width="20%" headers="d0e45 ">SQLCHAR *</td>
|
|
<td align="left" valign="top" width="20%" headers="d0e47 "><em>szTableName</em></td>
|
|
<td align="left" valign="top" width="20%" headers="d0e49 ">Input</td>
|
|
<td align="left" valign="top" width="40%" headers="d0e51 ">Buffer that might contain a <em>pattern-value</em> to
|
|
qualify the result set by table name.</td>
|
|
</tr>
|
|
<tr><td align="left" valign="top" width="20%" headers="d0e45 ">SQLSMALLINT</td>
|
|
<td align="left" valign="top" width="20%" headers="d0e47 "><em>cbTableName</em></td>
|
|
<td align="left" valign="top" width="20%" headers="d0e49 ">Input</td>
|
|
<td align="left" valign="top" width="40%" headers="d0e51 ">Length of <em>szTableName</em></td>
|
|
</tr>
|
|
<tr><td align="left" valign="top" width="20%" headers="d0e45 ">SQLCHAR *</td>
|
|
<td align="left" valign="top" width="20%" headers="d0e47 "><em>szColumnName</em></td>
|
|
<td align="left" valign="top" width="20%" headers="d0e49 ">Input</td>
|
|
<td align="left" valign="top" width="40%" headers="d0e51 ">Buffer that might contain a <em>pattern-value</em> to
|
|
qualify the result set by column name.</td>
|
|
</tr>
|
|
<tr><td align="left" valign="top" width="20%" headers="d0e45 ">SQLSMALLINT</td>
|
|
<td align="left" valign="top" width="20%" headers="d0e47 "><em>cbColumnName</em></td>
|
|
<td align="left" valign="top" width="20%" headers="d0e49 ">Input</td>
|
|
<td align="left" valign="top" width="40%" headers="d0e51 ">Length of <em>szColumnName</em></td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
<div class="section"><h4 class="sectiontitle">Usage</h4><p>This function retrieves information about
|
|
the columns of a table or a list of tables.</p>
|
|
<p><samp class="codeph">SQLColumns()</samp> returns
|
|
a standard result set. <a href="#rzadpfncoln__tbcols">Table 2</a> lists the
|
|
columns in the result set. Applications should anticipate that additional
|
|
columns beyond the REMARKS columns can be added in future releases.</p>
|
|
<p>The <em>szCatalogName,
|
|
szSchemaName, szTableName</em>, and <em>szColumnName</em> arguments accept search
|
|
patterns. An escape character can be specified in conjunction with a wildcard
|
|
character to allow that actual character to be used in the search pattern.
|
|
The escape character is specified on the SQL_ATTR_ESCAPE_CHAR environment
|
|
attribute. </p>
|
|
<div class="p">This function does not return information about the columns
|
|
in a result set, which is retrieved by <samp class="codeph">SQLDescribeCol()</samp> or <samp class="codeph">SQLColAttributes()</samp>.
|
|
If an application wants to obtain column information for a result set, it
|
|
should always call <samp class="codeph">SQLDescribeCol()</samp> or <samp class="codeph">SQLColAttributes()</samp> for
|
|
efficiency. <samp class="codeph">SQLColumns()</samp> maps to a complex query against
|
|
the system catalogs, and can require a large amount of system resources.
|
|
<div class="tablenoborder"><a name="rzadpfncoln__tbcols"><!-- --></a><table cellpadding="4" cellspacing="0" summary="" id="rzadpfncoln__tbcols" width="100%" frame="hsides" border="1" rules="all"><caption>Table 2. Columns
|
|
returned by SQLColumns</caption><thead align="left"><tr><th align="left" valign="top" width="29.47761194029851%" id="d0e217">Column name</th>
|
|
<th align="left" valign="top" width="27.425373134328357%" id="d0e219">Data type</th>
|
|
<th align="left" valign="top" width="43.09701492537313%" id="d0e221">Description</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody><tr><td align="left" valign="top" width="29.47761194029851%" headers="d0e217 ">BUFFER_LENGTH</td>
|
|
<td align="left" valign="top" width="27.425373134328357%" headers="d0e219 ">INTEGER</td>
|
|
<td align="left" valign="top" width="43.09701492537313%" headers="d0e221 ">The maximum number of bytes to store data
|
|
from this column if SQL_DEFAULT were specified on the <samp class="codeph">SQLBindCol(),
|
|
SQLGetData()</samp> and <samp class="codeph">SQLBindParam()</samp> calls.</td>
|
|
</tr>
|
|
<tr><td align="left" valign="top" width="29.47761194029851%" headers="d0e217 ">CHAR_OCTET_LENGTH</td>
|
|
<td align="left" valign="top" width="27.425373134328357%" headers="d0e219 ">INTEGER</td>
|
|
<td align="left" valign="top" width="43.09701492537313%" headers="d0e221 ">Contains the maximum length in octets for
|
|
a character data type column. For single byte character sets, this is the
|
|
same as LENGTH_PRECISION. For all other data types, it is NULL.</td>
|
|
</tr>
|
|
<tr><td align="left" valign="top" width="29.47761194029851%" headers="d0e217 ">COLUMN_DEF</td>
|
|
<td align="left" valign="top" width="27.425373134328357%" headers="d0e219 ">VARCHAR(254)</td>
|
|
<td align="left" valign="top" width="43.09701492537313%" headers="d0e221 ">The column's default value. If the default
|
|
value is a numeric literal, then this column contains the character representation
|
|
of the numeric literal with no enclosing single quotation marks. If the default
|
|
value is a character string, then this column is that string enclosed in single
|
|
quotation marks. If the default value a <em>pseudo-literal</em>, such as for
|
|
DATE, TIME, and TIMESTAMP columns, then this column contains the keyword of
|
|
the pseudo-literal (for example, CURRENT DATE) with no enclosing quotation
|
|
marks. <p>If NULL is specified as the default value, then this column returns
|
|
the word NULL, not enclosed in quotation marks. If the default value cannot
|
|
be represented without truncation, then this column contains TRUNCATED with
|
|
no enclosing single quotation marks. If no default value is specified, then
|
|
this column is NULL.</p>
|
|
</td>
|
|
</tr>
|
|
<tr><td align="left" valign="top" width="29.47761194029851%" headers="d0e217 ">COLUMN_NAME</td>
|
|
<td align="left" valign="top" width="27.425373134328357%" headers="d0e219 ">VARCHAR(128)</td>
|
|
<td align="left" valign="top" width="43.09701492537313%" headers="d0e221 ">Column identifier. The name of the column
|
|
of the specified view, table, or table's column the alias is built for.</td>
|
|
</tr>
|
|
<tr><td align="left" valign="top" width="29.47761194029851%" headers="d0e217 ">DATA_TYPE</td>
|
|
<td align="left" valign="top" width="27.425373134328357%" headers="d0e219 ">SMALLINT not NULL</td>
|
|
<td align="left" valign="top" width="43.09701492537313%" headers="d0e221 ">DATA_TYPE identifies the SQL data type of
|
|
the column. For CHAR FOR BIT DATA and VARCHAR FOR BIT DATA data types, the
|
|
CLI returns SQL_BINARY and SQL_VARBINARY to indicate it is a FOR BIT DATA
|
|
column.</td>
|
|
</tr>
|
|
<tr><td align="left" valign="top" width="29.47761194029851%" headers="d0e217 ">DATETIME_CODE</td>
|
|
<td align="left" valign="top" width="27.425373134328357%" headers="d0e219 ">INTEGER</td>
|
|
<td align="left" valign="top" width="43.09701492537313%" headers="d0e221 "><div class="p">The subtype code for date and time data
|
|
types: <ul><li>SQL_DATE</li>
|
|
<li>SQL_TIME</li>
|
|
<li>SQL_TIMESTAMP</li>
|
|
</ul>
|
|
</div>
|
|
<p>For all other data types, this column returns NULL.</p>
|
|
</td>
|
|
</tr>
|
|
<tr><td align="left" valign="top" width="29.47761194029851%" headers="d0e217 ">LENGTH_PRECISION</td>
|
|
<td align="left" valign="top" width="27.425373134328357%" headers="d0e219 ">INTEGER</td>
|
|
<td align="left" valign="top" width="43.09701492537313%" headers="d0e221 ">If DATA TYPE is an approximate numeric data
|
|
type, this column contains the number of bits of mantissa precision of the
|
|
column. For exact numeric data types, this column contains the total number
|
|
of decimal digit allowed in the column. For time and timestamp data types,
|
|
this column contains the number of digits of precision of the fractional seconds
|
|
component; otherwise, this column is NULL. <div class="note"><span class="notetitle">Note:</span> The ODBC definition of precision
|
|
is typically the number of digits to store the data type.</div>
|
|
</td>
|
|
</tr>
|
|
<tr><td align="left" valign="top" width="29.47761194029851%" headers="d0e217 ">NULLABLE</td>
|
|
<td align="left" valign="top" width="27.425373134328357%" headers="d0e219 ">SMALLINT not NULL</td>
|
|
<td align="left" valign="top" width="43.09701492537313%" headers="d0e221 ">SQL_NO_NULLS if the column does not accept
|
|
NULL values. <p>SQL_NULLABLE if the column accepts NULL values.</p>
|
|
</td>
|
|
</tr>
|
|
<tr><td align="left" valign="top" width="29.47761194029851%" headers="d0e217 ">NUM_PREC_RADIX</td>
|
|
<td align="left" valign="top" width="27.425373134328357%" headers="d0e219 ">SMALLINT</td>
|
|
<td align="left" valign="top" width="43.09701492537313%" headers="d0e221 ">The value is 10, 2, or NULL. If DATA_TYPE
|
|
is an approximate numeric data type, this column contains the value 2; then
|
|
the LENGTH_PRECISION column contains the number of bits allowed in the column.
|
|
<p>If DATA_TYPE is an exact numeric data type, this column contains the value
|
|
10 and the LENGTH_PRECISION and NUM_SCALE columns contain the number of decimal
|
|
digits allowed for the column.</p>
|
|
<p>For numeric data types, the Database
|
|
Management System (DBMS) can return a NUM_PREC_RADIX of either 10 or 2.</p>
|
|
<p>NULL
|
|
is returned for data types where radix is not applicable.</p>
|
|
</td>
|
|
</tr>
|
|
<tr><td align="left" valign="top" width="29.47761194029851%" headers="d0e217 ">NUM_SCALE</td>
|
|
<td align="left" valign="top" width="27.425373134328357%" headers="d0e219 ">SMALLINT</td>
|
|
<td align="left" valign="top" width="43.09701492537313%" headers="d0e221 ">The scale of the column. NULL is returned
|
|
for data types where scale is not applicable.</td>
|
|
</tr>
|
|
<tr><td align="left" valign="top" width="29.47761194029851%" headers="d0e217 ">ORDINAL_POSITION</td>
|
|
<td align="left" valign="top" width="27.425373134328357%" headers="d0e219 ">INTEGER NOT NULL</td>
|
|
<td align="left" valign="top" width="43.09701492537313%" headers="d0e221 ">The ordinal position of the column in the
|
|
table. The first column in the table is number 1.</td>
|
|
</tr>
|
|
<tr><td align="left" valign="top" width="29.47761194029851%" headers="d0e217 ">REMARKS</td>
|
|
<td align="left" valign="top" width="27.425373134328357%" headers="d0e219 ">VARCHAR(254)</td>
|
|
<td align="left" valign="top" width="43.09701492537313%" headers="d0e221 ">Might contain descriptive information about
|
|
the column.</td>
|
|
</tr>
|
|
<tr><td align="left" valign="top" width="29.47761194029851%" headers="d0e217 ">TABLE_CAT</td>
|
|
<td align="left" valign="top" width="27.425373134328357%" headers="d0e219 ">VARCHAR(128)</td>
|
|
<td align="left" valign="top" width="43.09701492537313%" headers="d0e221 ">The current server.</td>
|
|
</tr>
|
|
<tr><td align="left" valign="top" width="29.47761194029851%" headers="d0e217 ">TABLE_NAME</td>
|
|
<td align="left" valign="top" width="27.425373134328357%" headers="d0e219 ">VARCHAR(128)</td>
|
|
<td align="left" valign="top" width="43.09701492537313%" headers="d0e221 ">Name of the table, view or alias.</td>
|
|
</tr>
|
|
<tr><td align="left" valign="top" width="29.47761194029851%" headers="d0e217 ">TABLE_SCHEM</td>
|
|
<td align="left" valign="top" width="27.425373134328357%" headers="d0e219 ">VARCHAR(128)</td>
|
|
<td align="left" valign="top" width="43.09701492537313%" headers="d0e221 ">The name of the schema containing TABLE_NAME.</td>
|
|
</tr>
|
|
<tr><td align="left" valign="top" width="29.47761194029851%" headers="d0e217 ">TYPE_NAME</td>
|
|
<td align="left" valign="top" width="27.425373134328357%" headers="d0e219 ">VARCHAR(128) not NULL</td>
|
|
<td align="left" valign="top" width="43.09701492537313%" headers="d0e221 ">TYPE_NAME is a character string representing
|
|
the name of the data type corresponding to DATA_TYPE. If the data type is
|
|
FOR BIT DATA, then the corresponding string FOR BIT DATA is appended to the
|
|
data type, for example, CHAR () FOR BIT DATA.</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</div>
|
|
</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>
|
|
</ul>
|
|
</div>
|
|
<div class="section"><h4 class="sectiontitle">Diagnostics</h4>
|
|
<div class="tablenoborder"><table cellpadding="4" cellspacing="0" summary="" width="100%" frame="hsides" border="1" rules="rows"><caption>Table 3. SQLColumns SQLSTATEs</caption><thead align="left"><tr><th align="left" valign="top" id="d0e397">SQLSTATE</th>
|
|
<th align="left" valign="top" id="d0e399">Description</th>
|
|
<th align="left" valign="top" id="d0e401">Explanation</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody><tr><td align="left" valign="top" headers="d0e397 "><strong>HY</strong>001</td>
|
|
<td align="left" valign="top" headers="d0e399 ">Memory allocation failure</td>
|
|
<td align="left" valign="top" headers="d0e401 ">The driver is unable to allocate memory required
|
|
to support the processing or completion of the function.</td>
|
|
</tr>
|
|
<tr><td align="left" valign="top" headers="d0e397 "><strong>HY</strong>009</td>
|
|
<td align="left" valign="top" headers="d0e399 ">String or buffer length that is not valid</td>
|
|
<td align="left" valign="top" headers="d0e401 ">The value of one of the name length arguments
|
|
is less than 0, but not equal SQL_NTS.</td>
|
|
</tr>
|
|
<tr><td align="left" valign="top" headers="d0e397 "><strong>HY</strong>010</td>
|
|
<td align="left" valign="top" headers="d0e399 ">Function sequence error</td>
|
|
<td align="left" valign="top" headers="d0e401 ">There is an open cursor for this statement
|
|
handle, or there is no connection for this statement handle.</td>
|
|
</tr>
|
|
<tr><td valign="top" headers="d0e397 "><strong>HY</strong>021</td>
|
|
<td valign="top" headers="d0e399 ">Internal descriptor that is not valid</td>
|
|
<td valign="top" headers="d0e401 ">The internal descriptor cannot be addressed or allocated,
|
|
or it contains a value that is not valid.</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</div>
|
|
</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>
|
|
</body>
|
|
</html> |