Running a program in real time

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

<description>

Text description of the parameter, such as its intended use or recommended value.

<value>

Default value of the parameter.

Another workflow can access the properties file when the file is:

• Specified in the Output File field in the Workflows task UI.
• Read in as a workflow variable input file on creation of the workflow.

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>

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 <outputVariablesPrefix> 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.

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 - 2096128 (kilobytes). The Workflows task UI 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.

<timeout>

Time limit for an executable program. The valid range of values is 60 - 3600 (seconds). If no value is specified, the timeout value is 1800 seconds (30 minutes), by default.

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 an error condition. To do so, add the following sub-elements to the <submitAs> element:

<successPattern>

Successful completion message. This element is required. You must specify one (and only one) regular expression for a successful program completion.

The format is:

<successPattern>success regular expression</successPattern>

<failedPattern>

Error message. This element is optional. You can omit this element or specify up to 100 different expressions for potential program errors.

The format is:

<failedPattern>failure regular expression</failedPattern>

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.

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

In Figure 1, a template definition contains inline REXX commands for immediate processing. For more 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.

<step name="TSO-TSO-REXX_Execution">
        <title>A step that runs a REXX exec program.</title>
        <description>In this step, an inline REXX exec is processed immediately on the host system. 
                     The processing is ended by a time-out condition.
		</description>
        <variableValue name="st_group" required="true"/>
        <variableValue name="st_user" required="true"/>
		<variableValue name="procNameVariable" required="true"/>
		<instructions substitution="false">This step outputs some variables and prints a few words.
        </instructions>
        <weight>1</weight>
        <skills>System Programmer</skills>
        <template> 
       		<inlineTemplate substitution="true">/*  rexx  */
parse arg arg1
SAY "this is a sample to submit TSO REXX script to run immediately"
SAY "the first parameter is :" arg1
SAY ${instance-st_user}
SAY "prefix:st_group =" SYS123
SAY "prefix:st_user =" USERS
SAY "This execution will meets timeout."
    </inlineTemplate>
     <submitAs>TSO-REXX</submitAs>
	<successPattern>success.*</successPattern>
	<failedPattern>failed.*</failedPattern>  
	<outputVariablesPrefix needResolveConflicts="true">prefix:</outputVariablesPrefix>
	<scriptParameters>
		<description>A simple parameter</description>
		<value>para1</value>
	</scriptParameters>
	<procName substitution="true">${instance-procNameVariable}</procName>
	<regionSize>50000</regionSize>
	<timeout>60</timeout>
      <saveAsUnixFile substitution="true">/u/${instance-st_user}/savedStuff/myScript.sh</saveAsUnixFile>
 </template>
</step>