in operator

The operator in is a binary operator used in an elementary logical expression that has the following format:

Syntax diagram for the operator in

searchValue

A literal or item, but not a system variable.

array

A one-dimensional or multidimensional array. The operator in operates on a one-dimensional array, which may be part of a multidimensional array.

subscript

An integer, or an item (or system variable) that resolves to an integer. The value of a subscript is an index that refers to a specific element in an array.

An item used as a subscript of an array can not itself be an array element. In each of the following examples, myItemB[1] is both a subscript and an array element; as a result, the following syntax is not valid:

  /* the next syntax is not valid */ 
  myItemA[myItemB[1]]

  // this next syntax is not valid; but only 
  // because myItemB is myItemB[1], the 
  // first element of a one-dimensional array
  myItemA[myItemB]

dataTableItem

The name of a dataTable item. The item represents a column in the data table. The in operator interacts with that column as if the column were a one-dimensional array.

The logical expression resolves to true if the generated program finds the search value. The search begins at the element identified by the last array subscript. If array is a one-dimensional array, the last subscript is optional and defaults to 1. If array is a multidimensional array, the following statements are true:

A subscript must be present for each dimension
The generated program searches the one-dimensional array that is identified by the sequence of subscripts other than the last subscript
The search begins at the element identified by the last subscript

In relation to both one-dimensional and multidimensional arrays, the search ends at the last element of the one-dimensional array under review.

The logical expression that includes in resolves to false in either of these cases:

The search value is not found
The value of the last subscript is greater than the number of entries in the one-dimensional array being searched

If the elementary logical expression resolves to true, the operation in sets the system variable sysVar.arrayIndex to the subscript value of the element that contains the search value. If the expression resolves to false, the operation sets sysVar.arrayIndex to zero.

Examples with a one-dimensional array

Let's assume that the structure item myString is substructured to an array of three characters:

  structureItem name="myString" length=3
    structureItem name="myArray" occurs=3 length=1

The next table shows the effect of the operator in if myString is "ABC".

Logical expression	Value of expression	Value of sysVar. ArrayIndex	Comment
"A" in myArray	true	1	The subscript of a single-dimension array defaults to 1
"C" in myArray[2]	true	3	Search begins at second element
"A" in myArray[2]	false	0	The search ends at the last element

Examples with a multidimension array

Let's assume that the array myArray01D is substructured to an array of three characters:

  structureItem name="myArray01D" occurs=3 length=3
    structureItem name="myArray02D" occurs=3 length=1

In this example, myArray01D is a one-dimensional array, with each element containing a string that is substructured to an array of three characters. myArray02D is a two-dimensional array, with each element (such as myArray02D[1,1]) containing a single character.

If the content of myArray01D is "ABC", "DEF", and "GHI", the content of myArray02D is as follows:

  "A"   "B"   "C"
  "D"   "E"   "F"
  "G"   "H"   "I"

The next table shows the effect of the operator in.

Logical expression	Value of expression	Value of sysVar. ArrayIndex	Comment
"DEF" in myArray01D	true	2	A reference to a one-dimensional array does not require a subscript; by default, the search begins at the first element
"C" in myArray02D[1]	—	—	The expression is invalid because a reference to a multidimensional array must include a subscript for each dimension
"I" in myArray02D[3,2]	true	3	Search begins at the third row, second element
"G" in myArray02D[3,2]	false	0	Search ends at the last element of the row being reviewed
"G" in myArray02D[2,4]	false	0	The second subscript is greater than the number of columns available to search

Related tasks
Syntax diagram