WHEN

Situation in which to send the message. Valid values are:

• OK – The message is sent if the job ends OK.
• NOTOK – The message is sent if the job ends NOTOK.
• RERUN – The message is sent if the job is rerun and DO RERUN is specified in ON PGMST.
• LATESUB time + days – The message is sent if the job was not submitted by the specified day and time offset, where:

  — If Days is entered, it must be a number between zero and 120.

  — Time is in the format hhmm, *, or #mmm.

  If * is specified, the Control-M monitor uses the calculated DUE IN date and time of the job, as displayed in the Zoom screen, to determine if the first run of the job was not submitted at the correct date and time. For more information, see Automatic Job Flow Adjustment.

  If #mmm is specified, the Control-M monitor uses the calculated next run date and time, as displayed in the Zoom screen (NXT RUN), starting from the second job run. The mmm variable is an optional tolerance period in minutes, which allows you to set extra time before the SHOUT is issued.

  — Note that if the time is * or #mmm, Days must be blank.

• LATE time + days – The message is sent if the job did not finish executing by the specified day and time offset, where:

  — If Days is entered, it must be a number between zero and 120.

  — Time is in the format hhmm or an *. If * is specified, the Control-M monitor uses the calculated DUE IN date and time of the job, as displayed in the Zoom screen, to determine if the job was late. For more information, see Automatic Job Flow Adjustment.

  — Note that if the time is *, Days must be blank.

• EXECTIME limit – The message is sent if the elapsed runtime of the job is outside a specified limit. The limit can be expressed as a runtime limit, or as a deviation from the average runtime of the job. Valid formats for limit are (where n is a 3-digit nonzero value):
  >n    – The elapsed runtime of the job is greater than n
               minutes. n cannot exceed 999.
  <n    – The elapsed runtime of the job is less than n
              minutes. n cannot exceed 999.
  +n    – The elapsed runtime of the job exceeds the average
              execution time of the job by at least n minutes.
              n cannot exceed 999.
  –n    – The elapsed runtime of the job is at least n minutes
              less than its average execution time. n cannot
              exceed 999.
  +n% – The elapsed runtime of the job exceeds its average
              execution time by at least n%. n cannot exceed 900
  –n% – The elapsed runtime of the job is at least n% less
              than its average execution time. n cannot exceed
              99.

SHOUT WHEN LATE and SHOUT WHEN LATESUB (with time + days specified) are only activated for the first run of a job, not for subsequent job reruns. The exception is SHOUT WHEN LATESUB #mmm (with a tolerance period specified), which is activated only for subsequent job runs, starting from the second job run.

SHOUT WHEN EXECTIME limits coded in SMART Table Entities are not continuously checked, but only when each job in the SMART Table finishes executing.

TO

Destination of the message (1 through 16 characters).

Mandatory. Valid values are:

• U-userid or USERID-userid – Writes the message to the IOA Log file under the specified user ID. userid must be 1 through 8 characters.
• OPER[–n] – Sends a rollable message to the operator console. n is an optional 3-digit route code. If a route code is not specified, the default routes are Master Console and Programmer Information (1 and 11), and optionally, Control-M/Enterprise Manager. For more detailed information regarding route codes, refer to the IBM publication Routing and Descriptor Codes, GC38-1102.
• OPER2[–n] – Sends an unrollable, highlighted message to the operator console. n is an optional 3-digit route code. If a route code is not specified, the default routes are Master Console and Programmer Information (1 and 11), and optionally, Control-M/Enterprise Manager. For more detailed information regarding route codes, refer to the IBM publication Routing and Descriptor Codes, GC38-1102.

• [TSO - loginid | T - loginid] [;Nn | ;Mm | ;NnMm | ;Lname] – Sends the message to the specified ID (groupid or logonid). ID is mandatory.
  If a groupid is specified, it must be a valid ID found within the IOA Dynamic Destination Table.
  If a logonid is specified, it must be 1 through 7 characters.
  An optional second value, indicating the computer and/or node (such as Mm) of the TSO logonid, can be specified, as follows:
  Under JES2:
  Valid values are: Nn, Mm or NnMm, where:
  – m is the machine ID (the computer in JES2, not the
     4-character SMF system ID). For more information, see
     the description of specifying IOA CPUs in the discussion
     of the customization process in the INCONTROL for
     z/OS Installation Guide.
  – n is the 1 to 2 character JES/NJE node ID.
  Under JES3:
  The only valid value is Lname, where Lname is the logical JES name of the machine (that is, the name as used in JES3 command *T, not the SMF system ID.
  For more information, see the description of specifying IOA CPUs in the discussion of the customization process in the INCONTROL for z/OS Installation Guide.)

Note: A shout to a TSO user performs a TSO SEND command, which may require authorization at the receiving node.

• U-M:email_dest – Sends a message by e-mail to the recipient identified by the variable (email_dest), which consists of from 1 through 12 characters, and can be any of the following:
  — an e-mail name prefix, based on the full mail name address
       that is supplied by the MAILDEST table in the IOA PARM
       library
  — a nickname defined in the MAILDEST destination table
  — a group name defined in the MAILDEST destination
       table
• U-S:snmp_dest – Sends an SNMP trap (message) to the recipient identified by snmp_dest.
  snmp_dest consists of from 1 through 12 characters, and can be any of the following:
  — a host name
  — an IP address, if it fits in the screen field. Otherwise use a
       nickname.
  — a nickname defined in the SNMPDEST destination table
  — a group name defined in the SNMPDEST destination
       table
• U-ECS – Sends messages to the Control-M/Enterprise Manager user.

Note: If you want SHOUT Messages to be sent to the Control-M/Enterprise Manager, you must install Sample Exit IOAX034W, which is in the IOA SAMPEXIT library.

URGN

Determines the priority level of the message. Valid values are:

• R – Regular. Default.
• U – Urgent.
• V – Very urgent.

MS

Message text. Maximum length: 70 characters.

AutoEdit variables (both system and user-defined) are supported and automatically resolved (replaced) at the time the SHOUT message is issued. For AutoEdit usage information, see JCL and AutoEdit Facility.