Submitting a JCL job for batch processing

A template step that runs a program as a batch job is called a batch execution step. The submit as element (<submitAs>) indicates the type of program to be run.

To run an executable program as a batch job, such as a JCL job, a REXX exec, or a UNIX shell script, you include one of the following attributes on the submit as element (<submitAs>):

JCL: Submit a JCL job for batch processing on z/OS. The results are indicated in the job log.
TSO-REXX-JCL: Submit a JCL job that contains a REXX program. The program runs as a batch job on z/OS; the results are indicated in the job log.
shell-JCL: Submit a JCL job that contains a UNIX shell script. The program runs as a batch job on z/OS; the results are indicated in the job log.

Each program type is executed as a batch job by the Workflows task, which creates the necessary JCL and JOB statement, and displays the job output in the Workflows task. The size of any program to be run (JCL, REXX, or shell) is limited to 10000 lines of code.

In the following example, a template definition contains inline JCL that runs a TSO command:

<template>
        <inlineTemplate>//STEP1       EXEC  PGM=IKJEFT01,DYNAMNBR=20
//SYSTSPRT    DD    SYSOUT=A
//SYSTSIN     DD    *
LISTUSER IBMUSER
/*
        </inlineTemplate>
        <submitAs>JCL</submitAs>
</template>

Suppose that the first line of the JCL were to be placed on the next line after the beginning <inlineTemplate> tag. Doing so would inject a space into the JCL stream and cause a JCL error. Similarly, if any of the lines of JCL were to be indented, a JCL error would occur. Therefore, unless the file or program is small, use <fileTemplate> instead, which identifies the path name of an external file that contains the template. For path name examples, see References to external files.

In the following example, the file that is named jcljob.txt contains the JCL and exists in the same UNIX directory as the workflow definition file:

<template>
        <fileTemplate>
                jcljob.txt
        </fileTemplate>
        <submitAs>JCL</submitAs>
</template>

The Workflows task routes the job to another system in the sysplex, as determined by the system name that is chosen by the user when importing the workflow. Both JES2 and JES3 are supported. The JOB statement is entered by the Workflows task user separately, and applied to the job stream before it is submitted. Do not include a job card in your JCL template.

Observe the following considerations:

A JCL template is submitted by the Workflows task after it includes the user-specified JOB statement and the appropriate JES routing statement, if the job is to be run on a different system in the sysplex.
A REXX template is run by an IKJEFT01 job. This job creates a temporary data set to contain the REXX exec, and then executes the exec from that data set.
A shell script is run by the BPXBATCH program. A temporary directory and file is created to contain the script. The script is run from this location and then the temporary directory and file are deleted.

Writing variables to a properties file

In your program, you might choose to create variables, and save them to a properties file. When the file is saved, the properties are available for use with the same workflow. For more information, see Creating a properties file.

For a program that creates variables in a properties file, you can optionally include a prefix on the output variables. Here, you can specify a meaningful prefix that identifies a string as an output variable. To do so, add the element <outputVariablesPrefix> to the <submitAs> element.

In the following example, the string outvar: is applied to the names of any variables that are created by the step:

<outputVariablesPrefix needResolveConflicts="true">outvar:</outputVariablesPrefix>

To manage potential variable name conflicts, you can specify a default behavior by adding the attribute <needResolveConflicts> to the element <outputVariablesPrefix>. By default, the step owner is prompted to choose the appropriate variable value in the Workflows task.

For an array variable, variable name conflicts are handled differently. The step owner is not prompted to choose the appropriate variable value. Instead, variable name conflicts are handled by the behavior you specify on the (loadOutputFileArrayValue) attribute. Add this attribute to the element <output> and set it to true or false, as follows:

If set to true (the default), the workflow uses the array variable values from the output file, rather than from the Workflows task.
If set to false, the workflow uses the existing values from the Workflows task.

Maximum return code

On the <submitAs> element, you can optionally indicate the maximum acceptable return code from the program on the MaxRC= attribute.

When the user presses the Close button from the Status tab of the Perform page (which displays the job output), the Workflows task checks the job return code. If the return code is less than or equal to the maxRc value, the Workflows task UI marks the step as complete. Otherwise, the Workflows task UI marks the step as failed.

JCL limits the return code value to the range 0 – 4095. If you do not specify a return code, the Workflows task uses a value of zero by default. BPXBATCH, which runs a shell script, further limits the return code to the range 0 – 15. If you are familiar with BPXBATCH, you might be aware that this service multiplies the script return code by 256 to derive a final return code value. The Workflows task divides the result by 256. Thus, you can code your workflow to be consistent with the value that is returned by the script.

Maximum record length

For a step that submits a job, you can use the <maxLrecl> element to specify the maximum record length, in bytes, for the input data for the job. This value is used when the step is performed automatically (<autoEnable> is set to true; see Automated steps). If the step is performed manually, the user can optionally specify the maximum record length on the Edit JCL page in the Workflows task. If you omit the <maxLrecl> element, the default is 1024. For a job that uses the IEBUPDTE program to create or modify data sets, set this value to the minimum value of 80 to ensure that fixed-length records of 80 bytes or less can be processed.

Examples

For examples of submitting batch jobs from a step, see file workflow_sample_wizards.xml, which is supplied with z/OSMF in the /samples subdirectory of the product file system.