Using substitution variables in the Storage Toolkit

This section explains how to use substitution variables with the Storage Toolkit and provides examples.

You can use substitution variables to indicate portions of a Storage Toolkit command or batch job that require substitution with volume names, dataset names, or other values. Storage Toolkit limitations and hints provides helpful information about using substitution variables.

Setting substitution variables for toolkit commands

Many of the action requests that the Storage Toolkit generates can include substitution variables. You can define these variables in the Command tab in Step 6 as part of the following overall suggested procedure:

Note: A Command tab is not present in the Create Batch Job dialog box. In that dialog box, you set substitution variables in the Options tab.

Right-click rows in one of the views of a workspace to access the pop-up menu.
Select the Storage Toolkit command that you want to invoke. The Options tab is selected by default in the dialog box.
Note: An Options tab is not provided in the Issue Command dialog box, because you use this dialog box to create arbitrary free-form command and parameter strings. If you are using this dialog box, go to Step 6
Make selections and enter values in the Options tab, as appropriate.
Select the Command tab. The Command field shows how the options that you selected in the Options tab are rendered in raw text within a command.
Before you make any changes in the Command tab, inspect the command parameters and syntax that are displayed to ensure that they match your expectation. If necessary, modify the command using either of the following approaches:
- Before you make any changes in the Command tab, return to the Options tab and modify your selections.
  Note: If you make changes in the Command tab, the Options tab is disabled, and you cannot modify the selections that you made there. To be able to work with the Options tab again, you can open a new instance of the toolkit dialog box. Click Cancel to dismiss the current instance of the dialog box, and access the dialog box again through the Tivoli® Enterprise Portal.
- If you are familiar with command syntax, edit the raw text that you see in the Command field of the Command tab. Keep in mind that after you make changes in the Command tab, you cannot make further modifications to the Options tab.
If you want to define substitution variables, access the Command tab and define them in the Substitution variables and their runtime replacement values area. In many cases, the substitution variables and their runtime replacement values table are primed with variables and values defined by the Storage Toolkit based on the action and resources that you selected.
Note: A Command tab is not present in the Create Batch Job dialog box. In that dialog box, you set substitution variables in the Options tab.
Click the Show Data button to access the Data View dialog box to confirm that the correct volumes or data sets are targeted by the substitution variables.

Standard substitution variables in the toolkit

The following general guidelines apply to the substitution variables that the toolkit uses:

OMEGAMON® for Storage on z/OS® uses a pair of percent signs (%) surrounding the SUBnn name to identify the substitution variables that it provides, such as %SUB01%.
When you create variables for JCL files, it is recommended that you use the percent-sign (%) convention, as in this example: %MY_VAR%. This convention enables the Storage Toolkit to find these variables and list them automatically in the Create Batch Job dialog box. Variables that do not follow this convention are not listed automatically in the dialog box.
Do not create a variable that could be a subset of some other variable. For example, do not name a variable MY_VARNAME and another variable MY_VAR.
Do not create a variable that could match data in your command, JCL files, or generated JCL that should not be replaced. For example, in the following scenario a value might be replaced that should not be replaced:
1. You define an ADDR variable and assigned to it a value of 01AE.
2. You use the variable in the following command:
```
ANALYZE UNITADDRESS(ADDR) SCAN
```
3. Automatic substitution of the ADDR variable would generate the following command. The generated command includes a modification to the UNITADDRESS parameter that might have effects that you do not intend:
```
ANALYZE UNIT01AEESS(01AE) SCAN
```
DISP is another example of a variable name that is not recommended because that string is likely to appear on a JCL DD statement, where it should not be replaced.
The product provides generic attribute names, such as *DSN and *ROWNUMBER.

To view the scope of substitution variables that you define in the Options tab, click the Show Data button.

How commands run when substitution variables are defined

You specify substitution variables and their mappings in the Substitution variables and their run-time replacement values area of the dialog box. Depending on your settings, the action request issues the command one or more times as follows:

Number of rows selected in the workspace	Are substitution variables defined in the Command tab?	How the command runs
One	Yes or no	One time for the selected item.
Multiple	Yes	Multiple times; one time for each selected item.
One or more groups	Yes. Group attribute is specified.	Once for each volume or data set resource in each selected group.

Examples of substitution variables

The following example table shows typical substitution variables for a command that is issued by the Storage Toolkit. A similar, two-column table is provided in the dialog boxes of the toolkit.

Command Variable¹	Attribute or String²
`%dsname%`	`ENTRYNAME`
`my-volser`	`VOLUME`
`%job-name%`	`"USER01A"`
`%sysout-class%`	`"X"`
`%rownum%`	`*ROWNUMBER`
`%user-account%`	`*USERID`

The heading for this column is "Variable" when you are defining substitution variables for a batch job in the Create Batch Job dialog box. See About the "Command Variable" (or "Variable") column for more information.
You can enter raw text or use a drop-down menu to select the entries in the Attribute or string column. See About the "Attribute or String" column for more information.

About the "Command Variable" (or "Variable") column

An example of the Command Variable (or Variable) column for substitution variables is shown in Examples of substitution variables. These examples reflect names of substitution variables that might be present in user-defined JCL. The examples illustrate the following guidelines and characteristics for entries in the Command Variable column:

Strings can consist of up to 64 characters from the following character collection: [a-zA-Z0-9_.%-]. The strings are not case sensitive when processed by the mainframe agent.
The ampersand character (&) is not supported for a substitution variable. Otherwise, there could be confusion with other use of ampersands within the JCL.
Do not allow variable names to be a substring of another substitution variable. For example, do not use my_dsn and my_dsname as substitution variables.
Do not create a variable that could match data in your command, JCL files, or generated JCL that should not be replaced. For example, DISP is not recommended as the name of a substitution variable, because that string is likely to appear on a JCL DD statement, where it should not be replaced.

About the "Attribute or String" column

An example of the Attribute or String column for substitution variables is shown in Examples of substitution variables. In most cases, the values for substitution variables are taken from columns of data in the workspace where the toolkit action request originates. You use the drop-down list in the Attribute or String column to select a value. This value is used as the source of values for the corresponding substitution variable.

The toolkit detects the entries that are available for the row that you select in a workspace prior to invoking a Storage Toolkit dialog box. Examples of substitution variables illustrates the following guidelines and characteristics for entries in the Attribute or string column:

ENTRYNAME: In this example, the user selected a table attribute, ENTRYNAME, from a list box, for the value of the variable.
USER01A: In this example, the user typed a literal name (USER01A) to correspond to the %job-name% variable.
%job-name%, %sysout-class%: You can enter literal text strings in this column, instead of attribute names. The raw text can reference items in the JCL that are not related to the underlying table, such as a %job-name%, %sysout-class%, and so on. The toolkit treats a value that you enclose in single or double quotes entered as a literal string rather than the name of a table column. A single occurrence of this string is used in the batch job or command.
*ROWNUMBER: In this example, the user selected the *ROWNUMBER value from the drop-down menu that corresponds to the %rownum% variable. As a result of this setting a variable number of rows is generated for use in the JCL. The toolkit generates integer numbers ranging from 1 through the total number of data rows being passed from the underlying table. For example, you might select three rows from a workspace view when you create or resubmit an action request. In this case, the values 1, 2, and 3 would be generated.
*USERID: In this example, the user selected the *USERID value from the drop-down menu that corresponds to the %user-account% variable. This value is filled in with a single occurrence of the name of the user account that is currently active in the Tivoli Enterprise Portal.
The following points apply to setting up batch jobs in the Create Batch Job dialog:
- When the toolkit targets a member of a partitioned data set or a sequential dataset that already exists, the toolkit scans that file for strings that meet the following naming convention: %name%, where name is the name of a substitution variable. The toolkit populates the dialog box with each of the corresponding variables for %name%.
- The substitution of values for variables within the JCL might produce lines that are longer than 72 characters. If this occurs, this execution of the action request fails. A status of Invalid JCL is displayed in the Result Summary workspace.
- The substitution of values for variables within other data sets that require variable substitution might produce lines that are longer than 80 characters. If this occurs, this execution of the action request fails. A status of InvalidJCL is displayed in the Results Summary workspace.
- When configuration of the batch job is complete, you click OK in the Create Batch Job dialog box. At this point, the JCL file that you provide and any files outside that JCL that contain substitution variables are copied into temporary files. These temporary files are used when the batch job JCL is submitted. The toolkit does not modify the original files, because other users might be referencing the files at the same time.