ctmshout

The ctmshout utility sends a shout message to the specified user or destination and specify its level of severity. For more information, see Notification Destinations. For information about attaching the output of a job to a shout message, see Mail Server Settings .

Each parameter name can be shortened to the minimum number of letters required to uniquely identify the parameter.

‑ORDERID can be shortened to ‑O.

Notifications can be sent to multiple destinations or users in the same command.

Running the ctmshout Utility

This procedure describes how to run the ctmshout utility, which enables you to send a shout message to the specified user or destination and specify its level of severity.

Begin

  1. Do one of the following:

    • UNIX: Log in to a Control-M/Server account.

    • Windows: Open a command prompt window where Control-M/Server is installed.

  2. Type one of the following commands:

    • ctmshout

      -USER <userName> or -DEST <destinationName>

      -MESSAGE "<messageText>"

      [ -ORDERID <orderID>]

      [ -HOSTID <hostID>]

      [ -SEVERITY <severityLevel>]

    • ctmshout -input_file <fullPathFileName>

ctmshout Parameters

The following table lists the ctmshout utility parameters.

Parameter

Description

<username>

Defines the User ID that should receive the message. DEST and USER can be specified in the same ctmshout command.

<destinationName>

Defines a logical destination device name or a valid destination name in the Notification Destination folder. DEST and USER can be specified in the same ctmshout command.

<message>

Describes a message to be sent to the destination. 1–255 characters. If the text is more than one word, it must be enclosed in quotation marks.

<orderID>

Defines the order ID of a job, as displayed in the Job Details window in Control‑M/EM.

Associates the message with a specific job in the Active Network.

<hostID>

Host ID of the Agent computer. Used for messages whose destination is either a user in the data center or a user defined in the Notification Destination folder.

If ‑ORDERID is also specified, this Host_ID overrides the Host ID specified in the job with that Order ID.

<severityLevel>

Indicates the urgency of the message.

Valid Values:

  • R : Regular

  • U: Urgent

  • V: Very urgent

Default: R

<fullPathFileName>

Defines the name and full path of a file containing the utility parameters. In this file, each parameter and its values (if any) are on a separate line with the same syntax they would have on the command line.

The -input_file parameter enables you to:

  • Prepare and save files of utility parameters that can be reused.

  • Specify utility input longer than the number of characters allowed in the command line.

-input_file~<controlm_owner>/ctm_server/data/ctmshout_parms.txt

The following are examples of the ctmshout utility commands:

  • The following command sends the message, File not found, to the Alerts window in Control‑M/EM and associates it with a job whose Order ID is 1234:

    ctmshout -ORDERID 1234 -USER EM \

    -MESSAGE "File not found" -SEVERITY V

  • The same result is achieved by using the -input_file parameter as follows:

    ctmshout -input_file ~<controlm_owner>/ctm_server/data/ctmshout_payroll.txt

    The referenced file contains the following lines:

    -ORDERID 1234

    -USER EM

    -MESSAGE "File not found"

    -SEVERITY V

  • The following command sends the message, The weekly paycheck job has abended, to user John on Agent Diana:

    ctmshout -HOSTID Diana -USER John -MESSAGE
    "The weekly paycheck job\ has abended" -SEVERITY V

  • The following illustrates the use of the ctmshout utility in a job script command to send the shout message, Job started, to the Alerts window in Control‑M/EM.

    The job processing definition for a certain job contains the following Variable Assignment parameter:

    %%PARM1 = %%ORDERID

    The script used to execute the job contains the following command:

    ctmshout -O $1 -USER EM -MESSAGE "Job started" \
    -SEVERITY R