fteCreateMonitor: create an MFT resource monitor

Purpose

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

Special characters

Take care when you use parameter values that contain special characters so that you avoid the command shell interpreting the characters in a way you 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.

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, 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 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 you 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 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 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)

Required. The name of the XML document that contains the task definition that you want to carry out when the trigger condition is satisfied. For more information, see Using 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 you do not specify a path to the file, the command looks for it in the current working directory. Unless you are using the -ix or -ox parameters, -mt is 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.

You can also use the transfer recovery timeout, -rt parameter, along with the -gt parameter, when you run the fteCreateMonitor command. You 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. You cannot store task definition documents in z/OS sequential files or PDS members.

On IBM i, you 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, 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:

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

  -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 

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

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

For each monitor that you create, you 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. If you specify the -tcr parameter, you must also specify 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 you can change using the -tcc parameter.

For more information and examples, see Using 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.

If you specify the -tcc parameter, you must also specify 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. You 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. You must also specify the -mquserid parameter. If you specify -mquserid, but do not specify -mqpassword, you 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 resource monitor tasks with variable substitution. You 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 you do not specify this parameter, the set of configuration options based on the default coordination queue manager is used.

Return codes