Variables
Variables are memory locations with a user- or system-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 that are 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 folder, sub-folder, and job attributes:
-
User-Defined Variables: Variables that you create, name, and assign a value to.
-
System Variables: Preexisting variables with static names and Control-M-assigned values.
-
Variable Lists: A variable with a Control-M-defined name and user-assigned value, which references a Pool of named Pool variables
A type of variable that you create in one job and can reference in subsequent jobs with the same Pool parameter. A Named Pool is a logical grouping of variables. .
You can manage variables with the following Monitoring utilities:
-
ctmvar: Defines, deletes, modifies, and displays variables.
-
ctmstvar: Displays the current value of a variable or function.
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 their retrieved values 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 Scopes
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 that they are defined in, such as messages, If-Action arguments, or a job script in succeeding executions.
-
Named Pool: Variables are referenced by any job in the same Pool, which is a group of variables that share the same Pool name.
-
SMART Folder: Variables are referenced by jobs and sub-folders in the SMART folder.
You can determine the scope of a variable by the prefix that is added to its name, as described in Variable Reference Syntax.
System Variables
System variables are preexisting variables with static names and Control-M-assigned values. You can reference system variables in job attributes and user-defined variable values, as described in Variable Reference Attributes and User-Defined Variables. Before a job executes, Control-M resolves the variables and uses the retrieved values in the current job execution.
On 18 July 2025, a job is defined with a local, user-defined variable, named MyDate, and assigned the following value, with system variables %%DAY, %%MONTH, and %%YEAR:
%%DAY-%%MONTH-%%YEAR
Later that day, the job runs and resolves the variable to 18-07-25.
You can reference the following system variable types in job attributes and user-defined variable values:
-
Job General System Variables: Reflects attributes defined in a job definition.
-
Job Scheduling System Variables: Reflects the scheduling of a job.
-
Environment System Variables: Reflects your environment and are not specific to a job.
-
Action System Variables: Returns statistics about your job after it has been executed.
Variable Lists
A variable list is a variable with a Control-M-assigned name, such as POOLSYM, and a user-defined value. Variable lists enable you to define up to 1,024 variables inanother job or a utility, and reference them locally, without the need to manually redefine them in each job, SMART folder, or sub-folder.
You can reference the following types of variable lists in SMART folders, sub-folders, and jobs:
-
%%POOLSYM (Local): Contains a user-defined value that consists of a Pool name where one or more named Pool variables
A type of variable that you create in one job and can reference in subsequent jobs with the same Pool parameter. A Named Pool is a logical grouping of variables. are defined.
A job is defined with a %%POOLSYM local variable list that is assigned the value MyPool, which is an existing Pool that contains the following variable definitions:
-
var1=100
-
var1=200
-
var3=300
-
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
-
From the Variables area in the job or folder definitions, click
.
-
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.
-
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.
-
-
In the Name field, do one of the following:
-
User-Defined Variable: Type a logical variable name.
-
Variable List: Do the following:
-
POOLSYM: Type POOLSYM.
-
-
-
In the Value field, do one of the following:
-
User-Defined Variable: Type the variable value.
-
Variable List: Do the following:
-
POOLSYM: Type the Pool name.
-
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 the %%MYDATE variable 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
The Shared Variables tool enables you to monitor the current and changing resolved values of all named Pool variables in Workspaces, SMART folders, or active jobs during run time.
The following video describes Shared Variables:
You create a Federal_Reserve_Rate named Pool variable and set its value to the daily US Federal Reserve Interest rate, and a USD_to_ILS named Pool variable and set its value to the daily USD-to-ILS currency exchange rate. 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 definition The set of parameters that defines what the job does, when it runs, its prerequisites, and the post-processing actions that Control-M performs after the job completes execution..
Attribute |
Tab |
---|---|
Command |
General Tab: OS job type |
File Name |
|
File Path |
|
Alerts Window Message |
Actions Tab: If-Actions> Action> Notify |
Job Log Message |
|
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 |
|
File Name |
Actions tab: Output Handling options > Action > Copy |
Variable Reference Syntax
The following table describes the scope-specific syntax that enables you to reference a variable in a SMART folder, sub-folder, or job attribute.
Scope |
Syntax |
Description |
---|---|---|
Local |
%%<Variable_Name> |
Defines a local variable that resolves to the variable value. |
Named Pool |
%%\\<Pool_Name>\<Variable_Name> |
Defines a named Pool variable that resolves to the variable value. |
SMART Folder |
%%<Variable_Name> |
Defines a SMART folder variable that resolves to the variable value. |
All Scopes |
Windows: <Prefix>%#%<Variable_Name> |
Defines a local, Global, named Pool, or SMART folder variable value that resolves to the scope-specific prefix syntax and variable name. %%MYDATE is a local, user-defined variable that is referenced in the job Daily_Audit as %%%#%MYDATE. The following output appears: Job Daily_Audit returned a value for variable %%MYDATE. |
For more information on variable scopes, see Variable Scopes.
Job General System Variables
The following table describes the job general system variables.
Name |
Resolution |
Description |
---|---|---|
%%APPLIC |
String |
Resolves the Application |
%%APPLGROUP |
String |
Resolves the job Sub-application |
%%CYCLIC |
Y or N |
Resolves the cyclic
|
%%$FOLDER_ID |
String |
Resolves the SMART-folder-based job run ID |
%%GROUP_ORDID |
Numeric |
Resolves the Sub-application run ID where the active-SMART-folder-based job resides, in base 10. |
%%$GROUP_ORDID |
Numeric |
Resolves the Sub-application run ID where the active-SMART-folder-based job resides, in base 36. |
String |
Resolves the job name. |
|
%%ORDERID |
String |
Resolves the job run ID. |
%%OWNER |
String |
Resolves the Run as User |
%%RUNCOUNT |
Numeric |
Resolves the number of past job executions, including individual cyclic job executions. A resolved value of 1 indicates that the job has only executed once. |
%%SCHEDTAB |
String |
Resolves job parent folder name. |
%%SMART_ORDERID |
Numeric |
Resolves the SMART folder run ID in base 10. |
%%$SMART_ORDERID |
Numeric |
Resolves the SMART folder run ID in base 36. |
%%$TABLE_ID |
Numeric |
Resolves the job folder run ID in base 36. |
Application and Sub-application Variables
The following is a list of unique rules that apply to variables used in the Application and Sub-application fields:
-
Different Application names appear in the job output when the jobs that run at different times.
Application = APP_X_%%TIME
FolderX runs at a New Day time of 07:00, and then runs again via the ctmudly utility at 14:00. On the run day, the following Application names appear in successive job outputs:
-
APP_X_07:00: Jobs that ran at New Day time.
-
APP_X_14:00: Jobs that ran via the ctmudly utility.
-
-
The following system variables are resolved when the job runs:
-
%%$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 runs, but %%VAR1 only resolves when the job executes.
The following Application value appears in the output:
140413%%VAR1
-
-
Multiple variables and fixed text are used in a single field.
Application = Shipments_%%ODATE.%%TIME
The following Application value appears in the output:
Shipments_01012021.07:00
-
The following system 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 system 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 system 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 ODATE 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 Queue |
%%$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. |
%%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 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. |
%%DATACENTER |
String |
Resolves to the name of the Server for the current Control-M installation. |
%%DATE |
YYMMDD |
Resolves to the current date. |
YYYYMMDD |
Resolves to the current date (4-digit year). |
|
%%$RDATE |
YYYYMMDD |
Same as %%$DATE. |
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 |
Same as %%JULDAY. |
%%MONNAM |
String |
Resolves to the first 3 letters of the name of the current month. |
%%RMONNAM |
|
Same as %%MONNAM. |
%%MONTH |
MM |
Resolves to the current month. |
%%RMONTH |
MM |
Same as %%MONTH. |
%%RDAY |
1–31 |
Resolves to the current 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. |
%%RWDAY |
0–6 |
Same as %%WDAY. |
%%YEAR |
YY |
Resolves to the current year. |
%%RYEAR |
YY |
Same as %%YEAR. |
%%$RYEAR |
YYYY |
Resolves to the current year (4-digit year). |
%%TIME |
HHMMSS |
Resolves to the current time of day. |
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 Agent |
%%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. |
SLA Management Variables
The following table lists the SLA Management variables, which you can only define in the SLA Service Actions of an SLA Management job.
Variable |
Description |
---|---|
%%PROBLEMATIC_JOBS |
Defines the job name in a service that is not running on time, which impacts the service. If more than one job is problematic, all problematic job names are returned. |
%%SERVICE_DUE_TIME |
Time by which the entire service should complete. |
%%SERVICE_EXPECTED_END_TIME |
Time BMC SLA Manager estimates the service will complete. |
%%SERVICE_NAME |
Name of the service. |
%%SERVICE_PRIORITY |
Priority level of the service. |
Variable Names and Values
You must define user-defined variable names in the following format:
-
1–38 alphanumeric characters.
-
Case-sensitive.
-
Cannot begin with a number.
-
No blank spaces and none of the following special characters:
< > [ ] { } ( ) = ; ` ~ | : ? . + - * / & ^ # @ ! , " '
You must assign user-defined variable values
-
1–214 alphanumeric characters.
-
Variables set on the General tab, as described in Job General System Variables.
-
Variables set when you manually run a job, as described in Running Jobs or a Workspace.
-
Variables set in the If-Action
A post-processing action that you define for Control-M to perform after a job executes, if a condition is met. of a previous job, as described in If-Action Action Attributes.
Variable Manipulations
Variable manipulations are mathematical operations that enable you to redefine the date or numeric value of a variable, via the following syntax:
<VALUE> <OPERATOR> <NUMBER>
The following table describes the variable manipulation parameters:
Parameter |
Description |
---|---|
<VALUE> |
Defines a date or number. |
<OPERATOR> |
Determines one of the following operators:
|
<NUMBER> |
Defines the number that is applied to the variable value via the operator. |
The user-defined variable %%YESTERDAY is manipulated as follows:
%%DAY %%MINUS 1
where %%DAY a system variable that represents the current system day.
After this manipulation, %%YESTERDAY resolves to the day before the current system day when it is referenced in an attribute.
Variable Concatenations
Variable concatenation is the arrangement of multiple variables into a single, chained string, via the following syntax:
<Variable_1>.<Variable_2>
where the . (period) operator concatenates the variables.
You must type .. (two periods) to add a . to the string.
On 12 March, a user-defined variable is assigned a value via one of the following concatenations:
-
%%DAY.%%MONTH: Resolves to 1203.
-
%%DAY..%%MONTH: Resolves to 12.03.
-
Today is %%DAY/%%MONTH/%%YEAR resolves to Today is 12/03/05.
Variable Functions
A variable function performs an action or process on the variable, and is used instead of another expression, as described in each of the available functions:
%%CALCDATE
%%CALCDATE and %%$CALCDATE: Adds or subtracts a specified number of days from a specified date with %%CALCDATE in 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 + or - sign.
-
<NUMBER>: The number that is added to or subtracted from the original date.
On 15 November 2029, a variable with the following value shows the date two 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 whitespace characters 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.