%Iterator.Object

Adding an element to the %DynamicObject object can cause further calls on the %GetNext(.key,.value,.type) method to have undefined behavior. It is undefined whether the %GetNext iteration method will visit or skip the added element.

The first argument is an output argument .key which contains the key name string for the element that is returned.

The second argument is an output argument .value which contains the value for the returned element which is usually converted to ObjectScript.

The optional third output argument .type, when it is present, will be modified to contain the %GetTypeOf(key) string representing the original type of the returned %DynamicObject element. When this third argument variable is present it changes some of the conversion rules for converting a %DynamicObject element into an ObjectScript value.

The optional fourth output argument .keytype is igored on a Unicode IRIS instance. When .keytype is present on a non-Unicode IRIS instance, it will be modified to contain the type of the .key argument string. This is almost always "string" but it can contain "json" when the key string contains a UTF-16 character larger than $CHAR(255). A .keytype argument value of "json" indicates the .key argument value is formatted as a JSON format string including a leading " mark, a trailing " mark, and where required, the string will include JSON format character escapes.

If the optional third argument is not present then a <MAXNUMBER> error signal may occur if the element value is a JSON number that is too large to be converted to an ObjectScript computational canonical number.

If the optional third argument is not present then a <MAXSTRING> error signal may occur if the element value is a JSON string that when converted to ObjectScript string format exceeds the length limit for ObjectScript strings.

If the optional third argument is not present on a non-Unicode IRIS instance, then a <WIDE CHAR> error signal may occur if the key name string in .key or the %DynamicObject element value in .value are JSON strings containing a UTF-16 character with a value larger than $CHAR(255).

If the optional third argument, .type, is present then these conversion errors will be avoided.

If the third parameter variable, .type, is present then an element which was originally a JSON format number will always be returned as an ObjectScript string containing the JSON format number. If the element was originally an ObjectScript number then the returned value will be an ObjectScript canonical computational number. In either case, the third .type argument will contain "number". If the third parameter variable, .type, is not present then the JSON format number will be converted to an ObjectScript computational number before assignment to the .value argument variable.

If the .value element in the %DynamicObject was originally an ObjectScript oref then the .type argument will contain "oref". If the element was originally a long JSON string that would exceed the supported length for an ObjectScript string then the .value argument will contain the oref for a readonly ObjectScript %Stream.DynamicCharacter or %Stream.DynamicBinary class object containing the string characters but the type argument will still contain "string" and not "oref". This conversion from a string to %Stream does not occur if the third .type argument is not present.

On a non-Unicode instance, if a element in the %DynamicObject was originally a normal length JSON string containing UTF-16 characters larger than $CHAR(255), then the .value will be converted to an ObjectScript string containing a JSON format string including a leading " mark, a trailing " mark, and where required, the string will include JSON format character escapes. Also the type argument will contain "json" instead of containing "string". This conversion to JSON format does not occur if the third .type argument is not present.

On a non-Unicode instance, if the key name was originally a JSON string containing a UTF-16 character larger than $CHAR(255), then the .key will be an ObjectScript string containing a JSON format string including a leading " mark, a trailing " mark, and where required, the string will include JSON format character escapes. This conversion to JSON format does not occur if the third .type argument is not present. If the optional fourth argument .keytype is present then it contains "json" to indicate the conversion of the key string to JSON format has occurred.

The .type argument allows you to deterimine whether a %Stream oref returned in the .value argument was originally an ObjectScript oref or a long JSON string converted to a %Stream object.

The .type can also allow you to determine whether a .value containing the ObjectScript empty string, "", was originally type "string" or type "null" or whether a .value containing 0 or 1 was originally type "number" or type "boolean".

On a non-Unicode instance, if the element in the %DynamicObject was originally a normal length JSON string containing UTF-16 characters that could not be converted to an 8-bit ObjectScript string then the .value argument will contain an ObjectScript string containing a JSON format string constant and the .type argument will be "json" instead of "string" to specify the formatting type of the .value string.

On a non-Unicode instance, if the key string in the %DynamicObject was originally a JSON string containing UTF-16 characters that could not be converted to an 8-bit ObjectScript string then the .key argument will contain an ObjectScript string containing a JSON format string constant. And if present, the optional fourth argument .keytype will contain "json" instead of "string" to indicate the coversion of .key to JSON format.

To call %GetNext(.key,.value,.type) method, pass the .key and .value arguments, and optionally the .type argument, by reference to receive their return values. To iterate over a %DynamicObject on a Unicode IRIS instance use the following pattern:

      while iterator.%GetNext(.key,.value,.type) {
          // key contains the element key name
          // and value contains the value
          // and type contains a %GetTypeOf string
      }