The ARRAY_NEXT function returns the next larger array index value for an array relative to the specified array index argument.

The schema is SYSIBM.

array-expression

An SQL variable, SQL parameter, or global variable of an array type, or a CAST specification of a parameter marker to an array type.

array-index

Specifies a value that is assignable to the data type of the index of the array.
Valid values include any valid value for the data type.

The result is the next larger array index value defined in the array relative to the specified array-index value.
If array-index is less than the minimum index array value in the array, the result is the first array index value defined in the array.

The data type of the result of the function is the data type of the array index.
The result can be null; if either argument is null, the cardinality of the first argument is zero, or the value of array-index is greater than or equal to the value of the last index in the array, the result is the null value.

Examples

1. Return the next index value after the 9th index position in the ordinary array variable SPECIALNUMBERS to the SQL variable NEXT_CONSTIDX.

   SET NEXT_CONSTIDX = ARRAY_NEXT(SPECIALNUMBERS,9)

   The result is 10.


2. Given the associative array variable PHONELIST with index values and phone numbers:
   'Home' is '4163053745', 'Work' is '4163053746', and 'Mom' is '416-4789683', assign the value of the index in the array that is the next index after index value 'Dad', which does not exist for the array value, to the character string variable named X:

   SET X = ARRAY_NEXT(PHONELIST, 'Dad')

   The value of 'Home' is assigned to X, since the value 'Dad' is a value smaller than any index value for the array variable.
   Assign the value of the index in the array that is the next index after index value'Work':

   SET X = ARRAY_NEXT(PHONELIST, 'Work')

   The null value is assigned to X.