C-LANG Statements › FILENAME Statement—Specify File to Monitor

FILENAME Statement—Specify File to Monitor

The FILENAME statement specifies the path to and name of a file to monitor. It also specifies the monitor conditions for the file trigger.

Supported Job Type

This statement is required for the File Trigger job type.

Syntax

This statement has the following format, except for CA WA Agent for HP Integrity NonStop:

FILENAME file_name
{CREATE [SIZE(integer[K|M])] 
        [OWNER(owner)][GROUP(group)]
        [NOCHANGE(min)]
        [CONTINUOUS(alertid)]
        [RECURSIVE]}
{DELETE [OWNER(owner)][GROUP(group)]
        [CONTINUOUS(alertid)]
        [RECURSIVE]}
{EXIST [OWNER(owner)][GROUP(group)]
       [RECURSIVE]}
{EXPAND SIZE(integer[K|M])|DELTA(integer[K|M])|PERCENT(integer)
        [OWNER(owner)][GROUP(group)]
        [NOCHANGE(min)]
        [CONTINUOUS(alertid)]
        [RECURSIVE]}
{NOTEXIST [OWNER(owner)][GROUP(group)] 
          [RECURSIVE]}
{SHRINK SIZE(integer [K|M])|DELTA(integer [K|M])|PERCENT(integer)
        [OWNER(owner)][GROUP(group)]
        [NOCHANGE(min)]
        [CONTINUOUS(alertid)]
        [RECURSIVE]}
{UPDATE [OWNER(owner)][GROUP(group)]
        [NOCHANGE(min)]
        [CONTINUOUS(alertid)]
        [RECURSIVE]}

This statement has the following format for CA WA Agent for HP Integrity NonStop:

FILENAME file_name
{CREATE [CONTINUOUS(alertid)]}
{UPDATE [CONTINUOUS(alertid)]}

file_name

Specifies the path to and name of the file to monitor.

Limits: Up to 128 characters; case-sensitive

UNIX/Windows: You can use wildcards and spaces in your UNIX and Windows file names and paths.

i5/OS:

• To specify a file in the root file system, use UNIX path and file formats.
• To specify an object in QSYS in path format, use one of the following formats:

  /QSYS.LIB/library.LIB/object.type/
  

  /QSYS.LIB/library.LIB/object.FILE/member.MBR
  

• To specify an object in QSYS in i5/OS standard format, use one of the following formats:

  library/object/type
  

  library/object/*FILE(member)
  

library

Specifies the name of the library that contains the object. The value must be a valid i5/OS library name.

Limits: Up to 10 characters

Notes:

• You can specify *ALL to match any name.
• You can specify a generic name.

object

Specifies the name of the object. The value must be a valid i5/OS object name.

Limits: Up to 10 characters

Notes:

• You can specify *ALL to match any name.
• You can specify a generic name.

type

Specifies the type of object.

Limits: Up to 10 characters

Note: You can specify *ALL to match any name.

Example: FILE

member

Specifies a member in the *FILE object. The value must be a valid i5/OS member name.

Limits: Up to 10 characters

Notes:

• You can specify *FIRST.
• You can specify *ALL to match any name.

File Trigger Types

Specify one of the following file trigger types to monitor for. For each trigger type, you can specify additional criteria.

CREATE

Indicates that the file trigger occurs when the file is created. This is the default file trigger type.

DELETE

Indicates that the file trigger occurs when the file is deleted.

EXIST

Indicates that the file trigger occurs if the file exists. If the file does not exist, the job fails.

EXPAND

Indicates that the file trigger occurs when the file size increases. If the file does not exist, the job fails.

Note: If you specify the EXPAND file trigger type, you must specify one of the SIZE, DELTA, or PERCENT operands.

NOTEXIST

Indicates that the file trigger occurs if the file does not exist. If the file exists, the job fails.

SHRINK

Indicates that the file trigger occurs when the file size decreases. If the file does not exist, the job fails.

Note: If you specify the SHRINK file trigger type, you must specify one of the SIZE, DELTA, or PERCENT operands.

UPDATE

Indicates that the file trigger occurs when the file is updated.

Additional Criteria

You can specify the following additional criteria depending on the file trigger type. For information on the criteria that applies to each trigger type, refer to the Syntax.

CONTINUOUS(alertid)

(Optional) Specifies the identifier of an alert to be triggered when the specified file trigger conditions occur. Defines the job as continuous. To end continuous monitoring, you must complete the job manually or cancel it. If you do not specify this operand, the job completes when the specified file trigger conditions occur.

alertid

Specifies the alert identifier to be triggered.

Limits: 1-8 alphanumeric characters; the first character must be alphabetic

Note: The alert must have been previously defined to the scheduling manager. Not all scheduling managers support the CONTINUOUS operand.

Notes:

• If the file trigger type is CREATE, EXPAND, SHRINK, or UPDATE, the job will not complete unless it is forced to complete.
• If the file trigger type is DELETE, the job completes when all the monitored files are deleted or it is forced to complete.
• The following applies to using wildcards in the file name value with the CONTINUOUS operand:
  • If the file trigger type is CREATE or DELETE, a wildcard value is not mandatory for the file name value. The following shows how to use wildcards (* or ?): /usr/data/pay*.
  • If the file trigger type is EXPAND or UPDATE and the file name value contains a wildcard, the agent monitors all files that match the file name criteria when the file trigger is set. When the criteria is satisfied for any of the selected files, the trigger occurs and the agent continues to monitor the files.

    Note: If the CONTINUOUS operand is specified with the NOCHANGE operand and a wildcard is used in the file name value, all of the matching files must remain unchanged for the duration of the NOCHANGE interval. If another file satisfying the trigger criteria is updated during the NOCHANGE interval, the trigger waits until the trigger interval lapses on the first file before monitoring the second file for the duration of the NOCHANGE interval.

DELTA(integer[K|M])

Defines the number of bytes the file size must change for the file trigger to occur.

Limits: Up to 10 characters; the first character must be numeric

Note: You can specify the file size in kilobytes (KB) or megabytes (MB) instead of bytes by appending K or M.

GROUP(group)

(Optional) Specifies the name of the group that owns the file to be monitored.

Limits: Up to 16 characters; case-sensitive; it cannot contain delimiters (such as spaces)

Notes:

• Applies only to UNIX jobs and i5/OS jobs (if the file is not a QSYS object).
• If the file is not owned by the specified group, the following occurs:
  • The job continues monitoring if the file trigger type is CREATE.
  • The job completes if the file trigger type is DELETE or NOTEXIST.
  • The job fails if the file trigger type is EXPAND, EXIST, SHRINK, or UPDATE.

NOCHANGE(min)

(Optional) Defines the number of minutes the file must remain unchanged to satisfy the monitor condition.

Limits: Up to 8 numeric digits

Example: 60

OWNER(owner)

(Optional) Specifies the user ID that owns the file to be monitored.

Limits: Up to 16 characters; case-sensitive; it cannot contain delimiters (such as spaces)

Notes:

• Applies only to UNIX jobs and i5/OS jobs (if the file is not a QSYS object).
• If the file is not owned by the specified user ID, the following occurs:
  • The job continues monitoring if the file trigger type is CREATE.
  • The job completes if the file trigger type is DELETE or NOTEXIST.
  • The job fails if the file trigger type is EXPAND, EXIST, SHRINK, or UPDATE.

PERCENT(integer)

Defines the percentage the file size must change for the file trigger to occur.

Limits: Up to 10 characters; the first character must be numeric

RECURSIVE

(Optional) Specifies that the job monitors for file activity in the specified directory and all of its subdirectories.

SIZE(integer[K|M])

Defines a limit on the file size in bytes. If the file trigger type is CREATE or EXPAND, the file trigger occurs when the file size is equal to or greater than the specified size. If the file trigger type is SHRINK, the file trigger occurs when the file size is equal to or less than the specified size.

Limits: Up to 10 characters; the first character must be numeric

Note: You can specify the file size in kilobytes (KB) or megabytes (MB) instead of bytes by appending K or M.

i5/OS: When monitoring a *FILE object in QSYS with no member specified in the file name value, the job monitors the entire object size. The entire object size includes the size of the file object itself and the total size of the file object's members. To only monitor the total size of the file object's members, specify *ALL as the member name.

Notes:

• The default number of seconds the agent waits between scans is 30. If the monitored file changes more than once between scans, the trigger occurs only once, or not at all. For example, if the agent is monitoring updates to a file, and the file is updated twice between scans, the trigger occurs only once. If the agent is monitoring for the creation of a file, and the file is created and deleted between scans, the trigger does not occur. (The file does not exist when the directory is scanned.)
• To change the number of seconds between scans, ask the agent administrator to change the value for the filemonplugin.sleepperiod parameter in the agentparm.txt file. For more information on the filemonplugin.sleepperiod parameter, see the Implementation Guide for your agent. For CA WA Agent for HP Integrity NonStop, you cannot change the number of seconds between scans. The value is hard-coded at 60 seconds.
• If the path showing the location of the file contains spaces, put the entire path in single quotation marks, for example:

  FILENAME 'c:\data files\pay.dat' CREATE
  

• You can use wildcards in the file name value. The asterisk (*) is a wildcard for zero or more characters and the question mark (?) is a wildcard for a single character.

  In the following example, the agent monitors for any file in the /usr/data directory:

  FILENAME '/usr/data/*' CREATE
  

  In the following example, the agent monitors for any file in the /usr/data directory that has a file name with four characters and any extension:

  FILENAME '/usr/data/????.*' CREATE
  

• You cannot use a wildcard as a prefix or within the directory names in the file path.
• When using a wildcard immediately after a forward slash (/), enclose the path in single quotation marks. The quotation marks prevent part of the path from being recognized as a comment line. For example, this statement might not produce the desired results:

  FILENAME /usr/data/* UPDATE
  

  The /* characters are interpreted as the beginning of a comment, so the scheduling manager interprets the statement as follows:

  FILENAME /usr/data CREATE    /* UPDATE
  

  Instead of monitoring for updates to all files in the /usr/data/ directory, the agent monitors for the data file in the /usr/ directory. Also, since CREATE is the default file trigger type and UPDATE is considered part of the comment, the CREATE file trigger type is used instead of the intended UPDATE file trigger type.

• You can specify UNC (Universal Naming Convention) names. A UNC name is the name of a file or other resource that begins with two backslashes (\\), indicating that it exists on a remote computer.
• You can use generic names to specify library names and object names on the i5/OS system. A generic name starts with characters that are part of a valid name and ends with an asterisk (*). The asterisk denotes any number of characters and can only be placed at the end of a generic name.

  The following statement monitors for the creation of any file object in the QSYS file system with a file name that matches the PAY* generic name:

  FILENAME 'LIB/PAY*/*FILE' CREATE
  

  Note: A name cannot contain only a single asterisk and no other characters. To specify all possible names, use the special value *ALL.

CREATE file trigger type Notes:

• If the file name value contains wildcards, the first matching file is selected.
• If the file exists when the job is readied, the trigger occurs immediately. If the file does not exist when the job is readied, the trigger does not occur until the file is created.
• If the specified directory does not exist or is deleted during monitoring, the job fails.
• If the OWNER or GROUP operands are specified, the file trigger occurs only when all specified criteria are satisfied, including the OWNER and GROUP criteria. For example, the following statement monitors for the creation of a file named payroll, owned by JDOE:

  FILENAME /usr/data/payroll CREATE OWNER(JDOE)
  

  If the payroll file is created, but it is not owned by JDOE, the job does not complete. It waits until all specified criteria are satisfied, including the OWNER criteria. If you change the owner of the file to JDOE, the job completes.

DELETE file trigger type Notes:

• If the file does not exist when the job is readied, the file trigger occurs immediately.
• If the specified directory does not exist or is deleted during monitoring, the job fails.
• You can specify the CONTINUOUS operand with DELETE only when you are using a wildcard (* or ?) in the file name value. For example, the following statement triggers an alert named INFO when a file whose name begins with pay is deleted from the /usr/data/ directory:

  FILENAME /usr/data/pay* DELETE CONTINUOUS(INFO)
  

EXIST file trigger type Notes:

• If the file does not exist, the job fails.
• If the file name value contains wildcards, the file with the most recent modification time that matches the criteria is monitored.

EXPAND file trigger type Notes:

• If the file does not exist when the file trigger is set, the job fails.
• Deleting the monitored file causes the job to fail.
• If the job monitors for the file size to reach a value of n (SIZE(n)), the file is monitored until its size increases to n or greater than n. If the file size at initial monitor time is equal to or greater than n, the job completes.
• If the job continuously monitors for the file size to reach a value of n (SIZE(n) CONTINUOUS), the trigger occurs when the size increases to n or more than n. If the file size at initial monitor time is equal to or greater than n, the trigger occurs immediately. After the trigger occurs, the upper limit is set to the new file size and the job continues monitoring based on the new upper limit. For example, this table shows when the trigger will occur if EXPAND SIZE(10K) is set:

• If the job monitors for a change in size by a value of n (DELTA(n)), the specified file is monitored until it increases by n.
• If the job continuously monitors for a change in size by a value of n (DELTA(n) CONTINUOUS), the trigger occurs when the size increases by n. After the trigger occurs, the upper limit is set to the new file size and the job continues monitoring based on the new upper limit.
• If the job monitors for a change in size by percent (PERCENT) and the file size is 0, the trigger occurs when the file size increases.
• If the file name value contains wildcards, and more than one matching file exists, the file with the most current modification time that matches the criteria is monitored for the duration of the trigger. The only way to determine which file is being monitored is to view the debug output.
• If the OWNER or GROUP operands are specified, the file trigger occurs only when all specified criteria are satisfied, including the OWNER and GROUP criteria. If the OWNER or GROUP does not match, the job fails.

NOTEXIST File Trigger Type Notes:

• If the file does not exist, the job completes successfully.
• If the specified directory does not exist or is deleted during monitoring, the job fails.
• If the file name value contains wildcards, the file with the most recent modification time that matches the criteria is monitored.

SHRINK file trigger type Notes:

• If the file does not exist when the file trigger is set, the job fails.
• Deleting the monitored file causes the job to fail.
• If the job monitors for the file size to reach a value n (SIZE (n)), the file is monitored until its size decreases to n or less than n. If the file size at the initial monitor time is equal to or less than n, the job completes.
• If the job continuously monitors for the file size (SIZE(n) CONTINUOUS), the trigger occurs when the size decreases to n or less than n. If the file size at the initial monitor time is equal to or less than n, the trigger occurs immediately. After the trigger occurs, the lower limit is set to the new file size and the job continues monitoring based on the new lower limit. If the file reaches 0 bytes, the trigger does not occur and the job continues to run until you manually complete it.
• If the job monitors for a change in file size by a value of n (DELTA(n)), the specified file is monitored until its size decreases by n. If the file size at the time the trigger is set is less than n, the job completes when the file reaches size 0. For example, if SHRINK DELTA(10K) is set and the initial file size is 5 kilobytes, the job completes when the file reaches 0 bytes.
• If the job continuously monitors for a change in file size (DELTA(n) CONTINUOUS), the trigger occurs when the size decreases by n. After the trigger occurs, the lower limit is set to the new file size and the job continues monitoring based on the new lower limit. If the file reaches 0 bytes, the trigger does not occur and the job continues to run until you manually complete it. For example, suppose that the monitored file has an initial size of 25 KB and the following operands are defined:

  SHRINK DELTA(10K) CONTINUOUS(INFO)
  

  • When the file reaches 15 KB, the trigger occurs. The job continues to monitor the file for shrinkage to 5 KB.
  • When the file reaches 5 KB, the trigger occurs. Since the file is less than 10 KB, the job continues to run until you manually complete it.
  • When the file reaches 0 bytes, the trigger does not occur and the job continues to run until you manually complete it.
• If the file name value contains wildcards, and more than one matching file exists, the file with the most current modification time that matches the criteria is monitored for the duration of the trigger. The only way to determine which file is being monitored is to view the debug output.
• If the OWNER or GROUP operands are specified, the file trigger occurs only when all specified criteria are satisfied, including the OWNER and GROUP criteria. If the OWNER or GROUP criteria does not match, the job fails.

UPDATE file trigger type Notes:

• If the file exists when the job is readied, the trigger occurs when the file is updated.
• If the file does not exist when the job is readied, the job fails.
• If the file exists when the job is readied and is then deleted without modification, the job fails.
• If the OWNER or GROUP operands are specified, the file trigger occurs only when all specified criteria are satisfied, including the OWNER and GROUP criteria. If the OWNER or GROUP criteria does not match, the job fails.
• If the CONTINUOUS operand is specified and a wildcard is used in the file name value, file selection occurs after each trigger. The first matching file with a modification time later than the last trigger time is monitored.

Example: Monitor for an Increase in File Size to a Certain Amount

This example monitors the test file in the data directory. When the test file reaches one byte or more, the job completes.

AGENT NT_NY
FILENAME /data/test EXPAND SIZE(1)

Example: Monitor for an Increase in File Size by a Certain Amount

This example monitors the record file in the credit directory. When the record file expands by two megabytes or more, the job completes.

AGENT UNIX_TOR
FILENAME /credit/record EXPAND DELTA(2M)

Example: Monitor for a Decrease in File Size by a Certain Percentage

This example monitors the test file in the c:\amount directory. When the test file shrinks by 65% or more, the job completes.

AGENT NT_TOR
FILENAME c:\amount\test SHRINK PERCENT(65)

Example: Check that a File Exists in a Directory

This example monitors the money file in the c:\bank\account directory. If the money file exists in that directory, the job completes. If the money file does not exist in that directory, the job fails.

AGENT NT_TOR
FILENAME c:\bank\account\money EXIST

Example: Check that a File Exists in a Directory or Its Subdirectories

This example monitors the c:\bank\account directory and its subdirectories for the money file. If the money file exists in any of the monitored directories, the job completes. If the money file does not exist in any of the monitored directories, the job fails.

AGENT NT_TOR
FILENAME c:\bank\account\money EXIST RECURSIVE

Example: Check that a File Does Not Exist in a Directory

This example monitors the vacation file in the /start/term/ directory. If the vacation file does not exist in that directory, the job completes. If the vacation file exists in that directory, the job fails.

AGENT UNIX_NY
FILENAME /start/term/vacation NOTEXIST

Example: Monitor for an Increase in File Size to a Certain Amount with an Unchanged Condition

This example monitors the analysis file in the research directory. When the analysis file expands by 1 byte or more and remains unchanged for 5 minutes or more, the job completes.

AGENT UNIX_CHI
FILENAME /research/analysis EXPAND SIZE(1) NOCHANGE(5)

Example: Monitor for a Decrease in File Size to a Certain Amount

This example monitors the distribute file in the /cash/items directory. When the distribute file shrinks to 1 KB or less, the job completes.

AGENT UNIX_CHI
FILENAME /cash/items/distribute SHRINK SIZE(1K)

Example: Monitor for a Decrease in File Size by a Certain Amount

This example monitors the cash file in the c:\cost directory. When the cash file shrinks by 10 bytes, the job completes.

AGENT NT_TOR
FILENAME c:\cost\cash SHRINK DELTA(10)

Example: Monitor for an Update to a File in a Directory and its Subdirectories

This example monitors the /usr/data/ directory and its subdirectories for the payroll file. When the payroll file is updated in any of the monitored directories, the job completes.

AGENT UNIX_NY	
FILENAME /usr/data/payroll UPDATE RECURSIVE

Example: Monitor for Updates to All Files in a Directory and its Subdirectories

This example monitors all the files in the /usr/data/ directory and its subdirectories. When any file is updated in any of the monitored directories, the job completes.

AGENT UNIX_NY
FILENAME '/usr/data/*' UPDATE RECURSIVE

Example: Use Wildcards to Specify a File Name on the Root File System

This example monitors for files that are created in the /home/cybesp/ directory in the root file system:

AGENT I5AGENT
FILENAME '/home/cybesp/PID????.*' CREATE

The job completes if a file is created with a file name that matches the following criteria:

• Starts with PID
• Ends with four characters
• Has any extension

Example: Use a Generic Name to Specify a QSYS File Object

In this example, the job completes when any file object with a file name that starts with PAY and ends with any characters is created in the QSYS file system. Note that the file name is enclosed in single quotation marks so that the text following /* is not interpreted as a comment.

AGENT I5AGENT
FILENAME 'LIB/PAY*/*FILE' CREATE

Example: Monitor the Size of a QSYS File Object

In this example, the job completes when the EXPOBJ file object in the QSYS file system increases by 10 bytes or more. Since no member is specified in the file name, the job monitors the entire object size. The entire object size includes the size of the file object itself and the total size of the file object’s members.

AGENT I5AGENT
FILENAME 'LIB/EXPOBJ/*FILE' EXPAND SIZE(10)

Notes:

• The file name is enclosed in single quotation marks so that the text following /* is not interpreted as a comment.
• To monitor only the total size of the file object’s members, specify *ALL as the member name.

Example: Monitor the Same File Using Multiple File Trigger Jobs

In this example, two File Trigger jobs monitor the same file for a change in size by 10 KB and trigger the same alert. One job monitors for an increased change in size and the other job monitors for a decreased change in size. The jobs are independent and do not relate to each other in any way.

AGENT NT_TOR
FILENAME c:\data\totals EXPAND DELTA(10K) CONTINUOUS(MGMT)

AGENT NT_TOR
FILENAME c:\data\totals SHRINK DELTA(10K) CONTINUOUS(MGMT)

Suppose that the initial file size of totals (c:\data\totals) is 100 KB and it changes as follows:

80 KB, 90 KB, 110 KB, 50 KB, 60 KB

The following triggers occur:

• Because of the EXPAND file trigger type, when the file size changes from 90 KB to 110 KB, the first job issues the MGMT alert once.
• Because of the SHRINK file trigger type, the second job issues the MGMT alert twice. The triggers occur when the file shrinks from 100 KB to 80 KB and then again when the file shrinks from 110 KB to 50 KB.