C-LANG Statements › TEXTSTRING Statement—Specify a Text String to Search For

TEXTSTRING Statement—Specify a Text String to Search For

The TEXTSTRING statement specifies the text to search for.

Supported Job Type

This statement is required for the Text File Reading and Monitoring job type.

Syntax

This statement has the following format:

TEXTSTRING textstring [EXIST|NOTEXIST]  
[CONTINUOUS(alertid)]

textstring

Defines the text string to search for. You can specify the text string as a regular expression.

Limits: Up to 1024 characters; case-sensitive

EXIST|NOTEXIST

(Optional) Specifies whether the job monitors if a text string exists or does not exist.

EXIST

Monitors whether a text string exists in a specified text file. If the text string exists, the job completes successfully, or an alert is triggered (if monitoring continuously). This is the default.

NOTEXIST

Monitors whether a text string does not exist in a specified text file. If the text string does not exist, the job completes successfully. If the text string exists, the job fails.

Note: To use the NOTEXIST setting, you must specify NOW in the WAITMODE statement.

CONTINUOUS (alertid)

(Optional) Specifies the identifier of an alert to be triggered when the specified text monitoring conditions occur. Defines the job as continuous. To end continuous monitoring, you must complete the job manually or cancel it. If you do not specify this operand, the job completes when the job finds the first match to the text string.

alertid

Specifies the alert identifier to be triggered.

Limits: 1-8 alphanumeric characters; the first character must be alphabetic

Note: The alert must have been previously defined to the scheduling manager. Not all scheduling managers support the CONTINUOUS operand.

Notes:

• If the job finds one or more occurrences of the searched text, the first trigger takes place at the first occurrence only. Subsequently, the job only searches for new lines that are added to the text file. In other words, the job resumes the search from the first line following the last line of the file from the previous search.
• You cannot use the NOTEXIST operand in this statement with the CONTINUOUS operand.
• You cannot use the TO operand in the SEARCHRANGE statement with the CONTINUOUS operand.
• You cannot use the WAITMODE statement with the CONTINUOUS operand in the TEXTSTRING statement, they are mutually exclusive.

Notes:

• Enclose values that contain delimiters (such as spaces) in double quotation marks.
• To compose a regular expression, follow the rules for Java class java.util.regex.Pattern. You can find these rules using a Google search for java pattern.
• You can use escape sequences in the regular expression. The following characters have a special meaning in regular expressions. To use these characters literally, precede the characters with one backward slash (\).
  • \—backward slash
  • [—opening bracket
  • *—asterisk
  • |—vertical bar
  • {—opening brace
  • +—plus sign
  • (—opening parenthesis
  • ^—caret (circumflex)
  • ?—question mark
  • )—closing parenthesis
  • $—dollar sign
  • .—period

  For example, to match the characters *.* literally, specify \*\.\* in your regular expression. The backward slashes escape the characters' special meanings.

Example: Monitor a File for a String Using Special Characters

In this example, because the text string contains escape sequences, back slashes must precede the special characters asterisk (*), period (.), and zed (Z). The required text string is a wild card search for the text string "=jars*.* that must appear at the end of the line (\Z).

AGENT UNIXAGENT
TEXTFILE '/export/home/cybermation/agentdir/agentparm.txt'
TEXTSTRING '=jars/\*\.\*\Z'
SEARCHRANGE LINE FROM(1) TO(110)

Example: Monitor a File for a String using a Regular Expression

In this example, the text string contains regular expression pattern matching syntax. The search range is also a regular expression as indicated by the operand REGEX in the SEARCHRANGE statement.

AGENT UNIXAGENT
TEXTFILE '/export/home/cybermation/agentdir/agentparm.txt'
TEXTSTRING '^\w{4,10}\.' Exist                           
SEARCHRANGE REGEX FROM(\A\W\sE)

The regular expression can be interpreted as follows:

• ^ or \A—match only at the beginning of string (line)
• \Z or $—match only at the end of string
• \w—a word character [a-zA-Z0-9]
• \W—a non-word character
• \s—a whitespace character
• {4,10}—match at least 4 times but not more than 10 times

To illustrate the last item {4, 10}, consider the following syntax:

TEXTSTRING 'b1{1,3}c'

Evaluating this expression yields the following conditions:

• The line contains the text b1.
• Numeric 1 should exist at least once, but not more than three times.
• The specified text string must be followed by the letter c.

Example: Continuously Monitor a File for a String

This example searches the text file DATA SOURCE NAME for the text string EVENT ""COMPUTER() .

AGENT WINAGENT
USER CAUSER
JOBCLASS BA
TEXTSTRING 'EVENT ""COMPUTER() ' EXIST CONTINUOUS(A123)
TEXTFILE 'DATA SOURCE NAME'
SEARCHRANGE LINE FROM(123)

When the job first runs, it searches the content between line 123 and the end of the file. An alert is triggered the first time that the string is found. Subsequently, the job continues monitoring only the new data that is appended to the file. An alert is triggered each time the string is found in the appended data.

Note: Alerts are not triggered for new occurrences of the text string in the data that has already been searched. For example, suppose that the job has already searched lines 123 to 200 of the file. The file is then modified to include the text string on line 150. During continuous monitoring, an alert is not triggered for that occurrence.

This job runs until it is completed manually.