Actions

Actions are additional types of tasks that Control-M automatically performs before, during, or after a job executes.

You can define one or more of the following actions in the Actions tab of the job definitions:

Notifications before Job Completion Attributes

Notifications before Job Completion actions are user-defined messages that Control-M sends to one or more destinations at a user-defined time before a SMART folder or job executes.

The following table describes the Notifications before Job Completion panel attributes.

Attribute

Description

Job Not Submitted by <Time>

Sends a message when the job is not or cannot be not submitted by the time you define.

For cyclic folders and jobs, this attribute only controls the first execution. To define notifications for subsequent executions, see the Job's Calculated Cyclic Submission Is Late By option.

Job's Execution Time

Sends a message when the elapsed execution time exceeds the number of minutes you define.

Time limits are expressed as the actual elapsed minutes of a job execution, or as a deviation from the (statistical) average execution time.

Rules: 1–999 minutes.

Job Not Finished by <Time>

Sends a message when the job continues executing after the defined time.

Job Set to Rerun

Sends a message when the job is set to rerun, (not valid for folders).

Job's Calculated Cyclic Submission Is Late By

Sends a message when the beginning of the second or subsequent cyclic execution is late by the number of minutes you define.

You must select and define the Job Not Submitted by <Time> attribute to send a notification when the first cyclic execution is late.

A cyclic job is set to run at 11:00, 12:00, and 13:00. You want to receive a notification if one of its cyclic job submissions runs late by five minutes or longer, so you define two Notifications Before Job Completion actions, as follows:

  • Job Not Submitted By 11:05.

  • Job’s Calculated Cyclic Submission Is Late By 5 minutes.

Rules: 1–999 minutes.

Destination

Determines where the notification is sent, as follows:

  • Alerts Window: Sends a notification to the Alerts window, as described in Alerts.

  • Mail: Sends an email to the indicated email addresses, see Mail Attributes.

  • Job Log: Sends a notification to the job log.

Message

Defines the text of the notification message as follows:

Rules:

Characters: 1–255

Case Sensitive: Yes

Invalid Characters: None

Urgency

Determines one of the following levels of message urgency:

  • Normal

  • Urgent

  • Critical

If-Action If Attributes

The following table describes the If attributes in the If-Actions panel.

Options

Description

Job Ended Not OK

Performs the defined Action if the job ends with the status Ended Not OK.

Job Ended

Performs the defined Action if the job ends.

Job Ended OK

Performs the defined Action if the job ends with the status Ended OK.

OS Completion Status

Performs the defined Action in response to the OS completion code returned by the OS.

Job's Number of Executions

Performs the defined Action when the number of job executions is met.

Job's Number of Reruns

Performs the defined Action when the number of job reruns is met.

Output Cannot Be Found

Performs the defined Action if the output cannot be found.

Job Has Not Been Submitted Yet

Performs the defined Action if the job returns as not submitted.

Job's Number of Failures

Performs the defined Action in relation to the number of times the job failed.

Specific Statement Output

Performs the defined Action if one of the following is fulfilled:

  • The job script file contains the character string that you define in Statement.

  • The OS response to the character string that you define contains the code characters that you define in Code.

Rules:

  • Statement: 1–132 characters in length, from the job script file, containing at least one *.

  • Code: 1–255 characters in length, from the exit code of DOS BAT scripts and REXX CMD scripts that are returned to the Server.

Statement and code character strings can contain the following mask characters:

  • *: Represents any number of characters (including no characters).
  • $: Represents any single character.
  • ?: Represents any single character.

The following are statement and code combinations:

  • ON "*" "COMPSTAT>0"

  • Related to Output:

    ON "*cp aaa bbb*" "*not found*"

  • Based on the OK/NOTOK Job State:

    ON "*" "NOTOK"

Variable Value

Performs the defined Actions if the logical condition defined on the variable value returns True.

Rules:

  • Variable Name: Local, folder, or global, as described in Variables.

    Characters: 1–128. This includes the Pool name if the variable is in a Pool.

  • Operator: The Operator determines the relationship between the variable and the value. There are two kinds of operator types: integer operators (numeric values) and string operators (alphanumeric values). Depending on the operator type you select, you might need to provide one value, either a number or string, or two values, such as a Min and Max range.

  • Rules Value:

    • String:

      • 1–255 characters. String values can contain up to 4,000 characters.

      • Special characters: * (asterisks).

      • String values can contain other variables.

    • Integer:

      • 1–255 characters for both the Min and Max value field combined if one of the fields contains a variable.

      • 1–10 characters for each Min and Max value field (11 characters if you are using number signs '+' or '-'), if a variable is not used.

If-Action Action Attributes

The following table describes the Action attributes in the If-Actions panel.

Option

Description

Notify

Sends a notification to a specific destination, as described in Notify Attributes.

Set to OK

Sets the status of a job to OK, even if the job completes Not OK.

Set to Not OK

Sets the status of a job to Not OK, even if the job completes OK.

Rerun Job

Re-executes the job.

Stop Cyclic Run

Stops subsequent iterations of the current cyclic job.

Set Variable

Resolves the value of a user-defined variableClosed A type of variable whose name and value you manually define in a job and can reference in the same job and subsequent jobs. for use in subsequent jobs, with attributes, as described in Variables.

Run Job and Ignore Scheduling Criteria

Forces a job to execute, even if the scheduling criteria is not met. .

You can also select to Run as Independent Flow, which determines whether the job workflow in the folder executes independently from other instances of the same workflow using the same events. This is achieved by adding a unique suffix to the events used in each workflow instance. Run as Independent Flow is supported in SMART folders, sub-folders, and jobs.

Handle Output

Determines how the job handles the output, as follows:

  • Copy
  • Delete
  • Move
  • Print
  • None

Add/Delete Event

Determines whether to add or delete a prerequisiteClosed The part of the job definition that controls the flow of your jobs, such as an event that controls flow sequence or a resource that controls load balancing. event, as described in Events.

Notify Attributes

The following table describes the attributes for a Notify If-Action.

Attribute

Description

Destination

Determines the destination of the notification, as follows:

  • Alerts Window: Sends a notification to the Alerts window.

  • Mail: Sends an email to the indicated email addresses, as described in Mail Attributes.

  • Job Log: Sends a notification to the job log.

  • NotifyScriptLnx: Sends a notification to a destination via script $CONTROLM/NotifyScriptLinux.sh in the Control-M/Agent home directory. This option appears in the If-Actions drop-down list after you manually define it as free text.

    You must create script NotifyScriptLinux.sh under the Control-M/Agent home directory.

  • NotifyScriptWin: Sends a notification to a destination via script NotifyScriptWindows.bat in the Control-M/Agent home directory. This option appears in the If-Actions drop-down list after you manually define it as free text.

    You must create script NotifyScriptWindows.bat under the Control-M Agent home directory.

    • You can only notify via script (Windows and UNIX/Linux) on OS jobs.

    • The NotifyScriptLnx or NotifyScriptWin option executes according to the user defined in the job.

Message

Defines the text of the notification message.

Rules:

  • Characters: 1–4,000

  • Case sensitive: Yes

  • Invalid characters: ' (apostrophes).

  • Variable support: A variable or expression can be specified as all or part of the value for this parameter.

Urgency

Determines one of the following levels of message urgency:

  • Normal

  • Urgent

  • Critical

Mail Attributes

The following table describes the mail attributes when the Destination option is set to Mail.

Attribute

Description

To

Defines an email address for recipients of the mail message.

Rules:

CC

(Optional) Defines a carbon copy (CC) email address.

On some UNIX computers, the CC field is not supported, and all recipients must go in the To field.

Rules:

  • You must separate email addresses with a ;.

  • Characters: 1–255

  • Case Sensitive: Yes

  • Characters:

    • Blank spaces.

    • ' (apostrophes).

    • Latin-1 special character letters (uppercase and lowercase).

  • Variable Support: A variable or expression cannot be specified as all or part of the value for this parameter.

Subject

Defines the subject line for the message.

Rules:

  • Characters: 1–99

  • Case Sensitive: Yes

  • Invalid Characters:

    • ' (apostrophes).

    • Do not use a - (hyphen) as the first character

  • Variable Support: A variable or expression can be specified as all or part of the value for this parameter.

Attach Output

Determines whether the output is sent as an email attachment, as follows:

  • Yes: Send the job output as an attachment.

  • No /Default : Do not send the job output as an attachment.

If-Actions

If-Actions enable you to define when a certain action is performed when an if-condition that you define is met, as described in If-Action If Attributes and If-Action Action Attributes.

  • If you select Job's Number of Reruns to Equal To 3, and select the Set to OK action, after the job has rerun three times, the job is set to Ended OK.

  • If you select Output Cannot Be Found and select the Notifyaction, the Alerts window is notified that an output was not found.

  • If you select Job Ended and select the Handle Output action, the output is sent to another destination, such as copying it to another file path, when the job has ended.

  • If you select Job's Number of Executions to Greater Than 3, and select the Rerun Job action, the job is rerun when the number of job executions is greater than 3.

Notifications after Job Completion Attributes

Notifications after Job Completion actions are user-defined messages that Control-M sends to one or more destinations at a user-defined time after a SMART folder or job executes.

The following table describes the Notifications after Job Completion panel attributes.

Option

Description

Job Ended Not OK

Sends the message if the job finished executing with an unsuccessful operating system completion status, or due to a submission failure, such as the queue does not exist.

Job Ended OK

Sends the message if the job finished executing with a successful operating system completion status.

Destination

Determines where the notification is sent, as follows:

  • Alerts Window: Sends a notification to the Alerts window, as described in Alerts.

  • Mail: Sends an email to the indicated email addresses, see Mail Attributes.

  • Job Log: Sends a notification to the job log.

Message

Defines the text of the notification message as follows:

Rules:

Characters: 1–255

Case Sensitive: Yes

Invalid Characters: None

Urgency

Determines one of the following levels of message urgency:

  • Normal

  • Urgent

  • Critical

Capture from Job Output Attributes

Captures data from the job outputClosed A tab in the job properties pane of the Monitoring domain where the job output appears that indicates whether a job ended OK, and is used, for example, with jobs that check file location. and saves it to a local, global, Named Pool, or SMART folder variable, based on the attributes that you define.

The following table describes the Capture from Job Output attributes.

Attribute

Description

Name

Defines the variable name that contains the captured data, that can be used in other jobs.
Type

Determines the variable type as described in User-Defined Variables.
Cursor Position

Determines where in the output file to run the capture process as follows:

  • Move to the End of Below String: Moves the cursor position to the end of the string in the output file.

  • Forward By: Selects the number of lines to skip from the search string.

  • Words/Characters: Selects the number of words or characters to skip from the search string in the output file.

  • Delimiter: Selects a delimiter type that is used as a split separator between words in the job output file.

Data to Capture

Determines the specific data to capture as follows:

  • Up to the End of Line: Captures the whole string.

  • Number of Words: Captures a specific number of words in a string.

Output Handling

The Output Handling action copies, deletes, moves, or prints the job outputClosed A tab in the job properties pane of the Monitoring domain where the job output appears that indicates whether a job ended OK, and is used, for example, with jobs that check file location. to another location when the job completes execution with a status of Ended OK.

The following table describes the Output Handling action attributes.

Attribute

Description

Action

  • None

  • Copy: Copies the job output to a file that you define in the Filename field.

  • Delete: Deletes the job output from the default output directory.

  • Move: Moves the job output file from the default output directory to the pathname that you define in the New Destination field.

  • Print: Prints the job output to the printer that you define in the Printer Name field.

Default: None

Filename

Defines the filename and its position in the directory (pathname) of the file that contains the job ouput when the job ends OK.

New Destination

Defines the pathname that the job output is sent to when the job ends OK.

Printer Name

Determines the printer that prints the job output when the job ends OK.