Command: NEXT
Command: ORDER

Purpose: Obtains the next value of a persistent array's specified subscript. The next value is determined by the natural collating sequence in which GT.M and Caché save subscript values (both databases apply the same rules).

To obtain the first value of a subscript, a seed value of null ("") is used. NEXT or ORDER will return a null value if no more values exist for a specified subscript.

The hierarchical nature of the persistent arrays means that traversal of the levels of the hierarchy is an important aspect of their use. The synonymous ORDER and NEXT commands will therefore be amongst the most commonly used commands in the M/Wire protocol.

The use of these commands is best illustrated by an example. Consider the following array structure:

myArray="aaa"
myArray[1,"x"]="hello"
myArray[1,"y"]="world"
myArray[1,"y","hello world"]="ok"
myArray[1,"z","hello world"]="not ok"

The examples below demonstrate the behaviour of various NEXT or ORDER commands when applied to this array:

Client: NEXT myArray[""]
Server: $1
Server: 1

This is because we're wanting to find the first value that exists for the first subscript of the myArray array.

Client: NEXT myArray[1]
Server: $-1

This is because we've asked to return the value of the first subscript of the myArray array that follows the value 1. There are no other values for the first subscript, so it returns a null value, indicated by the $-1.

Client: NEXT myArray[1,""]
Server: $1
Server: x

This is because we're wanting to find the first value that exists for the second subscript of the myArray array where the first subscript is 1.

Client: NEXT myArray[1,"x"]
Server: $1
Server: y

This is because we're wanting to find the value of the second subscript of the myArray array that follows x where the first subscript is 1.

Client: NEXT myArray[1,"z"]
Server: $-1

This is because we're wanting to find the value of the second subscript of the myArray array that follows z where the first subscript is 1. In fact, z is the last value that exists, so a null value is returned, denoted by the $-1.

Arguments:

Argument No Description
1 An array node and subscript(s). This takes the format:
   arrayRef[subscr1,subscr2,..etc]
Testing a value at the first level of subscripting would look like:
   arrayRef[1]
Testing a value at the second level of subscripting would look like:
   arrayRef[1,"aaa"]

Note that subscripts can be numeric or text. Text subscripts must be wrapped in double quote (") characters. Quoting of numeric subscripts is optional.

Response

Two-line response

If the specified array and subscripts has an existing next value:

Server Line 1: $[no of bytes in next record]
Server Line 2: Subscript value

For those familiar with the native language of GT.M and Caché systems, the earlier examples above are the equivalent of:

write $order(^myArray(""))
write $order(^myArray(1))
write $order(^myArray(1,""))
write $order(^myArray(1,"x"))
write $order(^myArray(1,"z"))