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. 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. |
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#,,
See also: