# Create Batch Job dialog box

You use this dialog box to submit user-defined JCL. This action request is a more flexible equivalent to the toolkit commands that the product provides.

The Options tab of this dialog box provides the fields that are described below.

To learn about the standard capabilities of a dialog box, see Standard tabs in the dialog boxes of the Storage Toolkit. The topic includes a link to the Reference guides for commands that are used in the Storage Toolkit.

See Conventions for JCL files that you use with the Storage Toolkit. Also see Authentication and authorization for running Storage Toolkit commands regarding the authorization that is required for the action requests of the Storage Toolkit.

- Mainframe fully qualified dataset containing the batch JCL: Specifies the data set that contains the batch job. The data set must be a sequential data set or a member of a partitioned data set (PDS). The logical record length of the data set must be 80 and the data set must be a fixed length format. To edit or create the data set, click the Edit JCL button, which causes the Edit Data Set dialog box to be displayed.
  Note: The user ID for the Tivoli Enterprise Portal that you use must be authorized in the mainframe system to access the data set. When the user ID is not authorized, you see an error message when you click Edit JCL. For more information, see Authentication and authorization for running Storage Toolkit commands.
- Substitution variables and their run-time replacement values: Specifies replacement values to be used at run time. The replacement values allow the batch job to reference specific objects, such as data sets and volumes. For example, these objects might correspond to values in the table rows that you select prior to invoking this dialog box.
  In the Variable column, you can enter a unique name for each substitution variable that exists in the data set. In the cells of the Attribute or string column, you can select from the available names. These names reflect attributes from the table rows that you selected in a workspace, prior to invoking the Create Batch Job dialog box. Alternatively, you can manually enter values in the cells. For example, you might want to enter values such as job name, sysout class, and other values that might not be present in the workspace table from which you are selecting rows.
  Tip: Use the percent-sign convention for the substitution variables (`%name%`) that are present in your JCL data set. That way, this dialog box automatically finds and lists the JCL substitution variables.
- Files whose contents should be copied for later viewing: Specifies the DD names and data sets to be preserved as a record of the results of the batch job. The files are available for viewing in the Storage Toolkit Result Details workspace.
  In the Step name column, you specify the name of the step whose data you want to save. In the Fully Qualified Dataset or DD name column, you specify the sequential data sets, members of partitioned data sets, or DD names that you want to copy. The following table shows some sample settings for this area of the dialog box:

  Table 1. Sample settings for "Files whose contents should be copied for later viewing"
  Step name | Dataset or DD name
  --- | ---
  STEPX | USER02.LOG.LISTING
  STEPY | SYSPRINT

  The specification in row one preserves data from the USER02.LOG.LISTING data set.
  The specification in row two preserves the SYSPRINT file in STEPY. This output is saved in the checkpoint file. The following restrictions apply:
  - Only sequential data sets or members of a PDS are supported.
  - VSAM data sets are not supported.
  - Data sets or files that contain unprintable characters (for example hexadecimal code) might display improperly in the Storage Toolkit Result Details workspace.
  - Output lines longer than 256 characters are truncated.
- Fully Qualified Datasets needed by the job that also contain substitution variables: Specifies data sets that are located outside the JCL job stream. Such data sets might be needed to dynamically supply substitution variables that correspond to objects (such as data sets and volumes) that are needed when the batch job runs. These additional data sets can be sequential data sets or members of partitioned data sets. The logical record length of these data sets must be 80 and these data sets must be a fixed length format.

  For example, an IEHLIST job might use a SYSIN DD statement that points to a DASD data set rather than in-stream control cards. That data set could contain substitution variables that need replacement at execution time.

  If no data sets that contain substitution variables are referenced from the JCL, this area of the dialog box can remain empty.

  Be sure to consult the RKLVLOG for additional messages regarding these results.

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.

## Conventions for JCL files that you use with the Storage Toolkit

The data set for the JCL that you create or edit must be a sequential data set or a member of a partitioned data set (PDS). Any JCL data set that you use with the Storage Toolkit must follow conventions to enable the Tivoli Enterprise Portal to substitute data values at run time. The following elements (marked in bold text in Figure 1) are substitution variables that will be altered by the Storage Toolkit at job run time:

- `%job-name%` (see line 000100)
- `%sysout%` (see line 000100)
- `%my-volser%` (see line 000800)
- `%dsname%` (see line 000800)

Figure 1. Variable elements for JCL files used with the Storage Toolkit

    ****** ***************************** Top of Data ******************************
    000100 //%job-name% JOB (),'DHODS',REGION=4M,MSGCLASS=%sysout%,NOTIFY=&SYSUID,
    000200 //         CLASS=A
    000300 //* -------------------------------------------------------------------
    000400 //LISTVTOC EXEC PGM=IEHLIST
    000500 //SYSPRINT DD SYSOUT=*
    000600 //SYSIN    DD *
    000700 )DOT
    000800   LISTVTOC DUMP,VOL=3390=%my-volser%,DSNAME=(%dsname%)
    000900 )ENDDOT
    001000 /*
    001100 //
    ****** **************************** Bottom of Data ****************************

Tip: Use the percent-sign convention for the substitution variables (`%name%`) that are present in your JCL data set. That way, this dialog box automatically finds and lists the JCL substitution variables.
The )DOT and )ENDDOT lines in Figure 1 indicate the start and end of table processing. The JCL lines between the )DOT and )ENDDOT lines are repeated for each table row that is passed into the mainframe agent at JCL execution time. Typically, these lines contain substitution variables that are replaced with new values at run time. For example, the output for these SYSIN JCL lines might look similar to this excerpt:

    000600 //SYSIN    DD *
    000700   LISTVTOC DUMP,VOL=3390=TSO201,DSNAME=(SYS2.USER.CLIST)
    000800   LISTVTOC DUMP,VOL=3390=TSO202,DSNAME=(SYS2.USER.PROCLIB)
    000900   LISTVTOC DUMP,VOL=3390=MVSA12,DSNAME=(SYS2.PROD.LOADLIB)
    001000 /*