vpruthi/doc-exports
1
0
Fork 0
forked from docs/doc-exports
Code Pull Requests Activity
doc-exports/docs/dws/dev/dws_06_0188.html
Lu, Huayi e6fa411af0 DWS DEV 830.201 version 
Reviewed-by: Pruthi, Vineet <vineet.pruthi@t-systems.com>
Co-authored-by: Lu, Huayi <luhuayi@huawei.com>
Co-committed-by: Lu, Huayi <luhuayi@huawei.com>
2024-05-16 07:24:04 +00:00

76 lines
14 KiB
HTML
Raw Blame History

<a name="EN-US_TOPIC_0000001188588964"></a><a name="EN-US_TOPIC_0000001188588964"></a>
<h1 class="topictitle1">CURSOR</h1>
<div id="body8662426"><div class="section" id="EN-US_TOPIC_0000001188588964__s93eb61ce9b1b439784e20f167bf1a57d"><h4 class="sectiontitle">Function</h4><p id="EN-US_TOPIC_0000001188588964__a7d87db8cb7bd4f1ebdcc81446a305385">CURSOR defines a cursor. This command retrieves few rows of data in a query.</p>
<p id="EN-US_TOPIC_0000001188588964__a27e18591045748b8b82762655178a303">To process SQL statements, the stored procedure process assigns a memory segment to store context association. Cursors are handles or pointers to context regions. With cursors, stored procedures can control alterations in context regions.</p>
</div>
<div class="section" id="EN-US_TOPIC_0000001188588964__s9496bccd0ae04844b17f2b2fbe50e1f0"><h4 class="sectiontitle">Precautions</h4><ul id="EN-US_TOPIC_0000001188588964__ul9971164772915"><li id="EN-US_TOPIC_0000001188588964__li17971114716295"><strong id="EN-US_TOPIC_0000001188588964__en-us_topic_0058965644_b24134109171832">CURSOR</strong> is used only in transaction blocks.</li><li id="EN-US_TOPIC_0000001188588964__li2252132319303">Generally, <strong id="EN-US_TOPIC_0000001188588964__b12932143115711">CURSOR</strong> and <strong id="EN-US_TOPIC_0000001188588964__b293214355717">SELECT</strong> both have text returns. Since data is stored in binary format in the system, the system needs to convert the data from the binary format to the text format. If data is returned in text format, the client-end application needs to convert the data back to a binary format for processing. <strong id="EN-US_TOPIC_0000001188588964__b141514315815">FETCH</strong> implements conversion between binary data and text data.</li><li id="EN-US_TOPIC_0000001188588964__li7773508297">Use a binary cursor as needed, since a text cursor occupies larger storage space than a binary cursor. A binary cursor returns internal binary data, which is easier to operate. To return data in text format, it is advisable to retrieve data in text format, therefore reducing workload at the client end. For example, the value 1 in an integer column of a query is returned as a character string 1 if a default cursor is used, but is returned as a 4-byte binary value (big-endian) if a binary cursor is used.</li></ul>
</div>
<div class="section" id="EN-US_TOPIC_0000001188588964__s967bec7d7e7648deb0db68eccc27d2e4"><h4 class="sectiontitle">Syntax</h4><div class="codecoloring" codetype="Sql" id="EN-US_TOPIC_0000001188588964__sa77da8d338974af49daf706fc851cc81"><div class="highlight"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span class="normal">1</span>
<span class="normal">2</span>
<span class="normal">3</span></pre></div></td><td class="code"><div><pre><span></span><span class="k">CURSOR</span><span class="w"> </span><span class="k">cursor_name</span>
<span class="w"> </span><span class="p">[</span><span class="w"> </span><span class="nb">BINARY</span><span class="w"> </span><span class="p">]</span><span class="w"> </span><span class="p">[</span><span class="w"> </span><span class="k">NO</span><span class="w"> </span><span class="k">SCROLL</span><span class="w"> </span><span class="p">]</span><span class="w"> </span><span class="p">[</span><span class="w"> </span><span class="err">{</span><span class="w"> </span><span class="k">WITH</span><span class="w"> </span><span class="o">|</span><span class="w"> </span><span class="k">WITHOUT</span><span class="w"> </span><span class="err">}</span><span class="w"> </span><span class="k">HOLD</span><span class="w"> </span><span class="p">]</span>
<span class="w"> </span><span class="k">FOR</span><span class="w"> </span><span class="n">query</span><span class="w"> </span><span class="p">;</span>
</pre></div></td></tr></table></div>
</div>
</div>
<div class="section" id="EN-US_TOPIC_0000001188588964__se45abbdc0fad4dfe8f55783168245ed3"><h4 class="sectiontitle">Parameter Description</h4><ul id="EN-US_TOPIC_0000001188588964__u8938a5f81d304af89d920794d34f085c"><li id="EN-US_TOPIC_0000001188588964__l171094acc21142e59b03220b52d4a40a"><strong id="EN-US_TOPIC_0000001188588964__a088145cd5aab480da1dd06b04060dd0b">cursor_name</strong><p id="EN-US_TOPIC_0000001188588964__ac88e0e4917554a3eb74cf02da5c3677c">Specifies the name of a cursor to be created.</p>
<p id="EN-US_TOPIC_0000001188588964__a682ce8e60a2b4fca838c3e8b519bde1a">Value range: Its value must comply with the database naming convention.</p>
</li><li id="EN-US_TOPIC_0000001188588964__lee767812ed87457c9bf67d793e9a6fd0"><strong id="EN-US_TOPIC_0000001188588964__a1d54c3647e3044c78eac93f8f25db1ef">BINARY</strong><p id="EN-US_TOPIC_0000001188588964__a9409de239b52474f9049f8be79a2250b">Specifies that data retrieved by the cursor will be returned in binary format, not in text format.</p>
</li><li id="EN-US_TOPIC_0000001188588964__l77be8068a9714db095e9d8307b57f2a6"><strong id="EN-US_TOPIC_0000001188588964__ac8ed48a1bf194b86bf7fbce0e000763e">NO SCROLL</strong><p id="EN-US_TOPIC_0000001188588964__aa2c4efbcc4b748b282177ed20d8f1be6">Specifies the mode of data retrieval by the cursor.</p>
<ul id="EN-US_TOPIC_0000001188588964__ucc62a538be8148d3a7252607861a1960"><li id="EN-US_TOPIC_0000001188588964__l76ece1e6aa1a4ce3b60111f966a40936">NO SCROLL: If <strong id="EN-US_TOPIC_0000001188588964__b143200265289">NO SCROLL</strong> is specified, backward fetches will be rejected.</li><li id="EN-US_TOPIC_0000001188588964__l768cbcf7289d4906a57af7a1dd0e19ab">Not stated: The system automatically determines whether the cursor can be used for backward fetches based on the execution plan.</li></ul>
</li><li id="EN-US_TOPIC_0000001188588964__lae0f37dcf2f2494d910eb3aeb8467ab7"><strong id="EN-US_TOPIC_0000001188588964__a51bc7f36590b496f8a6b1b32bd776d56">WITH HOLD | WITHOUT HOLD</strong><p id="EN-US_TOPIC_0000001188588964__a3bde1da836074727b3ae6cc8b700450a">Specifies whether the cursor can still be used after the cursor creation event. </p>
<ul id="EN-US_TOPIC_0000001188588964__u5ac37ad7825c4bf6817dfc0a034f45db"><li id="EN-US_TOPIC_0000001188588964__le6affee6f07542568c35ee356f1f14b2"><strong id="EN-US_TOPIC_0000001188588964__b842352706191710">WITH HOLD</strong> indicates that the cursor can still be used.</li><li id="EN-US_TOPIC_0000001188588964__l3580a5266b854424a6682fbdac7fcbe8"><strong id="EN-US_TOPIC_0000001188588964__b842352706191734">WITHOUT HOLD</strong> indicates that the cursor cannot be used. </li><li id="EN-US_TOPIC_0000001188588964__l5db2c262d1d54ef1b86be66af082758a">If neither <strong id="EN-US_TOPIC_0000001188588964__b842352706191811">WITH HOLD</strong> nor <strong id="EN-US_TOPIC_0000001188588964__b842352706191824">WITHOUT HOLD</strong> is specified, the default value is <strong id="EN-US_TOPIC_0000001188588964__b842352706191854">WITHOUT HOLD</strong>.</li></ul>
</li><li id="EN-US_TOPIC_0000001188588964__l9eacbcb873c34093828c8b5239cd2d31"><strong id="EN-US_TOPIC_0000001188588964__a0900c27d6eba48819f79b9079d511555">query</strong><p id="EN-US_TOPIC_0000001188588964__aebeb3944853a418997b3a173e6a743b1">The <strong id="EN-US_TOPIC_0000001188588964__b123261426142810">SELECT</strong> or <strong id="EN-US_TOPIC_0000001188588964__b1932602612285">VALUES</strong> clause specifies the row to return the cursor value.</p>
<p id="EN-US_TOPIC_0000001188588964__a53726757d23349c886cf3427a03268fa">Value range: <strong id="EN-US_TOPIC_0000001188588964__b40274629173148">SELECT</strong> or <strong id="EN-US_TOPIC_0000001188588964__b41019479173148">VALUES</strong> clause</p>
</li></ul>
</div>
<div class="section" id="EN-US_TOPIC_0000001188588964__s5d3f4cbf2aa94b6ca954fc48310d38f0"><h4 class="sectiontitle">Examples</h4><p id="EN-US_TOPIC_0000001188588964__p16180195095511">Start a transaction:</p>
<div class="codecoloring" codetype="Sql" id="EN-US_TOPIC_0000001188588964__screen201801850185510"><div class="highlight"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span class="normal">1</span></pre></div></td><td class="code"><div><pre><span></span><span class="k">START</span><span class="w"> </span><span class="k">TRANSACTION</span><span class="p">;</span>
</pre></div></td></tr></table></div>
</div>
<p id="EN-US_TOPIC_0000001188588964__p539211618379">Create a cursor named <strong id="EN-US_TOPIC_0000001188588964__b6343219195017">cursor1</strong>:</p>
<div class="codecoloring" codetype="Sql" id="EN-US_TOPIC_0000001188588964__screen586172523715"><div class="highlight"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span class="normal">1</span></pre></div></td><td class="code"><div><pre><span></span><span class="k">CURSOR</span><span class="w"> </span><span class="n">cursor1</span><span class="w"> </span><span class="k">FOR</span><span class="w"> </span><span class="k">SELECT</span><span class="w"> </span><span class="o">*</span><span class="w"> </span><span class="k">FROM</span><span class="w"> </span><span class="n">tpcds</span><span class="p">.</span><span class="n">customer_address</span><span class="w"> </span><span class="k">ORDER</span><span class="w"> </span><span class="k">BY</span><span class="w"> </span><span class="mi">1</span><span class="p">;</span>
</pre></div></td></tr></table></div>
</div>
<p id="EN-US_TOPIC_0000001188588964__p639231643715">create a cursor named <strong id="EN-US_TOPIC_0000001188588964__b14892144510502">cursor2</strong>:</p>
<div class="codecoloring" codetype="Sql" id="EN-US_TOPIC_0000001188588964__screen15229183118376"><div class="highlight"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span class="normal">1</span></pre></div></td><td class="code"><div><pre><span></span><span class="k">CURSOR</span><span class="w"> </span><span class="n">cursor2</span><span class="w"> </span><span class="k">FOR</span><span class="w"> </span><span class="k">VALUES</span><span class="p">(</span><span class="mi">1</span><span class="p">,</span><span class="mi">2</span><span class="p">),(</span><span class="mi">0</span><span class="p">,</span><span class="mi">3</span><span class="p">)</span><span class="w"> </span><span class="k">ORDER</span><span class="w"> </span><span class="k">BY</span><span class="w"> </span><span class="mi">1</span><span class="p">;</span>
</pre></div></td></tr></table></div>
</div>
<p id="EN-US_TOPIC_0000001188588964__p19383184720134">An example of using the <strong id="EN-US_TOPIC_0000001188588964__b2098162317573">WITH HOLD</strong> cursor is as follows:</p>
<ol id="EN-US_TOPIC_0000001188588964__ol9674194310299"><li id="EN-US_TOPIC_0000001188588964__li8649134942910">Set up a WITH HOLD cursor.<div class="codecoloring" codetype="Sql" id="EN-US_TOPIC_0000001188588964__screen16511337183715"><div class="highlight"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span class="normal">1</span></pre></div></td><td class="code"><div><pre><span></span><span class="k">DECLARE</span><span class="w"> </span><span class="n">cursor3</span><span class="w"> </span><span class="k">CURSOR</span><span class="w"> </span><span class="k">WITH</span><span class="w"> </span><span class="k">HOLD</span><span class="w"> </span><span class="k">FOR</span><span class="w"> </span><span class="k">SELECT</span><span class="w"> </span><span class="o">*</span><span class="w"> </span><span class="k">FROM</span><span class="w"> </span><span class="n">tpcds</span><span class="p">.</span><span class="n">customer_address</span><span class="w"> </span><span class="k">ORDER</span><span class="w"> </span><span class="k">BY</span><span class="w"> </span><span class="mi">1</span><span class="p">;</span>
</pre></div></td></tr></table></div>
</div>
</li><li id="EN-US_TOPIC_0000001188588964__li2620121273010">Fetch the first two rows from cursor3.<div class="codecoloring" codetype="Sql" id="EN-US_TOPIC_0000001188588964__screen467112661511"><div class="highlight"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span class="normal">1</span></pre></div></td><td class="code"><div><pre><span></span><span class="k">FETCH</span><span class="w"> </span><span class="k">FORWARD</span><span class="w"> </span><span class="mi">2</span><span class="w"> </span><span class="k">FROM</span><span class="w"> </span><span class="n">cursor3</span><span class="p">;</span>
</pre></div></td></tr></table></div>
</div>
</li><li id="EN-US_TOPIC_0000001188588964__li154015223303">End the transaction.<div class="codecoloring" codetype="Sql" id="EN-US_TOPIC_0000001188588964__screen3399174191515"><div class="highlight"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span class="normal">1</span></pre></div></td><td class="code"><div><pre><span></span><span class="k">END</span><span class="p">;</span>
</pre></div></td></tr></table></div>
</div>
</li><li id="EN-US_TOPIC_0000001188588964__li14937267306">Fetch the next row from cursor3.<div class="codecoloring" codetype="Sql" id="EN-US_TOPIC_0000001188588964__screen11544058161"><div class="highlight"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span class="normal">1</span></pre></div></td><td class="code"><div><pre><span></span><span class="k">FETCH</span><span class="w"> </span><span class="k">FORWARD</span><span class="w"> </span><span class="mi">1</span><span class="w"> </span><span class="k">FROM</span><span class="w"> </span><span class="n">cursor3</span><span class="p">;</span>
</pre></div></td></tr></table></div>
</div>
</li><li id="EN-US_TOPIC_0000001188588964__li1189143213306">Close a cursor.<div class="codecoloring" codetype="Sql" id="EN-US_TOPIC_0000001188588964__screen1640841915160"><div class="highlight"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span class="normal">1</span></pre></div></td><td class="code"><div><pre><span></span><span class="k">CLOSE</span><span class="w"> </span><span class="n">cursor3</span><span class="p">;</span>
</pre></div></td></tr></table></div>
</div>
</li></ol>
</div>
<div class="section" id="EN-US_TOPIC_0000001188588964__s921fcf4824864fc6ac25b4cb01495d29"><h4 class="sectiontitle">Helpful Links</h4><p id="EN-US_TOPIC_0000001188588964__aa3f97a0960e74cee83d32e59e7572d2e"><a href="dws_06_0216.html">FETCH</a></p>
</div>
</div>
<div>
<div class="familylinks">
<div class="parentlink"><strong>Parent topic:</strong> <a href="dws_06_0118.html">DDL Syntax</a></div>
</div>
</div>
View Git Blame Copy Permalink