Skip to main content

z/OS Task Instance Web Services

Universal Controller supports the following RESTful-based web services for z/OS Task Instance operations, which are listed alphabetically on this page.

Formatting specifications for each web service, including details about parameter requirements, are provided.

Deselect Job Steps of a z/OS Instance​

Description

URI

http://host_name/uc/resources/taskinstance/zos/jobsteps/deselect

HTTP Method

PUT

Description

Deselect job steps of a z/OS task instance for Re-run.

Authentication

HTTP Basic

Example URI

http://localhost:8080/uc/resources/taskinstance/zos/jobsteps/deselect?taskinstanceid={taskinstanceid}&stepNum=2

http://localhost:8080/uc/resources/taskinstance/zos/jobsteps/deselect?taskinstancename={taskinstancename}&criteria=3&stepNum=2,4,6

Consumes Content-Type

n/a

Produces Content-Type

application/json

URI Properties

See Deselect Job Steps of a z/OS Instance: URI Properties

Example Responses

  • Status 200
    • Successful response.
      JSON
      JSON
      {
        "status": "success",
        "info": [
          {
            "message": "Step number 2 (JS1) already deselected."
          },
          {
            "message": "Step number 4 (JS3) deselected."
          },
          {
            "message": "Step number 6 (JS5) already deselected."
          }
        ]
      }
  • Status 400
    • SELECT Z/OS JOB STEPS failed to execute because the task instance type is incorrect.
    • Step number '{stepNum}' is not a valid integer.
    • Step number '{stepNum}' is specified more than once.
    • Step number '{stepNum}' is out of range.
    • stepNum is required.
      JSON
      JSON
      {
        "status": "error",
        "errors": [
          {
            "message": "Step number '{stepNum}' is not a valid integer."
          }
        ]
      }
  • Status 403
    • Operation prohibited due to security constraints.
  • Status 404
    • No match found for task instance name "{taskinstancename}“.
    • No match found for task instance id {taskinstanceid}.
  • Status 500
    • Unexpected request failure. See log(s) for more details.

Deselect Job Steps of a z/OS Instance: URI Properties​

Property

UI Field Name

Description

Specifications

Required

Mutually Exclusive With

criteria

n/a

Used if taskinstancename is specified; Specific task instance with this taskinstancename.

String; URI parameter. Valid values:

  • As String = Oldest Active Instance, As Value = 1
  • As String = Newest Active Instance, As Value = 2
  • As String = Oldest Instance, As Value = 3
  • As String = Newest Instance, As Value = 4

Default is Oldest Active Instance (1).

info

Values with an underscore characters ( _ ) instead of spaces also are supported (for example, oldest_active_instance).

N

stepNum

Step Number

Step Number(s) for z/OS Job steps.

Comma separated list of numbers.

Y

taskinstanceid

UUID

UUID of the task instance.

String; URI parameter.

Y
(unless taskinstancename is specified.)

taskinstancename

taskinstancename

Instance Name

Name of the task instance.

String; URI parameter.

Y
(unless taskinstanceid is specified.)

taskinstanceid

workflowinstancename

Workflow

Name of the parent Workflow of the task instance.

You can select to display the Workflow field on the Activity Monitor and/or Task Instances List; it is not displayed in the Task Instance Details.

N

Read Job Steps of a z/OS Instance​

Description

URI

http://host_name/uc/resources/taskinstance/zos/jobsteps

HTTP Method

GET

Description

Read job steps of a z/OS task instance.

Authentication

HTTP Basic

Example URI

  • http://localhost:8080/uc/resources/taskinstance/zos/jobsteps?taskinstanceid={taskinstanceid}
  • http://localhost:8080/uc/resources/taskinstance/zos/jobsteps?taskinstancename={taskinstancename}&criteria=3
  • http://localhost:8080/uc/resources/taskinstance/zos/jobsteps?taskinstancename={taskinstancename}&workflowname={workflowname}

Consumes Content-Type

n/a

Produces Content-Type

application/json

URI Properties

See Read Job Steps of a z/OS Instance: URI Properties.

Example Responses

  • Status 200
    • Successful response.
      JSON
      JSON
      {
        "status": "success",
        "restartableJobSteps": [
          {
            "attemptCount": 1,
            "cpuTime": 1,
            "dependsOn": "N/A",
            "elapsedTime": null,
            "ioOther": 1941,
            "ioReads": 0,
            "ioTotal": 1941,
            "ioWrites": 0,
            "memoryPeak": 344,
            "memoryUsed": 0,
            "programName": "UAGRERUN",
            "pstepName": null,
            "selectedForRerun": true,
            "stepCode": "0000",
            "stepCodeFail": false,
            "stepCodex": 0,
            "stepEndFlags": 1,
            "stepName": "OPSSTP00",
            "stepNum": 1,
            "stepRestartable": true
          },
          {
            "attemptCount": 1,
            "cpuTime": 1,
            "dependsOn": "N/A",
            "elapsedTime": null,
            "ioOther": 2638,
            "ioReads": 0,
            "ioTotal": 2638,
            "ioWrites": 0,
            "memoryPeak": 268,
            "memoryUsed": 0,
            "programName": "SBIRC",
            "pstepName": null,
            "selectedForRerun": false,
            "stepCode": "0004",
            "stepCodeFail": false,
            "stepCodex": 4,
            "stepEndFlags": 2,
            "stepName": "JS1",
            "stepNum": 2,
            "stepRestartable": true
          },
          {
            "attemptCount": 1,
            "cpuTime": 1,
            "dependsOn": "N/A",
            "elapsedTime": null,
            "ioOther": 2638,
            "ioReads": 0,
            "ioTotal": 2638,
            "ioWrites": 0,
            "memoryPeak": 268,
            "memoryUsed": 0,
            "programName": "SBIRC",
            "pstepName": null,
            "selectedForRerun": true,
            "stepCode": "0000",
            "stepCodeFail": false,
            "stepCodex": 0,
            "stepEndFlags": 3,
            "stepName": "JS2",
            "stepNum": 3,
            "stepRestartable": true
          }
        ]
      }
  • Status 400
    • READ Z/OS JOB STEPS failed to execute because the task instance type is incorrect.
      JSON
      JSON
      {
        "status": "error",
        "errors": [
          {
            "message": "READ Z/OS JOB STEPS failed to execute because the task instance type is incorrect."
          }
        ]
      }
  • Status 403
    • Operation prohibited due to security constraints.
  • Status 404
    • No match found for task instance name "{taskinstancename}“.
    • No match found for task instance id {taskinstanceid}.
  • Status 500
    • Unexpected request failure. See log(s) for more details.

Read Job Steps of a z/OS Instance: URI Properties​

Property

UI Field Name

Description

Specifications

Required

Mutually Exclusive With

criteria

n/a

Used if taskinstancename is specified; Specific task instance with this taskinstancename.

String; URI parameter. Valid values:

  • As String = Oldest Active Instance, As Value = 1
  • As String = Newest Active Instance, As Value = 2
  • As String = Oldest Instance, As Value = 3
  • As String = Newest Instance, As Value = 4

Default is Oldest Active Instance (1).

info

Values with an underscore characters ( _ ) instead of spaces also are supported (for example, oldest_active_instance).

N

taskinstanceid

UUID

UUID of the task instance.

String; URI parameter.

Y
(unless taskinstancename is specified.)

taskinstancename

taskinstancename

Instance Name

Name of the task instance.

String; URI parameter.

Y
(unless taskinstanceid is specified.)

taskinstanceid

workflowinstancename

Workflow

Name of the parent Workflow of the task instance.

You can select to display the Workflow field on the Activity Monitor and/or Task Instances List; it is not displayed in the Task Instance Details.

N

Select Job Steps of a z/OS Instance​

Description

URI

http://host_name/uc/resources/taskinstance/zos/jobsteps/select

HTTP Method

PUT

Description

Select job steps of a z/OS task instance for Re-run.

Authentication

HTTP Basic

Example URI

http://localhost:8080/uc/resources/taskinstance/zos/jobsteps/select?taskinstanceid={taskinstanceid}&stepNum=2

http://localhost:8080/uc/resources/taskinstance/zos/jobsteps/select?taskinstancename={taskinstancename}&criteria=3&stepNum=2,4,6&force=true

Consumes Content-Type

n/a

Produces Content-Type

application/json

URI Properties

See Select Job Steps of a z/OS Instance: URI Properties

Example Responses

  • Status 200
    • Successful response.
      JSON
      JSON
      {
        "status": "success",
        "info": [
          {
            "message": "Step number 2 (JS1) selected for re-run."
          },
          {
            "message": "Step number 3 (JS2) selected for re-run."
          },
          {
            "message": "Step number 4 (JS3) already selected for re-run."
          }
        ]
      }
  • Status 400
    • SELECT Z/OS JOB STEPS failed to execute because the task instance type is incorrect.
    • Step number '{stepNum}' is not a valid integer.
    • Step number '{stepNum}' is specified more than once.
    • Step number '{stepNum}' is out of range.
    • stepNum is required.
    • Cannot force select because Universal Controller property "Enable Force Rerun For z/OS Job Steps" is not enabled.
      JSON
      JSON
      {
        "status": "error",
        "errors": [
          {
            "message": "Cannot force select because Universal Controller property \"Enable Force Rerun For z/OS Job Steps\" is not enabled."
          }
        ]
      }
  • Status 403
    • Operation prohibited due to security constraints.
  • Status 404
    • No match found for task instance name "{taskinstancename}“.
    • No match found for task instance id {taskinstanceid}.
  • Status 500
    • Unexpected request failure. See log(s) for more details.

Select Job Steps of a z/OS Instance: URI Properties​

Property

UI Field Name

Description

Specifications

Required

Mutually Exclusive With

criteria

n/a

Used if taskinstancename is specified; Specific task instance with this taskinstancename.

String; URI parameter. Valid values:

  • As String = Oldest Active Instance, As Value = 1
  • As String = Newest Active Instance, As Value = 2
  • As String = Oldest Instance, As Value = 3
  • As String = Newest Instance, As Value = 4

Default is Oldest Active Instance (1).

info

Values with an underscore characters ( _ ) instead of spaces also are supported (for example, oldest_active_instance).

N

force

N/A

Forces the specified Step Numbers to be selected, even if they show as not restartable or depend on a step that is not selected. This option is only allowed if the system property Enable Force Rerun For z/OS Job Steps is enabled.

N

stepNum

Step Number

Step Number(s) for z/OS Job steps.

Comma separated list of numbers.

Y

taskinstanceid

UUID

UUID of the task instance.

String; URI parameter.

Y
(unless taskinstancename is specified.)

taskinstancename

taskinstancename

Instance Name

Name of the task instance.

String; URI parameter.

Y
(unless taskinstanceid is specified.)

taskinstanceid

workflowinstancename

Workflow

Name of the parent Workflow of the task instance.

You can select to display the Workflow field on the Activity Monitor and/or Task Instances List; it is not displayed in the Task Instance Details.

N

Select To End Job Steps of a z/OS Instance​

Description

URI

http://host_name/uc/resources/taskinstance/zos/jobsteps/selecttoend

HTTP Method

PUT

Description

Select job steps of a z/OS task instance for Re-run. All job steps following the specified stepNum will be selected for Re-run.

Authentication

HTTP Basic

Example URI

Consumes Content-Type

n/a

Produces Content-Type

application/json

URI Properties

See Select To End Job Steps of a z/OS Instance: URI Properties.

Example Responses

  • Status 200

    • Successful response.
      JSON
      JSON
      {
        "status": "success",
        "info": [
          {
            "message": "Step number 2 (JS1) selected for re-run."
          },
          {
            "message": "Step number 3 (JS2) selected for re-run."
          },
          {
            "message": "Step number 4 (JS3) already selected for re-run."
          }
        ]
      }

  • Status 400

      • SELECT Z/OS JOB STEPS failed to execute because the task instance type is incorrect.
      • Step number '{stepNum}' is not a valid integer.
      • Step number '{stepNum}' is out of range.
      • stepNum is required.
        JSON
        JSON
        {
          "status": "error",
          "errors": [
            {
              "message": "stepNum is required."
            }
          ]
        }

  • Status 403

    • Operation prohibited due to security constraints.

  • Status 404

    • No match found for task instance name "{taskinstancename}“.
    • No match found for task instance id {taskinstanceid}.

  • Status 500

    • Unexpected request failure. See log(s) for more details.

Select To End Job Steps of a z/OS Instance: URI Properties​

Property

UI Field Name

Description

Specifications

Required

Mutually Exclusive With

criteria

n/a

Used if taskinstancename is specified; Specific task instance with this taskinstancename.

String; URI parameter. Valid values:

  • As String = Oldest Active Instance, As Value = 1
  • As String = Newest Active Instance, As Value = 2
  • As String = Oldest Instance, As Value = 3
  • As String = Newest Instance, As Value = 4

Default is Oldest Active Instance (1).

info

Values with an underscore characters ( _ ) instead of spaces also are supported (for example, oldest_active_instance).

N

stepNum

Step Number

The starting z/OS Job Step Number to re-run. This step and all following steps will be selected for re-run.

Y

taskinstanceid

UUID

UUID of the task instance.

String; URI parameter.

Y
(unless taskinstancename is specified.)

taskinstancename

taskinstancename

Instance Name

Name of the task instance.

String; URI parameter.

Y
(unless taskinstanceid is specified.)

taskinstanceid

workflowinstancename

Workflow

Name of the parent Workflow of the task instance.

You can select to display the Workflow field on the Activity Monitor and/or Task Instances List; it is not displayed in the Task Instance Details.

N