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. Storage Toolkit limitations and hints provides helpful information about using this dialog box.

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.
  • Create Batch Job dialog panes: The right-hand pane is comprised of two tables. The first table includes the substitution variables and the value of their run-time replacements. The second table includes files whose contents you should copy to view later. The left-hand pane features a navigation tree view. Use the left-hand pane to view a collection of data sets. Each node on the tree represents a data set. A context menu item may be disabled based on the kind or number of data sets that are selected. Right-click on a data set node in the navigation tree, to display a context menu and the following list of menu options:
    • Add: To add a data set to the tree view. You can add only one data set at a time. Once you add a data set, the data set will be scanned for predefined substitution variables.
    • Remove: To remove a data set from the tree view. You can remove multiple data sets at a time. If you right-click and remove the parent data set node in the tree, then you will remove the parent data set as well as all the children data sets nodes that are associated with the parent node.
      Note:
      All substitution variables included in the substitution variable table that are associated with and are unique to the data set being removed will be deleted from the table. For example, you may select any number of data sets in the tree, then right-click and remove them.
    • Rename: To rename the data set in the tree view not on the z/OS® managed system.
    • Edit: To edit a data set in the tree view. You can edit only one data set at a time.
    • Refresh: To rescan the contents of the data set in the tree view. You can refresh multiple data sets at a time. Revalidates to make sure the substitution variables that are located in the substitution variable table still exist in the data set on the managed system.
    • Submit: To submit the batch JCL. This menu item is enabled only if the selected data set is a Master data set.
  • 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.

    Refer to Standard substitution variables in the toolkit for guidelines that apply to the use of 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.

    You might encounter the following return codes when the attempt to access data sets fails:
    Return code Description
    119 (DataSetError) The User Data Set server (UDS) has failed.
    121 (AuthorizationFailure) You are attempting to access a data set for which you do not have RACF® authority.
    123 (DataSetError) The data set does not exist or the data set is not a supported format or record length.
    You might also receive a return code (status) of 117 (InvalidJCL). This status typically indicates that the JCL exceeds 72 characters when the substitution variables are applied. It might also indicate other JCL-related errors, such as a missing JOB card, or that another data set requiring variable substitution exceeds 80 characters when the substitution variables are applied.

    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.

Parent topic: Custom actions in the Storage Toolkit
Related information:
Using substitution variables in the Storage Toolkit
Examples of substitution variables
Using the Storage Toolkit

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 /*