z/OS and Automatic FILE Events

Events in an AE system are objects that you can use to monitor certain conditions and trigger actions. The z/OS Agent can monitor your file system and make sure that files are closed. The event is triggered when a file is closed according to the conditions and filters that have been defined. You can either filter for a file name, or specify several filter criteria such as the name of the file, the Job that has processed the file, and its return code.

The Event Process page is processed when the event has been triggered. The GET_EVENT_INFO script function supplies information about the file. For more information, see GET_CONSOLE, GET_EVENT_INFO.

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

Important! Automatic FILE events on Partitioned Data Set (PDS) members are not supported.

Procedure 

1. Create a FILE event object
2. Open the object and switch to the Attributes page
3. Select a z/OS Agent
4. Go to the File Event page and in the Time Parameters section, activate Automatically

Setting Filter Criteria

The Event Monitor can consider one or several filter criteria when it is notified that a file is closed. In this case, the event only triggers if a particular Job has used the file, or if a specific return code occurs.

Filter criteria are stored in a separate file that contains one filter definition per line. If several filter definitions apply in an event because some of them overlap, an event is triggered per line.

Important! The filter file must have the Data Control Block (DCB) attributes RECFM=VB, LRECL=307, and BLKSIZE=3070.

You can define the following filter criteria:

• File name

  Filters for the file name. Data Set (DS) names including PDS members and GDGs are supported. Wildcard characters can be used.

  Columns: 1 to 81

• Job name

  Filters for the name of the z/OS Job that has closed the file. The wildcard characters * and ? are allowed.

  Columns: 82 to 89

• Job end

  Waits until the Job has ended

  Allowed values:

  • " "

    As soon as the file is closed, the event triggers although the Job has not ended.

  • X

    The file is closed, but the event only triggers when the Job has ended.

    Return codes: Not relevant

  • N

    The event triggers when the Job has ended normally.

    Return codes: 0-4095

  • A

    The event triggers when the Job has ended abnormally.

  Return codes: 4096-12287

  Column: 90

  Notes:

  • The Agent can analyze the Job end in two levels. It can consider the SMF records of the Job end and only distinguish normal and abnormal Job ends. It can additionally consider the SMF records of the STEP ends and achieve a more detailed analysis. In this case, the Event Monitor retrieves the maximum return-code value from each step.

  • Your system administrator can determine whether only the Job end or also STEP ends should be considered when checking the return code. The definitions must be set in the INI file of the z/OS Event Monitor with the smfStepFilter= parameter.

  • Define the filter criterion Job return code to set the expected return codes.

• Job return code

  Filters for the Job's return code such as Condition Code, User Abend, and System Abend. For more information, see Return Codes of z/OS Jobs

  Allowed values: Values are defined in z/OS or by using the AE-specific syntax.

  Return codes: Several return codes must be separated with a semicolon (;) or a colon (,). You can define from - to areas using a hyphen (-).

  Columns: 91 to 106

• Action

  Action that should follow the event

  Allowed values:

  • Y: The object that is defined in the Object filter criterion will be processed instead of the definitions that are available on the Event Process page.

  • N: The object (if specified) is not processed.

  Column: 107

• Object

  Name of the object that should be processed. You can store a Job object here.

  Important! The content of the Event Process page is ignored if you make a definition here.

  Columns: 108 to 307

Using the File Name as a Filter

1. In the File Event section, enter a dataset name in Path.
2. Enter the script statements that should be executed when the event triggers in the Event Process page. Use the script function GET_CONSOLE, GET_EVENT_INFO for this purpose, and see the example below for details.
3. Save the Event object and execute it when you want to monitor the file.

Using Several Filter Criteria

1. Create a file that contains the filter criteria on the LPAR on which the Agent runs. This file must fulfill the relevant filter criteria.
2. Specify the name of the filter file in Path in the File Event section.
   Format: *FILE(DSNAME)
   Example: *FILE(SGD.PROD.MASSFILTER)
   Wildcard characters are not allowed in DSNAME.
3. Enter the script statements that should be executed when the event triggers in the Event Process page. Use the script function GET_CONSOLE, GET_EVENT_INFO for this purpose, and see the example below for details.
   Important! Note that the Event Process page is not processed if the filter file includes the specification of an object that should start.
4. Save the Event object and execute it when the file should be monitored.

Using Extended Filter Criteria

Extended filter criteria allow you to use the Path field of a File Event to filter not only by dataset name, but also by Job end status or return code (completion code).

Note: The filter is used directly by the Event Monitor. Therefore, it is no longer necessary to create a filter file beforehand on mainframe systems.

The filter criteria uses the following format:

file_name/dataset_name; job_name; job_end; job_return_code

Examples

• To trigger events where the dataset name matches a specific pattern, the job ended normally and the job return code is between 0 and 16:

  *.TRG007.PDS;*;N;0-16

• To trigger events where the dataset name matches a specific pattern, the job ended abnormally and job return code is S806 or S807:

  *.TRGXYZ.PDS;*;A;S806-S807

Examples

The following sample is only an excerpt of a filter file and does not show all 307 characters, nor the full number of columns:

DEV.DS1        JOBA     A    
DEV.DS1        JOBB     A    S806            Y    CALL.ADMIN
AE.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 Monitor. When you change your filter criteria, you must restart the affected Event object or reload the filter file by using the MODIFY command:

Syntax

MODIFY Name of the Agent 's started task,FEVNT=Name of the filter file

Example

MODIFY UC600T1,FEVNT=UC600T.FILTER1

(Optional) You can define an object that should be activated in reaction to the occurred event. In this case, the Agent stores all information in the input buffer. This information can be read from the Event object with the script function GET_EVENT_INFO by using keywords. The activated object retrieves data by using the :READ script statement. Use the keywords as variable names.

Example

:SET &FILENAME# = GET_EVENT_INFO (FILENAME)

:READ &FILENAME#,,

See also:

• Event Monitor
• OS/390 JOBS
• FILE Events