friedkiwi/ibm-information-center
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
0332907f0f
ibm-information-center/dist/eclipse/plugins/i5OS.ic.db2_5.4.0.1/rbafzmstdescr.htm

314 lines
18 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 xmlns="http://www.w3.org/1999/xhtml" lang="en-US" xml:lang="en-us">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="dc.language" scheme="rfc1766" 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. -->
<meta name="dc.date" scheme="iso8601" content="2005-09-19" />
<meta name="copyright" content="(C) Copyright IBM Corporation 1998, 2006" />
<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="keywords" content="DESCRIBE statement, DESCRIBE, SQL statements,
with DESCRIBE, obtaining information, prepared SQL statement,
obtaining statement information with, dynamic SQL,
in USING clause of DESCRIBE statement, in DESCRIBE statement, statement-name,
USING keyword, SQL-descriptor-name, INTO keyword, descriptor-name, SQLN,
variables, SQLN field of SQLDA, SQLDAID, SQLDAID field of SQLDA, SQLDABC,
SQLDABC field of SQLDA, SQLD, SQLD field of SQLDA, SQLVAR, SQLVAR field of SQLDA,
USING clause, in USING clause, NAMES, SYSTEM NAMES, LABELS, ANY clause,
BOTH clause, ALL clause, system column name, by INTO with PREPARE" />
<title>DESCRIBE</title>
<link rel="stylesheet" type="text/css" href="ibmidwb.css" />
<link rel="stylesheet" type="text/css" href="ic.css" />
</head>
<body>
<a id="Top_Of_Page" name="Top_Of_Page"></a><!-- Java sync-link -->
<script language = "Javascript" src = "../rzahg/synch.js" type="text/javascript"></script>
<a name="descr"></a>
<h2 id="descr"><a href="rbafzmst02.htm#ToC_1016">DESCRIBE</a></h2>
<p><a id="idx2384" name="idx2384"></a><a id="idx2385" name="idx2385"></a><a id="idx2386" name="idx2386"></a><a id="idx2387" name="idx2387"></a><a id="idx2388" name="idx2388"></a>The DESCRIBE statement obtains
information about a prepared statement. For an explanation of prepared statements,
see <a href="rbafzmstpreph2.htm#preph2">PREPARE</a>.</p>
<a name="wq1450"></a>
<h3 id="wq1450"><a href="rbafzmst02.htm#ToC_1017">Invocation</a></h3>
<p>This statement can only be embedded in an application program,
SQL function, SQL procedure, or trigger. It is an executable statement that
cannot be dynamically prepared. It must not be specified in Java&trade;.</p>
<a name="wq1451"></a>
<h3 id="wq1451"><a href="rbafzmst02.htm#ToC_1018">Authorization</a></h3>
<p>None required. See <a href="rbafzmstpreph2.htm#preph2">PREPARE</a> for the authorization required
to create a prepared statement.</p>
<a name="wq1452"></a>
<h3 id="wq1452"><a href="rbafzmst02.htm#ToC_1019">Syntax</a></h3>
<a href="rbafzmstdescr.htm#synsdesc"><img src="c.gif" alt="Click to skip syntax diagram" /></a>
<pre class="cgraphic"><span><img src="c.gif" alt="Read syntax diagram" longdesc="rbafzmstsyn329.htm"
border="0" /></span><a href="#skipsyn-328"><img src="c.gif" alt="Skip visual syntax diagram"
border="0" /></a> .-OUTPUT-.
>>-DESCRIBE--+--------+--<span class="italic">statement-name</span>------------------------->
.-SQL-. .-LOCAL--.
>--+-USING--+-----+--DESCRIPTOR--+--------+--<span class="italic">SQL-descriptor-name</span>-+->&lt;
| '-GLOBAL-' |
'-INTO----<span class="italic">descriptor-name</span>----+-------------------------+------'
'-USING--+-NAMES--------+-'
+-SYSTEM NAMES-+
+-LABELS-------+
+-ANY----------+
+-BOTH---------+
'-ALL----------'
</pre>
<a name="skipsyn-328" id="skipsyn-328"></a>
<a name="synsdesc"></a>
<h3 id="synsdesc"><a href="rbafzmst02.htm#ToC_1020">Description</a></h3>
<dl class="parml">
<dt class="bold"><var class="pv">statement-name</var> </dt><a id="idx2389" name="idx2389"></a>
<dd>Identifies the prepared statement. When the DESCRIBE statement is executed,
the name must identify a prepared statement at the application server.
<p>If the prepared statement is a SELECT or VALUES INTO statement, the information
returned describes the columns in its result table. If the prepared statement
is a CALL statement, the information returned describes the OUT and INOUT
parameters of the procedure.</p>
</dd>
<dt class="bold">USING <a id="idx2390" name="idx2390"></a></dt>
<dd>Identifies an SQL descriptor.
<dl class="parml">
<dt class="bold">LOCAL</dt>
<dd>Specifies the scope of the name of the descriptor to be local to program
invocation.
</dd>
<dt class="bold">GLOBAL</dt>
<dd>Specifies the scope of the name of the descriptor to be global to the
SQL session.
</dd>
<dt class="bold"><var class="pv">SQL-descriptor-name</var></dt>
<dd>Names the SQL descriptor. The name must identify a descriptor that already
exists with the specified scope. <a id="idx2391" name="idx2391"></a>
</dd>
</dl>
</dd>
<dt class="bold">INTO <var class="pv">descriptor-name</var> </dt><a id="idx2392" name="idx2392"></a><a id="idx2393" name="idx2393"></a>
<dd>Identifies an SQL descriptor area (SQLDA), which is described in <a href="rbafzmstsqldda.htm#sqldda">Appendix D. SQLDA (SQL descriptor area)</a>. Before the DESCRIBE statement is executed, the following
variable in the SQLDA must be set.
<dl>
<dt class="bold">SQLN</dt><a id="idx2394" name="idx2394"></a><a id="idx2395" name="idx2395"></a>
<dd>Indicates the number of SQLVAR entries provided in the SQLDA. SQLN must
be set to a value greater than or equal to zero before the DESCRIBE statement
is executed. For information on techniques to determine the number of occurrences
requires, see <a href="rbafzmstfielddescsqlda.htm#howmany">Determining how many SQLVAR occurrences are needed</a>.
</dd>
</dl>The rules for REXX are different. For more information, see the <a href="../rzajp/rzajpkickoff.htm">Embedded SQL Programming</a> book.
</dd>
</dl>
<p>When the DESCRIBE statement is executed, the database manager assigns values
to the variables of the SQLDA as follows: </p>
<dl>
<dt class="bold">SQLDAID</dt><a id="idx2396" name="idx2396"></a><a id="idx2397" name="idx2397"></a>
<dd>The first 6 bytes are set to 'SQLDA ' (that is, 5 letters followed by
the space character).
<p>The seventh byte is set based on the result columns
described:</p>
<ul>
<li>If the SQLDA contains two, three, or four SQLVAR entries for
every select list item (or, column of the result table), the seventh byte
is set to '2', '3', or '4'. This technique is used in order to accommodate
LOB or distinct type result columns, labels, and system names.</li>
<li>Otherwise, the seventh byte is set to the space character.</li></ul>
<p>The seventh byte is set to the space character if there is not
enough room in the SQLDA to contain the description of all result columns.</p>
<p>The eighth byte is set to the space character.</p>
</dd>
<dt class="bold">SQLDABC</dt><a id="idx2398" name="idx2398"></a><a id="idx2399" name="idx2399"></a>
<dd>Length of the SQLDA in bytes.
</dd>
<dt class="bold">SQLD</dt><a id="idx2400" name="idx2400"></a><a id="idx2401" name="idx2401"></a>
<dd>If the prepared statement is a SELECT, SQLD is set to the
number of columns in its result table. If the prepared statement is a CALL
statement, SQLD is set to the number of OUT and INOUT parameters of the procedure.
Otherwise, SQLD is set to 0.
</dd>
<dt class="bold">SQLVAR</dt><a id="idx2402" name="idx2402"></a><a id="idx2403" name="idx2403"></a>
<dd>If the value of SQLD is 0, or greater than the value of SQLN, no values
are assigned to occurrences of SQLVAR.
<p>If the value of SQLD
is <span class="italic">n</span>, where <span class="italic">n</span> is greater than
0 but less than or equal to the value of SQLN, values are assigned to the
first <span class="italic">n</span> occurrences of SQLVAR so that the first occurrence
of SQLVAR contains a description of the first column of the result table (or
parameter), the second occurrence of SQLVAR contains a description of the
second column of the result table (or parameter), and so on. For information
on the values assigned to SQLVAR occurrences, see <a href="rbafzmstsqlvaroc.htm#sqlvaroc">Field descriptions in an occurrence of SQLVAR</a>.</p>
</dd>
</dl>
<dl class="parml">
<dt class="bold">USING </dt><a id="idx2404" name="idx2404"></a>
<dd>Specifies what value to assign to each SQLNAME variable in
the SQLDA. If the requested value does not exist or if the length of a name
is greater than 30, SQLNAME is set to a length of 0.
<dl class="parml">
<dt class="bold">NAMES </dt><a id="idx2405" name="idx2405"></a>
<dd>Assigns the name of the column (or parameter). This is the
default. For the DESCRIBE of a prepared statement where the name is explicitly
listed in the select-list, the name specified is returned. The column name
returned is case sensitive and without delimiters.
</dd>
<dt class="bold">SYSTEM NAMES </dt><a id="idx2406" name="idx2406"></a>
<dd>Assigns the system column name of the column.
</dd>
<dt class="bold">LABELS </dt><a id="idx2407" name="idx2407"></a>
<dd>Assigns the label of the column. (Column labels are defined by the LABEL
statement.) Only the first 20 bytes of the label are returned.
</dd>
<dt class="bold">ANY </dt><a id="idx2408" name="idx2408"></a>
<dd>Assigns the column label. If the column has no label, the column name
is used instead.
</dd>
<dt class="bold">BOTH </dt><a id="idx2409" name="idx2409"></a>
<dd>Assigns both the label and name of the column. In this case, two or
three occurrences of SQLVAR per column, depending on whether the result set
contains distinct types, are needed to accommodate the additional information.
To specify this expansion of the SQLVAR array, set SQLN to 2*<span class="italic">n</span> or 3*<span class="italic">n</span>(where <span class="italic">n</span> is the
number of columns in the table or view). The first <span class="italic">n</span> occurrences
of SQLVAR contain the column names. Either the second or third <span class="italic">n</span> occurrences contain the column labels. If there are no distinct types,
the labels are returned in the second set of SQLVAR entries. Otherwise, the
labels are returned in the third set of SQLVAR entries.
</dd>
<dt class="bold">ALL </dt><a id="idx2410" name="idx2410"></a><a id="idx2411" name="idx2411"></a>
<dd>Assigns the label, column name, and system column name. In
this case three or four occurrences of SQLVAR per column, depending on whether
the result set contains distinct types, are needed to accommodate the additional
information. To specify this expansion of the SQLVAR array, set SQLN to 3*<span class="italic">n</span> or 4*<span class="italic">n</span> (where <span class="italic">n</span> is the number of columns in the result table). The first <span class="italic">n</span> occurrences of SQLVAR contain the system column names. The second or
third <span class="italic">n</span> occurrences contain the column labels. The
third or fourth <span class="italic">n</span> occurrences contain the column names
if they are different from the system column name. Otherwise the SQLNAME field
is set to a length of zero. If there are no distinct types, the labels are
returned in the second set of SQLVAR entries and the column names are returned
in the third set of SQLVAR entries. Otherwise, the labels are returned in
the third set of SQLVAR entries and the column names are returned in the fourth
set of SQLVAR entries.
</dd>
</dl>
</dd>
</dl>
<a name="wq1453"></a>
<h3 id="wq1453"><a href="rbafzmst02.htm#ToC_1021">Notes</a></h3>
<p><span class="bold">PREPARE INTO:</span> Information about a prepared statement
can also be obtained by using the INTO clause of the PREPARE statement.</p>
<p><span class="bold">Allocating the SQL descriptor:</span> Before
the DESCRIBE statement is executed, the SQL descriptor must be allocated using
the ALLOCATE DESCRIPTOR statement. If the number of descriptor items allocated
is less than the number of result columns, a warning (SQLSTATE 01005) is returned.</p>
<p><span class="bold">Allocating the SQLDA:</span> In C, COBOL, PL/I, and RPG,
before the DESCRIBE or PREPARE INTO statement is executed, <a id="idx2412" name="idx2412"></a>enough storage must be allocated
for some number of SQLVAR occurrences. SQLN must then be set to the number
of SQLVAR occurrences that were allocated. To obtain the description of the
columns of the result table of a prepared SELECT statement, the number of
occurrences of SQLVAR entries must not be less than the number of columns.
Furthermore, if the columns include LOBs or distinct types, the number of
occurrences of SQLVAR entries should be two times the number of columns. See <a href="rbafzmstfielddescsqlda.htm#howmany">Determining how many SQLVAR occurrences are needed</a> for more information.Among the possible ways to allocate
the SQLDA are the three described below:</p>
<dl>
<dt class="bold">First technique</dt>
<dd>Allocate an SQLDA with enough occurrences of SQLVAR entries to accommodate
any select list that the application will have to process. At the extreme,
the number of SQLVARs could equal two times the maximum number of columns
allowed in a result table. Having done the allocation, the application can
use this SQLDA repeatedly.
<p>This technique uses a large amount of storage
that is never deallocated, even when most of this storage is not used for
a particular select list.</p>
</dd>
<dt class="bold">Second technique</dt>
<dd>Repeat the following three steps for every processed select list:
<ol type="1">
<li>Execute a DESCRIBE statement with an SQLDA that has no occurrences of
SQLVAR entries; that is, an SQLDA for which SQLN is zero. The value returned
for SQLD is the number of columns in the result table. This is either the
required number of occurrences of SQLVAR entries or half the required number.
Because there were no SQLVAR entries, a warning will be issued.</li>
<li>If the SQLSTATE accompanying that warning is equal to 01005, allocate
an SQLDA with 2 * SQLD occurrences and set SQLN in the new SQLDA to 2 * SQLD.
Otherwise, allocate an SQLDA with SQLD occurrences and set SQLN in the new
SQLDA to the value of SQLD.</li>
<li>Execute the DESCRIBE statement again, using this new SQLDA.</li></ol>
<p>This technique allows better storage management than the first technique,
but it doubles the number of DESCRIBE statements.</p>
</dd>
<dt class="bold">Third technique</dt>
<dd>Allocate an SQLDA that is large enough to handle most, and perhaps all,
select lists but is also reasonably small. If an execution of DESCRIBE fails
because the SQLDA is too small, allocate a larger SQLDA and execute DESCRIBE
again. For the new SQLDA, use the value of SQLD (or double the value of SQLD)
returned from the first execution of DESCRIBE for the number of occurrences
of SQLVAR entries.
<p>This technique is a compromise between the first two
techniques. Its effectiveness depends on a good choice of size for the original
SQLDA.</p>
</dd>
</dl>
<a name="wq1455"></a>
<h3 id="wq1455"><a href="rbafzmst02.htm#ToC_1022">Example</a></h3>
<p>In a C program, execute a DESCRIBE statement with an SQLDA that has no
occurrences of SQLVAR entries. If SQLD is greater than zero, use the value
to allocate an SQLDA with the necessary number of occurrences of SQLVAR entrires
and then execute a DESCRIBE statement using that SQLDA. </p>
<pre class="xmp"> EXEC SQL <span class="bold">BEGIN DECLARE SECTION</span>;
char stmt1_str [200];
EXEC SQL <span class="bold">END DECLARE SECTION</span>;
EXEC SQL <span class="bold">INCLUDE SQLDA</span>;
struct sqlda mja;
struct sqlda *mjap;
EXEC SQL <span class="bold">DECLARE</span> DYN_CURSOR <span class="bold">CURSOR FOR</span> STMT1_NAME;
... /* code to prompt user for a query, then to generate */
/* a select-statement in the stmt1_str */
EXEC SQL <span class="bold">PREPARE</span> STMT1_NAME <span class="bold">FROM</span> :stmt1_str;
... /* code to set SQLN to zero and to allocate the SQLDA */
EXEC SQL <span class="bold">DESCRIBE</span> STMT1_NAME <span class="bold">INTO</span> :mja;
if (mja.sqld == 0);
else
{
... /* Code to re-allocate the SQLDA and set mjap */
.
.
.
if (strcmp(SQLSTATE,"01005") == 0)
{
mjap->sqln = 2*mja.sqld;
SETSQLDOUBLED(mjap, SQLDOUBLED);
}
else
{
mjap->sqln = mja.sqld;
SETSQLDOUBLED(mjap, SQLSINGLED);
}
EXEC SQL <span class="bold">DESCRIBE</span> STMT1_NAME <span class="bold">INTO</span> :newda;
}
... /* code to prepare for the use of the SQLDA */
EXEC SQL <span class="bold">OPEN</span> DYN_CURSOR;
... /* loop to fetch rows from result table */
EXEC SQL <span class="bold">FETCH</span> DYN_CURSOR <span class="bold">USING DESCRIPTOR</span> :mja;
.
.
.</pre><a id="idx2413" name="idx2413"></a><a id="idx2414" name="idx2414"></a>
<hr /><br />
[ <a href="#Top_Of_Page">Top of Page</a> | <a href="rbafzmstdelst.htm">Previous Page</a> | <a href="rbafzdescrinput.htm">Next Page</a> | <a href="rbafzmst02.htm#wq1">Contents</a> |
<a href="rbafzmstindex.htm#index">Index</a> ]
<a id="Bot_Of_Page" name="Bot_Of_Page"></a>
</body>
</html>
Reference in New Issue View Git Blame Copy Permalink