Actions

Action attributes are automatically performed by Control-M before or after job completion. You can define one or more of the following Actions:

  • If-Actions: Defines which action Control-M performs based on the status of the job as described in If-Actions.

  • Capture from Job Output: Captures data from the output of a job and creates a variable, which can be used by another job within the same folder, either in the script during the execution, or in post-processing actions of the job, as described in Capture from Job Output Attributes.

If-Actions

If-Action attributes enable you to define which action Control-M performs based on the status of the job.

  • 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 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.

 

If Options

The following table describes the If options that you must define before creating an Action:

Options

Description

Job ended not OK

Performs the defined Action if the job ended not OK.

Job ended

Performs the defined Action if the job ended.

Job ended OK

Performs the defined Action if the job 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

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 asterisk.

  • Code: 1-255 characters in length, from the exit code of DOS BAT scripts and REXX CMD scripts that are returned to the Control-M/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 state of the job:

    ON "*" "NOTOK"

Variable value

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

This feature is supported in Control-M/Server 9.0.21 and higher.

Rules:

  • Variable name: Local, Folder, or Global, as described in Variables.

    Characters: 1-128, (z/OS 1-64)). This includes the Pool name if the variable is in a Pool.

    (z/OS only) If you are using a Global variable you must include a \, such as \MYVAR.

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

  • Rules value:

    • String:

      • 1-255 characters. The resolving string values can contain string lengths of up to 4000 characters.

      • (z/OS only) 1-64 characters. The resolving string values can contain string lengths of up to 80 characters.

      • Special characters: '*' ,(z/OS only '?')

      • 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.

      • (z/OS only) 1-64 characters for each Min and Max value field if one of the fields contains a variable.

      • (z/OS only) 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.

Any programs step

Performs the defined Action if the specified codes are found in any program step.

Rules:

  • Characters: 1-8

  • Invalid Characters: Non-English, blanks

Every program step

Indicates that the value is used without being accompanied by limiting step values when the code criteria are satisfied for every step. The code criteria are satisfied for every step in the job without exception.

Rules:

  • Characters: 1-8

  • Invalid Characters: Non-English, blanks

Specific step name

Defines the name of a specific procedure/program step. If a specific procedure/program step is specified, only program/procedure steps from the invoked procedure/program are checked to see if they satisfy the code criteria. Program/procedure steps directly from the job are not checked.

Rules:

  • Characters: 1-8

  • Invalid Characters: Non-English, blanks

Specific range name

(z/OS only) Specifies a range of steps in the steps of an Any program step statement.

Rules:

  • Characters: 1-8

  • Invalid Characters: Non-English, blanks

JOBRC

(z/OS only) Assign a completion code for the entire job based on the completion codes of its steps.

Output Pattern

(z/OS only) Performs the defined Action if the specified pattern is found in the output.

  • Pattern Length: 1-40 characters

  • From Col Length: 3 digit number

  • To Col Length: 3 digit number

Action Options

The following table describes the Action that Control-M can perform when the If-option is met:

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 completed not OK.

Set to not OK

Sets the status of a job to not OK, even if the job completed 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 variableClosedA type of variable whose name and value you manually set in a job, which you can reference in subsequent jobs or in the same job for use in subsequent jobs, with attributes, as described in Variables

Run job and ignore scheduling criteria

Forces the execution of a job, even if the scheduling criteria is not met. You can force the job in the local Control-M/Server or remote Control-M/Server.

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

  • Control-M/EM performs an authorization check when the Action is set to Run Job and Ignore Scheduling Criteria and it is executed with variables. To change the authorization configuration, update the XCTMDoForceAuth and XCTMDoForceUser system parameters, as described in Control-M/EM General Parameters.

  • This feature is supported in Control-M/Server 9.0.21 and higher.

Handle Output

Determines how the job handles the output:

  • Copy
  • Delete
  • Move
  • Print
  • None

z/OS:

  • None

  • Change jobs class

  • Delete output

  • Copy output

  • Move output

Add/Delete Event

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

Control-M Analyzer Rule

(z/OS only) Defines the Control‑M/Analyzer rule that Control-M executes.

Name:

  • Characters: 1-8

  • Case Sensitive: Yes

  • Invalid Characters: Blanks; non-English characters

Argument:

  • Characters: 1-45

  • Case Sensitive: Yes

  • Invalid Characters: Blanks; non-English characters

Set Restart Options

(z/OS only) Determines the job steps to execute during restart of a job:

Parameters:

  • From program: First program step within the job stream.

  • From procedure: First procedure step in the range. characters.

  • To program: Last program step within the job stream.

  • To procedure: Last procedure step in the range.

  • Request automatically: Enables you to specify whether manual confirmation is required before the job is restarted.

Notify Attributes

The following table describes the attributes for a Notify If-Action (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, see Mail Attributes.

  • Remedy: Opens a ticket in the Remedy Help Desk.

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

  • User Console: Sends a notification to the user console.

  • System Console: (z/OS only) Sends a notification to the operator console, as follows:

    • Route Code: Defines an optional 3 digit code.

    • Highlight: Determines whether the message is a highlighted unrollable message.

  • TSO User: Sends a message to the specified ID, as follows:

    • User ID: Defines the ID (1 to 7 characters) where Control-M writes the message.
    • Comp: (Optional) Defines the computer and/or host of the TSO logonid.

  • IOA Log: (z/OS only) Sends the message to the IOA log file under the specified User ID.

  • SNMP Destination: Sends an SNMP trap (message) to the recipient address that you define.

  • Mail Group: (z/OS only) Defines a group name in the SNMPDEST destination table.

You can customize the destination of a notification, such as an external application, as described in Shout destination management.

Message

Defines the text of the mail message.

Rules:

  • Characters: 1-4000

    z/OS: 1-255 lines, each containing 1-70 characters, must not exceed 4000 characters.

  • Case sensitive: Yes

  • Invalid characters: Single quotation marks

    z/OS: None

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

Defines the level of urgency for the message, as follows:

  • 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

Defines CC email address (Optional).

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

Rules:

  • Separate addresses with a semicolon ";".

  • Characters: 1-255, z/OS: 1-255

  • Case Sensitive: Yes

  • Characters:

    • Blanks

    • Single quotation marks

    • Latin-1 special character letters (upper and lower case)

    • z/OS: Blanks, non-English characters

  • 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, z/OS: 1-70

  • Case Sensitive: Yes

  • Invalid Characters:

    • Single quotation marks

    • Do not use "-" as the first character

    • z/OS: Non-English characters

  • 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’s output as an attachment.

  • No: Do not send the job’s output as an attachment.

  • Default: Refers to the ADD OUTPUT TO EMAIL value in the config.dat to determine whether to send the job’s output as an attachment.

Notifications before Job Completion Options

The following table describes the When parameter options for Notifications before Job Completion:

Option

Description

Job not submitted by <time>

Sends a message if the job is not submitted and cannot be submitted by the time specified.

For cyclic folders and jobs this option controls the first execution only. For subsequent executions, see the Job's calculated cyclic submission is late by option.

Job's execution time

Sends a message if the elapsed job run time is outside the defined limit. A limit is expressed as the actual elapsed minutes of the job run, or as a deviation from the job (statistical) average runtime.

Rules:1-999 minutes

Job not finished by <time>

Sends a message if the job does not finish executing by the time specified.

Job set to rerun

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

Job's calculated cyclic submission is late by

Sends a message if the second or subsequent cyclic submission is late by <x> minutes. You can select the Job not submitted by <time> option to send a message if the first cyclic submission is late.

This feature is supported in Control-M/Server 9.0.21 and higher.

If you define a cyclic job to run at 11:00, 12:00, and 13:00 and you want to receive a message if one of its cyclic job submissions is late by more than 5 minutes, you must define two Notifications Before Job Completion:

1. Job not submitted by: 11:05

2. Job’s calculated cyclic submission is late by: 5 minutes

Rules: 1-999 minutes

Notifications after Job Completion Options

The following table describes the When parameter options for Notifications after Job Completion:

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.

Send Notification To Attributes

The following table describes the attributes that define where notifications are sent, either before or after job completion:

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, see Mail Attributes.

  • Remedy: Opens a ticket in the Remedy Help Desk.

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

  • User Console: Sends a notification to the user console.

  • System Console: (z/OS only) Sends a notification to the operator console, as follows:

    • Route Code: Defines an optional 3 digit code.

    • Highlight: Determines whether the message is a highlighted unrollable message.

  • TSO User: Sends a message to the specified ID, as follows:

    • User ID: Defines the ID (1 to 7 characters) where Control-M writes the message.
    • Comp: (Optional) Defines the computer and/or host of the TSO logonid.

  • IOA Log: (z/OS only) Sends the message to the IOA log file under the specified User ID.

  • SNMP Destination: Sends an SNMP trap (message) to the recipient address that you define.

  • Mail Group: (z/OS only) Defines a group name in the SNMPDEST destination table.

Message

Defines the text of the notification message as follows:

Rules:

Characters: 1-255, z/OS: 1-70

Case Sensitive: Yes

Invalid Characters: None

Urgency

Defines the urgency of the notification message directed to the Alerts window, see Alerts page.

Capture from Job Output Attributes

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 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 Options

The following table describes the options of the Output Handling Action attributes:

Option

Description

Output Handling

  • None: (Default).

  • Copy: Copies the output to a selected filename.

  • Delete: Deletes the output.

  • Move: Moves the output to a selected path.

  • Print: Prints the output to a selected printer.

z/OS:

  • None: (Default).

  • Change jobs class: Changes the class of the job output.

  • Delete: Deletes the output.

  • Copy: Copies the output to a selected filename.

  • Move: Moves the output to a selected path.