www.openlinksw.com
docs.openlinksw.com

Book Home

Contents
Preface

Virtuoso Functions Guide

Administration
Aggregate Functions
Array Manipulation
BPEL APIs
Backup
Compression
Cursor
Date & Time Manipulation
Debug
Dictionary Manipulation
dict_dec_or_remove
dict_duplicate
dict_get
dict_inc_or_put
dict_iter_next
dict_iter_rewind
dict_list_keys
dict_new
dict_put
dict_remove
dict_size
dict_to_vector
Encoding & Decoding
File Manipulation
Free Text
Hashing / Cryptographic
LDAP
Locale
Mail
Miscellaneous
Number
Phrases
RDF data
Remote SQL Data Source
Replication
SOAP
SQL
String
Transaction
Type Mapping
UDDI
User Defined Types & The CLR
Virtuoso Java PL API
Virtuoso Server Extension Interface (VSEI)
Web & Internet
XML
XPATH & XQUERY

Functions Index

dict_iter_next

Fetches a pair of key and value from a dictionary iterator and moves the iterator to the next pair.
dict_iter_next (inout dict dictionary, out ret_key any, out ret_value any);
Description

The function gets the dictionary iterator initialized earlier by dict_iter_rewind and checks whether the iterator is still valid and not in conflict with any changes made by dict_put 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 ret_key and ret_value 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 ret_value 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, ret_key is not necessarily a variable.

Note that the values of ret_key and ret_value are left unchanged if the iterator points past the end of the dictionary. They are not filled in with NULLs or something like that.

Parameters
dict – Dictionary iterator
ret_key – The variable to be filled in with the key of the item. The parameter is ignored if it is not a plain variable.
ret_value – 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.
Return Types

The function returns a nonzero integer if the item is successfully fetched, zero otherwise

Errors

This function can generate the following errors:

Error CodeDescription 22023 SR630 Function dict_iter_next() tries to iterate a volatile dictionary changed after last dict_iter_rewind(). Not every change in the dictionary results in this error. If the dict_iter_next() and dict_put() (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 dict_put() 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.

Example
Simplest read throughout the dictionary.

The procedure creates a dictionary, puts couple of items into it and then print them to the server's console

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);
}

See Also

dict_new

dict_zap

dict_put

dict_get

dict_remove

dict_inc_or_put

dict_dec_or_remove

dict_size

dict_duplicate

dict_to_vector

dict_list_keys

dict_destructive_list_rnd_keys

dict_iter_rewind