C-LANG Statements › SEARCHRANGE Statement—Specify the Range to be Searched

SEARCHRANGE Statement—Specify the Range to be Searched

The SEARCHRANGE statement specifies the range to be searched in a text file using a search boundary type of line, regular expression, or date and time.

Supported Job Type

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

Syntax

This statement has the following format:

SEARCHRANGE LINE|REGEX|DATETIME [FROM(lower)] [TO(upper)]

LINE|REGEX|DATETIME

Specifies the mode of search. Options are the following:

LINE

Searches for the text string in the line boundaries defined by the upper and lower line boundaries. If LINE is specified, the search boundaries defined by FROM and TO are numeric.

REGEX

Searches for a text string within boundaries defined by regular expressions. If REGEX is specified, the search boundaries defined by FROM and TO are regular expressions.

DATETIME

Searches for a text string within boundaries defined by a specified date and time. If DATETIME is specified, the TIMEFORMAT statement must also be defined.

FROM(lower)

Defines the start of the range to be searched. The format of this value depends on the text file search mode. The formatting options are as follows:

• Numeric—Specify a numeric value if the search mode is LINE.
• Regular expression—Specify a regular expression if the search mode is REGEX.
• Date and time—Specify date and time values if the search mode is DATETIME. Define the date and time using the format specified by the time format.

Limits: Up to 256 characters; case-sensitive. When the search mode is LINE, the upper limit is 9223372036854775807.

TO(upper)

Defines the end of the range to be searched. The format of this value depends on the text file search mode. The formatting options are as follows:

• Numeric—Specify a numeric value if the search mode is LINE.
• Regular expression—Specify a regular expression if the search mode is REGEX.
• Date and time—Specify date and time values if the search mode is DATETIME. Define the date and time using the format specified by the time format.

Limits: Up to 256 characters; case-sensitive

Note: You cannot specify the TO operand when using the WAITMODE statement with the WAIT value.

Notes:

• Enclose values that contain delimiters (such as spaces) in double quotation marks.
• If you do not specify the FROM operand, you must specify the TO operand. The job starts searching from the first line of the text file to the upper boundary specified by the TO operand.
• If you do not specify the TO operand, you must specify the FROM operand. The job searches from the lower boundary specified by the FROM operand to the last line of the text file.
• If you specify the CONTINUOUS operand in the TEXTSTRING statement, you cannot use the TO operand in the SEARCHRANGE statement.
• When the search mode is REGEX, the search boundaries specified by the FROM and TO operands are regular expressions. 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 (\).
  • \—back slash
  • |—vertical bar
  • (—opening parenthesis
  • )—closing parenthesis
  • [—opening bracket
  • {—opening brace
  • ^—caret (circumflex)
  • $—dollar sign
  • *—asterisk
  • +—plus sign
  • ?—question mark
  • .—period

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

• If you specify the lower boundary as a regular expression and there are no strings in the text file that match it, the agent does not search for the text string.
• If you specify the upper boundary as a regular expression and there are no strings in the text file that match it, the agent searches for the text string to the last line of the text file.
• RANGE is an alias of SEARCHRANGE.

Example: Monitor a Windows Text File for a String Using the LINE Search Mode

This example searches the c:\ca\log file in line mode. The job starts searching the content from line 143 of the file. The upper boundary is not defined, so the job searches to the last line of the file. The job completes successfully if the ERROR MESSAGE string is found.

AGENT WINAGENT
TEXTSTRING 'ERROR MESSAGE' EXIST
TEXTFILE 'c:\ca\logfile'
SEARCHRANGE LINE FROM(143)

Example: Monitor a Windows Text File for a String Using the DATETIME Search Mode

This example searches the /export/home/logs/transmitter.log file in date and time mode. The job searches the content between May 20, 2010 at midnight and May 27, 2010 at 11:59 p.m. The date and time values are defined using the format specified in the TIMEFORMAT statement. The job completes successfully if the transmitted string is found.

AGENT UNIXAGENT
TEXTFILE '/export/home/logs/transmitter.log'
TEXTSTRING transmitted EXIST
SEARCHRANGE DATETIME +
  FROM('Thu May 20 00:00:00.000 EDT 2010') +
  TO('Thu May 27 23:59:59.999 EDT 2010')
TIMEFORMAT 'EEE MMM dd HH:mm:ss.SSS zzz yyyy' TIMEPOS(12)

Example: Monitor a Windows Text File for a String Using the REGEX Search Mode

This example searches the agentparm.txt file in regular expression mode. The job searches the content from the lower boundary (a line that contains the word CAWA) to the upper boundary (a line that contains the word service). The job completes successfully if the archive string is found.

AGENT WINAGENT
TEXTFILE 'c:\program files\agentdir\agentparm.txt'
TEXTSTRING archive EXIST
SEARCHRANGE REGEX FROM(CAWA) TO(service)

Example: Monitor a Windows Text File for a Windows Path

Because back slashes are interpreted as an escape sequence, the two back slashes in the text string, 'C:\\Program Files', must each be preceded by a back slash, giving four back slashes in the TEXTSTRING statement below:

AGENT WINAGENT
TEXTFILE 'c:\program files\agentdir\agentparm.txt'
TEXTSTRING 'C:\\\\Program Files' EXIST
SEARCHRANGE LINE FROM(1) TO(200)

Example: Monitor a UNIX Text File for a String Using the DATETIME Search Mode

This example searches the /export/home/agentdir/log/transmitter.log file in date and time mode. The job searches the content between May 20, 2010 at midnight and May 27, 2010 at 11:59 p.m. The date and time values are defined using the format specified in the TIMEFORMAT statement. The job completes successfully if the NTAGR6 string is found.

AGENT UNIXAGENT
TEXTFILE '/export/home/agentdir/log/transmitter.log'
TEXTSTRING NTAGR6 EXIST
SEARCHRANGE DATETIME+
  FROM('Thu May 20 00:00:00.000 EDT 2010')+
  TO('Thu May 27 23:59:59.999 EDT 2010')
TIMEFORMAT 'EEE MMM dd HH:mm:ss.SSS zzz yyyy' TIMEPOS(1)

Example: Monitor a UNIX Text File for a String at the Beginning of a Line

This example searches the /export/home/agentdir/agentparm.txt file. The search starts at the first line that contains the word agent at the beginning of the line (as specified by \A in the regular expression).

AGENT UNIXAGENT
TEXTFILE '/export/home/ca/agentdir/agentparm.txt'
TEXTSTRING \.0/MAIN$ EXIST
SEARCHRANGE REGEX FROM(\Aagent) TO(level=2\Z)

Example: Monitor a UNIX Text File for a String Using the REGEX Search Mode

This example searches for the string "# Runner plugin parameters", which is evaluated as a regular expression. The job searches from the first line that contains the word CAWA to the line that contains the word service.

AGENT UNIXAGENT
TEXTFILE '/export/home/agentdir/agentparm.txt'
TEXTSTRING \A\W\sRunner EXIST
SEARCHRANGE REGEX FROM(CAWA) TO(service)

The criteria \A, \W, and the word \sRunner are evaluated as follows:

• \A means match only at the beginning of the line.
• \W means match a non-word character.
• \sRunner means look for a white space before the word Runner.

Example: Monitor a UNIX Text File for a String Using the LINE Search Mode

This example searches the test file for the text string "agent".

AGENT UNIXAGENT
TEXTFILE '/export/home/log/test'
TEXTSTRING agent EXIST CONTINUOUS(text)
SEARCHRANGE LINE FROM(1)

When the job first runs, it searches the content between line 1 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 "agent" string in the data that has already been searched. For example, suppose that the job has already searched lines 1 to 100 of the file. The file is then modified to include "agent" on line 30. During continuous monitoring, an alert is not triggered for that occurrence.

This job runs until it is completed manually.

Example: Monitor an i5/OS Text File for a String in the First 20 Lines of the File

This example searches for a text string in the DATA member of a QSYS file object on an i5/OS computer. The job searches the content between lines 1 and 20. The job completes successfully if the string is found.

AGENT i5AGENT
TEXTFILE /QSYS.LIB/LIBRARY.LIB/RESULTS.FILE/DATA.MBR
TEXTSTRING 'Create file failed' EXIST
SEARCHRANGE LINE FROM(1) TO(20)