SETSTATE

Purpose

SETSTATE changes the agent automation status of a given subsystem.

Parameters

subsystem

Specifies the subsystem whose status (or whose dependent resource's status) you want to change. You can also specify the subsystem's job name.

AUTODOWN

Changes the status from CTLDOWN, STOPPED, BROKEN, MOVED or FALLBACK to AUTODOWN. It is primarily used to return the resource to automation control after the operator has fixed the problem.

CTLDOWN

Changes the status to CTLDOWN so that the subsystem cannot be started by automation.

ENDED

Changes the status to ENDED.

MOVED

The effect of this parameter depends on how the subsystem is defined:

• If the subsystem does not have any secondary system associations, the effect of the MOVED operand is the same as the effect of the CTLDOWN operand: the status of the subsystem is changed to CTLDOWN.
• If the subsystem does have secondary system associations:
  • If the command is issued on one of the subsystem's primary systems, the subsystem's status is changed to MOVED
  • If the command is issued on one of the subsystem's secondary systems, the subsystem's status is changed to FALLBACK.

RESTART

Changes the status to RESTART so that the subsystem can be restarted. Specify this if your Initstart flag is set to No. This can only be used when:

• SCOPE=ONLY or SCOPE=ALL
• The application monitor status of the subsystem is INACTIVE

UP

Changes the status to UP/RUNNING if the subsystem's UPMSG has been missed. This can only be used when:

• SCOPE=ONLY
• The application monitor status of the subsystem is ACTIVE
• If the subsystem is enabled for automatic restart management, its automatic restart management status must be AVAILABLE or AVAILABLE-TO.

Note: For transient subsystems, UP becomes RUNNING.

SCOPE

Specifies what is affected by this command:

ONLY

Changes the status of this resource only. This is the default.

ALL

Changes the status of this resource and its dependent resources.

CHILDREN

Changes the status of the dependent resources only.

TARGET

For information on the TARGET parameter, see TARGET Parameter.

OUTMODE

For information on the OUTMODE parameter, see OUTMODE Parameter.

Restrictions and Limitations

The SETSTATE command will not execute under the primary POI task (PPT).

The SETSTATE command can only be used when SA z/OS® is initialized.

When the SETSTATE command is used to change the status of a subsystem to UP or AUTODOWN, then this will trigger a call to ACTIVMSG or TERMMSG. When using AUTHCHK=SOURCEID as part of your SAF product authorization checking profile, the operator/task issuing the SETSTATE command will require the authority to issue commands and replies that may subsequently be triggered by ACTIVMSG or TERMMSG. This is due to the fact that the status change process did not originate on the work operator assigned to the subsystem as usual but on the operator/task who issued the SETSTATE command.

Security Considerations

For further details, refer to IBM Z System Automation Planning and Installation.

Usage

Use SETSTATE to:

• Resume handling an application after a manual operator shutdown or after any other event that causes an application to get into a non-automatable status (for example STOPPED, CTLDOWN, BROKEN, ACTIVE)
• Prevent automation from restarting an application if you specify CTLDOWN.
• Alert the automation that an application that was shut down will be moved to another system.
• The SETSTATE command issues an automation manager request with a priority of HIGH (unless overridden by the advanced automation global INGREQ_PRI). Because requests entered by the operator are persistent, it may be necessary to manually remove the associated vote before subsequent requests are activated.