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

Automatic File-System Events

The z/OS agentA program that enables the de-centralized execution of processes (such as deployments) on target systems (computers or business solutions) or a service that provides connectivity to a target system (such as for databases or middleware). An agent is also an object type in the Automation Engine. [Formerly called "Executor."] See also: host supports the monitoring of file systems and file closings. The eventAction that is triggered if particular conditions apply. It can be an Automation Engine object type or an entry in a Policy Orchestrator EventBase. is triggered when a file is closed according to the defined conditions.

In an Event objectAutomation Engine controlled activities and processes are structured in the form of objects. See also: Task, you can either filter by the file name or specify a series of filter criteria. The latter include the name of the file, the jobAn Automation Engine object type for a process that runs on a target system. which has processed the file and its return codeThe value that represents the result of tasks and script functions..

!Process is processed when the event has been triggered. The scriptA particular Automation Engine object type. functionPre-defined run book template in the Automation Engine. One single step only, e.g. Start Windows Service, Copy file,… 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 

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

File Name as Filter

  1. Enter a file name in the field Path. Use wildcard charactersThese are placeholders for characters when you specify filters. ? stands for exactly one character, * for any number of characters. if you intend to monitor several files or specify the exact name if a particular file should be monitored.
  2. 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.
  3. Enter the script statements to be executed when the event is triggered in the !Process tab. Use the script function GET_EVENT_INFO.
  4. Store the Event object and start it at the time when the file should be monitored.

Several Filter Criteria

  1. 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.
  2. 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.
  3. 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.
  4. 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 notificationAn Automation Engine object type used to send messages to users and user groups. [Formerly called "CallOperator."] 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 variableIt stores or retrieves values dynamically at runtime. An individual Automation Engine object type. names.

Example:

:SET &FILENAME# = GET_EVENT_INFO (FILENAME)

:READ &FILENAME#,,

 

See also:

GET_EVENT_INFO
Event Monitor

 


Automic Documentation - Tutorials - Automic Blog - Resources - Training & Services - Automic YouTube Channel - Download Center - Support

Copyright © 2016 Automic Software GmbH