Variables

Variables are memory locations with a defined name that can hold a value and be referenced in job and SMART folder definitions. A variable is resolved when its current value is retrieved from memory. Control-M resolves the variables used in a job definition when a job begins or completes execution, depending on the type of variable. The contents of the original job definition and variables remain unchanged.

You can use the following types of variables in SMART folders, sub-folders, and job attributes:

  • User-Defined Variables: Variables that you create by defining the variable name and assigning it a value.

  • System Variables: Preexisting variables whose names and values are defined and assigned by Control-M.

User-Defined Variables

User-defined variables are variables that you create by defining the variable name and assigning it a value in the job or SMART folder definitions. Before a job is submitted, Control-M resolves the variables and uses the value that is retrieved in the current job execution. For more information, see Adding Variables. For a description of the names and values that you can assign to user-defined variables, see Variable Names and Values.

Variable Scope

The scope of a variable is the extent of the area in Control-M where your variables can be referenced. You can set the scope of user-defined variables when you add variables to a job, as described in Adding Variables. The following list describes the different variable scope types:

  • Local: Variables are referenced by the job they are defined in, such as messages, if-action arguments, or the job script in succeeding executions.

  • Global: Variables are referenced by any job in the current environment.

  • Named Pool: Variables are referenced by any job in the same Named Pool.

  • SMART Folder: Variables are referenced by jobs and sub-folders in the SMART folder.

System Variables

System variables are preexisting variables whose names and values are defined and assigned by Control-M. You can reference system variables in the job definitionClosed The set of parameters that defines what the job does, when it runs, its prerequisites, and the post-processing actions Control-M performs after it ends (also called a job processing definition). attributes, as described in Variable Reference Attributes and in the values of User-Defined Variables. Before a job is submitted, Control-M resolves the variables and uses the retrieved values for the current execution of the job.

You can create user-defined variables using system variables, as follows:

  • MYDATE is entered into the Name field in the Variables area. This creates the user-defined variable %%MYDATE.

  • %%DAY, %%MONTH, and %%YEAR are system variables whose values correspond to the current day, month, and year (in dd, mm, and yy format) on the host machine.

  • %%DAY-%%MONTH-%%YEAR is entered into the Value field in the Variables area. This assigns %%MYDATE the value of a string that contains the current date in dd-mm-yy format.

The following is a list of system variables that you can reference in the attributes of a job definition and as values within User-Defined Variables:

Adding Variables

This procedure describes how to add user-defined variables or variable lists to a job, which enables you to share data between multiple jobs.

Begin

  1. From the Variables area in the job or folder definitions, click .

  2. From the Type drop-down list, select one of the following variable scope types:

    • Local: Defines a variable that can be referenced by the job or folder that they are defined in.

    • Global: Defines a variable that can be referenced by any job or folder in the current environment.

    • Named Pool: Defines a variable that can be referenced by referring to the pool name.

      In the Pool Name field that appears, type a logical pool name.

    • SMART Folder: Defines a variable that can be referenced by all jobs and sub-folders in the SMART folder.

  3. In the Name field, do one of the following:

    • User-Defined Variable: Type a logical variable name.

  4. In the Value field, do one of the following:

    • User-Defined Variable: Type the variable value.

    A variable is added to the job definition.

    To resolve and view the current values of your variables, see Variables.

Variable Simulation

Variable Simulation enables you to view the original and resolved values of variables in your SMART folder, sub-folder, or job, without the need to run any of them.

In an OS job, you can toggle back and forth between variable simulations in the Command field and Variables area of an OS job, all within the same Variable Simulation pane. This eliminates the need to close the Variable Simulation pane in one area of the job definitions and reopen it from another.

The following procedures describe how to simulate variables:

Simulating Added Variables

This procedure describes how to view the original and resolved values of added variables in SMART folders, sub-folders, or jobs.

Begin

  • From the top right corner of the Variables area, in the General tab, click .

    The Name, Original Value, and Resolved Value of each variable appear in the Variable Simulation pane.

    The error message CTMERR appears with the variable name in the Resolved Value when one of the following values have been assigned:

    • A nonexistent variable.

    • A user-defined variable that is assigned a value that includes a nonexistent variable.

On 29 January 2023, you add a variable called %%MYDATE to a Dummy job and run a Variable Simulation. The following results appear in the Variable Simulation pane:

  • Name: %%MYDATE

  • Original Value: %%DAY-%%MONTH-%%YEAR

  • Resolved Value: 29-01-23

Simulating Variables in OS Jobs

This procedure describes how to view the original and resolved values of variables in OS jobs.

Begin

  • Do one of the following:

    • To simulate variables used in the Command field, click .

      The Original Command Line and Resolved Command Line appear in the Variable Simulation pane.

      The error message CTMERR appears with the variable name in the Resolved Command Line when one of the following values have been assigned:

      • A nonexistent variable.

      • A user-defined variable that is assigned a value that includes a nonexistent variable.

    • To simulate variables added in the Variables area, see Simulating Added Variables.

    You can toggle back and forth between variable simulations in the Command field and the Variables area by clicking Command Line and Variables in the Variable Simulation pane.

You enter a command with a nonexistent variable, called %%var, in the Command field and run a Variable Simulation. The following results appear in the Variable Simulation pane:

  • Original Command Line: echo %%var

  • Resolved Command Line: echo CTMERRvar

Shared Variables

Shared Variables enables you to view the names and current resolved values of all Global and Named Pool variables in active jobs, SMART folders, or Workspaces. This tool enables you to track the changing values of variables during run time.

The following video describes Shared Variables:

You create a Named Pool variable, called Federal_Reserve_Rate, and a Global variable, called USD_to_ILS, and set their values to their daily market rates. You run the environment that contains these variables and check their resolved values with the Shared Values tool on the first weekday for two consecutive weeks. The following variable names and values appear:

  • Week 1:  The Federal_Reserve_Rate has a value of 4.75 and the USD_to_ILS variable has a value of 3.66227.

  • Week 2: The Federal_Reserve_Rate has a value of 5.00 and the USD_to_ILS variable has a value of 3.58738.

Variable Reference Attributes

The following table describes the attributes where you can reference User-Defined Variables and in a job definitionClosed The set of parameters that defines what the job does, when it runs, its prerequisites, and the post-processing actions Control-M performs after it ends (also called a job processing definition).:

Attribute

Tab

Command

General Tab: OS job type

File Name

File Path

Alerts Window Message

Actions Tab: If-Actions> Action> Notify

Job Log Message

Mail Attributes

File Name

Actions Tab: If-Actions > Action> Handle Output

Name

Actions Tab: If-Actions > Action> Set Variable

Value

Alerts Window Message

Actions Tab: Creating Notifications

Job Log Message

Mail Attributes

File Name

Actions tab: Output Handling options> Action> Copy

Variable Reference Syntax

The following table describes the syntax for referencing a variable in the attribute of a SMART folder, sub-folder, or job definition:

Variable

Syntax

Local Variables

%%<VARIABLE NAME>

Global Variables

%%\<VARIABLE NAME>

Named Pool Variables

%%\\<POOL NAME>\<VARIABLE NAME>

SMART Folder Variables

%%<VARIABLE NAME>

Variables that are not resolved

UNIX: #

Windows: %#%

If you want Control-M to reference the syntax for a variable as a literal string in your output, use # as follows:

Job Daily returned a value for variable %%#MYDATE

The output is:

Job Daily returned a value for variable %%MYDATE

Job General System Variables

The following table describes the Job General System Variables:

Name

Resolution

Description

%%APPLIC

String

Resolves the applicationClosed A job attribute that provides a logical name for sorting groups of jobs, which enables you to search for and update jobs. of the job.

z/OS: Used to reference the application name.

%%APPLGROUP

String

Resolves the sub-applicationClosed A job attribute that provides a logical name for sorting groups of jobs in an Application, which enables you to search and update jobs. of the job.

%%CYCLIC

Y or N

Resolves the cyclicClosed A SMART folder or job that executes multiple times in one run, whether for specific intervals, sequences of intervals, or times. status of the job, as follows:

  • Y: The job is cyclic.

  • N: The job is not cyclic.

%%$FOLDER_ID

String

Resolves the run IDClosed The identification code for a SMART folder, sub-folder, or job execution. of the job.

This variable is valid for jobs in a SMART folder and is evaluated in base 36.

%%GROUP_ORDID

Numeric

Resolves the Run ID of the sub-application where the job belongs.

This variable is valid only for jobs in an active SMART folder and is evaluated in base 10.

%%$GROUP_ORDID

Numeric

Resolves the Run ID of the sub-application where the job belongs.

This variable is valid only for job in an active SMART folder and is evaluated in base 36.

%%JOBNAME

String

Resolves the name of the job.

%%MEMLIB

String

Resolves the file path of the job (for an OS Job that executes a Script).

z/OS: Resolves the Mem Lib (name of the library or directory where the job script is stored) of the job.

%%ORDERID

String

Resolves the run ID of the job.

%%OWNER

String

Resolves the username with the authorization to execute the job and is defined in the Run as field.

%%RUNCOUNT

Numeric

Resolves the number of times the job run has ever executed (the first time the job executes, this variable returns a value of 1).

%%RUNCOUNT counts each execution of a job and each execution of a cyclic job as individual executions.

%%SCHEDTAB

String

Resolves the name of the parent folder of the job.

%%SMART_ORDERID

 

Resolves the run ID of an existing SMART folder.

This variable is valid for jobs in a SMART folder and is evaluated in base 10.

%%$SMART_ORDERID

 

Resolves the run ID of an existing SMART folder.

This variable is valid for jobs in a SMART folder and is evaluated in base 36.

%%$TABLE_ID

Numeric

Resolves the run ID of the folder where the job belongs.

This variable is valid for jobs in a SMART folder and is evaluated in base 36.

Application and Sub-application Variables

The following is a list of unique rules that apply when using variables in the Application and Sub-application fields:

  • Jobs that are run at different times have different Application names in the job output.

    Application = APP_X_%%TIME

    FolderX runs at New Day time, 07:00, and again using the ctmudly utility at 14:00.

    Application name in the job output for jobs that ran at New Day time: APP_X_07:00.

    Application name in the job output for jobs that ran using the ctmudly utility: APP_X_14:00.

  • The following variables are resolved when the job is ordered (run):

    • %%$DATE

    • %%$YEAR

    • %%MONTH

    • %%OWDAY

    • %%RMONTH

    • %%YEAR

    • %%$ODATE

    • %%CENT

    • %%ODATE

    • %%OYEAR

    • %%RWDAY

    • %%OMONNAM

    • %%$OYEAR

    • %%DATE

    • %%ODAY

    • %%RDATE

    • %%RYEAR

    • %%RMONNAM

    • %%$RDATE

    • %%DAY

    • %%OJULDAY

    • %%RDAY

    • %%TIME

    • %%MONNAM

    • %%$RYEAR

    • %%JULDAY

    • %%OMONTH

    • %%RJULDAY

    • %%WDAY

    Variables that are not listed above are resolved when the job executes.

    Application = %%TIME.%%VAR1

    %%TIME resolves to 140413 when the job is ordered, but %%VAR1 only resolves when the job executes.

    Application in the job output when the job is ordered: 140413%%VAR1.

  • Multiple variables and fixed text are used in a single field.

    Application = Shipments_%%ODATE.%%TIME

    Application in the job output: Shipments_01012021.07:00.

  • The following variables are resolved based on the ODAT received as a parameter to the run request or command:

    • %%ODATE

    • %%$ODATE

    • %%CENT

    • %%OYEAR,

    • %%$OYEAR

    • %%OMONTH

    • %%ODAY

    • %%OWDAY

    • %%OJULDAY

    • %%OMONNAM

  • The following variables are resolved based on the Control-M/Server date, or based on the next New Day date for pre-run:

    • %%RDATE

    • %%$RDATE

    • %%RYEAR

    • %%$RYEAR

    • %%RMONTH,

    • %%RDAY

    • %%RWDAY

    • %%RJULDAY

    • %%RMONNAM

  • The following variables are calculated based on the current date or on the next date for pre-run:

    • %%DATE

    • %%$DATE

    • %%YEAR

    • %%$YEAR

    • %%MONTH

    • %%DAY

    • %%WDAY

    • %%JULDAY

    • %%MONNAM

  • The %%TIME variable is calculated based on the current time or on the New Day time for pre-run.

Job Scheduling System Variables

The following table describes the Job Scheduling System Variables that reflect the scheduling of a job in relation to the ODATEClosed The date that a job joins the Run Queue. of the job:

Name

Resolution

Description

%%NEXT

YYMMDD

Resolves to the next scheduled date of the job.

%%$NEXT

YYYYMMDD

Resolves to the next scheduled date of the job (4-digit year).

%%ODATE

YYMMDD

Resolves to the date that the job joined the Run QueueClosed The queue of jobs that are scheduled to execute on a specific day, in states of Waiting or Executing, depending on their running phase.).

%%$ODATE

YYYYMMDD

Resolves to the date that the job joined the Run Queue (4-digit year).

%%ODAY

1–31

Resolves to the day of the month that the job joined the Run Queue.

%%OJULDAY

1–365

Resolves to the day of the year that the job joined the Run Queue such as, 36 for February 5th.

%%OMONTH

1–12

Resolves to the month that the job joined the Run Queue (1=January).

%%OWDAY

0–6

Resolves to the day of the week that the job joined the Run Queue.

Default: 1=Monday, 2=Tuesday, 3=Wednesday, 4=Thursday, 5=Friday, 6=Saturday, and 0=Sunday.

For more information, see the Start Day of the Week (SWEEK) parameter in Control-M/Server General Parameters and the ctmsys utility.

%%OYEAR

YY

Resolves to the year that the job joined the Run Queue.

%%$OYEAR

YYYY

Resolves to the year that the job joined the Run Queue (4-digit year).

%%PREV

YYMMDD

Resolves to the previous run date of the job.

%%$PREV

YYMMDD

Resolves to the previous run date of the job (4-digit year).

Environment System Variables

The Control-M/Server date changes when the New Day procedure runs. If New Day is at 07:00 am, then 06:00 am is still part of the previous date. This is the same for the Control-M/Server day, month, and year.

The following table describes the Environment System Variables:

Name

Resolution

Description

%%CENT

YY

Resolves to the first two digits in the current year such as, 20 in the year 2021.

%%DAILYNAME

 

Defines user daily jobs (Length: 1–10).

%%DATACENTER

String

Resolves to the name of the Control-M/Server for the current Control-M installation.

%%DATE

YYMMDD

Resolves to the current date.

%%$DATE

YYYYMMDD

Resolves to the current date (4-digit year).

%%$RDATE

YYYYMMDD

Resolves to the current Control-M/Server date (4-digit year).

%%DAY

1–31

Resolves to the current day of the month.

%%JULDAY

1–365

Resolves to the current system Julian day of the year, such as 36 for February 5th.

%%RJULDAY

1–365

Resolves to the current Control-M/Server Julian day of the year, such as 36 for February 5th.

%%MONNAM

String

Resolves to the first 3 letters of the name of the current month.

%%RMONNAM

 

Resolves to the first 3 letters of the name of the current Control-M/Server month.

%%MONTH

MM

Resolves to the current month.

%%RMONTH

MM

Resolves to the current Control-M/Server month.

%%RDAY

1–31

Resolves to the current Control-M/Server day of the month.

%%WDAY

0–6

Resolves to the current day of the week.

Default: 1=Monday, 2=Tuesday, 3=Wednesday, 4=Thursday, 5=Friday, 6=Saturday, and 0=Sunday.

For more information, see the Start Day of the Week (SWEEK) parameter in Control-M/Server General Parameters and the ctmsys utility.

%%RWDAY

0–6

Resolves to the current Control-M/Server day of the week.

Default: 1=Monday, 2=Tuesday, 3=Wednesday, 4=Thursday, 5=Friday, 6=Saturday, and 0=Sunday.

For more information, see the Start Day of the Week (SWEEK) parameter in Control-M/Server General Parameters and the ctmsys utility.

%%YEAR

YY

Resolves to the current year.

%%RYEAR

YY

Resolves to the current Control-M/Server year.

%%$RYEAR

YYYY

Resolves to the current Control-M/Server year (4-digit year).

%%TIME

HHMMSS

Resolves to the current time of day.

Command System Variables

The following table describes the Command System Variables that enable you to specify a command to run before or after running a job:

Name

Resolution

Description

%%PRECMD

Command

Specifies a command to run immediately before running the job. The return code is ignored.

%%POSTCMD

Command

Specifies a command to run immediately after running the job. The return code is ignored.

Action System Variables

The following table describes the Action System Variables that reflect the value in the attribute defined after job execution:

Name

Resolution

Description

%%AVG_CPU

Numeric

Resolves (in seconds), to the average CPU time for previous runs of the job (not folder).

%%AVG_TIME

Numeric

Resolves (in seconds), to the average run time for previous runs of the job or folder.

%%COMPSTAT

Numeric

Resolves to the completion code assigned to the job by the operating system of the computer that executes the job.

Initial Value: 0

%%JOBID

String

Resolves to the identification assigned to the job (not folder) by the operating system of the computer that executes the job.

%%NODEID

String

Resolves to the host ID of the AgentClosed A Control-M component installed on a host (computer) that runs and monitors the jobs on the host. computer that submitted the job.

%%SD_CPU

Numeric

Resolves (in seconds), to the standard deviation of the CPU time of the execution of the job (not folder) from the average CPU time for previous executions of the job.

Do not use this variable in a SMART folder definition.

%%SD_TIME

Numeric

Resolves (in seconds), to the standard deviation of the elapsed run time of the execution of the job or folder from the average elapsed run time for previous runs of the current job or folder.

Variable Names and Values

You can assign names to User-Defined Variables as follows:

  • 1–38 alphanumeric characters.

  • Names are case-sensitive.

  • Names cannot begin with a number.

  • No blank spaces or any of the following special characters: _ < > [ ] { } ( ) = ; ` ~ | : ? . + - * / & ^ # @ ! , " '.

You can set the values of User-Defined Variables with one or more of the following elements:

Variable Manipulations

You can use an operator in the value to manipulate a date variable or numeric variable using the following syntax:

<VALUE> <OPERATOR> <NUMBER>

Where:

  • <VALUE>: A date or number.

  • <OPERATOR>: %%PLUS or %%MINUS.

  • <NUMBER>: Applied to the operator.

You can set a variable %%YESTERDAY as the following:

%%DAY %%MINUS 1

The %%DAY variable is a system variable representing the current system day.

If %%YESTERDAY is referenced in an attribute, Control-M resolves it as the day before the current system day.

Variable Concatenations

You can concatenate variables to resolve into a single string using the "." operator. To include a period separator between two variables you must use "..".

On 12 March, you can set a variable to show the date in the following ways:

  • %%DAY.%%MONTH

    This resolves to 1203

  • %%DAY..%%MONTH

    This resolves to 1203

  • Today is %%DAY/%%MONTH/%%YEAR

    This resolves to Today is 12/03/05

Variable Functions

A variable function performs an action or process on the variable. Variable functions are used instead of another expression. The following functions are available:

%%CALCDATE

%%CALCDATE and %%$CALCDATE: Adds or subtracts a specified number of days from a specified date with %%CALCDATE in the yymmdd format, and %%$CALCDATE in the yyyymmdd format, using the following syntax:

%%CALCDATE <DATE> <OPERATOR><NUMBER>

Where:

  • <DATE>: A date in yymmdd or yyyymmdd format, such as 291115, or a variable that resolves to a date, such as %%DAY.

  • <OPERATOR>: Either the + (plus) or - (minus) sign.

  • <NUMBER>: The number you want to add to or subtract from the original date.

On 15 November 2029, a variable with the following value shows the date 2 days earlier:
%%CALCDATE %%DATE -2

%%GETENV

GETENV: Retrieves the value of an environment variable, using the following syntax:

%%GETENV <ENVIRONMENT>

Where <ENVIRONMENT>: is the environment variable, such as HOME.

%%GETENV HOME resolves to the Server user home directory.

%%SUBSTR

%%SUBSTR: Extracts a substring from within the value of a string variable, using the following syntax:

%%SUBSTR <VARIABLE> <START POSITION> <LENGTH>

Where:

  • <VARIABLE>: The string variable from where to extract the new substring.

  • <START POSITION>: A number or numeric variable indicating the starting character of the substring in the <VARIABLE>.

    The number of the first character in the <VARIABLE> is 1.

  • <LENGTH>: is equal to the number of characters in the substring.

The following variable %%Number resolves to TWO:

%%Nstring=ONETWOTHREE

%%Number=%%SUBSTR %%Nstring 4 3

If <START POSITION> is a variable, Control-M resolves this variable first before it resolves %%Number.

The following variable %%Number resolves to THREE:

%%Nstring=ONETWOTHREE

%%Start=7

%%Number=%%SUBSTR %%Nstring %%Start 5

In the body of an email, %%SUBSTR should be the last statement, such as:

**Start Message**

%%TIME

Hello world

%%SUBSTR GoodMorning 1 4

%%$WCALC

%%$WCALC: Adds or subtracts a specified number of days from a specified Regular Calendars in the yyyymmdd format, using the following syntax:

%%$WCALC <DATE> <INSTRUCTION> <CALENDAR>

Where:

  • <DATE>: A date in yyyymmdd format, such as 20291115, or a variable that resolves to such a date, such as %%$DATE.

  • <INSTRUCTION> Do one of the following:

    • +<NUMBER> or -<NUMBER>: Instructs Control-M to calculate the date that you specify the <NUMBER> of working days after or before the <DATE>.

    • > More than: Instructs Control-M to calculate after the <DATE> the next working day in the calendar that you specify.

    • > Less than: Instructs Control-M to calculate before the <DATE> the previous working day in the calendar that you specify.

  • <CALENDAR>: The name of the Regular calendar where Control-M calculates the date.

The Workdays calendar is a Regular calendar that marks Monday to Friday as working days.

A variable with the following value resolves to the tenth working day after the specific date was specified in the Workdays calendar:

%%$WCALC <date> +10 Workdays

%%BLANK

%%BLANK: Inserts spaces in the value where you define the number of spaces, using the following syntax:
%%BLANK<N>

Where <N> is the number of spaces you want to insert.