<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html>
<head profile="http://internetalchemy.org/2003/02/profile">
<link rel="foaf" type="application/rdf+xml" title="FOAF" href="http://www.openlinksw.com/dataspace/uda/about.rdf" />
<link rel="schema.dc" href="http://purl.org/dc/elements/1.1/" />
<meta name="dc.title" content="Function: dict_iter_next - Virtuoso Functions Guide" />
<meta name="dc.subject" content="Function: dict_iter_next - Virtuoso Functions Guide" />
<meta name="dc.creator" content="OpenLink Software Documentation Team ; " />
<meta name="dc.copyright" content="OpenLink Software, 1999 - 2009" />
<link rel="top" href="index.html" title="OpenLink Virtuoso Universal Server: Documentation" />
<link rel="search" href="/doc/adv_search.vspx" title="Search OpenLink Virtuoso Universal Server: Documentation" />
<link rel="parent" href="functions.html" title="Chapter Contents" />
<link rel="prev" href="appendixa.html" title="Appendix" />
<link rel="next" href="functions.html#.html" title="" />
<link rel="shortcut icon" href="../images/misc/favicon.ico" type="image/x-icon" />
<link rel="stylesheet" type="text/css" href="doc.css" />
<link rel="stylesheet" type="text/css" href="/doc/translation.css" />
<title>Function: dict_iter_next - Virtuoso Functions Guide</title>
<meta http-equiv="Content-Type" content="text/xhtml; charset=UTF-8" />
<meta name="author" content="OpenLink Software Documentation Team ; " />
<meta name="copyright" content="OpenLink Software, 1999 - 2009" />
<meta name="keywords" content="" />
<meta name="GENERATOR" content="OpenLink XSLT Team" />
</head>
<body>
<div id="header">
<a name="fn_dict_iter_next" />
<img src="../images/misc/logo.jpg" alt="" />
<h1>22. Virtuoso Functions Guide - dict_iter_next</h1>
</div>
<div id="navbartop">
<div>
<a class="link" href="functions.html">Chapter Contents</a> | <a class="link" href="fn_dict_inc_or_put.html" title="dict_inc_or_put">Prev</a> | <a class="link" href="fn_dict_iter_rewind.html" title="dict_iter_rewind">Next</a>
</div>
</div>
<div id="currenttoc">
<form method="post" action="/doc/adv_search.vspx">
<div class="search">Keyword Search: <br />
<input type="text" name="q" /> <input type="submit" name="go" value="Go" />
</div>
</form>
<div>
<a href="http://www.openlinksw.com/">www.openlinksw.com</a>
</div>
<div>
<a href="http://docs.openlinksw.com/">docs.openlinksw.com</a>
</div>
<br />
<div>
<a href="index.html">Book Home</a>
</div>
<br />
<div>
<a href="contents.html">Contents</a>
</div>
<div>
<a href="preface.html">Preface</a>
</div>
<br />
<div>
<a class="selected" href="functions.html">Virtuoso Functions Guide</a>
</div>
<br />
<div>
<a href="functions.html#admin">Administration</a>
</div>
<div>
<a href="functions.html#aggr">Aggregate Functions</a>
</div>
<div>
<a href="functions.html#array">Array Manipulation</a>
</div>
<div>
<a href="functions.html#bpel">BPEL APIs</a>
</div>
<div>
<a href="functions.html#backup">Backup</a>
</div>
<div>
<a href="functions.html#compression">Compression</a>
</div>
<div>
<a href="functions.html#cursors">Cursor</a>
</div>
<div>
<a href="functions.html#time">Date & Time Manipulation</a>
</div>
<div>
<a href="functions.html#debug">Debug</a>
</div>
<div>
<a class="selected" href="functions.html#dict">Dictionary Manipulation</a>
</div>
<div class="selected">
<div>
<a href="fn_dict_dec_or_remove.html">dict_dec_or_remove</a>
</div>
<div>
<a href="fn_dict_duplicate.html">dict_duplicate</a>
</div>
<div>
<a href="fn_dict_get.html">dict_get</a>
</div>
<div>
<a href="fn_dict_inc_or_put.html">dict_inc_or_put</a>
</div>
<div>
<a class="selected" href="fn_dict_iter_next.html">dict_iter_next</a>
</div>
<div>
<a href="fn_dict_iter_rewind.html">dict_iter_rewind</a>
</div>
<div>
<a href="fn_dict_list_keys.html">dict_list_keys</a>
</div>
<div>
<a href="fn_dict_new.html">dict_new</a>
</div>
<div>
<a href="fn_dict_put.html">dict_put</a>
</div>
<div>
<a href="fn_dict_remove.html">dict_remove</a>
</div>
<div>
<a href="fn_dict_size.html">dict_size</a>
</div>
<div>
<a href="fn_dict_to_vector.html">dict_to_vector</a>
</div>
</div>
<div>
<a href="functions.html#encoding">Encoding & Decoding</a>
</div>
<div>
<a href="functions.html#file">File Manipulation</a>
</div>
<div>
<a href="functions.html#ft">Free Text</a>
</div>
<div>
<a href="functions.html#hash">Hashing / Cryptographic</a>
</div>
<div>
<a href="functions.html#ldap">LDAP</a>
</div>
<div>
<a href="functions.html#localization">Locale</a>
</div>
<div>
<a href="functions.html#mail">Mail</a>
</div>
<div>
<a href="functions.html#misc">Miscellaneous</a>
</div>
<div>
<a href="functions.html#number">Number</a>
</div>
<div>
<a href="functions.html#phrz">Phrases</a>
</div>
<div>
<a href="functions.html#rdf">RDF data</a>
</div>
<div>
<a href="functions.html#rmt">Remote SQL Data Source</a>
</div>
<div>
<a href="functions.html#repl">Replication</a>
</div>
<div>
<a href="functions.html#soap">SOAP</a>
</div>
<div>
<a href="functions.html#sql">SQL</a>
</div>
<div>
<a href="functions.html#string">String</a>
</div>
<div>
<a href="functions.html#txn">Transaction</a>
</div>
<div>
<a href="functions.html#type">Type Mapping</a>
</div>
<div>
<a href="functions.html#uddi">UDDI</a>
</div>
<div>
<a href="functions.html#udt">User Defined Types & The CLR</a>
</div>
<div>
<a href="functions.html#vad">VAD</a>
</div>
<div>
<a href="functions.html#jvmpl">Virtuoso Java PL API</a>
</div>
<div>
<a href="functions.html#bif">Virtuoso Server Extension Interface (VSEI)</a>
</div>
<div>
<a href="functions.html#ws">Web & Internet</a>
</div>
<div>
<a href="functions.html#xml">XML</a>
</div>
<div>
<a href="functions.html#XPATH">XPATH & XQUERY</a>
</div>
<br />
<div>
<a href="functionidx.html">Functions Index</a>
</div>
<br />
</div>
<div id="text">
<h2>dict_iter_next</h2>
<div class="refpurpose">Fetches a pair of key and value from a dictionary iterator and moves the iterator to the next pair.</div>
<div class="funcsynopsis">
<span class="funcdef">
<span class="function">dict_iter_next</span>
</span>
(<span class="paramdef">inout <span class="parameter">dict</span> dictionary</span>,
<span class="paramdef">out <span class="parameter">ret_key</span> any</span>,
<span class="paramdef">out <span class="parameter">ret_value</span> any</span>);
</div>
<div class="refsect1">
<div class="refsect1title">Description</div>
<p>The function gets the dictionary iterator initialized earlier by <a href="fn_dict_iter_rewind.html">dict_iter_rewind</a>
and checks whether the iterator is still valid and not in conflict with any changes made by <a href="fn_dict_put.html">dict_put</a> or the like.
After that, if the iterator is in the position past the last item of the dictionary then zero is returned.
If the iterator points to some item then <span class="computeroutput">ret_key</span> and <span class="computeroutput">ret_value</span> parameters are set to the key and value of the current item,
the iterator is advanced to the next position (next item if present, otherwise past the end of the dictionary) and a nonzero integer is returned.
If <span class="computeroutput">ret_value</span> is a constant or an expression but not a plain variable then it is left unchanged but no error is signalled,
so if the caller procedure needs only values of keys from dictionary then any constant like zero can be passed as a third parameter.
Similarly, <span class="computeroutput">ret_key</span> is not necessarily a variable.
</p>
<p>Note that the values of <span class="computeroutput">ret_key</span> and <span class="computeroutput">ret_value</span> are left unchanged if the iterator points past the end of the dictionary.
They are not filled in with NULLs or something like that.
</p>
</div>
<div class="refsect1">
<div class="refsect1title">Parameters</div>
<div class="refsect2">
<span class="refsect2title">dict – </span>
Dictionary iterator
</div>
<div class="refsect2">
<span class="refsect2title">ret_key – </span>
The variable to be filled in with the key of the item. The parameter is ignored if it is not a plain variable.
</div>
<div class="refsect2">
<span class="refsect2title">ret_value – </span>
The variable to be filled in with the value (dependant part) of the item. The parameter is ignored if it is not a plain variable.
</div>
</div>
<div class="refsect1">
<div class="refsect1title">Return Types</div>
<p>The function returns a nonzero integer if the item is successfully fetched, zero otherwise</p>
</div>
<div class="refsect1title">Errors</div>
<p>This function can generate the following errors:</p>
Error CodeDescription
<a name="err22023" />
<span class="errorcode">22023</span>
<span class="errorname">SR630</span> Function dict_iter_next() tries to iterate a volatile dictionary changed after last <a href="fn_dict_iter_rewind.html">dict_iter_rewind</a>().
Not every change in the dictionary results in this error.
If the dict_iter_next() and <a href="fn_dict_put.html">dict_put</a>() (or similar function) are both called with same variable passed as dict parameter
then the function might adjust the iterator to match the changed state of the dictionary so it remains valid.
In addition, if <a href="fn_dict_put.html">dict_put</a>() changes only the value associated with some key but does not extend the dictionary with a new item
then it does not invalidate any iterators.
<p />
<div class="refsect1">
<div class="refsect1title">Example</div>
<a name="ex_dict_iter_next" />
<div class="example">
<div class="exampletitle">Simplest read throughout the dictionary.</div>
<p>The procedure creates a dictionary, puts couple of items into it and then print them to the server's console</p>
<div>
<pre class="screen">
create function dict_iterator_test ()
{
declare dict, dkey, dvalue any;
dict := dict_new (10);
dict_put (dict, 'a', 1); dict_put (dict, 'b', 2);
dict_iter_rewind (dict);
while (dict_iter_next (dict, dkey, dvalue))
dbg_obj_princ (' key is ' dkey, ', corresponding value is ', dvalue);
}
</pre>
</div>
</div>
</div>
<div class="refsect1">
<div class="refsect1title">See Also</div>
<p>
<a href="fn_dict_new.html">dict_new</a>
</p>
<p>
<a href="">dict_zap</a>
</p>
<p>
<a href="fn_dict_put.html">dict_put</a>
</p>
<p>
<a href="fn_dict_get.html">dict_get</a>
</p>
<p>
<a href="fn_dict_remove.html">dict_remove</a>
</p>
<p>
<a href="fn_dict_inc_or_put.html">dict_inc_or_put</a>
</p>
<p>
<a href="fn_dict_dec_or_remove.html">dict_dec_or_remove</a>
</p>
<p>
<a href="fn_dict_size.html">dict_size</a>
</p>
<p>
<a href="fn_dict_duplicate.html">dict_duplicate</a>
</p>
<p>
<a href="fn_dict_to_vector.html">dict_to_vector</a>
</p>
<p>
<a href="fn_dict_list_keys.html">dict_list_keys</a>
</p>
<p>
<a href="">dict_destructive_list_rnd_keys</a>
</p>
<p>
<a href="fn_dict_iter_rewind.html">dict_iter_rewind</a>
</p>
</div>
</div>
<div id="footer">
<div>Copyright© 1999 - 2009 OpenLink Software All rights reserved.</div>
<div id="validation">
<a href="http://validator.w3.org/check/referer">
<img src="http://www.w3.org/Icons/valid-xhtml10" alt="Valid XHTML 1.0!" height="31" width="88" />
</a>
<a href="http://jigsaw.w3.org/css-validator/">
<img src="http://jigsaw.w3.org/css-validator/images/vcss" alt="Valid CSS!" height="31" width="88" />
</a>
</div>
</div>
</body>
</html>
distrib
>
Fedora
>
14
>
x86_64
>
media
>
updates
>
by-pkgid
>
71d40963b505df4524269198e237b3e3
>
files
>
249
