DataObject.SetVarValueOrder

Prototypes

void SetVarValueOrder( String sVarName, Matrix mValues <, Matrix mOrder> )

void SetVarValueOrder( String sVarName, Matrix mValues, Matrix mOrder <, int nFlags> )

Parameters

String sVarName
The name of the variable whose values you want to order.

Matrix mValues
A vector that lists unique values of the specified variable. If the variable has values that are not listed in mValues, those values are treated as missing values. The missing values always appear first in any ordering.

Matrix mOrder
A vector of integer values that (a) determines the ordering of the entries in mValues, and (b) optionally specifies that specific entries in mValues be treated as missing values. If the integer mOrder[i] is in the range -2147483648 to -1, the value mValues[i] is treated as a missing value. If the integer mOrder[i] is in the range 0 to 2147483647, it specifies a numeric sort value for mValues[i]. The ordering of the variable's values is the ascending sort order of the non-negative integers in mOrder. If you do not specify mOrder, the values in mValues are assumed to be in sorted order already.

int nFlags
One or more flags that control the ordering. See Remarks for information about the flags. To specify multiple flags, use the addition operator (+) to add them together. Calling this method without specifying nFlags is equivalent to calling it with nFlags equal to VVO_ENABLE.

Remarks

This method assigns a custom ordering to a variable's values. By default, the DataObject orders a variable's values using an ascending sort. You can assign a custom ordering to a character variable or to a nominal numeric variable. You cannot assign a custom ordering to an interval variable.

The parameter nFlags specifies one or more flags that control the variable's custom ordering. The flags are as follows:

VVO_ENABLE
This flag specifies that the custom ordering should be enabled. If you omit this flag, the DataObject stores the custom ordering information but does not enable it. When a variable's custom ordering is disabled, the variable's values are ordered using an ascending sort.

VVO_CASESENSITIVE
This flag specifies that two character values that differ only in case are treated as two unique values. If you omit this flag, two character values that differ only in case are treated as one unique value. You can only specify this flag for character variables.

VVO_STRINGPREFIX
This flag specifies that the vector mValues contains prefixes and not complete values. When you specify this flag, two character values that share a common prefix listed in mValues are treated as one unique value. You can only specify this flag for character variables.

VVO_SETMODIFIED
This flag specifies that the DataObject is marked modified whenever the variable's custom ordering information changes. Closing a DataObject that is marked modified causes IML Studio to prompt you to save changes if you used IML Studio's user interface to do either of the following:

Open a data file. (This implicitly created the DataObject.)
Save the DataObject to a file.

Notes

If you assign a custom ordering to a nominal numeric variable and then use the method DataObject.SetNominal to change the variable's measurement level to Interval, the custom ordering is deleted.
If you call SetVarValueOrder a second time for the same variable, the new custom ordering information replaces the earlier information.

Example

declare DataObject dobj;

x = { "Low", "Medium", "Medium", "High", "High", "High" };

dobj = DataObject.Create( "Example", "X", x );

values = { "Low", "Medium", "High" };

dobj.SetVarValueOrder( "X", values );