Command: PREVIOUS
Command: REVORDER

Purpose: Obtains the previous value of a persistent array's specified subscript. The previous value is determined by the natural collating sequence in which GT.M and Caché save subscript values (both databases apply the same rules). PREVIOUS and its synonym REVORDER traverse the subscripts in the opposite direction to NEXT and its synonym ORDER.

To obtain the last value of a subscript, a seed value of null ("") is used. PREVIOUS or REVORDER will return a null value if no previous value exists 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 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: PREVIOUS myArray[""]
Server: $1
Server: 1

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

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

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

Client: PREVIOUS myArray[1,""]
Server: $1
Server: z

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

Client: PREVIOUS myArray[1,"z"]
Server: $1
Server: y

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

Client: PREVIOUS myArray[1,"x"]
Server: $-1

This is because we're wanting to find the value of the second subscript of the myArray array that precedes x where the first subscript is 1. In fact, x is the first 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(""),-1)
write $order(^myArray(1),-1)
write $order(^myArray(1,""),-1)
write $order(^myArray(1,"z"),-1)
write $order(^myArray(1,"x"),-1)