Pre-Notifications

The Pre-Notifications parameter gives you the ability to create a message that is sent to one or more specified destinations when certain conditions are encountered.

Additional information	Description

Usage	Optional
Format	The Pre-Notifications parameter consists of the sub-parameters described below
Variable Support	Yes. A variable or expression can be specified as all or part of the value for this parameter.
Alternate names	Control‑M/EM Utilities: NOTIFICATION Control-M Report: (none) Control‑M/Server Utilities: ‑notification Control‑M for z/OS: NOTIFICATION Control-M/EM API: notification
Sub-parameters
Job's average execution time	Send the message if the job’s elapsed runtime is outside a specified limit. The limit is specified in the Time field. A limit can be expressed as the actual elapsed minutes of the job run, or as a deviation from the job’s (statistical) average runtime. The limit for Job's average execution time can be expressed in any of the following formats: Greater than: The message is sent if the elapsed runtime of the job is greater than n minutes. in z/OS environments, n is a number from 0 through 999. On other computers, n is a number from 1 through 999. Less than: The message is sent if the elapsed runtime of the job is less than n minutes. n is a number from 1 through 999. Exceeds average time: The message is sent if the elapsed runtime of the job exceeds its average execution time by at least n minutes. n is a number from 1 through 999. Percent: The message is sent if the elapsed runtime of the job exceeds/less than its average execution time by at least n%. n is a number from 1 through 900. Less than average time: The message is sent if the elapsed runtime of the job is at least n minutes less than its average execution time. n is a number from 1 through 999. NOTE: A job processing definition can contain more than one notification parameter with a When of Job's average execution time. For more information, see examples of the use of Job's average execution time below.
Job not submitted by time	Send the message if the job is still not submitted and cannot be submitted at the time specified in the accompanying Parm (time) field. Specify the time in hhmm format. Z/OS: Specific Time: Specify the time in hhmm format. Job's calculated time Days:Sets the number of days relative to the ODAT by which the sending of the Notification message is offset. Valid values: a number from 0 through 120 blank – no offset. If the Parm (time) value is , leave this field blank. In the following discussion, time is formatted according to international standard notation. (In Control-M for z/OS, you can alternatively specify an for the time; this results in use of the job’s calculated DUE IN time to determine if the job was not submitted on time.) By default, a valid time must be in the range of 00:00 through 23:59. However, if Time Synonym (in File/Options>Job Properties) is checked, a valid time must be in the range from NewDay time until NewDay Time-plus-23:59. For example, if New Day time is 8:00 A.M., the range of valid times is from 08:00 until 31:59. NOTE: When specifying the time for this parameter, use the hhmm (24-hour time) format. The notification message is sent only if the job is actually not submittable. That is, if a runtime criterion (in condition, quantitative resource, and so on) is not met at the given time. However, if a job is ordered after the specified time but starts running immediately because it meets all runtime criteria, the Job not submitted by time parameter doesn't apply
Job not finished by time	Send the message if the job does not finish executing by the time specified in the accompanying Parameter (time) field. Specify the time in hhmm format. Specify the time in hhmm format. Z/OS: Specific Time: Specify the time in hhmm format. Job's calculated time Days:Sets the number of days relative to the ODAT by which the sending of the Notification message is offset. Valid values: a number from 0 through 120 blank – no offset. If the Parm (time) value is , leave this field blank. In the following discussion, time is formatted according to international standard notation. (In Control-M for z/OS, you can alternatively specify an for the time; this results in use of the job’s calculated DUE OUT time to determine if the job is late.) By default, a valid time must be in the range of 00:00 through 23:59. However, if Time Synonym (in File/Options>Job Properties) is checked, a valid time must be in the range from New Day time until New Day Time-plus-23:59. For example, if New Day time is 8:00 A.M., the range of valid times is from 08:00 until 31:59. NOTE: When specifying the time for this parameter, use the hhmm (24-hour time) format. No message is sent if the job is being rerun.
Job set to rerun	Send the message if the job’s completion status was set to Rerun (not valid for SMART Folders).
Destination	Logical destination of the notification message. Mandatory. Destination is the name of an entry in the Shout Destination table.
	Computers other than z/OS: Valid values a user logged onto the Control‑M installation a user’s mail in the Control‑M installation a specific terminal system console Alerts window in all Control‑M/EM workstations connected to the specified Control‑M installation NOTE: The Control‑M/EM workstations to which an alert is issued may be limited by user authorizations. For more information, see Control-M security in Control-M Administration. Control‑M log All notification messages are recorded in the Control‑M log. Select the log as a destination only when you do not wish to send the message to an additional destination.
	Length	1 through 16 characters
	Case Sensitive	Yes
	Invalid Characters	Blanks; single quotation marks
	Variable Support	Yes. A variable or expression can be specified as all or part of the value for this parameter.
	z/OS: The following are valid values for Destination:
	U-userid	Writes the message to the IOA Log file userid is a user ID consisting of 1 through 8 characters but containing no blanks
	OPER [-n]	Sends a scrollable message to the operator console n is an optional up to 3-digit route code If a route code is not specified, the default routes are Master Console and Programmer Information (1 and 11). For more information regarding route codes, refer to the IBM publication Routing and Descriptor Codes, GC38-1102.
	OPER2[-n]	Sends an unscrollable message to the operator console n is an optional up to 3-digit route code If a route code is not specified, the default routes are Master Console and Programmer Information (1 and 11). For more information regarding route codes, refer to the IBM publication Routing and Descriptor Codes, GC38-1102.
	TSO - logonid or T - logonid	Where logonid is one of the following: a valid logon identity consisting of 1 through 7 characters a valid group identity found within the IOA Dynamic Destination Table An optional second value, indicating the computer or node of the TSO logonid, can be specified, as follows: Under JES2: ;Nn, ;Mm or ;NnMm, where — m is the ID of the computer in JES2 (not the 4-character SMF system ID) — n is the 1- to 2-character JES/NJE node ID Under JES3: Lname, where Lname is the logical JES name of the computer (that is, the name as used in the JES3 command *T, not the SMF system ID)
	TSO - logonid or T - logonid	A notification to a TSO user preforms a TSO SEND command, which may require authorization at the receiving end.
	U-M: mail_ name_ prefix	Sends a message to the recipient identified by mail_name_prefix, a mail name prefix consisting of 1 through 12 characters (z/OS platform: 1 through 8 characters)
	U-EM	Sends a message that is displayed in the Control‑M/EM Alerts window
Urgency	Urgency of the notification message directed to the Alerts window. Urgency assigned to the notification message affects the appearance of the message in the Alerts window. Urgency levels are: R - Regular (Default) U - Urgent V - Very Urgent
Message	Text of the notification message. Length:1 through 255 characters z/OS: 1 through 70 characters Case Sensitive: Yes Invalid Characters: None Variable Support: Yes. The message can include variables, including any combination of text, Control-M system variables, job submission variables and User variables (created using the Variable Assignment parameter). However, the length of the message after decoding cannot exceed the length specified above. For more information, see Control-M Variable facility.

A "notification message" is a message sent to one or more destinations when the condition specified by the When parameter is satisfied.

The Notify parameter (described in Notify) can be used to issue notification messages conditioned by an On Statement/Code parameter.

Notification messages can also be issued from the Control-M/Server using the utility. For more information, see ctmshout in Control‑M Utilities.

When Job's average execution time values are specified with a + or – sign (that is, when elapsed runtime is compared to average runtime), the notification applies only if there are current statistics data for the job (containing statistics for at least one of the last 20 runs of the job).

If current job statistics data exists, all available elapsed-time statistics for the last 20 job runs are averaged to generate the average runtime, and the current runtime is compared to this figure according to the specified criteria.

If no job statistics data exist, or if the data is not current (there are no elapsed-time statistics for any of the last 20 job runs), the notification parameter is not applied.

More about Job's average execution time

The following additional considerations apply to the use of Job's average execution time:

When Job's average execution time values are negative (for example, -n; -n%), the check can be performed only after the job has finished running.
When Job's average execution time values are positive (for example, +n; +n%), the check can be performed (and if the elapsed runtime limits are exceeded, the message can be sent) before the job has finished running.
Relative Job's average execution time limits should not exceed 24 hours. When relative Job's average execution time limits exceed 24 hours (that is, if +n(%) of the average runtime exceeds 24 hours), the message is sent if and when processing reaches 24 hours.

If a relative Job's average execution time is not specified prior to job submission, but is specified afterwards (for example, the job is Held, the parameters changed, and the job then Freed), the Job's average execution time value is ignored.

More about destinations

When the destination is a user, the message is also sent to the user’s mail.

If not found in the Shout Destination table, the destination is assumed to be a user name. In this instance, the notification message is sent to the user’s terminal and the user’s mail.

The Shout Destination table is maintained by the Control‑M administrator. Several such tables may exist. Each table contains the same logical destinations, but the physical (actual) destinations can vary from table to table.

Only one table is in use ("active") at any time, as determined by the administrator. A notification message sent to a logical destination is directed by Control‑M to the corresponding physical destination listed in the active Shout Destination table.

For z/OS jobs

Sends notification message to a specified user when job ends OK

Notification Statements:

When OK
Destination SHIFTMNGR
Urgency R
Message NIGHTSHIFT RUN COMPLETED
The message is sent to Control‑M logical destination SHIFTMNGR.
Sends notification message to Control-M/EM when job terminates NOTOK
If the job terminates with a status of NOTOK, send a message to Control‑M/EM, indicating the completion code:
Notification Statements:
When NOTOK
Destination EM
Urgency U
Message Job NOTOK – Completion code=%%COMPSTAT
The message is sent to the Control‑M/EM Alerts window.

Sends Notification message when job runtime is less than expected

Given that a job whose average run time is 50 minutes completes in 40 minutes. The job processing definition contains a notification statement with When Job's average execution time . The following table indicates which Time parameter values would and which would not cause a notification message to be issued:

Notification Message Issued	Notification Message Not Issue
>39	>40
<41	<40
-10	-11
-20%	-21%

No notification message although job runtime is more than expected

Given that a job whose average run time is 50 minutes completes in 90 minutes. The job processing definition contains a notification statement with When Job's average execution time. The following table indicates which Time parameter values would and which would not cause a notification message to be issued:

Notification Message Issued	Notification Message Not Issue
>89	>90
<91	<90
+41	+40
+79%	+80%

Parent Topic

Actions parameters