Variables
Variables are memory locations with a given name that can hold a value and be referenced in job 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 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.
The following video describes Shared Variables:
User-Defined Variables
User-defined variables are variables that you create by defining the variable name and assigning it a value in the job definitions of a folder, sub-folder, or job. Before the job is submitted, Control-M resolves the variables and uses the value that is retrieved in the current execution of the job. For more information on creating user-defined variables, see Adding Variables. For a description of the values that you can assign in user-defined variables, see Variable Values.
You can set the scope of the variable based on where you want to reference it, as follows:
-
Local: Enables the variable to be referenced by the current job only, in the post-processing actions of the job or in the script in the next run of the job.
-
Named Pool: Enables any job in the same Named Pool that you define to reference the variable in any subsequent jobs in the post-processing actions of the job, or in the script itself in the next run of the job.
-
Folder: Enables the variable to be referenced by the sub-folder, or job within the same folder in the post-processing actions of the job, or in the script during the run.
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 definitionThe set of parameters that defines what the job does, when it must run, its prerequisites to run, and post-processing actions for Control-M to perform after its completion (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:
-
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.
Adding Variables
This procedure describes how to add user-defined variables to a job, which enables you to share data between multiple jobs.
Begin
-
From the General tab, in the Variables area, click
.
-
From the Type drop-down list, select one of the following:
-
Local: Defines variables that can be used by other post-processing actions of the job, such as messages, do-action arguments, or the script itself in the next run.
-
Named Pool: Organizes variables into groups in a hierarchy. The variable is referenced by the pool name.
In the Pool Name field that appears, enter the name of the pool.
-
Folder: Enables other jobs in the folder to access the specified variable either in the script during the job run, or in post-processing.
-
-
In the Name field, enter the variable name.
-
In the Value field, enter the value of the variable.
A user-defined variable is added to the job definition.
To resolve and view the current values of your variables, see Variables.
Variable Reference Attributes
The following table describes the attributes where you can reference User-Defined Variables and in a job definitionThe set of parameters that defines what the job does, when it must run, its prerequisites to run, and post-processing actions for Control-M to perform after its completion (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 |
|
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 syntax for referencing a variable in the attribute of a folder, sub-folder, or job definition:
Variable |
Syntax |
---|---|
Local Variables |
%%<VARIABLE NAME> |
Named Pool Variables |
%%\\<POOL NAME>\<VARIABLE NAME> |
Folder Variables |
%%<VARIABLE NAME> |
Variables that are not resolved |
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 application |
%%APPLGROUP |
String |
Resolves the sub-application |
%%CYCLIC |
Y or N |
Resolves the cyclic
|
%%$FOLDER_ID |
String |
Resolves the run ID |
String |
Resolves the name of the job. |
|
%%MEMLIB |
String |
Resolves the file path of the job (for an OS job type of the Script type). |
%%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. |
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 at run time:
-
%%$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 at execution time.
Application = %%TIME.%%VAR1
At run time, %%TIME resolves to 140413, but %%VAR1 only resolves during execution time.
Application in the job output at run time: 140413%%VAR1
-
-
Multiple variables and fixed text can be 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 ODATEThe 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 Rune 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 |
1-7 |
Resolves to the day of the week that the job joined the Run Queue (1=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 day of the year in Julian format 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 |
D |
Resolves to the current day of the week (1=Sunday). |
%%RWDAY |
D |
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 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 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 |
Name of any job in a service that is not running on time, and, as a result, will impact the service. If more than one job is problematic, the names of all problematic jobs is 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 Values
You can set the value of User-Defined Variables with one or more of the following:
-
Any alphanumeric string up to 214 characters in length.
-
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 Action Options
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>: is a date or number
-
<OPERATOR>: is %%PLUS or %%MINUS
-
<NUMBER> : is 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>: is a date in the yymmdd or yyyymmdd format , such as 291115, or a variable that resolves to a date, such as %%DAY.
-
<OPERATOR>: is either the (+) or (-) sign.
-
<NUMBER>: is 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>: is the string variable from where to extract the new substring.
-
<START POSITION>: is 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>: is a date in the yyyymmdd format, such as 20291115, or a variable that resolves to such a date, such as %%$DATE.
-
<INSTRUCTION> can be 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>: is 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