fteCreateMonitor (create new resource monitor)
The fteCreateMonitor command creates and starts a new resource monitor from the command line. You can monitor a resource (for example, the contents of a directory) using IBM® WebSphere® MQ Managed File Transfer so that when a trigger condition is satisfied, a specified task, such as a file transfer, is started.
Purpose
Use the fteCreateMonitor command to create and then start a new resource monitor using a WebSphere MQ Managed File Transfer agent. For example, you can use a resource monitor in the following way: An external application puts one or more files in a known directory and when processing is complete, the external application places a trigger file in a monitored directory. The trigger file is then detected and a defined file transfer starts, which copies the files from the known directory to a destination agent.You can use the -ox and -ix parameters to export and import a resource monitor configuration to an XML file. Importing this file with the fteCreateMonitor command creates a new resource monitor with the same parameters as the resource monitor given in the fteCreateMonitor command to export to the XML file. You can also use the fteListMonitors command to export a resource monitor configuration to an XML file. Additionally, you can use the -f and -c parameters to overwrite a monitor configuration dynamically.
The fteCreateMonitor command is not supported on protocol bridge agents.
Syntax
Parameters
- -ix (xml_filename)
- Optional. Imports the resource monitor configuration from an XML file.
- -ox (xml_filename)
- Optional. This parameter must be specified with the -ma and -mn parameters. Exports the resource monitor configuration to an XML file.
- -ma (monitoring_agent_name)
- Optional. The name of the agent to perform the resource monitoring. This monitoring agent must be the source agent for the monitor task that you want to trigger.
- -mn (monitor_name)
- Optional. The name that you assign to this monitor. The monitor name must be unique to the
monitoring agent. However, you can delete a monitor and then create a monitor with the same name.
The maximum length for a resource monitor name is 256 characters. Resource monitor names are not case-sensitive. Resource monitor names entered in lowercase or mixed case are converted to uppercase. Resource monitor names must not contain asterisk (*), percent (%) or question mark (?) characters.
- -mm (monitoring_agent_qmgr_name)
- Optional. The name of the queue manager that the monitoring agent is connected to. Because the monitoring agent and the source agent must be same, this queue manager is also your source agent queue manager.
- -f
- Optional. Use this parameter to overwrite a resource monitor configuration. For example, when the resource monitor name you have chosen already exists on the resource monitoring agent and you want to update it rather than delete and re-create a monitor with the same name. Using this parameter causes the agent to restart the monitor process.
- -c
- Optional. This parameter clears the history of an updated resource monitor, which causes the resource monitor to check the trigger conditions again. You can use this parameter with the -f parameter only.
- -md (directory_path)
- Optional. The absolute name of the directory path that you want to monitor. Unless you are using the -ix or -ox parameters you must specify one of the -md or -mq parameters.
- -mq (queue_name)
- Optional. The name of the queue that you want to monitor. This queue must be located on the monitoring agent queue manager. Unless you are using the -ix or -ox parameters you must specify one of the -md or -mq parameters.
- -mt (task_definition_file_name)
- Optional. The name of the XML document that contains
the task definition that you want to carry out when the trigger condition
is satisfied. The path to the transfer definition XML document must
be on the local file system that you run the fteCreateMonitor command from. Unless you are using the -ix or -ox parameters this will be a required parameter.
You can use the -gt parameter on the fteCreateTransfer command to generate a template XML document that contains your file transfer request. The monitor uses the transfer template as its task definition.
- -rl (number_of_recursion_levels)
- Optional. The level of monitoring recursion of the root monitoring
directory, that is how many levels of subdirectory to go down into.
For example in a directory structure like the following example with C:\wmqfte\monitor set as the root monitoring directory:
If you specifyC:\wmqfte\monitor C:\wmqfte\monitor\reports C:\wmqfte\monitor\reports\2009 C:\wmqfte\monitor\reports\2009\April
-rl 2
, WebSphere MQ Managed File Transfer only searches as far down as the C:\wmqfte\monitor\reports\2009 directory and its sibling directories. The C:\wmqfte\monitor\reports\2009\April directory is ignored. By default, recursion is set to none. - -pi (interval_period)
- Optional. The interval period between each monitor of a directory. The poll interval must be a positive integer value. The default value for -pi is 1.
- -pu (units)
- Optional. The time units for the monitor poll interval. If you
specify the -pu parameter, you must also specify
the -pi parameter. The default value for -pu is minutes. Specify one of the following
options:
- seconds
- minutes
- hours
- days
- -tr
- Optional. Specifies the trigger condition that
must be satisfied for the defined task to take place. If the condition
is not satisfied, according to the source agent, the monitor task
(for example the file transfer) is not started. A trigger condition
consists of two optional parts, condition and pattern, separated by
a comma. Specify one of the following formats:
where condition is one of the following values:condition,pattern
- match
- For each trigger that is satisfied, the defined task
is performed. match is the default value.
For example, if the match is *.go and the files LONDON.go and MANCHESTER.go are present, the task is performed for LONDON.go and another task is performed for MANCHESTER.go.
If the same trigger file is present from a previous poll (that is, the file has not been modified), this file has a not satisfied trigger condition. That is, the match trigger file must be new and must have been modified since last the poll before the defined task is performed.
- noMatch
- No files in the monitored directory match the pattern. That is, if any of the files in the monitored directory do not exist, the condition is satisfied. If no files match the trigger condition at the time the monitor is created, the monitor starts instantly, but does not start again until a file match is found, and then removed.
- noSizeChange=n
- A minimum of one of the files in the directory matches the pattern and has a file size that does not change for n polling intervals. The value of n is a positive integer.
- fileSize>=size
- A minimum of one of the files in the directory matches the pattern
and has a minimum file size greater or equal to size. The value size is a combination of an integer with an optional size unit
of B, KB, MB, or GB. For example,
fileSize">"=10KB
. If you do not specify a size unit, the default size used is bytes. On all operating systems, you must enclose the greater than symbol (>) in double quotation marks when you specify the fileSize option on the command line, as shown in this example.
The pattern is a file pattern match sequence in wildcard or Java regular expression format. The default value for the pattern is *, or match any file, and the default format is wildcard format. Use the -pt to specify the format of the pattern.
For example, the following trigger condition is satisfied when a file exists in the monitored directory with the suffix .go.
The following trigger condition is satisfied when there are no files in the monitored directory which have the suffix .stop.-tr match,*.go
-tr noMatch,*.stop
You can only specify
condition,pattern
if you have also specified the -md parameter.
where condition is one of the following values:condition
- queueNotEmpty
- The monitored queue is not empty. That is, if there are any IBM WebSphere MQ messages on the monitored queue, the condition is satisfied. A single task is run for all of the messages on the queue.
- completeGroups
- There is a complete group on the monitored queue. That is, if any of the WebSphere MQ message groups on the monitored queue are complete, the condition
is satisfied. An individual task is run for each complete group on
the queue.
If a single message that is not in a group is put on the queue, it is treated as if it is a complete group and a task is run for the single message.
You can only specify
condition
if you have also specified the -mq parameter.
For each monitor that you create, you can specify the -tr parameter once only.
- -x (exclude_pattern)
- Optional. Specifies files that are excluded from the trigger pattern
match. The trigger pattern is specified by the -tr parameter.
The pattern is a file pattern match sequence in wildcard or Java regular expression format. The default format is wildcard format. Use the -pt parameter to specify the format of the pattern.
- -jn (job name)
- Optional. Specifies a job name reference, which is a user-defined identifier for the request.
- -pt (pattern_type)
- Optional. The type of pattern that is used by the -tr and -x parameters. Valid values are:
- wildcard
- The patterns are evaluated as wildcard patterns. An asterisk (*) matches zero or more characters and a question mark (?) matches exactly one character. This is the default.
- regex
- The patterns are evaluated as Java regular expressions. For more information, see Regular expressions used by WebSphere MQ Managed File Transfer.
- -bs (matches_per_task)
- Optional. The maximum number of trigger matches to include in
a single task. For example, if a value of 5 is specified for matches_per_task and nine trigger matches occur in a single
poll interval, two tasks are performed. The first task corresponds
to triggers 1-5 inclusive, and the second task corresponds to triggers
6-9. The default value of matches_per_task is 1.
The -bs parameter is supported only when the task definition XML that you supply to the -mt parameter is a managedTransfer. A managedCall is not supported with the -bs parameter.
- -dv (default_variables)
- Optional. A comma-separated list of default variables that can
be used in variable substitution when monitoring a queue. The values
are in the format of a key-value pair. For example:
For more information about variable substitution, see Customizing tasks with variable substitution. You can only specify the -dv parameter if you have also specified the -mq parameter.-dv size=medium,color=blue
- -? or -h
- Optional. Displays command syntax.
- -p(configuration_options)
- Optional. This parameter determines the set of configuration options
to use to cancel the transfer. By convention use the name of a nondefault
coordination queue manager as the input for this parameter. The command
then uses the set of properties files associated with this nondefault
coordination queue manager.
If you do not specify this parameter, the set of configuration options based on the default coordination queue manager is used.
Examples
fteCreateMonitor -ma MYAGENT -md C:\wmqfte\monitors -mn MYMONITOR -mt C:\templates\transfer_reports.xml
-tr fileSize">"=5MB,*.go
fteCreateMonitor -ox monitor.xml -ma AGENT1 -mn MONITOR1 -mt task.xml -tr "fileSize>=5MB,*.zip"
Then the XML file is imported and changed to exclude any files greater
than 10MB. fteCreateMonitor -ix monitor.xml -x "fileSize>=10MB,*.zip" -f
fteCreateMonitor -ma MYAGENT -md c:\wmqfte -mn MYMONITOR -mt c:\templates\transfer_reports.xml -tr "fileSize>=5MB,*.go"
However the trigger is initially incorrectly set to monitor c:\wmqfte rather than c:\wmqfte\monitors. The fteCreateMonitor request is immediately
re-issued with the monitor directory corrected and the -f (overwrite) and -c (clear history) parameters
used to update the monitor. fteCreateMonitor -ma MYAGENT -md c:\wmqfte\monitors -mn MYMONITOR -mt c:\templates\transfer_reports.xml
-tr "fileSize>=5MB,*.go" -f -c
Return codes
Return code | Description |
---|---|
0 | Command completed successfully. |
1 | Command ended unsuccessfully. |