Knowledge Base > Automation Engine and Target Systems > z/OS > Automatic File-System Events

Automatic File-System Events

The z/OS agent supports the monitoring of file systems and file closings. The event is triggered when a file is closed according to the defined conditions.

In an Event object, you can either filter by the file name or specify a series of filter criteria. The latter include the name of the file, the job which has processed the file and its return code.

!Process is processed when the event has been triggered. The script function GET_EVENT_INFO supplies information about the file.

The administrator must set the parameter smfwrite=1 in the INI file of the agent or Event Monitor. Make sure in your z/OS system that the SMF subsystem allows the system exits IEFU83 and IEFU84. The entries 14, 15, 30 and 64 must be logged.

Automatic FileSystem events on PDS members are not supported.

Procedure

Create an Event object of type File System.
Open it and switch to the File System tab.
Select a z/OS agent.
The section Timer control now shows the additional menu item "Automatically". Select it.

File Name as Filter

Enter a file name in the field Path. Use wildcard characters if you intend to monitor several files or specify the exact name if a particular file should be monitored.
The option Startup Event serves to check the file's existence when the Event object is activated. An event is triggered if the file exists.
Enter the script statements to be executed when the event is triggered in the !Process tab. Use the script function GET_EVENT_INFO.
Store the Event object and start it at the time when the file should be monitored.

Several Filter Criteria

Create a file containing the filter criteria on the LPAR on which the agent runs. This file must have a particular format which is described in the table below.
Specify the filter-file name in the field Path. Use the following format: *file(DSNAME)
Example: *file(SGD.PROD.MASSFILTER)
Wildcard characters are not allowed in DSNAME.
Enter the script statements to be executed when the event is triggered in the !Process tab. Use the script function GET_EVENT_INFO.
Note that "Process" is not processed if the filter file contains the specification of an object that should be started.
Store the Event object and start it at the time when the file should monitored.

Filter criteria

The Event Monitor is able to consider several filter criteria upon the notification of a file closing. In this case, the event is only triggered if a particular job has used the file or if a specific return code occurs.

Filter criteria are stored in a separate file which contains one filter definition per line. If several filter definitions apply in an event (e.g. because they overlap), an event is triggered per applicable line.

The filter file must have the DCB attributes RECFM=FB, LRECL=512 and BLKSIZE=5120.

Each filter-file line is limited to 307 characters. The following areas are available:

Filter criteria	Digits	Description
File name	1 to 81	Filters for the file name DS names including PDS members and GDGs are supported. Wildcard characters can be used.
Job name	82 to 89	Filters for the name of the z/OS job which has closed the file The wildcard characters "*" and "?" are allowed.
Job end	90	Waits for the job end Allowed values: " ", "X", "N" or "A" " " - File closing immediately triggers the event. The job end is not waited for. "X" - File closing only triggers the event when the job ends. The return code is irrelevant. "N" - The event is triggered when the job ends normally (return code 0-4095). "A" - The event is triggered when the job ends abnormally (return code 4096-12287). Use the filter criterion "Job return code" to define the expected return codes. When analyzing the job end, the agent either refers to the job end's SMF records or it also considers the records of the STEP ends. Normal and abnormal job ends can be distinguished if only the job end's SMF records are considered. The analysis is more detailed if STEP ends are also considered. In this case, the Event Monitor retrieves the maximum value. The administrator can determine whether only the job end or also STEP ends should be considered when checking the return code. Specifications are made in the Event Monitor's INI file using the parameter smfStepFilter=.
Job return code	91 to 106	Filters for the job's return code (Condition Codes, User Abends and System Abends) Values can be specified as in z/OS or using the AE-specific syntax. If you intend to specify several return codes, separate them with ";" or ",". Areas are defined using "-".
Action	107	Action which should follow the event Allowed values: "Y" and "N" (default value) "Y" - The object specified in the following area is processed instead of !Process. "N" - The object (if specified) is not processed.
Object	108 to 307	Name of the object to be processed You can store a Job object here. Note that the content of !Process is NOT processed. Instead, the object specified here is activated.

For lack of space the following example does not show all 307 characters and the full number of digits:

DEV.DS1         JOBA     A
DEV.DS1         JOBB     A    S806            Y    CALL.ADMIN
UC4.D*.*LIB     TEST2    N    0-12;16-18      Y    MM.CLOSING
SYS1.PARMLIB
TEST.S62*.T*    TEST1    X    11-17;S806

When the Event object starts, the agent reads the filter file and automatically notifies the Event Monitors. Changing filter criteria requires the affected Event object to be restarted or the filter file to be reloaded using the statement MODIFY.

Syntax:

MODIFY Name of the Agent-STC,FEVNT=Name of the filter file

Example:

MODIFY UC600T1,FEVNT=UC600T.FILTER1

Optionally, you can define an object which should be activated in reaction to the occurred event. In this case, the agent stores all information in the input buffer which can be read in the Event object with the script function GET_EVENT_INFO using keywords. Thus, the activated object can retrieve data using the script statement :READ. Use the keywords as variable names.

Example:

:SET &FILENAME# = GET_EVENT_INFO (FILENAME)

:READ &FILENAME#,,