DataObject.SelectObsWhere

Prototypes

void SelectObsWhere( String sVarName, int nOperator, Matrix mRhsValue <, int nFlags> )

void SelectObsWhere( String sVarName, int nOperator, Matrix mRhsValue, int nFlags <, double dTolerance> )

void SelectObsWhere( String sVarName, int nOperator, double dRhsValue <, int nFlags> )

void SelectObsWhere( String sVarName, int nOperator, double dRhsValue, int nFlags <, double dTolerance> )

void SelectObsWhere( String sVarName, int nOperator, String sRhsValue <, int nFlags> )

Parameters

String sVarName
The name of the variable whose values you want to use to select observations conditionally. The method uses the values of this variable as the left-hand operand of the comparison operator specified by nOperator.

int nOperator
A predefined constant specifying the operator to use to compare the variable's values with the right-hand side value. See Remarks for details.

Matrix mRhsValue
A scalar matrix containing the character or numeric value to use as the right-hand operand of the comparison operator.

double dRhsValue
The numeric value to use as the right-hand operand of the comparison operator.

String sRhsValue
The character string to use as the right-hand operand of the comparison operator. If you call the version of the method that accepts this parameter, the method sets the flag WF_PRESERVESPACES automatically. See Notes for additional details.

int nFlags
One or more flags that control the selection process. 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 WF_NEWSELECTION.

double dTolerance
The tolerance you want used in numeric comparisons. The method selects an observation if the condition specified by nOperator can be satisfied by adding or subtracting dTolerance from the variable's value. Calling this method without specifying dTolerance is equivalent to calling it with dTolerance equal to a missing value, which results in dTolerance not being used.

Remarks

This method selects the observations in the DataObject that satisfy a condition. You specify the condition as a variable name, a comparison operator, and a right-hand side value. The method selects an observation if the variable's value for the observation satisfies the condition specified by the operator and the right-hand side value.

The parameter nOperator is a predefined constant that specifies the operator the method uses to compare the variable's values with the right-hand side value. The predefined constants for this parameter are as follows:

WHERE_EQ
The variable's value is equal to the right-hand side value.

WHERE_NE
The variable's value is not equal to the right-hand side value.

WHERE_LT
The variable's value is less than the right-hand side value.

WHERE_GT
The variable's value is greater than the right-hand side value.

WHERE_LE
The variable's value is less than or equal to the right-hand side value.

WHERE_GE
The variable's value is greater than or equal to the right-hand side value.

WHERE_ISMISSING
The variable's value is a missing value. The right-hand side value is ignored.

WHERE_CONTAINS
The variable's value contains the right-hand side value. You cannot use this operator with a numeric variable unless you specify the flag WF_FORMATVALUES.

WHERE_NOTCONTAINS
The variable's value does not contain the right-hand side value. You cannot use this operator with a numeric variable unless you specify the flag WF_FORMATVALUES.

WHERE_PREFIX
The right-hand side value is a prefix of the variable's value. You cannot use this operator with a numeric variable unless you specify the flag WF_FORMATVALUES.

The parameter nFlags specifies one or more flags that control the selection process. The flags are as follows:

WF_NEWSELECTION
This flag instructs the method to deselect all observations prior to beginning the selection process. This flag is the default if you do not specify either the flag WF_SUBSETSELECTION or the flag WF_EXTENDSELECTION.

WF_SUBSETSELECTION
This flag instructs the method to process only those observations that were selected prior to the call to the method. The use of this flag has the effect of deselecting those observations that do not satisfy the specified condition.

WF_EXTENDSELECTION
This flag instructs the method not to deselect any observations. This flag is mutually exclusive with the flag WF_SUBSETSELECTION.

WF_CASESENSITIVE
This flag instructs the method to perform string comparisons in a case-sensitive manner. By default, the method performs string comparisons in a case-insensitive manner. The flag applies both to comparisons involving a character variable and to comparisons involving a numeric variable when the flag WF_FORMATVALUES is set.

WF_FORMATVALUES
This flag instructs the method to format the variable's values using the variable's format before performing the comparison with the right-hand side value. If you use this flag with a numeric variable, the right-hand side value must be a character string.

WF_PRESERVESPACES
This flag instructs the method not to strip trailing spaces from the right-hand side value. By default, the method strips trailing spaces from the right-hand side value. If you call the method with a Java String object for the right-hand side value (the parameter sRhsValue), the method sets the flag WF_PRESERVESPACES automatically.

Notes

Unless you specify the flag WF_PRESERVESPACES, the method strips trailing spaces from the right-hand side value.
The flag WF_PRESERVESPACES is useful when used in conjunction with the operators WHERE_CONTAINS, WHERE_NOTCONTAINS, and WHERE_PREFIX.
The method always strips trailing spaces from the variable's values before comparing them with the right-hand side value regardless of whether you specify the flag WF_PRESERVESPACES.
If you call the method with a literal string for the right-hand side value and you do not specify the parameter dTolerance, IMLPlus calls the version of the method that accepts a Java String object for the right-hand side value. In this case, the method sets the flag WF_PRESERVESPACES automatically.
If you specify an empty string for the right-hand side value, the method converts the empty string to a single space character. This behavior mirrors that of the DATA step's WHERE statement.

Example

declare DataObject dobj;

dobj = DataObject.CreateFromFile( "baseball" );

range = { 60, 80 };

dobj.SelectObsWhere( "no_runs", WHERE_GE, range[1] );

dobj.SelectObsWhere( "no_runs", WHERE_LE, range[2], WF_SUBSETSELECTION );