The documentation set for this product strives to use bias-free language. For the purposes of this documentation set, bias-free is defined as language that does not imply discrimination based on age, disability, gender, racial identity, ethnic identity, sexual orientation, socioeconomic status, and intersectionality. Exceptions may be present in the documentation due to language that is hardcoded in the user interfaces of the product software, language used based on RFP documentation, or language that is used by a referenced third-party product. Learn more about how Cisco is using Inclusive Language.
TES provides a rich set of variables representing system, job and job event data points. In addition, users can define their own variables to represent dynamic information. You can use variables for command parameters, in various action messages and in job and job group dependencies. You can update user-defined variables through variable actions. For more information about jobs and job groups, see Chapter 5, “Jobs”.
Variables are useful for specifying information that continually changes or is only available at certain times. For example, if you want to know which queue your job enters when it runs, you can use the Queue Name variable to specify that information. Using the Queue Name variable in a mail action message, you can email yourself the name of the queue your job enters at every runtime.
TES’s variables function is a blend of power and flexibility that you expect in a world-class application.
Note Any argument that either explicitly has a space in it or could have a space in the argument should be enclosed in quotation marks; otherwise, the argument is returned as separate arguments wherever the spaces occur. For example, a job called Section 59 Tally would be returned as separate arguments, “Section,” “59” and “Tally.” Similarly, if a variable like <jobname> could return an argument containing a space, it also should be enclosed in quotation marks.
You can use job variables to use the information that pertains to a specific job in its definition. Job property information is represented by many variables. Some of these variables are:
In addition, to the variables for the job being defined, if a job is dependent on another job, then the variables for job “A” also show under the job variables for job “B.” That is, the same variables defined for Job “A” become available for use in the dependent job “B.”
In the same way, child jobs can access the job variables of their parent. The job variables of the parent and higher-level job groups appear as a submenu of the Job Variables menu under the name of the job group.
When the parent variable is selected, the level within the parent-child hierarchy is denoted by a suffix of a period and the letter p ( .p ). (Some variables without a time or date format may have two periods.) When the child job uses the parent variable, it is distinguished as a parent variable by a .p suffix. A grandparent variable would be .p2 , a great-grandparent variable would be .p3 , and so on.
Job variables can also be used to help communicate and/or diagnose the condition under which a job’s action was triggered.
You can define your own variables to use as command parameters or in action message text.
By using the same user-defined variable in multiple job and action definitions, you can update all the jobs and actions by just updating the variable you created.
You can declare any user-defined variable as public. Any TES user can refer to a public variable. For example, you could use public variables to refer to key employees by their title. For example, if you had a public variable named Payroll Manager which refers to the name of the Payroll Manager, you would update the variable definition when a new employee takes that position, and all instances of Payroll Manager would be updated.
You can use variables as dependencies to prevent jobs from running until their value qualifies. Variable dependencies are defined as a part of a job or job group definition. In the definition, you specify the value a variable must have before the job or job group can run. You can change variables manually to satisfy dependencies or they can change automatically when a job event or system event triggers a variable action. Thus, you can use variables to trigger the start of a job based on any system or job event.
For example, assume Job A needs to run 100 times, and when it runs, it saves a file. Job A also increments a variable from 1 to 10. When the variable reaches 10, Job B starts, resets the variable to 1, and transfers the files created by Job A to another location, freeing up disk space. TES repeats this process 10 times until Job A has run 100 times.
From the Navigator pane, select Definitions>Variables to display the Variables pane.
The Variables interface contains the following buttons:
Enter text that you want to search for within the columns displayed into this field.
Note This field at the top right of the grids will only search text columns that are not grayed out and are string-based. See Searchable Columns.
The Variables interface contains the following buttons:
If you select Preferences from the View main menu while viewing the Variables pane, the Variables Preferences dialog displays.
From the Variables Preferences dialog, you can select which columns are displayed in the Variables pane and in what order they appear.
When you right-click in the Navigator pane while viewing the Variables pane, the Navigator context menu displays.
The following describes the items in the Variables Navigator context menu:
When you right-click in the Variables pane, the Variables pane context menu displays.
The Variables pane context menu contains the following options:
The Variable Definition dialog displays when adding or editing a variable.
This dialog contains the following elements:
Note Name – The name of the variable that displays in the variable pane and in the variable selection context menus. The name of a variable cannot include the following five characters: <, >, :, . or @.
– String – The value of the variable will be a text string consisting of no more than 255 characters. Note that if you type a number when the STRING type is selected, the result will still be a string, not a numerical value.
– Number – The value of the variable must be a number (base 10).
– Date – The value of the variable will be a date string and must conform to the same format as set in the operating system that the master is running.
– Boolean – The variable uses Boolean logical operators to determine a true or false value.
If you wish to use a specific calendar date for the date value then simply enter the date in a specified format. The date format is defined on the Date tab of your computer’s Regional Options setting ( Start>Settings>Control Panel>Regional Options ).
If you wish to calculate a date, then you must configure the formula to be used in creating the date variable. You associate a date calculation with a variable from the Date Calculation dialog.
To display the Date Calculation dialog:
Step 1 Select the Date option in the Type field of the Variable Definition dialog.
Step 2 Select the Calculated option.
Step 3 Click the drill-down button in the Value field to display the Date Calculation dialog.
This dialog contains the following elements:
– Calendar Start Section – The fields that are available in the Date Calculation dialog vary according to the option selected in the Starting with field in the Calendar Start section. Some fields are unavailable with certain options while other options display new fields.
Starting with – The starting point of the date calculation. All defined offsets are offset from this date. As soon as an option is selected from the drop-down list, the resulting date displays in parentheses to the right of the field.
The possible starting points of the date calculation and their definition are listed in the following table:
– Offset section – Date offsets are optional but you may require one or more offsets from the starting date to calculate the desired date. The offset units used when calculating dates in a variable vary from a specific number of days to fiscal periods and calendar periods. You select a unit of offset from the drop-down list of unit options, select how many units to use and whether the offset is positive or negative.
For example, if the date offset is + 0 Sunday, and the start date falls on a Sunday then use that Sunday, but if the start date falls on a day other than Sunday use the next occurrence of Sunday. If the start date is March 10th, then because the start date falls on the same date as the date unit (Sunday), the calculated date is March 10th. If the start date was on a different day within the week, say on the 12th, then the calculated date would be March 17th.
For example, if the date offset is – 0 Sunday, and the start date falls on a Sunday then use that Sunday, but if the start date falls on a day other than Sunday use the previous occurrence of Sunday. If the start date is March 10th, then because the start date falls on the same date as the date unit (Sunday), the calculated date is March 10th. If the start date was on a previous day within the week, say on the 9th, then the calculated date would be March 3th.
– Offset Units – Select from the drop-down list of unit options. These options range from specific days of the week to fiscal and calendar periods of time.
– Calendar Offset – This column lists the defined calendar offset parameters.
– Offset End – This column lists the calendar date derived from the defined calendar offset relative to the starting date if the variable were to be calculated now.
– Add – Click this button to add the calendar offset parameters that are displayed to the list of calendar offsets.
– Edit – Click a listed calendar offset to select it. Click the Edit button to display and, if desired, to modify the existing parameters.
– Delete – Click this button to remove the selected calendar offset.
– Test – Click this button to test the specified date offset. Clicking this button displays a calendar tab dialog. Click a date in the calendar month to apply the offset to that date and display the resulting calculated date. The Test button is unavailable if an offset date is not selected.
A few examples may illustrate some important points about how calendar offsets work.
Fiscal calendar offsets key off both the quarter breakdown and the starting date of the fiscal calendar used in the date calculation variable. A fiscal period is often independent of a calendar period. For example, assume that the fiscal calendar being used for a fiscal quarter offset is defined to start on a Monday, January 1st with a 4-4-5 quarter breakdown. If the starting date is February 2, 2001 and the calendar offset is “+ 1 Fiscal Quarter” then the calculated offset date is April 2, 2001. This is calculated from the starting point of January 1st and counting 13 weeks (4-4-5).
Using the same fiscal calendar parameters as the preceding example, for a fiscal month with a starting date of February 2, 2002 and a “+ 1 Fiscal Month” offset calculates an offset date of February 26, 2002. It seems odd that the next fiscal month begins in the same month but the fiscal calendar is counting months according to the designated quarter breakdown and not according to the calendar month. Counting from the start of the fiscal quarter (January 1, 2002), a 4-4-5 quarter breakdown means that the months of the first fiscal quarter start on 1/1, 1/29 and 2/26 respectively. The fourth fiscal month (and second fiscal quarter) begins on 4/2.
You can also use multiple offsets. Each listed calendar offset uses the date calculated from the preceding offset to build upon when calculating its result.
In the multiple calendar offsets in the example, there are three calendar offsets used to arrive at the date offset.
A table of more calendar offset examples is provided for the user to study how calendar offsets work.
The Variables button context menu displays when you click the Variables button in the Job , Job Group or Action Definition dialogs.
When selecting a variable for a command parameter, the Variable Search dialog displays when there are too many variables to list in a context menu.
You can scroll down the list of variables and make a selection or you can start typing in the name of the variable to display the variables that match your entry.
The following describes the System Variables available from the Variables button context menu.
This context menu contains the following options:
The Variables button context menu contains the following Job variables:
– # of Files – Details the number of files FTP’ed.
– # of Bytes – Details the size of the file (in bytes) that was FTP’ed.
– # Skipped – Details the number of files within a designated directory that were not FTP’ed.
– Duration (Seconds) – Details how long (in seconds) that it took to perform the FTP operation.
Job event variables are only available when you are composing a message in the message field of an action.
The Variables button context menu contains the following Event variables:
If you are the owner (by default, the creator) of any variables, this menu selection (replaced with your user name) appears. The submenu lists all your user variables.
If you or the workgroup to which you belong own any variables, this menu selection will appear. The submenu lists all the variables owned by that workgroup.
This menu item appears if there are any public variables. Any variable can be made a public variable by selecting the Public option in its definition.
The Date Format Selection dialog displays when you choose to change the format of a date variable that was selected from a Variables button context menu. You could be in a Job , Job Group or Action Definition dialog.
This dialog contains the following elements:
– ddd (Abbreviated day of the week) – Use this date format for abbreviated days only. The first letter (of three) is capitalized. For example: Mon , Tue , Wed , etc.
– dddd (Day of week) – Use this date format for days only. The first letter is capitalized. For example: Monday , Tuesday , etc.
– dddd, mmmm dd, yyyy – The long date format. Use this format to exclude any abbreviations. For example: Friday, October 6, 2006 .
– mmmm dd, yyyy – Letterhead date format. For example: October 6, 2006 .
– dddd, dd mmmm, yyyy – An alternative long date format. Use this format to exclude any abbreviations. For example: Friday, 6 October, 2006 .
– dd mmmm, yyyy – An alternative letterhead date format. For example: 06 October, 2006 .
– Order – Arranges the order of the day, month, and year in the date format as follows:
Month, Day, Year – For example: October 6, 2006
Day, Month, Year – For example: 6 October 2006
Year, Month, Day – For example: 2006 October 6
Year, Day, Month – For example: 2006 6 October
– Separator – The character to use to separate your format into year, month and day. You can have only one separator character. The default is a forward slash /.
– Month/Qtr – Select this option to include the month or quarter in your custom date format. The default is selected.
– Day – Select this option to include the day in your custom date format. The default is selected.
– Year – Select this option to include the year in your custom date format. The default is selected.
– Month, Day and Year drop-down menus – Selects the format for each of the date elements.
– Fiscal Calendar (For Fiscal Month, Quarter or Year) – If a fiscal format was selected in either the Month/Qtr or Year fields then select a predefined fiscal calendar from this drop-down list.
– Apply – Click this button to display the custom date format in the Date Format field, and show an example using the current date in the Sample field.
The time formats available from the time format submenu use the following conventions:
Note By default the characters that comprise the time format are separated by colons but you may replace the colon with a period or manually delete the separator if desired.
When you create a variable definition, you can use it as a command parameter or as part of the message text in an action.
Step 1 From the Navigator pane, select Definitions>Variables to display the Variables pane.
Step 2 Right-click and select Add Variable from the context menu or click the Add button on the TES toolbar to display the Variable Definition dialog.
Step 3 In the Name field, type a name for the variable you are defining.
Step 4 In the Owner field, if you want to change the ownership of the variable, select a new Owner from the drop-down menu.
Step 5 In the Type field, from the drop-down menu, select the type of variable you are defining:
– String – This setting accepts any string up to 255 characters, including numerical strings. Note that STRING types cannot be incremented with a variable update action.
– Number – This setting accepts only values in numerical format, including those in exponential format (i.e., 1E5 ). It does not accept algebraic formats such as 1+2 .
– Date – This setting accepts only date values. You can only enter dates in the format defined in your Windows control panel. For example, if you have selected the short date style m/d/yy in the Regional Settings control panel, you cannot enter the date here as 10-6-07 .
– Boolean – The variable uses Boolean logical operators to determine a true or false value.
Step 6 In the Value field type a starting value for the variable. You do not have to use quotation marks. You can type up to 255 characters.
Step 7 In the Description field, type a description for the variable (optional).
Step 8 If you want the variable to be public, select the Public option. This makes the variable accessible to all TES users, within the limits of their security policy.
You can edit a variable when you want to change its current value. The new value will be used everywhere that the variable is referred to, such as in the job definition, or an action definition.
Note By default the characters that comprise the time format are separated by colons but you may replace the colon with a period or manually delete the separator if desired.
You can delete variables that are no longer used. If there are references to the variables in jobs and actions, they will be replaced with an empty string.
Note If the variable to be deleted is already in use, you will lose that variable’s value in all those instances. You can disturb your production schedule, depending on how the variable was used. Once a variable definition is deleted, it will not be automatically replaced in any instances where it has been used, even if the new variable is given exactly the same name.
Step 1 From the Navigator pane, select Definitions>Variables to display the Variables pane.
Step 2 Right-click the variable and select Delete Variable from the context menu or select the variable and click the Delete button on the TES toolbar or the Delete key on your keyboard.
Step 3 When the Confirmation dialog displays, click Yes to delete the variable.
Step 1 From the Navigator pane, select Definitions>Variables to display the Variables pane.
Step 2 Double-click the variable or right-click the variable and select Edit Variable from the context men, or select the variable and click the Edit button on the TES toolbar.
Step 3 In the Name field, edit the name of the variable.
Note If you change the name of the variable, the new variable name does not automatically get updated in all job and action definitions where it was previously used. However, the correct substitution will still occur.
Step 4 In the Type field, edit the type of variable:
– STRING – This setting accepts any string up to 255 characters, including numerical string types. Note that STRING types cannot be incremented with a variable update action.
– NUMBER – This setting accepts only values in numerical format, including those in exponential format (e.g., 1E5 ). It does not accept algebraic formats such as 1+2 .
– DATE – This setting accepts only date values. You can only enter dates in the format defined in your Windows control panel. For example, if you have selected the short date style m/d/yy in the Regional Settings control panel, you cannot type the date here as 10-6-06 .
– Boolean – The variable uses Boolean logical operators to determine a true or false value.
Step 5 In the Value field, edit the variable’s value. You do not have to use quotation marks. You can type up to 255 characters.
Step 6 In the Description field, type a description for the variable (optional).
Step 7 If you want the variable to be public, select the Public option. This makes the variable accessible to all TES users, within the limits of their security policy. To limit use of the variable to yourself and your Workgroup, clear the Public option.
You can view all the user-defined variables available to you from the Variables pane.
From the Navigator pane, select Definitions>Variables to display the Variables pane.
To view the value of a variable:
Step 1 From the Navigator pane, select Definitions>Variables to display the Variables pane.
Step 2 The Variables pane includes a Value column. If the Value column is not visible in the Variables pane, select Preferences from the View main menu to display the Variables Preferences dialog.
Step 3 On the Columns tab, select the Value option.
Step 4 For more information about the Variables Preferences dialog, see “Variables Preferences Dialog” section .
Step 5 You can also double-click the variable, or right-click and select Edit Variable from the context menu, or select the variable and click the Edit button on the TES toolbar to open the Variable Definition dialog and view its value.