Variables

Variables are names with an assigned value that you can reference in your job processing definitions. Control-M resolves the variable when the job begins execution or completes execution and then uses the variable’s resolution for the current execution of the job. The contents of the original job processing definition and variables, remain unchanged.

The following lists variable types that you can define in your folder, sub-folder, and job attributes:

• User-Defined Variables: Describes variables that you set manually by setting the variable name and assigning a value.

• System Variables: Describes variables with reserved names. Control-M sets the name and assigns a value.

The following video describes Shared Variables:

User-Defined Variables

User-defined variables are variables that are set manually in the definition of a folder, sub-folder, or job. Before the job is submitted Control-M resolves the variables and uses the value for the current execution of the job. 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.

• Global: Enables any job in your environment to reference the variable.

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

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

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
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 folder, sub-folder, or job definition:

Variable	Syntax
Local Variables	%%<VARIABLE NAME>
Global Variables	%%\<VARIABLE NAME>
Named Pool Variables	%%\\<POOL NAME>\<VARIABLE NAME>
Folder Variables	%%<VARIABLE NAME>
Variables that are not resolved	UNIX: # Windows: %#%

System Variables

System variables are variables where the names and values are defined and set 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 value for the current execution of the job.

The following lists 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

• Command System Variables: Enables you to specify a command to run before or after running the job

• Action System Variables: Returns statistics about your job after it has been executed

Job General System Variables

The following table describes the Job General System Variables:

Name	Resolution	Description
%%APPLIC	String	Resolves to the applicationA job attribute that provides a logical name for sorting groups of jobs, which you can use to search and update jobs of the job. z/OS: Used to reference the application name.
%%APPLGROUP	String	Resolves to the sub-applicationA job attribute that provides a logical name for sorting groups of jobs within an application, which you can use to search and update jobs of the job.
%%CYCLIC	Y or N	Resolves to the cyclicA folder or job that executes multiple times in one run, at a specific interval or specific times, or according to a specific sequence of intervals status of the job, as follows: Y: The job is cyclic. N: The job is not cyclic.
%%$FOLDER_ID	String	Resolves to the run IDThe ID code of the run of a folder, sub-folder, or job of the job. This variable is valid for jobs in a folder and is evaluated in base 36.
%%GROUP_ORDID	Numeric	Resolves to the Run ID of the sub-application where the job belongs. This variable is valid only for jobs in an active folder and is evaluated in base 10.
%%$GROUP_ORDID	Numeric	Resolves to the Run ID of the sub-application where the job belongs. This variable is valid only for job in an active folder and is evaluated in base 36.
%%JOBNAME	String	Resolves to the name of the job.
%%MEMLIB	String	Resolves to the file path of the job (for an OS job type of the Script type). z/OS: Resolves to the Mem Lib (name of the library or directory where the job script is stored) of the job.
%%ORDERID	String	Resolves to the run ID of the job.
%%OWNER	String	Resolves to the username with the authorization to execute the job and is defined in the Run as field.
%%RUNCOUNT	Numeric	Resolves to 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 to the name of the parent folder of the job.
%%SMART_ORDERID		Defines 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		Determines 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	Defines 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 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 is resolved to 140413, but %%VAR1 is only resolved 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 QueueThe 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 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 Control-M/Server date changes when the New Day procedure runs. If New Day is at 7:00 am, then 6: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 day of the year in Julian format such as, 36 for February 5th.
%%RJULDAY	1-365	Resolves to the current Control-M/Server day of the year in Julian format 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	D	Resolves to the current day of the week (1=Sunday).
%%RWDAY	D	Resolves to the current Control-M/Server day of the week (1=Sunday).
%%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 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 AgentA Control-M component installed on a host 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 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-actionA 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

• System Variables

• Variable Reference Attributes

• Variable Concatenations

• Variable Functions

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

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

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

• %%GETENV

• %%SUBSTR

• %%$WCALC

• %%BLANK

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

%%GETENV

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

%%GETENV <ENVIRONMENT>

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

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

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

%%$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.

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