The dictionary is always passed by reference, due to its (potentialy big) size. The reference variable contains not only pointer to the whole dictionary but also a forward-only iterator (a "cursor") that can be used to retrieve items of the dictionary one after the other. The function sets the iterator to the very first item of the dictionary.
The function returns an integer that is the expected number of items in the dictionary; the value may not match to the number of items retrieved later by dict_iter_next() if a dictionary is edited by some thread.
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); }