Text - Find
Declaration
<AMTEXT TEXT="text" FIND="text" RESULTVARIABLE="Text" USERE="YES/NO" USECASE="YES/NO" INDEX="number" FOUNDTEXTVARIABLE="text" TOTALMATCHESVARIABLE="text" />
Description: Finds each or every occurrence of a text sequence and places the result into a variable. Regular expressions may be used for added power and flexibility.
Practical Usage
Commonly used to locate a word or phrase inside of a larger piece of text.
General Parameters
|
Property |
Type |
Required |
Default |
Markup |
Description |
|---|---|---|---|---|---|
|
Text |
Text |
Yes |
(Empty) |
TEXT="My name is Joe" |
The target body of text to be searched. As with every text parameter, if the data you wish to enter is contained in a variable, simply enter the variable name surrounded by percentage signs to resolve it to its contents at runtime (e.g., %VarName%). |
|
Find |
Text |
Yes |
(Empty) |
FIND="name" |
The portion of text contained in the main body of text to search for. |
|
Case Sensitive |
Yes/No |
No |
No |
USECASE="YES" |
Specifies whether the search performed should be case sensitive. If set to YES, the search is case sensitive. This parameter is set to NO by default. |
|
Regular Expression |
Yes/No |
No |
No |
USERE="YES" |
Specifies whether the Find parameter is a regular expression. If set to NO (default), the Find parameter contains literal text. If set to YES, the Find parameter contains a regular expression. |
|
Populate variable with first index |
Text |
Yes |
(Empty) |
RESULTVARIABLE="varname" |
The name of an existing variable to receive the first position of the text to search for, if found. |
Advanced Parameters
|
Property |
Type |
Required |
Default |
Markup |
Description |
|---|---|---|---|---|---|
|
Starting at the following instance |
Number |
No |
1 |
INDEX="2" |
Indicates that the target text should be searched starting at the following instance. |
|
Total find count into variable |
Text |
No |
(Empty) |
TOTALMATCHESVARIABLE="varname" |
The name of an existing variable to receive the total instances found. |
|
Populate variable with found text |
Text |
No |
(Empty) |
FOUNDTEXTVARIABLE="varname" |
The name of an existing variable to receive the text that was found. This parameter is useful if regular expression is used to find text. |
Description tab - A custom description can be provided on the Description tab to convey additional information or share special notes about a task step.
Error Causes tab - Specify how this step should behave upon the occurrence of an error. (Refer to Task Builder > Error Causes Tab for details.)
On Error tab - Specify what AWE should do if this step encounters an error as defined on the Error Causes tab. (Refer to Task Builder > On Error Tab for details.)
Example
The sample AML code below can be copied and pasted directly into the Steps panel of the Task Builder.
Description: This sample task searches a body of text for the word 'occurrence' and displays the total number of times it was found as well as the position of the first instance in a message dialog.
<AMVARIABLE NAME="indexVar"></AMVARIABLE> <AMVARIABLE NAME="totalInstances"></AMVARIABLE> <AMFINDTEXT TEXT="This action finds each or every occurrence of a text pattern and places the result of each occurrence into a variable." FIND="occurrence" RESULTVARIABLE="indexVar" TOTALMATCHESVARIABLE="totalInstances" /> <AMMESSAGEBOX>The word 'occurrence' was found at position %indexVar%.
The total number of times this word appeared was %totalInstances% times.</AMMESSAGEBOX>