Z/OS Task

From OpsWise Documentation Wiki

Your trail:Viewing Activity by Group Windows Resource Windows Task Z/OS Resource Z/OS Task

Before You Begin

The z/OS task allow you to run a platform-specific application on a z/OS machine. To run a z/OS task, you must first complete the following tasks:

Install an OpsWise Automation Center z/OS agent on a z/OS machine.
Launch the agent. When the agent connects with the core processor, it automatically creates a z/OS agent resource definition in the database.
Optionally, customize the agent heartbeat and log levels, as described in z/OS Resource Field Definitions.

Creating a New z/OS Task

From the Navigation Pane, select z/OS Tasks.
From the trigger wizard, select New. OpsWise Automation Center displays the z/OS Task screen.
Using the field descriptions provided below as a guide, complete the fields as needed.
Click the Submit button to save the record and return to the menu, or, right-click on the title bar and select Save to save the record and remain on the current display.
If appropriate, repeat these steps for any additional tasks you want to add.

Shown below is a sample z/OS task screen. Task run statistics appear after the first time this task has been launched.

z/OS Task Field Descriptions

The table below describes the fields and buttons on the z/OS task definition and task instance screens. Most fields appear on both screens; however they do not always appear at the same spot. In the latter case, the table provides a field description at the location found on the task definition screen. Some fields appear only on one of the screens. Field labels shown in bold appear only on the task instance screen and are labelled as such.

Field Name	Description
Task / Instance Name	Required. Name used within OpsWise Automation Center to identify this task. Up to 40 alphanumerics; variables supported. It is the user’s responsibility to develop a workable naming scheme for tasks.
Invoked by	Task instance only; system-supplied. How the task instance was launched. Options: Trigger: [Trigger Name] - The instance was launched by the named trigger. Workflow: [Workflow Name] - The instance was launched by the named workflow. Manually Launched - The instance was launched by a user. To identify the user who launched the instance:
Task	Task instance only; system-supplied.
Execution User	Task instance only; system-supplied.
Instance Reference Id	Task instance only; system-supplied.
Credentials	Required for z/OS. The login credentials OpsWise Automation Center will use to access the remote machine. See Credentials.
Credentials Variable	Optional. If enabled, the Credentials field (see above) converts from a reference field (where you browse and select a record) into a text field that allows you to enter a variable. Use the format: ${variable name}. The variable must be a supported type as described in Using Variables.
Agent	Optional. The name of the z/OS agent resource w that describes the machine where the application will run. If you do not specify an agent, you must specify an agent group (see below).
New Jobname	Optional. Jobname to replace the one in the JCL member. This allows you to override the value in your JCL from OpsWise without having to modify the JCL.
Agent Variable	Optional. If enabled, the Agent field (see above) converts from a reference field (where you browse and select a record) into a text field that allows you to enter a variable. Use the format: ${variable name}. The variable must be a supported type as described in Using Variables.
New Jobclass	New Jobclass to replace the one in the JCL member. This allows you to override the value in your JCL from OpsWise without having to modify the JCL.
Hold on Start	Optional. If enabled, when the task is launched it appears in the Activity display with a status of Held. The task runs when the user releases it. .
New Msgclass	Optional. New MSGCLASS to replace the one in the JCL member. This allows you to override the value in your JCL from OpsWise without having to modify the JCL.
PROCLIB	Optional. Enter a PROCLIB for the JESPARM statement PROCLIB=. This allows you to add a value to your JCL from OpsWise without having to modify the JCL.
Schedule ID	Optional. The CA7 Schedule ID; for CA7 compatibility only.
Hold Reason	Task instance only. For a task on hold, provides information about the hold.
Summary	Optional. User-supplied information about this task.
Member of Groups	Optional. Allows you to select one or more Opswise groups that this task definition belongs to. Click on the lock icon to unlock the field and select groups.
Status	Task instance only; system-supplied. See Task Status.
Status Description	Task instance only; system-supplied. Provides additional information, if any, about the status of the task.
Queued Time	Task instance only; system-supplied. The time the task was queued for processing.
CPU Time	Task instance only; system-supplied. The amount of CPU time the task took to run.
Start Time	Task instance only; system-supplied. The time the task started.
Duration	Task instance only; system-supplied. The amount of time the task took to run.
End Time	Task instance only; system-supplied. The time the task completed.
User-Estimated Duration	Optional. The estimated amount of time it should normally take to run this task. The value in this field is used by OpsWise Automation Center to calculate the User Estimated End Time when the task is launched. You can view this information by selecting the Task Instance record from the Activity screen.
JCL Location	Required. The file and member name containing the JCL script.
Exit Code Processing	Required. Specifies how OpsWise Automation Center should determine whether the each step in the JCL failed or completed successfully. Options: Success Exitcode Range - The program is considered completed successfully if its exitcode falls within the range specified in the Exit Codes field (see below). Failure Exitcode Range - The program is considered failed if its exitcode falls within the range specified in the Exit Codes field (see below). Success Output Contains - The program is considered completed successfully if its output contains the text specified in the Scan Output For field (see below). Failure Output Contains - The program is considered failed if its output contains the text specified in the Scan Output For field (see below).
Output Type	Required if Exit Code Processing = Success Output Contains or Failure Output Contains. This field specifies the type of output. Options: Standard Output (STDOUT) Standard Error (STDERR) File
Exit Codes	Required if Exit Code Processing = Success Exitcode Range or Failure Exit Code Range. This field specifies the range. Each step in the JCL must end with an exit code that falls within the specified range or the step goes to a Failed status. Format: Numeric. Use commas to list a series of exitcodes; use hyphens to specify a range. Example: 1,5, 22-30.
Scan Output For	Required if Exit Code Processing = Success Output Contains or Failure Output Contains. This field specifies the text for which OpsWise Automation Center should scan the output file.
Output File	Required if Output Type = File. This field specifies the path and file name of the file containing exit code processing data.
Parameters	Optional. Allows you to enter parameters needed by the JCL to run. Type in the name of the parameter and its value, and click Add. The system displays the parameter in the space underneath. You can add as many parameters as needed. To delete a parameter, click the X button. You can also use this field to specify any steps you want skipped during the job run.
Automatic Output Retrieval	Optional. Allows you to specify whether you want the system to automatically retrieve any output from the job and attach it to the task instance record. Options: None - Do not attach any output to the task instance record. Standard Output - Attach all standard output. Standard Error - Attach standard error output. File - Attach the file specified in the Output File field. Joblog - Attach output from the z/OS joblog.
Output File	Required if Automatic Output Retrieval=File. This field specifies the path and filename containing the output that you want attached to the task instance.
Starting Line	Optional. Allows you to instruct the system to fetch data beginning at the line indicated.
Number of Lines	Optional. Allows you to limit the retrieved data to the number of lines specified. The default is 100. You can change the default by modifying the record Configuration > Properties > Retrieve Output Default Maximum Lines.
Scan Output For	Optional. Instructs the system to scan the data for the text specified and retrieve only that.
Task Priority	Task instance only; system-supplied.
Retry Indefinitely	Task instance only; system-supplied.
Late Start	Optional. If enabled, and if the task instance starts after the time specified in the Late Start Time field (see below), the task instance is flagged as late. To determine whether a task instance started late, open the task instance and locate the Started Late field; the field is checked if the instance started late.
Late Start Type	Required if Late Start is enabled. Options are: Time - Flag the task if it starts after the specified time. Duration - Flag the task if it starts a certain amount of time after the programmed start time. The task must have a specific start time.
Late Start Time (hh:mm)	Required if Start Type=Time. The time after which the task start time is considered late. Use hh:mm, 24-hour time.
Late Finish	Optional. If enabled, and if the task instance finishes after the time or period specified, the task instance is flagged as late. You can specify a time or duration to determine a late finish (see Late Finish Type below). To determine whether a task instance finished late, open the task instance and locate the Finished Late field; the field is checked if the instance finished after the specified time or lasted longer than expected.
Late Finish Type	Required if Late Finish is enabled. Use this field to specify whether you want to use time (see Late Finish Time below) or duration (see Late Finish Duration below) to determine whether the task instance finished late.
Late Finish Time (hh:mm)	Required if Late Finish Type=Time. Use this to specify the time after which the task finish time is considered late. Use hh:mm, 24-hour time.
Late Finish Duration	Required if Late Finish Type is Duration. Use this to specify the longest amount of time this task instance should take to run. You can specify any combination of days, hours, minutes, and seconds.
Early Finish	Optional. If enabled, and if the task instance finishes before the time or period specified, the task instance is flagged as early. You can specify a time or duration to determine an early finish (see Early Finish Type below). To determine whether a task instance finished early, open the task instance and locate the Finished Early field; the field is checked if the instance finished before the specified time or did not last as long as expected.
Early Finish Type	Required if Early Finish is enabled. Use this field to specify whether you want to use time (see Early Finish Time below) or duration (see Early Finish Duration below) to determine whether the task instance finished early.
Early Finish Time (hh:mm)	Required if Early Finish Type is Time. Use this to specify the time before which the task finish time is considered early. Use hh:mm, 24-hour time.
Early Finish Duration	Required if Early Finish Type is Duration. Use this to specify the shortest amount of time this task instance should take to run. If the task finishes before the amount of time specified, it is flagged as early. You can specify any combination of days, hours, minutes, and seconds.
Maximum Retries	Optional. Allows you to specify the maximum number of times the system should retry running the task if technical problems are keeping it from running.
Retry Interval (Seconds)	Optional. Allows you to specify how often the system should retry the task if technical problems are keeping it from running.
Current Retry Count	Task instance only; system-supplied. If the system is having technical problems launching the task and is retrying, it keeps a tally of retries in this field.
User Estimated End Time	Task instance only; system-supplied.
Shortest Estimated End Time	Task instance only; system-supplied.
Average Estimated End Time	Task instance only; system-supplied.
Longest Estimated End Time	Task instance only; system-supplied.
Submit button	Submits the new record to the database.
Update button	Saves updates to the record.
View Parent	Task instance only; Displays this task's parent task (workflow), if any.
Show Details	Task instance only; displays more details about this task instance.
Skip	Task instance only; See Skipping a Task.
Hold	Task instance only; see Putting a Task on Hold.
Force Finish	Task instance only; see Force Finishing a Task.
Launch Task button	Task definition record only. Manually launches the task.
Delete button	Deletes the current record.
Task Virtual Resources tab	Task definition record only. Allows you to create virtual resource definitions for controlling access to resources by multiple tasks. See Creating Virtual Resources.
Variables tab	Task Definition Record only. Displays all variables associated with this task.
Actions tab	Task definition record only. Allows you to specify actions that the system will take automatically based on events that occur during the execution of this task. Events supported are task instance status, exit codes, late start, late finish, and early finish. Actions include: Abort Action - Abort the task if certain events occur. For details, see Setting Up Abort Actions. Email Notification - Send an email if certain events occur. For details, see Creating Email Notifications. SNMP Notification - Send an email if certain events occur. For details, see Creating SNMP Notifications. Set Variable - Set a variable if certain events occur. For details, see Setting Variables in a Workflow.
Task Instances tab	Task instance record only; system-supplied. Displays a list of all instances generated by this task.
Triggers tab	Task definition record only. Displays a list of all triggers that have been defined to launch this task. Also allows you to add new triggers. For instructions, see Triggers.
Notes tab	Task definition record only. Displays all notes associated with this task. See Runbook Notes.
Output	Task instance record only. See the field description for Automatic Output Retrieval and Retrieving Output.
Z/OS Restartable JobSteps	See Rerunning a z/OS Task and Confirming any JCL Changes.
Restart Confirmation	See Rerunning a z/OS Task and Confirming any JCL Changes.

Specifying When a Task Runs

You can run the task as part of a workflow, specify triggers that run the task automatically based on times or events, or run the task manually.

Monitoring Task Execution

You can monitor all system activity from the Activity screen and can view activity history from the Activity History screen.

Special Processing on z/OS Tasks

The following special processing features are available for running z/OS tasks:

Instructing the system to skip one or more specific steps during the initial run
Changing the Jobname, Jobclass, Msgclass or adding a *JOBPARM card

The following failure processing features are available for handling job failures:

Restarting the task from a specific step
Instructing the system to skip one or more specific steps when performing a restart
Reviewing and confirming any JCL changes before running the restart
Changing the step code on a previous step to allow a job to continue to success

OpsWise provides the following reports that track error processing:

Ops Rerun Reports
Detailed Audit Trails

Each of these features is described in detail below.

Skipping Steps during Initial Run

You can specify in a z/OS task that one or more steps from the JCL should be skipped when Opswise launches the job. You achieve this by adding SKIPSTNN variables (or parameters) to your z/OS task record.

To configure your z/OS task to skip specific JCL steps:

Open the task record.
Use the 'add parameters' feature to add the first parameter in the following format:
SKIPSTAA=STEPNAME
Where AA is any unique combination of alphanumerics and STEPNAME is the JCL step name.
Click the Add button. The new parameter is added to your parameter list.
Repeat the above step for each step you want to skip. Change the AA portion of the SKIPST parameter for each parameter you add. That is, each parameter name must be unique.
In the example below, two skipstep parameters have been added to the record, instructing OpsWise to skip JCL steps 03 and 05.

To delete a parameter, click the X.

Overriding Old JCL Parameters from OpsWise

When you launch a z/OS task from OpsWise, you can specify a different Jobname, Jobclass, Msgclass, Schedule ID or add a *JOBPARM card. This enables you to run your old JCL jobs from OpsWise without having to go in and modify your JCL. See the screen shot under Creating a New z/OS Task for the location of these fields.

Rerunning a z/OS Task and Confirming Any JCL Changes

When you rerun a z/OS task, OpsWise Automation Center allows you to specify which step you want to start from or which specific steps you want the system to rerun. The Restartable Steps tab provides a list of steps and flags which ones you can rerun.

When you rerun a z/OS task, the system automatically performs the following:

Deletes temporary data sets that were created in dependent steps.
Maintains Generation Data Set bias.

You must restart the z/OS task from OpsWise in order for these cleanup procedures to be performed. Do not restart the task from the z/OS prompt. If you make any JCL changes, OpsWise will prompt you for a confirmation, as described in the procedure below.
To restart a z/OS task from a specific step:

Open the z/OS task instance by clicking its name on the Activity screen.
Click the Z/OS Restartable Job Steps tab. This displays each step of the Z/OS job on a separate line in the list. If applicable, the Failed column indicates "true", highlighted in red, to show where the job failed.
Assuming the failure was caused by error(s) in the JCL, examine the JCL and make your corrections. OpsWise uses a background process to determine whether changes have been made to the JCL. Any changes trigger the confirmation process.
When you have corrected the JCL, consult the Restartable column to determine which steps are available as restart points. A value of True means you can restart from this JCL step; a value of False means you cannot restart from this step. If you choose to rerun specific steps, you can only run steps flagged as True in the Restartable column.
In the example shown below, the job failed at step 7 and the latest step you can restart from is step 4.

You can restart the job from a specific step or select specific steps to re-run.

To restart the task from a specific step and run it to the end:
1. Click the box to the left of the step from which you want to restart the task, as shown in the illustration below. For example, to restart the job from step 4 to the end, select 4.
2. Click the down-arrow in Actions on selected rows... and select Select steps to end to rerun.
3. Return to the z/OS Task main screen and click the Re-run button.
To re-run one or more specific steps:
1. Click the box to the left of the steps you want to re-run.
2. Click the down-arrow in Actions on selected rows... and select Select steps to rerun.
3. Return to the z/OS Task main screen and click the Re-run button.
To re-run a range of steps:
1. Click the boxes to the left of the first and last steps you want to re-run. For example, to run steps 3 through 8, click 3 and 8.
2. Click the down-arrow in Actions on selected rows... and select Select steps inclusive to rerun.
3. Return to the z/OS Task main screen and click the Re-run button.
To start over before clicking on the Re-run button, click the down-arrow in Actions on selected rows... and select Deselect steps for rerun.
Once you have made your restart selection, Opswise reruns the task.
If you have made changes to the JCL, the task goes into a status of Confirmation Required on the Activity screen. Confirm the change as follows:
1. From the Activity screen, click on the task name to open the record.
2. Click the Restart Confirmation tab. This displays a record for each change that was made to the JCL, with a description in the Error Message column, as shown in the following example.
3. To confirm the change(s), click the box to the left of each listed change and click the Actions on selected rows.
4. Select Force Rerun.
5. Return to the z/OS Task main screen and click the Re-run button.
After the rerun is complete, the Failed column should show false for each step.

Note: If you repeat the above process on the same task instance, the previous list of JCL changes, if any, is wiped clean and replaced with the most recent list of changes.

z/OS Restartable JobSteps Tab Column Descriptions

The following table describes each column on the Z/OS Retartable Job Steps screen.

Column Name	Description
Step #	The number assigned to this step by OpsWise Automation Center.
Run Step	Indicates whether this step ran during the last run or restart of this job. For example, if you just re-started the job from step 4, steps 1, 2, and 3 would indicate false, and steps 4 to the end would indicate true.
Restartable	When the JCL job fails, OpsWise Automation Center determines the latest step you can restart from. A step indicating True and highlighted in green means you can restart from this step.
Depends On	Indicates which step or steps must be completed successfully before you can run this step.
Attempt	The number of times this step has been run or attempted to run.
Step Name	Extracted from the JCL. The name of the JCL step.
Pstep Name	The process step name from within the JCL step.
Program	The name of the program being executed by the step.
Step Code	Extracted from the JCL. Exit code for this step of the program.
Failed	True or false. Indicates whether or not this step failed. True means the step failed.
CPU Time	Number of CPU seconds it took for the JCL step to run.
IO Total	Total input/output operations for this step.
Memory Peak	The peak amount of memory used during the execution of this step.

z/OS Restart Confirmation Tab Column Descriptions

The following table describes each column on the Z/OS Retartable Job Steps screen.

Column Name	Description
Jobid	The number assigned to this step by OpsWise Automation Center.
Step#	The JCL step number that was modified.
Error message	A description of the change.
Old Data	The JCL before the change.
New Data	The JCL after the change.

Skipping One or More Steps During a Restart

OpsWise can read and interpret JCL step names that have been customized for CA11 and UCC. This allows you to launch your old CA11 and UCC jobs from OpsWise without modifying the JCL. An additional customized step name has also been added for possible other uses. When OpsWise encounters one of the step names listed below in your JCL, OpsWise will skip the step during a restart:

CA11NR
UCC11NR
OPSNR000

In the example shown below, steps 3, 4, and 5 each have one of the above DD Names and are therefore non-restartable steps.

Changing the Step Code on a Previous Step to Force-Run the Task

If the exit code on a previous step is causing a step failure and you have determined that you want to finish the job run anyway, you can change the exit code to force finish the task.

Open the task instance from the Activity screen.
From the Restartable Steps tab, click on the step whose exit code you want to change. OpsWise opens the record for this step, as shown below:
Enter the new code in the Step Code field and click Update.
Return to the main task screen and click Rerun.

Viewing Ops Rerun Reports

OpsWise keeps a detailed record of task restarts. This data is written to the Output tab on the task instance record, as shown in the sample below:

Viewing Audit Trails on a Restart

OpsWise maintains detailed audit records on all system activity. The sample below shows an audit record for a re-run on a z/OS task called SKIPNR.

Automation Center Documentation