257 lines
16 KiB
HTML
257 lines
16 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, SQL-control-statement,
|
||
|
|
SQL statements, CLASS_ORIGIN, SUBCLASS_ORIGIN" />
|
||
|
|
<title>SIGNAL statement</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="signalstmt"></a>
|
||
|
|
<h2 id="signalstmt"><a href="rbafzmst02.htm#ToC_1476">SIGNAL statement</a></h2><a id="idx3370" name="idx3370"></a><a id="idx3371" name="idx3371"></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>. The syntax of SIGNAL in an
|
||
|
|
SQL function, SQL procedure, or SQL trigger is a similar to what is supported
|
||
|
|
as a SIGNAL statement in other contexts. See <a href="rbafzmstsignal.htm#signal">SIGNAL</a> for details.</p>
|
||
|
|
<a name="wq1901"></a>
|
||
|
|
<h3 id="wq1901"><a href="rbafzmst02.htm#ToC_1477">Syntax</a></h3>
|
||
|
|
<a href="rbafzmstsignalstmt.htm#syncsignal"><img src="c.gif" alt="Click to skip syntax diagram" /></a>
|
||
|
|
<pre class="cgraphic"><span><img src="c.gif" alt="Read syntax diagram" longdesc="rbafzmstsyn424.htm"
|
||
|
|
border="0" /></span><a href="#skipsyn-423"><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">label:</span>-' | '-<span class="italic">sqlstate-string-variable</span>-' |
|
||
|
|
'-<span class="italic">condition-name</span>------------------------------------'
|
||
|
|
|
||
|
|
>--+--------------------+--------------------------------------><
|
||
|
|
'-<span class="italic">signal-information</span>-'
|
||
|
|
|
||
|
|
signal-information:
|
||
|
|
|
||
|
|
.-,-----------------------------------------------------------.
|
||
|
|
V |
|
||
|
|
|--+-SET----+-MESSAGE_TEXT-------+-- = --+-<span class="italic">SQL-variable-name</span>----------+-+-+--|
|
||
|
|
| +-CONSTRAINT_CATALOG-+ +-<span class="italic">SQL-parameter-name</span>---------+ |
|
||
|
|
| +-CONSTRAINT_SCHEMA--+ '-<span class="italic">diagnostic-string-constant</span>-' |
|
||
|
|
| +-CONSTRAINT_NAME----+ |
|
||
|
|
| +-CATALOG_NAME-------+ |
|
||
|
|
| +-SCHEMA_NAME--------+ |
|
||
|
|
| +-TABLE_NAME---------+ |
|
||
|
|
| +-COLUMN_NAME--------+ |
|
||
|
|
| +-CURSOR_NAME--------+ |
|
||
|
|
| +-CLASS_ORIGIN-------+ |
|
||
|
|
| '-SUBCLASS_ORIGIN----' |
|
||
|
|
'-(--<span class="italic">diagnostic-string-constant</span>--)-------------------------------------'
|
||
|
|
|
||
|
|
</pre>
|
||
|
|
<a name="skipsyn-423" id="skipsyn-423"></a>
|
||
|
|
<a name="syncsignal"></a>
|
||
|
|
<h3 id="syncsignal"><a href="rbafzmst02.htm#ToC_1478">Description</a></h3>
|
||
|
|
<dl class="parml">
|
||
|
|
<dt class="bold"><span class="italic">label</span></dt>
|
||
|
|
<dd>Specifies the label for the SIGNAL statement. The label name
|
||
|
|
cannot be the same as another label within the same scope. For more information,
|
||
|
|
see <a href="rbafzmstsqlprocstmt.htm#psscope">Labels</a>.
|
||
|
|
</dd>
|
||
|
|
<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"><span class="italic">condition-name</span></dt>
|
||
|
|
<dd>Specifies the name of the condition that will be signalled. The <span class="italic">condition-name</span> must be declared within the <span class="italic">compound-statement</span>.
|
||
|
|
</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>
|
||
|
|
<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>
|
||
|
|
<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>
|
||
|
|
<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>
|
||
|
|
<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>
|
||
|
|
<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>
|
||
|
|
<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>
|
||
|
|
<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>
|
||
|
|
<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>
|
||
|
|
<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="idx3372" name="idx3372"></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="idx3373" name="idx3373"></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">SQL-variable-name</span></dt>
|
||
|
|
<dd>Identifies an SQL variable declared within the <span class="italic">compound-statement</span>, that contains the value to be assigned to the <span class="italic">condition-information-item</span>. The SQL 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">SQL-parameter-name</span></dt>
|
||
|
|
<dd>Identifies an SQL parameter declared within the <span class="italic">compound-statement</span>, that contains the value to be assigned to the <span class="italic">condition-information-item</span>. The SQL parameter 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>
|
||
|
|
<dt class="bold"><span class="italic">( diagnostic-string-constant )</span></dt>
|
||
|
|
<dd>Specifies a character string constant that contains the message text.
|
||
|
|
Within the triggered action of a CREATE TRIGGER statement, the message text
|
||
|
|
can only be specified using this syntax:
|
||
|
|
<pre class="xmp"> SIGNAL SQLSTATE <var class="pv">sqlstate-string-constant</var> (<var class="pv">diagnostic-string-constant</var>);</pre> To conform with the ANS
|
||
|
|
and ISO standards, this form should not be used. It is provided for compatibility
|
||
|
|
with other products.
|
||
|
|
</dd>
|
||
|
|
</dl>
|
||
|
|
<a name="wq1902"></a>
|
||
|
|
<h3 id="wq1902"><a href="rbafzmst02.htm#ToC_1479">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>, <span class="italic">SQL-parameter-names</span>, and <span class="italic">SQL-variable-names</span> is assigned (using storage assignment) 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 returned in the SQLCA 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>
|
||
|
|
<p>If the SQLSTATE or condition indicates that an exception (SQLSTATE class
|
||
|
|
other than '01' or '02') is signalled, </p>
|
||
|
|
<ul>
|
||
|
|
<li>If a handler exists in the same compound statement as the SIGNAL statement,
|
||
|
|
and the compound statement contains a handler for SQLEXCEPTION or the specified
|
||
|
|
SQLSTATE or condition; the exception is handled and control is transferred
|
||
|
|
to that handler.</li>
|
||
|
|
<li>If the <span class="italic">compound-statement</span> is nested
|
||
|
|
and an outer level <span class="italic">compound-statement</span> has a handler
|
||
|
|
for SQLEXCEPTION or the specified SQLSTATE or condition; the exception is
|
||
|
|
handled and control is transferred to that handler.</li>
|
||
|
|
<li>Otherwise, the exception is not handled and control is immediately returned
|
||
|
|
to the end of the compound statement.</li></ul>
|
||
|
|
<p>If the SQLSTATE or condition indicates that a warning (SQLSTATE class '01')
|
||
|
|
or not found (SQLSTATE class '02') is signalled, </p>
|
||
|
|
<ul>
|
||
|
|
<li>If a handler exists in the same compound statement as the SIGNAL statement,
|
||
|
|
and the compound statement contains a handler for SQLWARNING (if the SQLSTATE
|
||
|
|
class is '01'), NOT FOUND (if the SQLSTATE class is '02'), or the specified
|
||
|
|
SQLSTATE or condition; the warning or not found condition is handled and control
|
||
|
|
is transferred to that handler.</li>
|
||
|
|
<li>If the <span class="italic">compound-statement</span> is nested and an outer
|
||
|
|
level compound statement contains a handler for SQLWARNING (if the SQLSTATE
|
||
|
|
class is '01'), NOT FOUND (if the SQLSTATE class is '02'), or the specified
|
||
|
|
SQLSTATE or condition; the warning or not found condition is handled and the
|
||
|
|
exception is handled and control is returned to that handler.</li>
|
||
|
|
<li>Otherwise, the warning is not handled and processing continues with the
|
||
|
|
next statement.</li></ul>
|
||
|
|
<a name="wq1903"></a>
|
||
|
|
<h3 id="wq1903"><a href="rbafzmst02.htm#ToC_1480">Example</a></h3>
|
||
|
|
<p>An SQL procedure for an order system that signals an application error
|
||
|
|
when a customer number is not known to the application. The ORDERS table includes
|
||
|
|
a foreign key to the CUSTOMER table, requiring that the CUSTNO exist before
|
||
|
|
an order can be inserted. </p>
|
||
|
|
<pre class="xmp"> <span class="bold">CREATE PROCEDURE</span> SUBMIT_ORDER
|
||
|
|
(<span class="bold">IN</span> ONUM <span class="bold">INTEGER</span>, <span class="bold">IN</span> CNUM <span class="bold">INTEGER</span>,
|
||
|
|
<span class="bold">IN</span> PNUM <span class="bold">INTEGER</span>, <span class="bold">IN</span> QNUM <span class="bold">INTEGER</span>)
|
||
|
|
<span class="bold">LANGUAGE SQL
|
||
|
|
MODIFIES SQL DATA
|
||
|
|
BEGIN</span>
|
||
|
|
<span class="bold">DECLARE EXIT HANDLER FOR SQLSTATE VALUE</span> '23503'
|
||
|
|
<span class="bold">SIGNAL SQLSTATE</span> '75002'
|
||
|
|
<span class="bold">SET MESSAGE_TEXT =</span> 'Customer number is not known';
|
||
|
|
<span class="bold">INSERT INTO</span> ORDERS (ORDERNO, CUSTNO, PARTNO, QUANTITY)
|
||
|
|
<span class="bold">VALUES</span> (ONUM, CNUM, PNUM, QNUM);
|
||
|
|
<span class="bold">END</span></pre>
|
||
|
|
<hr /><br />
|
||
|
|
[ <a href="#Top_Of_Page">Top of Page</a> | <a href="rbafzmstreturnstmt.htm">Previous Page</a> | <a href="rbafzmstwhilestmt.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>
|