AT( ) function
Returns a number specifying the starting location of a particular occurrence of a substring within a character value.
Syntax
AT(occurrence_num, search_for_string, within_text)
Parameters
Name | Type | Description |
---|---|---|
occurance_num |
numeric |
The occurrence (instance) of search_for_string to return the location of. For example, specify 1 to return the starting location of the first occurrence of search_for_string. |
search_for_string |
character |
The substring to search for in within_text. This value is case-sensitive. If search_for_string includes double quotation marks, you need to enclose the value in single quotation marks: AT(1,'"test"', Description) |
within_text | character |
The value to search in. You can concatenate two or more fields in the within_text parameter if you want to search in more than one field in a table: AT(1,'"test"', Description+Summary) |
Output
Numeric. Returns the starting byte position of the specified occurrence of the search_for_string value, or 0 if no matches are found.
Examples
Basic examples
Occurrences found
Returns 4:
AT(1, "-", "604-669-4225")
Returns 8:
AT(2, "-", "604-669-4225")
Occurrences not found
Returns 0, because there is not a third hyphen in the value:
AT(3, "-", "604-669-4225")
Returns 0, because there is not a fourth lowercase "a" in the value:
AT(4, "a", "Alabama")
Groups of characters
Returns 5:
AT(2, "iss", "Mississippi")
Searching a field
Returns the byte position of the first hyphen in each value in the Invoice_Number field:
AT(1, "-", Invoice_Number)
Advanced examples
Finding invoice numbers in which the second hyphen occurs after the tenth byte position
You can analyze the consistency of invoice numbers in a table by using the AT( ) function to create a filter like the one below. This filter isolates all records in which the invoice number contains two or more hyphens, and the second hyphen occurs after the tenth byte position:
SET FILTER TO AT(2, "-", Invoice_Number) > 10
Remarks
When to use AT( )
Use this function to retrieve the following starting positions within a character value:
- the starting position of a substring
- the starting position of a subsequent occurrence of the substring
If you only want to confirm multiple occurrences of the same substring in a field, the OCCURS( ) function is a better alternative. For more information, see OCCURS( ) function.
Return value when occurrence_num exceeds the number of occurrences
If occurrence_num is greater than the actual number of substring occurrences in within_text, the function returns 0 because it cannot find that occurrence of the substring.
Concatenated fields and return values
When you search in more than one field, the value returned for the instance is the starting location of search_for_string across all fields that you specify. The concatenated fields are treated like a single field that includes leading and trailing spaces from the individual fields, unless you use the ALLTRIM( ) function to remove spaces.
For example, if you search for the first occurrence of a string in two fields with a width of eight characters each, and the string is found at the beginning of the second field, the return value is 9.