214 lines
12 KiB
HTML
214 lines
12 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="SIGNAL statement, SIGNAL, SQL statements,
|
||
|
|
MESSAGE_TEXT, CONSTRAINT_CATALOG, CONSTRAINT_SCHEMA, CONSTRAINT_NAME,
|
||
|
|
CATALOG_NAME, SCHEMA_NAME, TABLE_NAME, COLUMN_NAME, CURSOR_NAME, CLASS_ORIGIN,
|
||
|
|
SUBCLASS_ORIGIN" />
|
||
|
|
<title>SIGNAL</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="signal"></a>
|
||
|
|
<h2 id="signal"><a href="rbafzmst02.htm#ToC_1369">SIGNAL</a></h2><a id="idx3239" name="idx3239"></a><a id="idx3240" name="idx3240"></a>
|
||
|
|
<p>The SIGNAL statement signals an error or warning condition. It causes an
|
||
|
|
error or warning to be returned with the specified SQLSTATE and optional <span class="italic">condition-information-items</span>.</p>
|
||
|
|
<a name="wq1818"></a>
|
||
|
|
<h3 id="wq1818"><a href="rbafzmst02.htm#ToC_1370">Invocation</a></h3>
|
||
|
|
<p>This statement can only be embedded in an application program. It is an
|
||
|
|
executable statement that cannot be dynamically prepared. It must not be specified
|
||
|
|
in REXX.</p>
|
||
|
|
<a name="wq1819"></a>
|
||
|
|
<h3 id="wq1819"><a href="rbafzmst02.htm#ToC_1371">Authorization</a></h3>
|
||
|
|
<p>None required.</p>
|
||
|
|
<a name="wq1820"></a>
|
||
|
|
<h3 id="wq1820"><a href="rbafzmst02.htm#ToC_1372">Syntax</a></h3>
|
||
|
|
<a href="rbafzmstsignal.htm#synsignal"><img src="c.gif" alt="Click to skip syntax diagram" /></a>
|
||
|
|
<p> </p>
|
||
|
|
<a name="wq1821"></a>
|
||
|
|
<div class="fignone" id="wq1821">
|
||
|
|
<pre class="cgraphic"><span><img src="c.gif" alt="Read syntax diagram" longdesc="rbafzmstsyn396.htm"
|
||
|
|
border="0" /></span><a href="#skipsyn-395"><img src="c.gif" alt="Skip visual syntax diagram"
|
||
|
|
border="0" /></a> .-VALUE-.
|
||
|
|
>>-SIGNAL-SQLSTATE--+-------+--+-<span class="italic">sqlstate-string-constant</span>-+----->
|
||
|
|
'-<span class="italic">sqlstate-string-variable</span>-'
|
||
|
|
|
||
|
|
>--+--------------------+--------------------------------------><
|
||
|
|
'-<span class="italic">signal-information</span>-'
|
||
|
|
|
||
|
|
signal-information:
|
||
|
|
|
||
|
|
.-,-----------------------------------------------------------.
|
||
|
|
V |
|
||
|
|
|--SET----+-MESSAGE_TEXT-------+-- = --+-<span><span class="italic">variable</span></span>-------------------+-+--|
|
||
|
|
+-CONSTRAINT_CATALOG-+ '-<span class="italic">diagnostic-string-constant</span>-'
|
||
|
|
+-CONSTRAINT_SCHEMA--+
|
||
|
|
+-CONSTRAINT_NAME----+
|
||
|
|
+-CATALOG_NAME-------+
|
||
|
|
+-SCHEMA_NAME--------+
|
||
|
|
+-TABLE_NAME---------+
|
||
|
|
+-COLUMN_NAME--------+
|
||
|
|
+-CURSOR_NAME--------+
|
||
|
|
+-CLASS_ORIGIN-------+
|
||
|
|
'-SUBCLASS_ORIGIN----'
|
||
|
|
|
||
|
|
</pre>
|
||
|
|
<a name="skipsyn-395" id="skipsyn-395"></a></div>
|
||
|
|
<a name="synsignal"></a>
|
||
|
|
<h3 id="synsignal"><a href="rbafzmst02.htm#ToC_1373">Description</a></h3>
|
||
|
|
<dl class="parml">
|
||
|
|
<dt class="bold">SQLSTATE VALUE</dt>
|
||
|
|
<dd>Specifies the SQLSTATE that will be signalled. The specified
|
||
|
|
value must not be null and must follow the rules for SQLSTATEs:
|
||
|
|
<ul>
|
||
|
|
<li>Each character must be from the set of digits ('0' through '9') or non-accented
|
||
|
|
upper case letters ('A' through 'Z').</li>
|
||
|
|
<li>The SQLSTATE class (first two characters) cannot be '00' since this represents
|
||
|
|
successful completion.</li></ul>
|
||
|
|
<p>If the SQLSTATE does not conform to these rules, an error is returned.</p>
|
||
|
|
<dl class="parml">
|
||
|
|
<dt class="bold"><span class="italic">sqlstate-string-constant</span></dt>
|
||
|
|
<dd>The <span class="italic">sqlstate-string-constant</span> must be a character
|
||
|
|
string constant with exactly 5 characters.
|
||
|
|
</dd>
|
||
|
|
<dt class="bold"><span class="italic">sqlstate-string-variable</span></dt>
|
||
|
|
<dd>The <span class="italic">sqlstate-string-variable</span> must be a character,
|
||
|
|
UTF-16 graphic, or UCS-2 graphic variable. The actual length of the contents
|
||
|
|
of the <var class="pv">variable</var> must be 5.
|
||
|
|
</dd>
|
||
|
|
</dl>
|
||
|
|
</dd>
|
||
|
|
<dt class="bold">SET</dt>
|
||
|
|
<dd>Introduces the assignment of values to <span class="italic">condition-information-items</span>. The <span class="italic">condition-information-item</span> values can be
|
||
|
|
accessed using the GET DIAGNOSTICS statement. The only <span class="italic">condition-information-item</span> that can be accessed in the SQLCA is MESSAGE_TEXT.
|
||
|
|
<dl class="parml">
|
||
|
|
<dt class="bold">MESSAGE_TEXT</dt><a id="idx3241" name="idx3241"></a>
|
||
|
|
<dd>Specifies a string that describes the error or warning.
|
||
|
|
<p>If an SQLCA
|
||
|
|
is used, </p>
|
||
|
|
<ul>
|
||
|
|
<li>the string is returned in the SQLERRMC field of the SQLCA</li>
|
||
|
|
<li>if the actual length of the string is longer than 70 bytes, it is truncated
|
||
|
|
without a warning.</li></ul>
|
||
|
|
</dd>
|
||
|
|
<dt class="bold">CONSTRAINT_CATALOG</dt><a id="idx3242" name="idx3242"></a>
|
||
|
|
<dd>Specifies a string that indicates the name of the database that contains
|
||
|
|
a constraint related to the signalled error or warning.
|
||
|
|
</dd>
|
||
|
|
<dt class="bold">CONSTRAINT_SCHEMA</dt><a id="idx3243" name="idx3243"></a>
|
||
|
|
<dd>Specifies a string that indicates the name of the schema that contains
|
||
|
|
a constraint related to the signalled error or warning.
|
||
|
|
</dd>
|
||
|
|
<dt class="bold">CONSTRAINT_NAME</dt><a id="idx3244" name="idx3244"></a>
|
||
|
|
<dd>Specifies a string that indicates the name of a constraint related to
|
||
|
|
the signalled error or warning.
|
||
|
|
</dd>
|
||
|
|
<dt class="bold">CATALOG_NAME</dt><a id="idx3245" name="idx3245"></a>
|
||
|
|
<dd>Specifies a string that indicates the name of the database that contains
|
||
|
|
a table or view related to the signalled error or warning.
|
||
|
|
</dd>
|
||
|
|
<dt class="bold">SCHEMA_NAME</dt><a id="idx3246" name="idx3246"></a>
|
||
|
|
<dd>Specifies a string that indicates the name of the schema that contains
|
||
|
|
a table or view related to the signalled error or warning.
|
||
|
|
</dd>
|
||
|
|
<dt class="bold">TABLE_NAME</dt><a id="idx3247" name="idx3247"></a>
|
||
|
|
<dd>Specifies a string that indicates the name of a table or view related
|
||
|
|
to the signalled error or warning.
|
||
|
|
</dd>
|
||
|
|
<dt class="bold">COLUMN_NAME</dt><a id="idx3248" name="idx3248"></a>
|
||
|
|
<dd>Specifies a string that indicates the name of a column in the table
|
||
|
|
or view related to the signalled error or warning.
|
||
|
|
</dd>
|
||
|
|
<dt class="bold">CURSOR_NAME</dt><a id="idx3249" name="idx3249"></a>
|
||
|
|
<dd>Specifies a string that indicates the name of a cursor related to the
|
||
|
|
signalled error or warning.
|
||
|
|
</dd>
|
||
|
|
<dt class="bold">CLASS_ORIGIN</dt><a id="idx3250" name="idx3250"></a>
|
||
|
|
<dd>Specifies a string that indicates the origin of the SQLSTATE class related
|
||
|
|
to the signalled error or warning.
|
||
|
|
</dd>
|
||
|
|
<dt class="bold">SUBCLASS_ORIGIN</dt><a id="idx3251" name="idx3251"></a>
|
||
|
|
<dd>Specifies a string that indicates the origin of the SQLSTATE subclass
|
||
|
|
related to the signalled error or warning.
|
||
|
|
</dd>
|
||
|
|
<dt class="bold"><span class="italic">variable</span></dt>
|
||
|
|
<dd>Identifies a variable that must be declared in accordance with the rules
|
||
|
|
for declaring variables (see <a href="rbafzmstch2refvar.htm#ch2host">References to host variables</a>). The variable contains
|
||
|
|
the value to be assigned to the <span class="italic">condition-information-item</span>. The variable must be defined as CHAR, VARCHAR, UTF-16 or UCS-2 GRAPHIC,
|
||
|
|
or UTF-16 or UCS-2 VARGRAPHIC variable.
|
||
|
|
</dd>
|
||
|
|
<dt class="bold"><span class="italic">diagnostic-string-constant</span></dt>
|
||
|
|
<dd>Specifies a character string constant that contains the value to be
|
||
|
|
assigned to the <span class="italic">condition-information-item</span>.
|
||
|
|
</dd>
|
||
|
|
</dl>
|
||
|
|
</dd>
|
||
|
|
</dl>
|
||
|
|
<a name="wq1822"></a>
|
||
|
|
<h3 id="wq1822"><a href="rbafzmst02.htm#ToC_1374">Notes</a></h3>
|
||
|
|
<p><span class="bold">SQLSTATE values:</span> Any valid SQLSTATE value can be
|
||
|
|
used in the SIGNAL statement. However, it is recommended that programmers
|
||
|
|
define new SQLSTATEs based on ranges reserved for applications. This prevents
|
||
|
|
the unintentional use of an SQLSTATE value that might be defined by the database
|
||
|
|
manager in a future release.</p>
|
||
|
|
<p>SQLSTATE values are comprised of a two-character class code value, followed
|
||
|
|
by a three-character subclass code value. Class code values represent classes
|
||
|
|
of successful and unsuccessful execution conditions.</p>
|
||
|
|
<ul>
|
||
|
|
<li>SQLSTATE classes that begin with the characters '7' through '9' or 'I'
|
||
|
|
through 'Z' may be defined. Within these classes, any subclass may be defined.</li>
|
||
|
|
<li>SQLSTATE classes that begin with the characters '0' through '6' or 'A'
|
||
|
|
through 'H' are reserved for the database manager. Within these classes,
|
||
|
|
subclasses that begin with the characters '0' through 'H' are reserved for
|
||
|
|
the database manager. Subclasses that begin with the characters 'I' through
|
||
|
|
'Z' may be defined.</li></ul>
|
||
|
|
<p>For more information about SQLSTATEs, see the<a href="../rzala/rzalakickoff.htm"> SQL Messages
|
||
|
|
and Codes</a> book in the iSeries Information Center.</p>
|
||
|
|
<p><span class="bold">Assignment:</span> When the SIGNAL statement is executed,
|
||
|
|
the value of each of the specified <span class="italic">string-constants</span> and <span class="italic">variables</span> is assigned (using storage assignment
|
||
|
|
rules) to the corresponding <span class="italic">condition-information-item</span>. For details on the assignment rules, see <a href="rbafzmstch2bas.htm#ch2bas">Assignments and comparisons</a>. For
|
||
|
|
details on the maximum length of specific <span class="italic">condition-information-items</span>, see <a href="rbafzmstgetdiag.htm#getdiag">GET DIAGNOSTICS</a>.</p>
|
||
|
|
<p><span class="bold">Processing a SIGNAL statement:</span> When a SIGNAL statement
|
||
|
|
is issued, the SQLCODE is based on the SQLSTATE value as follows:</p>
|
||
|
|
<ul>
|
||
|
|
<li>If the specified SQLSTATE class is either '01' or '02', a warning or not
|
||
|
|
found is signalled and the SQLCODE is set to +438.</li>
|
||
|
|
<li>Otherwise, an exception is signalled and the SQLCODE is set to –438.</li></ul>
|
||
|
|
<a name="wq1823"></a>
|
||
|
|
<h3 id="wq1823"><a href="rbafzmst02.htm#ToC_1375">Examples</a></h3>
|
||
|
|
<p><span class="italic">Example 1:</span> Signal SQLSTATE '75002' with a descriptive
|
||
|
|
message text. </p>
|
||
|
|
<pre class="xmp"> EXEC SQL <span class="bold">SIGNAL SQLSTATE</span> '75002'
|
||
|
|
<span class="bold">SET MESSAGE_TEXT =</span> 'Customer number is not known';</pre>
|
||
|
|
<p><span class="italic">Example 2:</span> Signal SQLSTATE '75002' with a descriptive
|
||
|
|
message text and associate a specific table with the error. </p>
|
||
|
|
<pre class="xmp"> EXEC SQL <span class="bold">SIGNAL SQLSTATE</span> '75002'
|
||
|
|
<span class="bold">SET MESSAGE_TEXT =</span> 'Customer number is not known',
|
||
|
|
<span class="bold"> SCHEMA_NAME =</span> 'CORPDATA',
|
||
|
|
<span class="bold"> TABLE_NAME =</span> 'CUSTOMER';</pre>
|
||
|
|
<hr /><br />
|
||
|
|
[ <a href="#Top_Of_Page">Top of Page</a> | <a href="rbafzmstsetinto.htm">Previous Page</a> | <a href="rbafzmstupdt.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>
|