Template steps

A step that runs a program, such as a JCL job, a REXX exec, or a UNIX shell script, is referred to as a template step. On step completion, the program results can be made available to other steps, in the form of variables or an output property file. This topic describes how to write a template step, so that you can run programs and batch jobs in your workflow.

To enable a step to run a program or batch job, you must include the template element (<template>) and related elements and attributes from the Workflows schema in the XML structure for the step.

For the program that you want to run, you must determine:

Whether to include the program code inline (that is, within the step XML structure), or in a separate, external file that can be called from the step. You indicate your choice by using the appropriate element tag, as follows:
<inlineTemplate>

Program code is specified inline in the step XML.

<fileTemplate>

Program is contained in an external file. The path name is also included on this element tag.
Whether the program uses variables. If so, include the "substitution=" attribute on the <inlineTemplate> or <fileTemplate> tag. For more information, see Using variables in a template step.
Whether the program runs in real time or is submitted as a batch job. You can choose to:
- Run a program in real time for immediate results. The program can be a REXX exec or a UNIX shell script.
- Submit a job for batch processing. The batch job contains JCL and might also imbed an executable program that runs under batch, such as a REXX exec or UNIX shell script.
Include the submit as element <submitAs> to indicate the type of program processing to be performed. The Workflows XML schema supports the use of an inline template or a file template for all of the program processing types. For more information about the element <submitAs> and program processing types, see Running a program in real time and Submitting a JCL job for batch processing.
Whether the program output is saved. For a step that saves its output, you can use the <output> element to name the output file that is produced by the step. The <output> element specifies a default data set name or UNIX path name for the output file.
A step can use an output file to write variables for subsequent steps to reference, as described in Saving properties to an output file.

In the Workflows task, the step owner can override the value of the <output> element and choose a different output file, if wanted.
Whether the program execution results are saved. For information, see Saving the results of a program or job.

Note:

Avoid creating an inline template with characters that interfere with XML. If this problem occurs, use a file template instead. Also, when you use Velocity comparison operators in the instructions, do not use the less than (<) or greater than (>) characters, as they interfere with XML. Instead, use the alternative notation: lt, le, gt, and ge.
No white space manipulation occurs for the inline template. Use care when typing the template into the XML, based on the context of the template. If writing JCL, for example, start the first line of the template immediately after the beginning <inlineTemplate> element. Subsequent lines must start on column 1, rather than being indented for readability.

How the user interacts with a template step

When a step includes a template element, the Workflows task enables the Next button on the wizard instructions page. When the user presses Next, the wizard guides the user through the activity, such as running a program or job, or creating and saving an output file. The behavior of the wizard is further controlled through the sub-elements that you define within the template element.

Using variables in a template step

The "substitution=" attribute on the template element indicates whether the template contains variables. The default is false. If you specify "substitution=true," you must also specify at least one variable value element (<variableValue>) in the step. Otherwise, the workflow fails validation when the user attempts to import the workflow definition into the Workflows task.

Observe the following considerations:

If you include more variables than you reference, no errors result.
If you refer to variables that are not included, but you do include at least one variable, no validation errors result. However, the Workflows task cannot resolve the variables during the substitution process.

Running a program in real time

A template step that runs a program in real time is called an immediate execution step. To run an executable program (a REXX exec or UNIX shell script) in real time, you include one of the following attributes on the submit as element (<submitAs>):

TSO-REXX: Run a REXX exec program in real time.
TSO-UNIX-REXX: Run a REXX exec program for the UNIX environment in real time.
TSO-UNIX-shell: Run a UNIX shell script in real time.

The program results are immediately available to the step owner.

When running a program using these program types, understand that the program must run in the same system as the workflow instance that contains the step.

On completion of program execution, standard TSO/E service messages are written to the script log. As the workflow author, you can supplement the TSO/E messages with your own customized messages to indicate successful completion or errors. To do so, add the following elements to the <submitAs>:

<successPattern>success regular expression.*</successPattern>
<failedPattern>failure regular expression.*</failedPattern>

The element <successPattern> is required. You must specify one (and only one) regular expression for a successful program completion. The element <failedPattern> is optional. You can omit this element or specify up to 100 different specifications for the element <failedPattern>.

The messages are limited in size, based on the program type, as follows:

TSO-REXX: The maximum length is 10000 lines.
TSO-UNIX-REXX: The maximum length is 255 characters; extra characters are truncated.
TSO-UNIX-shell: The maximum length is 255 characters; extra characters are truncated.

To enable an executable program to receive input parameters from the step owner, include the following elements on the <scriptParameters> element:

<description>: Text description of the parameter, such as its intended use or recommended value.
<value>: Value of the parameter.

To enable an executable program to create output variables for use elsewhere in the workflow, add the element <outputVariablesPrefix> to the <submitAs> element. On this element, you can specify a meaningful prefix that identifies a string as a variable.

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.

The executable program runs in a TSO/E address space on the z/OS host system. You can control how the TSO/E address space is started by including the following elements:

<regionSize>: Region size (in kilobytes) to be used for the address space. The valid range of values is 50000 to 2096128 (kilobytes). The Workflows task allows the step owner to specify a different region size, or use the supplied value. If no value is specified, the region size is 50000 kilobytes, by default.
<procName>: TSO logon procedure to be used for the address space. If no value is specified, the default is to use IZUFPROC, which is supplied by IBM as a cataloged procedure in proclib.

You can use the element <timeout> to set a time limit for an executable program. The valid range of values is 60 to 3600 (seconds). If no value is specified, the timeout value is 1800 seconds (30 minutes), by default.

Before running the program, z/OSMF saves the program to a temporary file. On completion of the program execution, z/OSMF deletes the temporary file. The location of the temporary file depends on the program type, as follows:

TSO-REXX: userID.IZUWFTSO.W, plus a randomly generated 7-digit number.
TSO-UNIX-REXX: /tmp/fileName-scriptRexxFile.rexx, where fileName is a randomly generated 32-digit number
TSO-UNIX-shell: /tmp/fileName-scriptShellFile.sh, where fileName is a randomly generated 32-digit number.

Other related output files are saved to the following temporary locations:

Variable output file is saved at /data/app/IZUWorkflows-workflowKey/outputFiles/stepName-outputfile
Message output file is saved at /data/app/IZUWorkflows-workflowKey/scriptFile/stepName-scriptOutputMessageFile

For examples of running programs from a step, see file workflow_sample_program_execution.xml, which is supplied with z/OSMF in the /samples subdirectory of the product file system.

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.

These program types are ultimately executed as a JCL 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 ten thousand (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, you should 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.

The <submitAs> element contains a "maxRc=" attribute, which identifies the maximum return code to consider as successful. 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 marks the step as complete. Otherwise, the Workflows task 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 returned by the script.

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.

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.

Saving the results of a program or job

To specify where to save the results of the step, depending on whether the template is used for file-generation or program execution, use the element <saveAsDataset> or <saveAsUnixFile>.

For a file create operation, the Workflows task recognizes that the file might be a configuration file and might therefore be required to reside in a data set or a UNIX file. Thus, the presence of each element determines whether the user is presented with a window to save the file in the corresponding location. The file is always saved in EBCDIC (code page IBM-1047). The elements serve another purpose in that a value can be specified by the workflow author as a default location, and that value itself supports variable substitution. This value is initialized in the widget that is presented to the user, who can override it.

For example, if you require the file to be saved in a data set, you would include a <saveAsDataset> element, but not a <saveAsUnixFile> element. If you did not care in which data set the file was saved, you can provide an empty element: <saveAsDataset/>.

If you want to provide a default value in which you substitute a high-level qualifier that is entered by the user, you can specify the <saveAsDataset/> element like this:

<saveAsDataSet substitution="true">${instance-hlq}.MYPROD(CONFIG)</saveAsDataset>

You can provide either, both, or neither of these elements, with or without a default value, which might or might not have substitution, as needed. Providing neither element has the same result as defining both elements without a value. Consider it a shorthand way of indicating that you can tolerate the file in either a data set or a UNIX file, and you have no suggestion as to what to name the output.

For a program template, the Workflows task always presents the user with a window to save the generated job in a user-specified location. Here, you can use the <saveAsDataset> element or the <saveAsUnixFile> element to provide a default value, with or without substitution, for either or both elements.