WATCH_DIRECTORY
This is an iterator activity that watches a specified directory for new, changed and/or deleted files and sub-directories. Upon each iteration, it will output details of the file or sub-directory affected, if any.
The processing logic nested beneath the WATCH_DIRECTORY activity is repeated each time that a file or sub-directory is added, changed or deleted or each time the specified wait time (WAIT parameter) is exceeded.
A stereotypical application of this activity is where you have a particular directory in which other users or applications can place new files that need to be processed by your solution – a"dropbox" directory. This activity enables you to implement such a solution by watching that directory and receiving notifications when a file is added.
There remains an important consideration for any application that performs this type of processing, and especially when doing so without complete understanding and/or control over the other users or applications that are submitting files for processing.
Your solution will receive a notification of a *CREATE event, for example, as soon as a file is added to the watched directory. But that does not necessarily mean the file is ready or available for your solution to process. For example, the source application may still be writing it, or even may have created it with a temporary file name before renaming it when the file is complete. Your solution may need a means to decide when a new (or changed) file is ready for it to process.
LANSA Composer provides the WAIT_FILESREADY activity to assist with many such situations. If you are using the WATCH_DIRECTORY activity, you may need to use it in conjunction with the WAIT_FILESREADY activity for a robust solution.
You can refer to the EXAMPLE_WATCH01 Processing Sequence for an example of using the WATCH_DIRECTORY activity in conjunction with the WAIT_FILESREADY activity.
Note: This activity requires that the LANSA Integrator JSM is executing on a JVM at Java 7 or above.
Note: Unlike many other iterator activities, this activity will iterate indefinitely unless you take specific action in the iterator block to exit the iteration. It is designed to be used in a potentially long running processing sequence that perpetually waits on a message arriving at the specified message queue and then processes the message or initiates another processing sequence to process the message. For more information refer to Considerations for Extended Duration Processing Sequences.
Restarting the WATCH_DIRECTORY activity
The WATCH_DIRECTORY activity supports processing sequence restart if an error occurs while it is active. However, it is possible that some previously queued file system events may have been lost when the activity restarts. Your solution may need to take account of this.
If your solution uses the "drop-box" approach where the directory should always be empty of anything but unprocessed files, then you will probably specify *YES for the EXISTINGCONTENTS parameter. In this case the existing contents of the specified directory will be enumerated and iterated when the processing sequence restarts, and you will usually need to take no further action with respect to the processing sequence restart support.
INPUT Parameters:
DIRECTORY: Required
This parameter must specify the full path to the directory to be watched.
RECURSIVE: Optional
This parameter specifies whether descendant directories of the specified directory are also watched. The default value is *NO which means that descendant directories are not watched. You may specify *YES if you want the activity to watch the descendant directories. If you specify *YES and you are watching for *CREATE events (see the WATCHEVENTS parameter), then any new sub-directories that are created while this iterator activity is active will also be watched.
EXISTINGCONTENTS: Optional
This parameter specifies whether the activity enumerates and iterates for the existing contents of the specified directory when the activity starts up or when it is restarted.
The default value is *YES which means that the existing directory contents will be processed and an *EXISTS event generated for each existing file or sub-directory. If your solution uses the "drop-box" approach where the directory should always be empty of anything but unprocessed files, then this is the behaviour you probably will want.
Alternatively, specify *NO if you do not want the activity to process the existing directory contents. In this case, your solution will receive notifications only for files that are added, changed or deleted after the iterator activity begins processing.
WAIT: Optional
Specifies the length of time (in seconds) that the activity will wait, on each iteration, for a watched event to occur in the specified directory.
The default value is 20 (twenty) seconds. This default value has been chosen to be less than the default controlled end delay times used on IBM i system commands such as ENDJOB (End Job). You should consider also the corresponding delay times used with IBM i system commands such as ENDSBS (End Subsystem) or PWRDWNSYS (Power Down System). This enables your processing sequence to have the opportunity to check the value of the *SHUTDOWN built-in variable and end in a controlled fashion if one of those commands is issued.
You may specify the special value of 0 (zero) which means that the activity does not wait for a watched event to occur in the specified directory.. Instead the next iteration is performed immediately. Use of this value is not generally recommended with the WATCH_DIRECTORY activity as it may result in your long-running processing sequence being heavily CPU intensive, instead of simply entering an idle/wait state when it has no work to perform.
WATCHEVENTS: Optional
This parameter specifies the types of file system events that the activity watches for in the specified directory. The default value is *CREATE which means that the activity watches only for new files or sub-directories.
Alternatively you may specify one or more of the following values (each value should be separated by at least one space):
*CREATE
*MODIFY
*DELETE
You must specify quote marks around the value(s) to distinguish them from built-in variable names.
Note that if you specify *YES for the EXISTINGCONTENTS parameter, then your solution may also receive *EXISTS events, irrespective of your choices for the WATCHEVENTS parameter.
OUTPUT Parameters:
EVENTOUT:
Upon each iteration, the value of this output parameter will indicate whether a watched file system event occurred, and, if so, the type of event. It may have one of the following values:
*NONE: indicates that no watched event occurred. This value is returned whenever the wait time specified on the WAIT parameter elapsed with no watched file system events for the specified directory.
*EXISTS: indicates that the remaining output parameter values refer to a file or sub-directory that exists in the specified directory when the activity starts up or when it is restarted. This value will occur only if you specify *YES for the EXISTINGCONTENTS parameter.
*CREATE: indicates that the remaining output parameter values refer to a new file or sub-directory that has been created in the specified directory.
*MODIFY: indicates that the remaining output parameter values refer to a file or sub-directory that has changed in the specified directory.
*DELETE: indicates that the remaining output parameter values refer to a file or sub-directory that has been deleted in the specified directory. Only the value of the FILEPATHOUT parameter is valid for this event.
*OVERFLOW: indicates that the file system may have reported events faster than they can be retrieved or processed by this activity. In this case, some events may have been lost. If you process this event, you might use it to re-examine the contents of the directory being watched. The remaining output parameters values are not filled when this event occurs. Your solution may receive this event irrespective of the value(s) specified for the WATCHEVENTS parameter.
FILEPATHOUT:
Upon each iteration, for events *EXISTS, *CREATE, *MODIFY and *DELETE, this parameter will contain the full path of the file or sub-directory affected.
ISDIROUT:
Upon each iteration, for events *EXISTS, *CREATE and *MODIFY, this parameter will contain 'Y' if the event refers to a sub-directory. Otherwise the event refers to a file.
SIZEOUT:
Upon each iteration, for events *EXISTS, *CREATE and *MODIFY, this parameter will contain the size in bytes of the affected file or sub-directory.
LASTMODOUT:
Upon each iteration, for events *EXISTS, *CREATE and *MODIFY, this parameter will contain the last modified date and time for the affected file or sub-directory.