Chapter 9: File Trigger Jobs

Chapter 9: File Trigger Jobs 

File Trigger Jobs :

File Trigger jobs let you monitor file activity. You can define File Trigger jobs for UNIX, 

Linux, Windows, or i5/OS systems. 

Note: To run these jobs, your system requires CA WA Agent for UNIX, Linux, Windows, 

or i5/OS. 

The File Trigger job can monitor when a file is created, updated, deleted, expanded, or 

shrunk, and when a file exists or does not exist. 

Example: Monitor for an Update to a File 

Suppose that a File Trigger job named PAYDATA monitors for an update to the 

payroll.dat file on a Windows computer. When the file is updated, the job completes 

and the scheduling manager releases a job named PAYRUN. 

 Define a File Trigger Job 

The following diagram shows the scenario: 

Define a File Trigger Job 

You can define a File Trigger job to monitor when a file is created, updated, deleted, 

expanded, or shrunk, and when a file exists or does not exist. By default, File Trigger 

jobs monitor for the existence of a file. 

Note: To run these jobs, your system requires CA WA Agent for UNIX, Linux, or 

Windows. 

Follow these steps: 

1. Insert a job and specify the following attributes in the definition: 

job_type: FT 

Specifies that the job type is File Trigger. 

machine 

Specifies the name of the machine on which the job runs. 

watch_file 

Specifies the path to and name of one or more files to monitor. 

 Define a File Trigger Job 

Chapter 9: File Trigger Jobs 283 

2. (Optional) Specify optional File Trigger attributes: 

■ continuous 

■ job_class 

■ job_terminator 

■ watch_file_change_type 

■ watch_file_change_value 

■ watch_file_groupname 

■ watch_file_owner 

■ watch_file_recursive 

■ watch_file_type 

■ watch_file_win_user 

■ watch_no_change 

3. (Optional) Specify common attributes that apply to all job types. 

The File Trigger job is defined. When the job runs, it monitors for the existence of 

the specified file. 

Notes: 

■ Attributes that have a default value automatically apply to the job definitions; 

therefore, they are optional. For example, jobs with no specified job type are 

defined as command jobs by default. Other optional attributes specify information 

that is not required but affects how or when a job runs, such as attributes that 

specify scheduling conditions. 

■ Some optional attributes are common to all job types but others apply to certain 

jobs types only. Optional attributes that apply to all job types are known as 

common optional attributes. For more information about common optional 

attributes and the values that you can specify for them (including their default 

values when applicable), see the Reference Guide. 

■ For information about required attributes and job type specific optional attributes, 

see the procedure topics that provide instructions for defining jobs. 

■ This guide provides instructions for defining jobs interactively. You also create job 

definitions in script files and then import them using the jil command or use CA 

WCC to define them. For more information about the JIL command and JIL syntax, 

see the Reference Guide. For more information about using CA WCC to define the 

job, see the CA Workload Control Center Workload Scheduling Guide. 

 Monitor for Other Types of File Activity 

284 User Guide 

Example: Monitor for the Existence of a File 

This example monitors for the existence of the batch.input file in the tmp directory. If 

the file exists in the directory, the job completes. If the file does not exist in that 

directory, the job fails. 

insert_job: ft_job 

job_type: FT 

machine: unixagt 

watch_file: /tmp/batch.input 

watch_file_type: EXIST 

More information: 

Insert a Job Definition (see page 88) 

Monitor for Other Types of File Activity 

A File Trigger job checks for the existence of a file by default. You can define the job to 

monitor for other types of file activity. 

Follow these steps: 

1. Define a File Trigger job (see page 282). 

2. Add the following attribute to the job definition: 

watch_file_type 

Specifies the type of file activity that a File Trigger job monitors for. Choose one 

of the following options: 

■ CREATE—Indicates that the file trigger occurs when the file is located and 

remains unchanged for the amount of time specified in the 

watch_no_change attribute. When the watch_no_change attribute is not 

specified, the trigger occurs as soon as the file is located. A file that exists 

when the job starts is located during the first scan, which occurs 30 

seconds after the job starts. Subsequent scans occur every 30 seconds, so 

a file that does not exist when the job starts is located a maximum of 30 

seconds after it is created. 

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

 Monitor for Other Types of File Activity 

Chapter 9: File Trigger Jobs 285 

■ EXPAND—Indicates that the file trigger occurs when the file meets the 

specified size requirements and then remains unchanged for the amount 

of time specified in the watch_no_change attribute. When the 

watch_no_change attribute is not specified, the trigger occurs as soon as 

the size requirements are met. When the file meets the size requirements 

before the job starts, the job detects this during the first scan. In this case, 

the trigger occurs 30 seconds after the job starts unless the 

watch_no_change attribute is specified. The size requirement is met when 

the file is equal to or larger than the specified size or expands by at least 

the specified amount, depending on the type of size change that you 

specify in the job definition. 

■ SHRINK—Indicates that the file trigger occurs when the file meets the 

specified size requirements and then remains unchanged for the amount 

of time specified in the watch_no_change attribute. When the 

watch_no_change attribute is not specified, the trigger occurs as soon as 

the size requirements are met. When the file meets the size requirements 

before the job starts, the job detects this during the first scan. In this case, 

the trigger occurs 30 seconds after the job starts unless the 

watch_no_change attribute is specified. The size requirements are met 

when the file is equal to or smaller than the specified size or shrinks by at 

least the specified amount. 

■ UPDATE—Indicates that the file trigger occurs when the file is updated and 

then remains unchanged for the amount of time specified in the 

watch_no_change attribute. When the watch_no_change attribute is not 

specified, the trigger occurs as soon as the file is updated. 

■ GENERATE—Indicates that the trigger occurs when the file is created or 

updated and then remains unchanged for the amount of time specified in 

the watch_no_change attribute. When the watch_no_change attribute is 

not specified, the trigger occurs as soon as the file is created or updated. 

Note: If the file exists when the job starts and is not updated after the job 

starts, no trigger occurs. In this case, the job does not complete and remains in 

the RUNNING state indefinitely. 

 Monitor for Other Types of File Activity 

286 User Guide 

3. (As applicable) Specify the size change information. Ensure that you specify this 

information for any job that monitors for the creation of a file or for a change in the 

size of file; otherwise, it is not applicable. To specify size change information, enter 

the following attribute arguments: 

[watch_file_change_type: {DELTA|PERCENT|SIZE}] 

watch_file_change_value: value 

[watch_file_change_type: {DELTA|PERCENT}] 

(Optional) Specifies the type of size as follows: 

By default, the trigger occurs when the file expands to or shrinks to the 

specified size. To issue a trigger when a file expands or decreases by a specified 

amount, include this argument. You can measure expansion or shrinkage as a 

percentage of total size or as a specific amount. 

watch_file_change_value: value 

Specifies a number of bytes or a percentage depending on the type of size 

change you specified. The trigger occurs when the file expands to at least the 

specified size or by at least the specified amount, when the file shrinks by at 

least the specified amount, or when the file shrinks to the specified size or less. 

When monitoring for a specific size or for a change in size that is not a 

percentage change, specify the value in bytes. When measuring size change as 

a percentage of the total size, specify a value between 1 and 100. 

4. Run the job. 

The job monitors the file for the specified activity. 

Notes: 

■ For more information about JIL job types and other job definition attributes, the 

values that you can specify for those attributes, and JIL syntax, see the Reference 

Guide. 

■ By default, the agent scans for the monitored conditions every 30 seconds. If the 

file changes more than once between scans, the trigger occurs only once or not at 

all. For example, suppose that your job monitors for the creation of a file and that 

file is created and deleted between scans. The trigger does not occur because the 

file does not exist when the directory is scanned. 

Example: Monitor the Creation of a File 

This example monitors for the creation of a file named monthly.log. The job completes 

when the file is created. 

insert_job: ft_job 

job_type: FT 

machine: ftagt 

watch_file: "c:\data\monthly.log" 

watch_file_type: CREATE Monitor for Other Types of File Activity 

Chapter 9: File Trigger Jobs 287 

Example: Monitor the Creation and Stability of a File 

This example monitors for the creation of a file named monthly.log. The job completes 

when the file is created and has not changed for consecutive watch_no_change polling 

intervals. 

insert_job: ft_job 

job_type: FT 

machine: ftagt 

watch_file: "c:\data\monthly.log" 

watch_file_type: GENERATE 

watch_no_change: 2 

Example: Monitor for the Deletion of Files with Names Beginning with Pay 

This example continuously monitors the /usr/data/ directory for files that have names 

beginning with pay. When all files that have a name beginning with pay are deleted, the 

job completes successfully. 

insert_job: ftjob 

job_type: FT 

machine: ftagt 

watch_file: /usr/data/pay* 

watch_file_type: DELETE 

continuous: Y 

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

This example defines a job named ft_unix_delta to monitor the file named record in the 

credit directory and issue a trigger when the file increases in size by at least 200000 

bytes and then remains unchanged for 30 minutes. 

insert_job: ft_unix_delta 

job_type: FT 

machine: unixagt 

watch_file: /credit/record 

watch_file_type: EXPAND 

watch_file_change_type: DELTA 

watch_file_change_value: 200000 

watch_no_change: 30 Attributes with Default Values 

288 User Guide 

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

This example defines a job named ft_unix_notexist to search the /start/term/ directory 

for a file named vacation and to issue a trigger if the file does not exist. 

insert_job: ft_unix_notexist 

job_type: FT 

machine: unixagt 

watch_file: /start/term/vacation 

watch_file_type: NOTEXIST 

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

This example defines a job named ft_unix_shrink to issue a trigger when the file named 

distribute that is located in the /cash/items directory is 1000 bytes or smaller. 

insert_job: ft_unix_shrink 

job_type: FT 

machine: unixagt 

watch_file: /cash/items/distribute 

watch_file_type: SHRINK 

watch_file_change_type: SIZE 

watch_file_change_value: 1000 

Example: Monitor for Updates to Any of the Files in a Directory and its Subdirectories 

This example defines a job named ft_unix_update to monitor the /usr/data/ directory 

and all of its subdirectories and to issue a trigger when any file that is located in those 

directories is updated and then is not modified again during the next 30 minutes. 

insert_job: ft_unix_update 

job_type: FT 

machine: unixagt 

watch_file: "/usr/data/*" 

watch_file_type: UPDATE 

watch_file_recursive: Y 

watch_no_change: 30 

Attributes with Default Values 

Attributes that have a default value automatically apply to the job definition. Therefore, 

you do not have to specify those attributes in the definition. Your agent administrator 

can define some default values on the agent in the agentparm.txt file. 

If you specify the attribute in a job definition, it overrides the default. 

 Attributes with Default Values 

Chapter 9: File Trigger Jobs 289 

The following File Trigger job attributes have default values: 

continuous 

Specifies whether the job monitors the file continuously for a specified condition. 

Default: N (The job immediately checks for the condition and completes.) 

watch_file_recursive 

Specifies whether the job monitors for file activity in the specified directory only or 

in the specified directory and all of its subdirectories. 

Default: N (The job does not monitor subdirectories.) 

watch_file_change_type 

Specifies the type of change to detect when monitoring a file for an increase or 

decrease in size.. 

Default: SIZE (The job monitors the file to reach a specified size.) 

watch_file_type 

Specifies the type of file activity to monitor for. 

Default: CREATE (The job monitors for the creation of a file.) 

watch_no_change 

Defines the number of minutes the file must remain unchanged to satisfy the 

monitor condition. 

Default: 1 (The file must remain unchanged for 1 minute.) 

Note: For more information about JIL job types and other job definition attributes, the 

values that you can specify for those attributes, and JIL syntax, see the Reference Guide. 

Example: Override Default Values 

The watch_file_type and watch_no_change attributes in the following job definition 

override the default values. 

In this example, the unixagt agent monitors the analysis file in the /research directory. If 

the file size expands to 1 byte or more and remains unchanged for 120 minutes or more, 

the job completes. 

insert_job: ft_unix_nochange 

job_type: FT 

machine: unixagt 

watch_file: /research/analysis 

watch_file_type: EXPAND 

watch_file_change_type: SIZE 

watch_file_change_value: 1 

watch_no_change: 120 Monitor a File Continuously 

290 User Guide 

Monitor a File Continuously 

You can define a File Trigger job to monitor a file continuously for a CREATE, GENERATE, 

EXPAND, UPDATE, DELETE, or SHRINK condition. Each time the condition occurs, an alert 

is written to the scheduler log file (event_demon.$AUTOSERV on UNIX and 

event_demon.%AUTOSERV% on Windows). 

If a job monitors for the deletion of files, the job completes when all the monitored files 

are deleted or it is completed manually. For all other conditions, the job continues to 

monitor until it is completed manually. 

Note: You cannot define File Trigger jobs to monitor a file continuously for the EXIST or 

NOTEXIST conditions. 

Follow these steps: 

1. Define a File Trigger job (see page 282). 

2. Add the following attribute to the job definition: 

continuous 

Specifies whether the job monitors the file continuously for a specified 

condition. 

3. Run the job. 

The specified file is monitored continuously. 

Note: For more information about JIL job types and other job definition attributes, the 

values that you can specify for those attributes, and JIL syntax, see the Reference Guide. 

E 

Example: Continuously 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. 

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. 

insert_job: ftjob1 

job_type: FT 

machine: ftagent 

watch_file: "c:\data\totals" 

watch_file_type: EXPAND 

continuous: Y 

watch_file_change_type: DELTA 

watch_file_change_value: 10240 /* The value must be entered in bytes (10 x 1024 bytes 

= 10240) */ Monitor a File that is Owned by a UNIX Owner or Group 

Chapter 9: File Trigger Jobs 291 

insert_job: ftjob2 

job_type: FT 

machine: ftagent 

watch_file: "c:\data\totals" 

watch_file_type: SHRINK 

continuous: Y 

watch_file_change_type: DELTA 

watch_file_change_value: 10240 /* The value must be entered in bytes (10 x 1024 bytes 

= 10240) */ 

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

follows: 

100 KB (initial size), 80 KB, 90 KB, 110 KB, 50 KB, 60 KB 

The following triggers occur: 

■ Because the file trigger type is EXPAND, the first job (ftjob1) writes an alert to the 

scheduler log file once when the file size changes from 90 KB to 110 KB. 

■ Because the file trigger type is SHRINK, the second job (ftjob2) writes an alert to the 

scheduler log file 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. 

The jobs end when they are forced to complete. 

Monitor a File that is Owned by a UNIX Owner or Group 

You can define a File Trigger job to monitor a file that is owned by a specific UNIX owner 

or group. If the file is not owned by the specified owner or group, the following occurs: 

■ The job continues monitoring if the file trigger type is CREATE or GENERATE. 

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

Note: You can monitor a file owned by a specific owner or group on i5/OS if the file is 

not a QSYS object. 

Follow these steps: 

1. Define a File Trigger job (see page 282). 

2. Add one or more of the following attributes to the job definition: 

watch_file_groupname 

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

watch_file_owner 

Specifies the user ID that owns the file to be monitored. 

 Monitor a File that is Owned by a UNIX Owner or Group 

292 User Guide 

3. Run the job. 

The specified file is monitored. 

Note: For more information about JIL job types and other job definition attributes, the 

values that you can specify for those attributes, and JIL syntax, see the Reference Guide. 

Example: Monitor for the Creation of a File that Is Owned by a Specified UNIX User ID 

This example defines a job named ft_job to issue a trigger in the following situations: 

■ When a file named payroll with attributes that specify JDOE as the file owner is 

created and is not modified within the first 30 minutes of existence. 

■ When a file named payroll with attributes that specify JDOE as the file owner exists 

before the job starts, is located during the first scan, and is not modified within the 

following 30 minutes. 

■ When the owner of the file named payroll changes to JDOE and the file is not 

modified within the next 30 seconds. 

insert_job: ft_job 

job_type: FT 

machine: ftagt 

watch_file: /usr/data/payroll 

watch_file_type: CREATE 

watch_file_owner: JDOE 

■ watch_no_change: 30 

Example: Monitor for the Existence of a File that Is Owned by a Specified UNIX Group 

Suppose that you want a job to monitor for the existence of the /data/payroll.dat file 

that is owned by the UNIX group ACCTS: 

■ If the file exists and the file is owned by the group ACCTS when the job is readied, 

the job completes immediately. 

■ If the file exists and the file is not owned by the group ACCTS when the job is 

readied, the job fails. 

insert_job: ft_unixgroup 

job_type: FT 

machine: unixagent 

watch_file: /data/payroll.dat 

watch_file_type: EXIST 

watch_file_groupname: ACCTS Configure the Agent to Run File Trigger Jobs as an External Process 

Chapter 9: File Trigger Jobs 293 

Configure the Agent to Run File Trigger Jobs as an External 

Process 

File Trigger jobs typically run as threads under the CA Workload Automation Agent 

process. If you want to monitor files with names that contain variables, or if you want to 

monitor a file on a remote computer, you must run the job as an external process. 

To configure the agent to run File Trigger jobs as an external process, ask your agent 

administrator to set the following parameters in the agent's agentparm.txt file: 

filemonplugin.runexternal=true 

oscomponent.default.user=user 

oscomponent.default.password=password 

filemonplugin.runexternal=true 

Runs File Trigger jobs run as an external process. 

oscomponent.default.user=user 

(Optional) Specifies the default operating system user ID that all jobs on the agent 

computer run under. This user ID must have access to all files monitored by all File 

Trigger jobs. 

Note: If this parameter is not set, File Trigger jobs run under the user ID that started 

the agent. 

oscomponent.default.password=password 

(Optional) Specifies the password for the default user ID. 

Resolve File Names That Contain Variables 

You can define a File Trigger job that monitor a file whose name contains variables. To 

resolve the variables in the file name, the agent runs the File Trigger job as an external 

process. 

Follow these steps: 

1. Configure the agent to run File Trigger jobs as an external process (see page 293). 

2. Define a File Trigger job (see page 282). 

3. Add the following attribute: 

watch_file 

Specifies the path to and name of one or more files to monitor. You can specify 

file names that contain variables. 

Example: $AUTOSYS/reports/august2011.out 

 Monitor a File on a Remote UNIX Computer 

294 User Guide 

4. Run the job. 

The specified files are monitored. 

Note: For more information about JIL job types and other job definition attributes, the 

values that you can specify for those attributes, and JIL syntax, see the Reference Guide. 

Example: Monitor for the Existence of a File 

This example monitors for the existence of the august2011.out file on the unixagt 

machine. The job monitors the directory specified by the $MY_PATH variable. The job 

runs under the user that started the unixagt agent. The filemonplugin.runexternal agent 

parameter is set to true. If the file exists in the directory, the job completes. If the file 

does not exist in that directory, the job fails. 

insert_job: ft_job 

job_type: FT 

machine: unixagt 

watch_file: $MY_PATH/reports/august2011.out 

watch_file_type: EXIST 

Monitor a File on a Remote UNIX Computer 

You can define a File Trigger job to monitor remote files across a UNIX network using a 

specified user ID. 

Follow these steps: 

1. Configure the agent to run File Trigger jobs as an external process (see page 293). 

2. Define a File Trigger job (see page 282). 

3. Add the following attribute: 

watch_file 

Specifies the path to and name of one or more files to monitor. You can specify 

file names that contain variables and remote files on a UNIX network. 

Example: $AUTOSYS/reports/august2011.out 

4. Run the job. 

The specified files are monitored. 

Note: For more information about JIL job types and other job definition attributes, the 

values that you can specify for those attributes, and JIL syntax, see the Reference Guide. 

 Monitor a File on a Remote Windows Computer 

Chapter 9: File Trigger Jobs 295 

Example: Monitor for the Existence of a File 

This example monitors for the existence of the august2011.out file on the unixagt 

machine. The job monitors the directory specified by the $MY_PATH variable. The job 

runs under the user that started the unixagt agent. The filemonplugin.runexternal agent 

parameter is set to true. If the file exists in the directory, the job completes. If the file 

does not exist in that directory, the job fails. 

insert_job: ft_job 

job_type: FT 

machine: unixagt 

watch_file: $MY_PATH/reports/august2011.out 

watch_file_type: EXIST 

owner: jsmith 

Monitor a File on a Remote Windows Computer 

You can define a File Trigger job to monitor a file on a remote Windows system if the 

agent runs as a Windows service under the local system account. 

Follow these steps: 

1. Verify with your agent administrator that the agent is running as a Windows service 

under the local system account. 

2. (Optional) Ask your agent administrator to set the following parameters in the 

agent's agentparm.txt file: 

oscomponent.default.user=user 

oscomponent.default.password=password 

oscomponent.default.user=user 

Specifies the default operating system user ID that all jobs on the agent 

computer run under. This user ID must have access to the monitored files. 

Notes: 

■ The watch_file_win_user attribute overrides this parameter. 

■ If this parameter is not set, you must specify the watch_file_win_user 

attribute in the File Trigger job definition. 

oscomponent.default.password=password 

Specifies the password for the default user ID. 

Note: If this parameter is not set, you must specify the watch_file_win_user 

attribute in the File Trigger job definition and define the corresponding user ID 

and password via autosys_secure. 

 Monitor a File on a Remote Windows Computer 

296 User Guide 

3. Ask your CA Workload Automation AE administrator to define a user ID and 

password on CA Workload Automation AE that has access to the file on the remote 

Windows computer. 

4. Define a File Trigger job (see page 282). 

5. Add the following attributes to the job definition: 

watch_file 

Specifies the path to and name of one or more files to monitor. Specify a UNC 

(Universal Naming Convention) name. 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. 

watch_file_win_user 

Specifies the user ID and the domain the user ID belongs to. This user ID must 

have access to the remote files in the UNC path. This attribute overrides the 

oscomponent.default.user parameter on the agent. 

6. Run the job. 

The specified file on the remote Windows computer is monitored. 

Note: For more information about JIL job types and other job definition attributes, the 

values that you can specify for those attributes, and JIL syntax, see the Reference Guide. 

Example: Monitor for an Update to a File on a Remote Windows Computer 

This example monitors for an update to the payroll.dat file on a remote Windows 

computer named CYBNT. The job runs under JSMITH, which is a user ID on CYBNT and is 

in the CYBDOM domain. JSMITH is defined on the scheduling manager and has access to 

the AccountingFiles directory. The winagent machine must have been defined to CA 

Workload Automation AE with the opsys: windows attribute. 

insert_job: ft_remotefile 

job_type: FT 

machine: winagent 

watch_file: \\CYBNT\AccountingFiles\payroll.dat 

watch_file_type: UPDATE 

watch_file_win_user: CYBDOM\JSMITH@CYBDOM