HCL Workload Automation, Version 9.4

FileMonitor events

FileMonitor events are:
  • FileCreated
  • FileDeleted
  • ModificationCompleted
  • LogMessageWritten

When you monitor files by using the FileCreated, FileDeleted, and LogMessageWritten events, the memory consumed by the ssmagent.bin and ssmagent.exe processes increases linearly with the number of files monitored and with the number of events created. Therefore, keep in mind that the heavier use of wildcards you make within these event types, and the consequent higher number of files monitored, will result in a heavier memory consumption by the ssmagent.bin and ssmagent.exe processes.

FileMonitor events are not supported on:
  • Pools, dynamic pools, and remote engine workstations.
  • IBM i systems.
Click here to see the Dynamic Workload Console fields for each event type.
Note: PDF users, the above parameter tables are an html file referenced by the PDF. It is not saved locally with the PDF from the infocenter. You must first view it on the infocenter before saving or printing.

Using the MatchExpression property of the LogMessageWritten event rule

The LogMessageWritten event plug-in uses the regular expression specified in the MatchExpression property to perform substring matches on entries in the log files being monitored. The value of MatchExpression must be a valid regular expression in accordance with the regular expression syntax rules of the Netcool/SSM agent that the event plug-in uses.

The following table describes the syntax of the regular expression tokens supported by Netcool/SSM. Note that to write a valid regular expression for the MatchExpression property, you must write the \ (backslash) escape character before each token used in the regular expression syntax (for example, \^ or \$). When the token already specifies a backslash character, you must write two backslash characters (for example, \\< or \\b).
Table 1. Regular expression syntax.
Token Matches
. Any character.
^ The start of a line (a zero-length string).
$ The end of a line; a new line or the end of the search buffer.
\< The start of a word (where a word is a string of alphanumeric characters).
\> The end of a word (the zero length string between an alphanumeric character and a non-alphanumeric character).
\b Any word boundary (this is equivalent to (\<¦\>) ).
\d A digit character.
\D Any non-digit character.
\w A word character (alphanumeric or underscore).
\W Any character that is not a word character (alphanumeric or underscore).
\s A whitespace character.
\S Any non-whitespace character.
\c Special characters and escaping. The following characters are interpreted according to the C language conventions: \0, \a, \f, \n, \r, \t, \v. To specify a character in hexadecimal, use the \xNN syntax. For example, \x41 is the ASCII character A.
\ All characters apart from those described above may be escaped using the backslash prefix. For example, to specify a plain left-bracket use \[.
[]

Any one of the specified characters in a set. An explicit set of characters may be specified as in [aeiou] as well as character ranges, such as [0-9A-Fa-f], which match any hexadecimal digit. The dash (-) loses its special meaning when escaped, such as in [A\-Z] or when it is the first or last character in a set, such as in [-xyz0-9].

All of the above backslash-escaping rules may be used within []. For example, the expression [\x41-\x45] is equivalent to [A-D] in ASCII. To use a closing bracket in a set, either escape it using [\]] or use it as the first character in the set, such as []xyz].

POSIX-style character classes are also allowed inside a character set. The syntax for character classes is [:class:]. The supported character classes are:
  • [:alnum:] - alphanumeric characters.
  • [:alpha:] - alphabetic characters.
  • [:blank:] - space and TAB characters.
  • [:cntrl:] - control characters.
  • [:digit:] - numeric characters.
  • [:graph:] - characters that are both printable and visible.
  • [:lower:] - lowercase alphabetic characters.
  • [:print:] - printable characters (characters that are not control characters).
  • [:punct:] - punctuation characters (characters that are not letters, digits, control characters, or spaces).
  • [:space:] - space characters (such as space, TAB and form feed).
  • [:upper:] - uppercase alphabetic characters.
  • [:xdigit:] - characters that are hexadecimal digits.

Brackets are permitted within the set's brackets. For example, [a-z0-9!] is equivalent to [[:lower:][:digit:]!] in the C locale.
[^] Inverts the behavior of a character set [] as described above. For example, [^[:alpha:]] matches any character that is not alphabetical. The ^ caret symbol only has this special meaning when it is the first character in a bracket set.
{n} Exactly n occurrences of the previous expression, where 0 <= n <= 255. For example, a{3} matches aaa.
{n,m} Between n and m occurrences of the previous expression, where 0 <= n <= m <= 255. For example, a 32-bit hexadecimal number can be described as 0x[[:xdigit:]]{1,8}.
{n,} At least n or more (up to infinity) occurrences of the previous expression.
* Zero or more of the previous expression.
+ One or more of the previous expression.
? Zero or one of the previous expression.
(exp) Grouping; any series of expressions may be grouped in parentheses so as to apply a postfix or bar (¦) operator to a group of successive expressions. For example:
  • ab+ matches all of abbb
  • (ab)+ matches all of ababab
¦ Alternate expressions (logical OR). The vertical bar (¦) has the lowest precedence of all tokens in the regular expression language. This means that ab¦cd matches all of cd but does not match abd (in this case use a(b¦c)d ).
Tip: When defining regular expressions to match multi-byte characters, enclose each multi-byte character in parentheses ().

Table 2 provides a set of regular expression examples, together with sample strings as well as the results of applying the regular expression to those strings.

There are two important cases in matching regular expressions with strings. A regular expression may match an entire string (a case known as a string match) or only a part of that string (a case known as a sub-string match). For example, the regular expression \<int\> will generate a sub-string match for the string int x but will not generate a string match. This distinction is important because some subagents do not support sub-string matching. Where applicable, the results listed in the examples differentiate between string and sub-string matches.

Table 2. Regular expression examples.
This expression... Applied to this string... Results in...
. a String match
! String match
abcdef Sub-string match on a
empty string No match
M..COUNT MINCOUNT String match
MXXCOUNTY Sub-string match on MXXCOUNT
NONCOUNT No match
.* empty string String match
Animal String match
.+ Any non-empty string String match
empty string No match
^ empty string String match
hello Sub-string match of length 0 at position 0 (position 0 = first character in string)
$ empty string String match
hello Sub-string match of length 0 at position 5 (position 0 = first character in string)
^$ empty string String match
hello No match
\bee tee No match
Paid fee No match
feel No match
eel Sub-string match on ee
.*thing.* The thing is in here String match
there is a thing String match
it isn't here No match
thinxxx No match
a* empty string String match
aaaaaaaaa String match
a String match
aardvark Sub-string match on aa
this string Sub-string match
((ab)*c)* empty string String match
ccccccccc String match
ccccabcccabc String match
a+ empty string No match
aaaaaaaaa String match
a String match
aardvark Sub-string match on aa
this string No match
(ab)+c)* empty string String match
ababababcabc String match
(ab){2} abab String match
cdabababab Sub-string match on abab
[0-9]{4,} 123 No match
a1234 Sub-string match on 1234
a{0} empty string String match
a No match
hello Sub-string match of length 0 at position 0 (position 0 = first character in string)
[0-9]{1,8} this is not a number No match
a=4238, b=4392876 Sub-string match on 4238
([aeiou][^aeiou])+ Hello Sub-string match on el
!!! Supacalafraglistic Sub-string match on upacalaf
[+-]?1 1 String match
+1 String match
-1 String match
.1 Sub-string match on 1
value+1 Sub-string match on +1
a¦b a String match
b String match
c No match
Daniel Sub-string match on a
abcd¦efgh abcd String match
efgh String match
abcdfgh Sub-string match on abcd
[0-9A-F]+ BAADF00D String match
C String match
baadF00D Sub-string match on F00D
c No match
G No match
g No match
x = \d+ x = 1234 String match
x = 0 String match
x = 1234a Sub-string match on x = 1234
x = y No match
x^=^ where ^ represents a space character No match
\D\d a1 String match
a11 Sub-string match on a1
-9 String match
a No match
8 No match
aa No match
4t No match
\s+ Hello_w0rld No match
Hello^^^world where ^ represents a space character Sub-string match on ^^^ where ^ represents a space character
Widget^ where ^ represents a space character Sub-string match on ^ where ^ represents a space character
^^^^^ where ^ represents a space character String match
\S+ Hello_w0rld Sub-string match of length 11 on Hello_w0rld
Hello^^^world where ^ represents a space character Sub-string match on Hello
Widget^ where ^ represents a space character Sub-string match on Widget
^^^^^ where ^ represents a space character No match
\w+ D4n_v4n Vugt Sub-string match on D4n_v4n
^^^hello where ^ represents a space character Sub-string match on hello
blah String match
x#1 No match
foo bar No match
\W Hello there Sub-string match of length 1 on separating space character
~ String match
aa No match
a No match
- No match
^^^^444 == 5 where ^ represents a space character Sub-string match of length 1 on first ^ where ^ represents a space character
\w+\s*=\s*\d+ x = 123 String match
count0=555 String match
my_var=66 String match
0101010=0 String match
xyz = e No match
delta= No match
==8 No match
[[:alnum:]]+ 1234 String match
...D4N13L Sub-string match on D4N13L
[[:alpha:]]+ Bubble String match
...DANI3L Sub-string match on DANI
69 No match
[:blank:]]+ alpha^^^^and beta where ^ represents a space character Sub-string match on ^^^^ where ^ represents a space character
Animal No match
empty string No match
[[:space:]]+ alpha^^^^and beta where ^ represents a space character Sub-string match on ^^^^ where ^ represents a space character
Animal No match
empty string No match
[[:cntrl:]]+ ...Hello W0rld! No match
empty string No match
[[:graph:]]+ hello world Sub-string match on hello
^^^^^ where ^ represents a space character No match
^^^!? where ^ represents a space character Sub-string match on !?
[:lower:]]+ Animal Sub-string match on nimal
ABC No match
0123 No match
foobar String match
^^^0blaH! where ^ represents a space character Sub-string match on bla
[_[:lower:]]+ foo_bar String match
this_thinG!!! Sub-string match on _thin
[[:upper:]]+ YES String match
#define MAX 100 Sub-string match on MAX
f00 b4r No match
[[:print:]]+ hello world String match
^^^^^ where ^ represents a space character String match
[[:punct:]]+ didn't Sub-string match on '
Animal No match
[[:xdigit:]]+ 43298742432392187ffe String match
x = bAAdF00d Sub-string match on bAAdF00d
4327afeffegokpoj Sub-string match on 4327afeffe
c:\\temp c:\temp String match

Example

The rule in the following example sends an email to a list of recipients as soon as file /home/book.txt is created on workstation editor_wrkstn.
<?xml version="1.0"?>
<eventRuleSet xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xmlns="http://www.ibm.com/xmlns/prod/tws/1.0/event-management/rules"
      xsi:schemaLocation="http://www.ibm.com/xmlns/prod/tws/1.0/
                          event-management/rules/EventRules.xsd">
   <eventRule name="FILE_MONITOR_FILE_CREATED" ruleType="filter" isDraft="no">
      <description>Event: File Created; Action: Send mail</description>
      <validity to="2012-04-22" />
      <eventCondition name="fileCrtEvt1" eventProvider="FileMonitor" eventType="FileCreated">
      <scope>/HOME/BOOK.TXT ON EDITOR_WRKSTN</scope>
         <filteringPredicate>
          <attributeFilter name="FileName" operator="eq">
         <value>/home/book.txt</value>
          </attributeFilter>
         <attributeFilter name="SampleInterval" operator="eq">
         <value>60</value>
         </attributeFilter>
         <attributeFilter name="Workstation" operator="eq">
         <value>editor_wrkstn</value>
         </attributeFilter>
         <attributeFilter name="Hostname" operator="eq">
         <value>ceditor</value>
         </attributeFilter>
                  </filteringPredicate>
      </eventCondition>
      <action actionProvider="MailSender" actionType="SendMail" responseType="onDetection">
         <description>Send an eMail</description>
         <scope>SAUL.FELLOW@US.IBM.COM, ISAAC.LINGER@US.IBM.COM : THE EXPECTED FILE
                HAS BEEN CREATED!</scope>
         <parameter name="Cc">
            <value>william.waulkner@us.ibm.com</value>
         </parameter>
         <parameter name="Bcc">
            <value>ernest.demingway@us.ibm.com</value>
         </parameter>
         <parameter name="Body">
            <value>The expected file was created!
                   The book is ready to be published.</value>
         </parameter>
         <parameter name="To">
            <value>saul.fellow@us.ibm.com, isaac.linger@us.ibm.com</value>
         </parameter>
         <parameter name="Subject">
            <value>The expected file was created!</value>
         </parameter>
      </action>
   </eventRule>
</eventRuleSet>