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
- 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.
- Before you make any changes in the Command tab,
return to the Options tab and modify your selections.
- 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
- 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:
- You define an ADDR variable and assigned to it a value of 01AE.
- You use the variable in the following command:
ANALYZE UNITADDRESS(ADDR) SCAN
- 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
- 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
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
Command Variable1 | Attribute or String2 |
---|---|
%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
- 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.
- 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.