189 lines
11 KiB
HTML
189 lines
11 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 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 INPUT statement, DESCRIBE INPUT,
|
|
SQL statements, with DESCRIBE INPUT, obtaining input information,
|
|
prepared SQL statement, obtaining input information with, dynamic SQL,
|
|
in DESCRIBE INPUT statement, statement-name, USING keyword, SQL-descriptor-name,
|
|
INTO keyword, 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,
|
|
SQL (Structured Query Language), description" />
|
|
<title>DESCRIBE INPUT</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="descrinput"></a>
|
|
<h2 id="descrinput"><a href="rbafzmst02.htm#ToC_1023">DESCRIBE INPUT</a></h2>
|
|
<p><a id="idx2415" name="idx2415"></a><a id="idx2416" name="idx2416"></a><a id="idx2417" name="idx2417"></a><a id="idx2418" name="idx2418"></a></p>
|
|
<p>The DESCRIBE INPUT statement obtains information about the IN
|
|
and INOUT parameter markers of a prepared statement. For an explanation of
|
|
prepared statements, see <a href="rbafzmstpreph2.htm#preph2">PREPARE</a>.</p>
|
|
<a name="wq1456"></a>
|
|
<h3 id="wq1456"><a href="rbafzmst02.htm#ToC_1024">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™ or REXX.</p>
|
|
<a name="wq1457"></a>
|
|
<h3 id="wq1457"><a href="rbafzmst02.htm#ToC_1025">Authorization</a></h3>
|
|
<p>None required.</p>
|
|
<a name="wq1458"></a>
|
|
<h3 id="wq1458"><a href="rbafzmst02.htm#ToC_1026">Syntax</a></h3>
|
|
<a href="rbafzdescrinput.htm#synsdinput"><img src="c.gif" alt="Click to skip syntax diagram" /></a>
|
|
<pre class="cgraphic"><span><img src="c.gif" alt="Read syntax diagram" longdesc="rbafzmstsyn330.htm"
|
|
border="0" /></span><a href="#skipsyn-329"><img src="c.gif" alt="Skip visual syntax diagram"
|
|
border="0" /></a>>>-DESCRIBE INPUT--<span class="italic">statement-name</span>------------------------------->
|
|
|
|
.-SQL-. .-LOCAL--.
|
|
>--+-USING--+-----+--DESCRIPTOR--+--------+--<span class="italic">SQL-descriptor-name</span>-+-><
|
|
| '-GLOBAL-' |
|
|
'-INTO----<span class="italic">descriptor-name</span>-------------------------------------'
|
|
|
|
</pre>
|
|
<a name="skipsyn-329" id="skipsyn-329"></a>
|
|
<a name="synsdinput"></a>
|
|
<h3 id="synsdinput"><a href="rbafzmst02.htm#ToC_1027">Description</a></h3>
|
|
<dl class="parml">
|
|
<dt class="bold"><var class="pv">statement-name</var> </dt><a id="idx2419" name="idx2419"></a>
|
|
<dd>Identifies the prepared statement. When the DESCRIBE INPUT statement
|
|
is executed, the name must identify a prepared statement at the application server.
|
|
</dd>
|
|
<dt class="bold">USING <a id="idx2420" name="idx2420"></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="idx2421" name="idx2421"></a>
|
|
</dd>
|
|
</dl>
|
|
</dd>
|
|
<dt class="bold">INTO <var class="pv">descriptor-name</var> <a id="idx2422" name="idx2422"></a></dt>
|
|
<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 INPUT statement is executed, the following
|
|
variable in the SQLDA must be set.
|
|
<dl>
|
|
<dt class="bold">SQLN</dt><a id="idx2423" name="idx2423"></a><a id="idx2424" name="idx2424"></a>
|
|
<dd>Specifies the number of SQLVAR occurrences provided in the SQLDA. SQLN
|
|
must be set to a value greater than or equal to zero before the DESCRIBE INPUT
|
|
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>
|
|
<p>When the DESCRIBE INPUT 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="idx2425" name="idx2425"></a><a id="idx2426" name="idx2426"></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 parameter markers
|
|
described:</p>
|
|
<ul>
|
|
<li>If the SQLDA contains two SQLVAR entries for every input parameter,
|
|
the seventh byte is set to '2'. This technique is used in order to accommodate
|
|
LOB input parameters.</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 input parameter
|
|
markers.</p>
|
|
<p>The eighth byte is set to the space character.</p>
|
|
</dd>
|
|
<dt class="bold">SQLDABC</dt><a id="idx2427" name="idx2427"></a><a id="idx2428" name="idx2428"></a>
|
|
<dd>Length of the SQLDA in bytes.
|
|
</dd>
|
|
<dt class="bold">SQLD</dt><a id="idx2429" name="idx2429"></a><a id="idx2430" name="idx2430"></a>
|
|
<dd>The number of input parameter markers in the prepared statement.
|
|
</dd>
|
|
<dt class="bold">SQLVAR</dt><a id="idx2431" name="idx2431"></a><a id="idx2432" name="idx2432"></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 input parameter marker, the
|
|
second occurrence of SQLVAR contains a description of the second input parameter
|
|
marker, 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>
|
|
</dd>
|
|
</dl>
|
|
<a name="wq1459"></a>
|
|
<h3 id="wq1459"><a href="rbafzmst02.htm#ToC_1028">Notes</a></h3>
|
|
<p><span class="bold">Allocating the SQL descriptor:</span> Before
|
|
the DESCRIBE INPUT statement is executed, the SQL descriptor must be allocated
|
|
using the ALLOCATE DESCRIPTOR statement. The number of descriptor items allocated
|
|
must not be less than the number of input parameter markers or an error is
|
|
returned.</p>
|
|
<p><span class="bold">Allocating the SQLDA:</span> Before the DESCRIBE
|
|
INPUT statement is executed, the value of SQLN must be set to a value greater
|
|
than or equal to zero to indicate how many occurrences of SQLVAR are provided
|
|
in the SQLDA and enough storage must be allocated to contain SQLN occurrences.
|
|
To obtain the description of the input parameter markers in the prepared statement,
|
|
the number of occurrences of SQLVAR must not be less than the number of input
|
|
parameter markers. Furthermore, if the input parameter markers include LOBs,
|
|
the number of occurrences of SQLVAR should be two times the number of input
|
|
parameter markers. See <a href="rbafzmstfielddescsqlda.htm#howmany">Determining how many SQLVAR occurrences are needed</a> for more information.</p>
|
|
<p>If not enough occurrences are provided to return all sets of
|
|
occurrences, SQLN is set to the total number of occurrences necessary to return
|
|
all information. Otherwise, SQLN is set to the number of input parameter markers.</p>
|
|
<p>For a description of techniques that can be used to allocate the SQLDA,
|
|
see <a href="rbafzmstsqldda.htm#sqldda">Appendix D. SQLDA (SQL descriptor area)</a>.</p>
|
|
<a name="wq1460"></a>
|
|
<h3 id="wq1460"><a href="rbafzmst02.htm#ToC_1029">Examples</a></h3>
|
|
<p><span class="italic">Example 1:</span> Allocate a descriptor called 'NEWDA'
|
|
large enough to hold 20 item descriptor areas and use it on DESCRIBE INPUT. </p>
|
|
<pre class="xmp"> EXEC SQL <span class="bold">ALLOCATE DESCRIPTOR</span> 'NEWDA'
|
|
<span class="bold">WITH MAX</span> 20;
|
|
|
|
EXEC SQL <span class="bold">DESCRIBE INPUT</span> STMT1
|
|
<span class="bold">USING SQL DESCRIPTOR</span> 'NEWDA';</pre>
|
|
<p><span class="italic">Example 2:</span> Execute a DESCRIBE INPUT statement with
|
|
an SQLDA that has enough SQLVAR occurrences to describe any number of input
|
|
parameters a prepared statement might have. Assume that five parameter markers
|
|
at most will need to be described and that the input data does not contain
|
|
LOBs.</p>
|
|
<pre class="xmp"> /* STMT1_STR contains INSERT statement with VALUES clause */
|
|
char table_name[201];
|
|
EXEC SQL <span class="bold">PREPARE</span> STMT1_NAME
|
|
<span class="bold"> FROM</span> :STMT1_STR;
|
|
|
|
... /* code to set SQLN to 5 and to allocate the SQLDA */
|
|
EXEC SQL <span class="bold">DESCRIBE INPUT</span> STMT1_NAME <span class="bold">INTO</span> :SQLDA;
|
|
|
|
.
|
|
.
|
|
.</pre><p class="indatacontent">This example uses the first technique described in <a href="rbafzmstsqldda.htm#sqldda">Appendix D. SQLDA (SQL descriptor area)</a>.<a id="idx2433" name="idx2433"></a><a id="idx2434" name="idx2434"></a><a id="idx2435" name="idx2435"></a><a id="idx2436" name="idx2436"></a></p>
|
|
<hr /><br />
|
|
[ <a href="#Top_Of_Page">Top of Page</a> | <a href="rbafzmstdescr.htm">Previous Page</a> | <a href="rbafzmstdescrtb.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>
|