User-defined variables

A user-defined variable is created when it is assigned a value using the Variable Assignment parameter or the Do Variable parameter. User variables can also be defined for all jobs in a SMART Folder in the folder properties pane. For more information about assigning a value to a variable, see Variable Expressions.

User-defined variables can be used to

Store intermediate values in a series of Variable parameters
Store values to be included in a command string in the Command parameter
Store information to be included in a Notification message
Store information to be included in an e-mail message created with a Do Mail parameter
Global variables can be used to pass information between jobs in a Control-M/Server. For example, job A can set global variable %%A to Yes, and job B on another agent in the same Control-M/Server can reset %%A to No in response. Global variables can also be created and modified using the ctmvar utility. For more information about this utility, see Control-M Workload Automation Utilities.

Resolution of each user variable depends on the specified prefix, and the scope of the specified variable. Each of these concepts is described below.

Syntax

Valid names for user variables are any alphanumeric string (up to 38 characters in length) preceded by a prefix of %%. Blanks are not allowed in a user variable name.

The following characters cannot be included as part of the name of a User-defined variable: < > [ ] { } ( ) = ; ` ~ | : ? . + - * / & ^ # @ ! , " '.

Application-specific job parameters may not be specified in variable values. The names of application-specific job parameters are prefixed by two percent signs, the application’s abbreviation and a hyphen (%%SAPR3- for SAP, %%OAP- for Oracle, and so on).

Names and values for User variables are case sensitive. For example, %%TEST and %%Test are regarded as two separate variables.

Names of variables in Control‑M for z/OS must always be in uppercase.

All variables are prefixed by %%. In addition to the %% prefix, certain characters can be added to determine special characteristics. These special prefixes are described in the following table.

Variable Prefix	Description
%%\	Indicates that a variable is global for the Control-M/Server (Control‑M/Server and all its connected agents). This prefix is used only when creating or modifying the variable. When the variable is referenced (for example, in a Notification message) it is referenced without the \. For more information about global variables, see the Scope section below.
%%#	Indicates that the variable should not be resolved. This prefix enables inclusion of a variable name as text in job output. The # symbol is stripped from the output, and the remaining variable name is included as text in the appropriate location. For example, a Notification message of Job Daily returned a value for variable %%#PARM1 is output as: Job Daily returned a value for variable %%PARM1
%%@	Indicates that the variable should contain a value to be resolved by each job that uses it. For example: %%\PARM1 = %%@TIME Indicates that whenever a job uses Global variable %%PARM1, it should be resolved to the execution time of the job (that is, the time at which the variable is referenced). If the above parameter is specified without the @ sign (%%\PARM1 = %%TIME), it always resolves to the execution time of the job that set the variable (that is, the time at which the variable was created). This prefix is relevant only for Global variables whose values contain variables.
%%	For Windows agents: When specifying variables in the CMDLINE or COMMAND parameters on Control-M/Agent for Windows, the Variable prefix must be specified as %%.
%%	If you use an agent utility (such as ctmcreate) in a batch file to specify an variable, ensure that the prefix is %%%%.

Variable Prefix	Description
%%A=%%ODATE	The %%A variable is resolved to the original scheduling date of the job. %%A is local to the job.
%%\A=%%ODATE	Global variable %%\A is assigned to the original scheduling date of the job. %%A can be referenced by Control-M/Server or any agent in the data centerControl-M/Server. All references to variable %%A resolve to the %%ODATE value for the job in which %%A was set.
%%\A=%%@ODATE	Global variable %%\A is resolved to the original scheduling date of the job. If %%A is referenced by Control-M/Server or a job in any agent in the Control-M/Server, it resolves to the current value of variable %%ODATE. @ indicates that %%\A should contain a value to be resolved by each job that uses it (in this case, ODATE).
%%#A	%%#A is not resolved. The text string %%A is returned.

Scope

The scope of a variable is the extent to which it is available to other jobs. As mentioned above, each variable can be

local for a specific job
common to all jobs in a SMART Folder
global for an entire Control-M/Server (a Control‑M/Server and all its agents)
system Variables which are predefined and available for any job in the Control-M/Server

Multiple variables (each with a different scope) can have the same name. If more than one variable with the same name has been defined, the variable with the narrowest scope is used.

The exception to this rule occurs when the variable is distributed from the Control‑M/Server to the Control‑M/Agent. The variable from the narrowest scope may not be the one that is used by the Control‑M/Agent.

Depending on the value of the VARIABLE_INC_SEC variable of the Control‑M/Server, duplicate variables from different scopes can be distributed to the agents. For more information, see Control-M Administration.

Control‑M uses the following logic to determine which value to use when a variable is specified in a job processing definition:

Control‑M checks if a local variable (for the job) has been defined with the specified name. If a local variable exists, the value specified for that variable is used.
If no local variable exists with the specified name, and the job is in a SMART Folder, Control‑M checks for a variable with the specified name in the SMART Folder definition. If the variable is defined in the SMART Folder definition, that value is used.
If the job is not in a SMART Folder, or the variable is not defined in the SMART Folder definition, Control‑M searches for a Global variable with the specified name.
If no definition is found for a specified variable, the variable is resolved to the reserved word CTMERR.

Parent Topic

Control-M Variable facility