|
|
|
|
|
The message is sent to the specified destination when the WHEN condition is satisfied. The relationship between multiple SHOUT statements is OR (that as, each statement is evaluated and performed independently of the others).
AutoEdit variables (system- and/or user-defined) in the message text are supported and automatically resolved (replaced) when the SHOUT message is issued. For more information, see JCL and AutoEdit Facility.
SHOUT statements can also be defined in SMART Table Entities, where they are used in a manner similar to jobs. For example, SHOUT WHEN OK is activated when all the jobs in the SMART Table end OK.
The WHEN Subparameter
If SHOUT WHEN EXECTIME values are stated with a + or – sign, that is, when elapsed runtime is compared to average runtime, the shout applies only if there is a Job Statistics record for the job, containing statistics for at least one of the last 200 runs of the job.
If a Job Statistics record exists, all available elapsed-time statistics for the last 200 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 file exists, or a record for the job does not exist, that is, there are no elapsed-time statistics for any of the last 200 job runs, the SHOUT is not activated.
Note: Your INCONTROL administrator can tell you if the job has a Statistics file, and if the Statistics file is updated after each job run.
If EXECTIME values are negative (that is, if they are –n or –n%), the check can be performed only after the job has finished running.
When EXECTIME values are positive (that is, if they are +n or +n%), the check can be performed (and if the elapsed runtime limits are exceeded, the message can be "shouted") before the job has finished running.
When Control-M calculates EXECTIME values, such as job start time, average execution time, actual elapsed time, shout message time, and so on, calculations are made only in minutes, and seconds are ignored. Therefore, the results of expressions such as SHOUT WHEN EXECTIME >001 (or +001) are unpredictable. BMC recommends that you use SHOUT WHEN EXECTIME only when you need to monitor jobs of more than a few minutes duration.
Relative EXECTIME limits must not exceed 24 hours. When relative EXECTIME limits exceed 24 hours (such as if +n(%) of the average runtime exceeds 24 hours), the message is "shouted" if and when processing reaches 24 hours.
If a relative EXECTIME is not specified prior to job submission, but is specified afterwards (that is, the job is held, the parameters changed in the Zoom screen, and the job is then freed), the EXECTIME value is ignored.
When the New Day procedure runs, any unexecuted SHOUT statements that relate to jobs ordered on the previous day are automatically cancelled.
If, when you order jobs, you often specify a LATE or LATESUB time that crosses the New Day time, you should consider implementing Wish WM2344. This Wish enables jobs to operate with a "shifted" New Day time for SHOUT purposes. You can find Wish WM2344 in the IOADFLT member in the IOA IOAENV library.
If you want only some specific jobs to operate with a "shifted" New Day time for SHOUT purposes, you may not want to implement Wish WM2344. An alternative method for use in such a case is illustrated in SHOUT Example 4 in Examples for SHOUT.
The TO Subparameter
Specify TO=USERID-userid to write the message to the IOA Log file under the user ID specified in the parameter.
Specify TO=OPER[–n] to send the message to the operator console (route code n). If the n value is omitted, the message is sent to all consoles to which route codes 1 or 11 are assigned. For more detailed information regarding route codes, refer to the IBM publication Routing and Descriptor Codes, GC38-1102. Optionally, the message can also be sent to the Control-M/Enterprise Manager user. This is described in "Shouting to Control-M/Enterprise Manager" below.
Specify TO=OPER2[–n] to send a highlighted, unrollable message to the operator console (route code n). If the n value is omitted, the message is sent to all consoles to which route codes 1 or 11 are assigned. For more detailed information regarding route codes, refer to the IBM publication Routing and Descriptor Codes, GC38-1102. Optionally, the message can also be sent to the Control-M/Enterprise Manager user, as described in the following section, "Shouting to Control-M/Enterprise Manager".
Specify TO=TSO-id or T-id to send the message to a groupid or logonid. The Shout facility first searches the IOA Dynamic Destination table for the specified ID. If the table contains an entry (groupid) that matches the value, the content of the entry is used as the target for the shouted message. (The entire TO field is used. Therefore, when directing the message to a remote user, do not append Nn or Mm. Instead, do this in the IOA Dynamic Destination Table itself. For more information, see the discussion of Destination Tables in the INCONTROL for z/OS Administrator Guide.)
If no matching ID is found in the Dynamic Destination table, the Shout facility assumes the specified ID is a logonid. It then creates a TSO message that it hands over to MVS. MVS then sends the message to that logonid. (If the logonid does not exist, MVS cannot send the message, but no error message is generated.) When a second value is used, the message is sent to the TSO logonid in the specified computer or node (machine ID). To determine the machine ID under JES2, specify JES command $D MEMBER.
Specify TO=U-M: email_dest to send the message by e-mail to the recipient identified by the variable (email_dest). For more information about mail destinations, see the INCONTROL for z/OS Administrator Guide. The IOAPARM member includes DFLTSFFX, the mail address suffix, such as MAIL.DOMAIN.COM, the SMTP STC name, and the HOSTNAME. If installation parameter ATTSYSOT=Y, the job's SYSOUT will be attached to the e-mail message.
Specify TO=U-S:snmp_dest to send the SNMP trap (message) to the recipient identified by snmp_dest. For more information about mail destinations, see the INCONTROL for z/OS Administrator Guide.
Shouting to Control-M/Enterprise Manager
For Control-M to be able to shout to Control-M/Enterprise Manager, the following conditions must be satisfied at the site:
When OPER2ECS is set to Y:
Once the above conditions are satisfied, messages can be shouted to Control-M/Enterprise Manager by specifying a destination of TO=OPER or TO=OPER2 (without a route code qualifier) or TO=U-ECS.
Such messages are then placed by Control-M in the M2G file. Once the shouted message is in the M2G file, the Control-M Application Server reads the file and sends the message to the Control-M/Enterprise Manager user.
The URGN Subparameter
The URGN value indicates the urgency level of the message.
In addition, if the destination is USERID–userid (or U–userid), the user can control, according to urgency, which messages are displayed when the IOA Log file is accessed. Urgent and very urgent messages are highlighted on the screen. For more details, see IOA Log Facility.
Differences between SHOUT and DO SHOUT
SHOUT and DO SHOUT statements have the following differences:
By contrast, a SHOUT statement requires that a value be specified, in the WHEN subparameter, indicating when to shout the message. Messages can be shouted when the job ends OK or NOTOK, when the job is late for submission or completion, or when the job runs too long.
The SHOUT MS subparameter is equivalent to the DO SHOUT subparameter.
Parent Topic |