ctmvar

The ctmvar utility defines, deletes, modifies and displays variables. This utility can be applied to variables in the following instances:

  • A specific job in a SMART folder.

  • All jobs in a SMART folder.

  • Global variables.

  • Named pool variables.

A value specified for a Global variable is overridden if a local variable with the same name is defined in a job processing definition, sub-folder or SMART folder.

Sub-folders cannot be modified using the ctmvar utility.

Creating and Editing Variables Using the ctmvar Utility

This procedure describes how to run the ctmvar utility, which enables you to define, delete, modify and display variables.

Begin

  1. Do one of the following:

    • UNIX: Log in to a Control-M/Server account

    • Windows: Open a command prompt window where Control-M/Server is installed.

      You can also run this utility on the Agent by navigating to where the Agent is installed.

  2. Type one of the following commands:

    • ctmvar -ACTION <action parameters> [ -QUIET ] [ -DEBUG <debug level> ]

    • ctmvar -POOL <pool parameters> [ -QUIET ] [ -DEBUG <debug level> ]

    • ctmvar -input_file <fullPathFileName>

    If the command ends with a backslash, add %%BLANK at the end of the command.

    ctmvar -action set -var "%%\prueba" -varexpr \c:\\home\\\test\\%%BLANK

ctmvar Parameters

The following table lists the ctmvar utility parameters.

Parameter

Description

-ACTION

Indicates the action to be performed on the specified variable. The possible actions are:

  • LOAD: Loads variables from a file. When this option is used, parameter -filename is required. The format for each variable in the specified file is:

    %%[\<SMART folder>[\<job>]]\"%%\<variable name>"=<expression>

    If the variable does not exist in the data center or the specified SMART folder or job, it is created.

    If the variable already exists, it is updated with the specified value.

  • SET: Defines a new variable. When this option is used, parameters -var and varexpr are required for each variable that you want to set.

    • If the variable does not exist in the data center or the specified SMART folder or job, it is created.

    • If the variable already exists, it is updated with the specified value.

    • If a SMART folder specified in the ctmvar utility has been run more than once, the utility updates every instance of that SMART folder in the Active Jobs database.

    Use the following syntax to set variables:

    ctmvar -action set -var "%%\<variable name>" -varexpr <variable value> -var "%%\<variable name>" -varexpr <variable value>

  • DELETE: Deletes a Global variable. When this option is used, the -var parameter is mandatory.

    This action cannot be used for variables that have been defined for a specific job or SMART folder.

  • LIST: Displays all Global variables for the data center or all variables for the specified SMART folder specified in the -var parameter.

    • ctmvar -action LIST: Displays all Global variables for the data center.

    • ctmvar -action LIST -var "%%\PAYROLL": Displays all variables that are specific to the PAYROLL SMART folder.

  • UPDATE_FOLDER_VAR: Updates the value of a local variable at folder level in a specific instance, according to the <smart_folder_orderid> that you define in -FOLDER_ORDER_ID

    ctmvar -action UPDATE_FOLDER_VAR -VAR <local_var> -varexpr <variable_new_value> -FOLDER_ORDER_ID <smart_folder_orderid>.

    The var must be without %%\

Variable values can also be displayed using the ctmstvar utility. However, the ctmstvar utility resolves the current value of only a specified variable or function. The ctmvar utility displays all variables in the data center or the specified SMART folder.

-VAR

Defines the name and location of the variable that the specified action should be applied to.

Valid Formats:

  • -var "%%\<variable name>": Defines a global variable for an entire data center.

  • -var "%%\<SMART folder name>\<variable name>": Defines a local variable for every SMART folder with the specified name.

  • -var "%%\<folder name>\<job name>\<variable name>": Defines a local variable for a specified job in the relevant folder.

  • -var "<variable name>": Defines a variable name when you update a specific folder with ACTION UPDATE_FOLDER_VAR

  • The <job name> must not belong to a sub-folder.

  • This parameter cannot be specified together with -action LOAD. For more information about variables, see Control-M Variable facility.

  • You cannot assign values to the following system variables: %%ODATE, %%$ODATE, %%GROUP_ORDID, %%$GROUP_ORDID, %%TABLE_ID, %%$TABLE_ID, %%FOLDER_ID, %%$FOLDER_ID, %%JOBNO, %%JOBID, %%ORDERID, %%SMART_ORDERID, %%$SMART_ORDERID.

-VAREXPR

Describes the value to be assigned to the specified variable.

Valid Values:

  • String

  • Integer

  • Variable

  • Another existing global variable.

-FOLDER_ORDER_ID

Determines order id of a specific folder.

Only valid when you define UPDATE_FOLDER_VAR.

-FILENAME

Defines the path and name of the file containing the list of variables. The file must be accessible to Control-M/Server. This parameter is only valid when specified together with -action LOAD.

The syntax for each line in the specified file is

%%[\<ctmvar>[\<job>]]\<varName>=<expression>

Specify the entire pathname in this parameter.

-QUIET

Suppresses the display of the results.

-DEBUG

Sets a debug level for the utility. This parameter is used for maintenance and troubleshooting purposes. The level, a numeric value from 0 to 5, must be used only if requested and specified by Technical Support.

Performance is somewhat slower and requires a larger number of resources when operating in debug mode. BMC recommends that you activate debug mode only when absolutely necessary and revert to normal mode as soon as possible.

-input_file

Defines the name and full path of a file containing parameters for the utility. In this file, each parameter and its values (if any) are on a separate line with the same syntax they would have on the command line.

Using the -input_file parameter enables you to:

  • prepare and save files of utility parameters that can be reused.

  • specify utility input longer than the number of characters allowed in the command line.

-input_file ctmvar_parms.txt

-POOL

Indicates the variable action to be performed in the specified named pool.

The following are possible actions:

  • LOAD: Loads variable values from a specified file to pool. The file name is the path name of a text file containing the variable assignment statements.

    This file must be accessible to the Control-M/Server. The file must contain a single assignment on each line.

    The following is the syntax to load variable values from a file to a named pool:

    ctmvar -pool load -poolname <pool name> -from <file name>

  • SETVAR: Defines new variables or updates existing variables in the specified named pool. When this option is used, parameters -var and value are required for each variable that you want to set.

    If the variable does not exist in the data center, it is created.

    If the variable already exists, it is updated with the specified value.

    The following is the syntax to set variables in a named pool:

    ctmvar -pool setvar -poolname <pool name> -var <variable1 name> -value <variable1 value> -var <variable2 name> -value <variable2 value>

  • DELETE: Deletes a named pool from the data center or variables from the specified named pool.

    The following is the syntax to delete all of the variables in a named pool:

    ctmvar -pool delete -poolname <pool name>

    The following is the syntax to delete specific variables in a named pool:

    ctmvar -pool deletevar -poolname <pool name> -var <variable1 name> -var <variable2 name>

    You cannot use wildcards in the name of the named pool or variable that you want to delete.

  • LIST: Lists all named pools in the data center.

    The following is the syntax to list all named pools:

    ctmvar -pool list

  • VIEW: Displays the list of variables in the named pool or specific variables in the named pool.

    The following is the syntax to view the variables in a named pool:

    ctmvar -pool view -poolname <pool name>

    The following is the syntax to view specific variables in the named pool:

    ctmvar -pool view -poolname <pool name> -var <variable name>

    You can use wildcards in the name of the named pool or variable that you want to view.

ctmvar Examples

  • The following command assigns the value UP to variable %%CTMSTATUS:

    ctmvar -action set -var "%%\CTMSTATUS" -varexpr "UP"

  • The following command assigns the value 31 to variable %%MONTHDAYS in the folder called PAYROLL:

    ctmvar -action set -var "%%\PAYROLL\MONTHDAYS" -varexpr 31

  • The following command assigns the current value of system variable %%TIME to variable %%AAA:

    ctmvar -action set -var "%%\AAA" -varexpr %%TIME

  • You can get the same result using the -input_file parameter as follows:

    ctmvar -input_file var_expr_parms.txt

    The referenced file contains the following lines:

    -action set

    -var "%%\AAA"

    -varexpr %%TIME

  • The format variable %%@varname indicates that the variable should contain a value to be resolved by each job that uses it. In the following example, the command assigns the value %%@TIME to variable %%AAA:

    ctmvar -action set -var "%%\AAA" -varexpr %%@TIME

  • The following command sets the name of the POOL to "test" and assigns the value %%ODATE to the variable A:

    ctmvar -POOL SETVAR -POOLNAME "test" -VAR "A" -VALUE "%%ODATE"