ibm-information-center/dist/eclipse/plugins/i5OS.ic.cli_5.4.0.1/rzadpfncoln.htm

296 lines
18 KiB
HTML
Raw Normal View History

2024-04-02 14:02:31 +00:00
<?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>