fteCreateMonitor: create an MFT resource monitor

The fteCreateMonitor command creates and starts a new resource monitor from the command line. We can monitor a resource (for example, the contents of a directory) by using 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 by using a Managed File Transfer agent. For example, we 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 and copies the files from the known directory to a destination agent.

We 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. Additionally, we can use the -f and -c parameters to overwrite a monitor configuration dynamically.

The fteCreateMonitor command is not supported on protocol bridge agents.

Tip: We can also use the fteListMonitors command to export resource monitor configurations to an XML file:

  • Use the fteListMonitors command with the -ox exports the definition for a single resource monitor.
  • From IBM MQ Version 9.1.0, using the fteListMonitors command with the -od exports multiple resource monitor definitions to a specified directory. We can also use the -od option to export a single resource monitor definition to a specified directory.

For more information about the fteListMonitors command, see fteListMonitors: list MFT resource monitors.


Special characters

Take care when we use parameter values that contain special characters so that you avoid the command shell interpreting the characters in a way we do not expect. For example, fully qualified file paths and names that contains such characters as space, quotation mark (single or double), forward-slash or back-slash characters, might be interpreted by the command shell rather than being passed through directly to the command itself. To avoid characters being interpreted by the command shell, enclose the entire parameter in double/single quotation marks or escape the special characters by using the escape sequence of the command shell.


Syntax


fteCreateMonitor

fteCreateMonitor  -ix  monitor_definition_file  -ox  monitor_definition_file  -ma  monitoring_agent_name  -mn  monitor_name  -mm  monitoring_agent_qmgr_name   -f   -c  -md  directory_path  -mq  queue_name   -mt   task_definition_file_name   -rl  number_of_recursion_levels  -pi  interval_period  -pu  units -tr  condition , pattern -tc-tcr pattern -tccsrcDestdestSrc -x  exclude_pattern  -mmd  monitor metadata  -pt  pattern_type  -bs  matches_per_task -mquseriduserID-mqpasswordpassword -dv  default_variables  -p  configuration_options 


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.

    -mn (monitor_name)
    Required. The name that you assign to this monitor. The monitor name must be unique to the monitoring agent. However, we can delete a monitor and then create a monitor with the same name.

    Resource monitor names are not case-sensitive. Resource monitor names that are entered in lowercase or mixed case are converted to uppercase. Resource monitor names must not contain asterisk (*), percent (%), or question mark (?) characters.

    -ma (monitoring_agent_name)
    Required. The name of the agent to perform the resource monitoring. This monitoring agent must be the source agent for the monitor task that we want to trigger.

    -mm (monitoring_agent_qmgr_name)
    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.Note: The fteCreateMonitor command connects to the command queue manager for a Managed File Transfer topology. If the command queue manager is also the agent queue manager for the monitoring agent, then this parameter is optional. Otherwise, the parameter is required.

    -f
    Optional. Use this parameter to overwrite a resource monitor configuration. For example, when the resource monitor name you choose already exists on the resource monitoring agent and we 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. We can use this parameter with the -f parameter only.

    -md (directory_path)
    Optional. The absolute name of the directory path that we want to monitor. Unless we are using the -ix or -ox parameters we must specify one of the -md or -mq parameters.

    -mq (queue_name)
    Optional. The name of the queue that we want to monitor. This queue must be on the monitoring agent queue manager. Unless we are using the -ix or -ox parameters we must specify one of the -md or -mq parameters.

    -mt (task_definition_file_name)
    Required. The name of the XML document that contains the task definition that we want to carry out when the trigger condition is satisfied. For more information, see Use transfer definition files. The path to the transfer definition XML document must be on the local file system that you run the fteCreateMonitor command from. If we do not specify a path to the file, the command looks for it in the current working directory. Unless we are using the -ix or -ox parameters, -mt is a required parameter.

    We 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.

    We can also use the transfer recovery timeout, -rt parameter, along with the -gt parameter, when you run the fteCreateMonitor command. We can set the amount of time in seconds during which the source agent keeps retying to recover a transfer that is stalled. The recovery timeout parameter is then included in the XML document with the transfer definition that the monitor uses. For more information on how to set this parameter, see fteCreateTransfer command.

    On z/OS, you must store the task definition document in a UNIX file on z/OS UNIX System Services. We cannot store task definition documents in z/OS sequential files or PDS members.

    On IBM i, we must store the task definition document in the integrated file system.

    -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 
    C:\wmqfte\monitor
C:\wmqfte\monitor\reports
C:\wmqfte\monitor\reports\2009
C:\wmqfte\monitor\reports\2009\April
    If you specify -rl 2, Managed File Transfer searches only 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, we 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: 

    • condition,pattern
      where condition is one of the following values:

        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 that is used is bytes. On all operating systems, we 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.
      -tr match,*.go
      The following trigger condition is satisfied when there are no files in the monitored directory that have the suffix .stop. 
      -tr noMatch,*.stop

      We can specify condition,pattern only if you also specify the -md parameter.

    • condition
      where condition is one of the following values:

        queueNotEmpty
        The monitored queue is not empty. That is, if there are any IBM 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 IBM 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.

      We can specify condition only if you also specify the -mq parameter.

    For each monitor that you create, we can specify the -tr parameter once only.

    -tc
    Optional. Indicates that the triggered file contains one or more file paths to generate a transfer request. The default format of the trigger file's contents is one file entry on each line. Specify the file paths either as source file path or source file path,destination file path. This parameter is available only for directory monitor triggers match and noSizeChange.

    -tcr (pattern)
    Optional. Specifies a replacement regular expression for parsing trigger files. We must specify this parameter with the -tc parameter. Design the pattern to parse each line entry completely with one or two capture groups. Group one defines the source file path and the optional group two defines the destination file path. This is the default behavior, which we can change using the -tcc parameter.

    For more information and examples, see Use a trigger file.

    -tcc
    Optional. Defines the regular expression capture group order.

      srcDest
      The default value where group one is the source file path and group two is the destination file path.

      destSrc
      The reverse of srcDest. Group one is the destination file path and group two is the source file path. Ensure that the regular expression for destSrc has two capture groups.

    We must specify this parameter with the -tcr parameter.

    -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.

    -mmd (monitor metadata)
    Optional. Specifies the user-defined metadata that is passed to the monitor's exit points. The parameter can take one or more name pairs that are separated by commas. Each name pair consists of a name=value. We can use the -mmd parameter more than once in a command.

    -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 MFT.

    -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.

    -mquserid (userID)
    Optional. Specifies the user ID to authenticate with the command queue manager.

    -mqpassword (password)
    Optional. Specifies the password to authenticate with the command queue manager. We must also specify the -mquserid parameter. If you specify -mquserid, but do not specify -mqpassword, we are prompted to supply the associated password. The password is not displayed.

    -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: 
    -dv size=medium,color=blue
    For more information about variable substitution, see Customizing MFT tasks with variable substitution. We can only specify the -dv parameter if you have also specified the -mq parameter.

    -? 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 that are associated with this nondefault coordination queue manager.

    If we do not specify this parameter, the set of configuration options based on the default coordination queue manager is used.


Examples

In this example, a new resource monitor is created called MYMONITOR using the monitoring agent MYAGENT. Provided the trigger condition that a file larger than 5 MB is present in the directory C:\wmqfte\monitors, the file transfer that is defined in the file C:\templates\transfer_reports.xml is started. MYAGENT is also the source agent for the file transfer that is defined in C:\templates\transfer_reports.xml:
fteCreateMonitor -ma MYAGENT -md C:\wmqfte\monitors -mn MYMONITOR -mt C:\templates\transfer_reports.xml
 -tr fileSize">"=5MB,*.go
In this example, a resource monitor called MONITOR1 using the agent AGENT1 is created to transfer files greater than 5 MB and is exported to the XML file monitor.xml.
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
In this example, a new resource monitor is created called MYMONITOR using the agent MYAGENT.
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 reissued 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.
Parent topic: MFT commands


Related reference


Related information