WSSTAT

Purpose

The WSSTAT command lets you change the status of a workstation in the current plan. The status information is communicated to the controller to indicate a workstation as active, offline, or failed. When you use the WSSTAT command you can optionally define restart and routing options for the workload defined on the workstation when you are reporting a status of offline or failed.

Usage

You can invoke WSSTAT as a TSO command or by using a batch job which executes program EQQEVPGM. If you invoke WSSTAT as a TSO command, you must allocate the EQQMLIB data set to the address space of the TSO user, either by adding DD statements to the logon procedure, or by using the ALLOC command after TSO logon. In the TSO environment, error messages and trace records are sent directly to the terminal user. Messages are not delivered to indicate successful command execution.

Use of the WSSTAT command can be restricted with fixed resource code RL and subresource RL.WSSTAT. The authority of the requester is verified by the subsystem name identified in the command if an AUTHDEF statement is defined for that subsystem. When SUBSYS(MSTR) is specified, all tracker subsystems defined on the z/OS® system where the WSSTAT command is issued will attempt to verify the authority of the requester before an event is generated. It is possible to be rejected by one subsystem and accepted by another.

The subsystem to which you direct the command does not have to be active when the command is issued. An event will be generated and queued in CSA along with other job-tracking events. If the subsystem is not active when the command is issued, the authority of the requester is verified using the class name specified in the AUTHDEF statement when the subsystem was last started. If the subsystem has not been started since a z/OS® IPL, no authority verification can be performed.

Note: If the status of a workstation has been set to offline manually, using the panels, then you are not allowed to reset it to active using the WSSTAT command.

The status of a workstation is active and a WSSTAT is performed to change the status to offline. If the HCL Workload Automation for Z subsystem is stopped using a cancel command before a CP backup occurs, when the HCL Workload Automation for Z subsystem restarts the workstation status is active and not offline. The same behaviour happens when the status is varied from offline to active.

Format


1 WSSTAT
2?  ALTWS (
3.1 alternate workstation name
2 )
2?  REROUTE (
3.1 R
3.1 L
2 )
2?  STARTOPR (
3.1 R
3.1 L
3.1 E
2 )
1  STATUS (
2.1 A
2.1 O
2.1 F
1 )
3?  SUBSYS (
4.1! OPCA
4.1 subsystem name
4.1 MSTR
3 )
3?  TRACE (
4.1! 0
4.1 trace level
3 )
3  WSNAME (
4.1 workstation name
3 )

Parameters

ALTWS (alternate workstation name)
When the workstation status is set to offline or failed, you can specify the alternate workstation where reroutable operations should be started.

If this parameter is omitted the value defined for the current workstation open interval will be used. If the REROUTE parameter specifies L, or if the default specifies no rerouting, the value of ALTWS is ignored.

The parameter is optional.

REROUTE (R | L)
This parameter is optional. When the workstation status is set to offline or failed, you can specify R for operations to be rerouted to the alternate workstation, or L for no rerouting (to leave the operations at the inactive workstation).

If this parameter is omitted, the value defined in either the WSOFFLINE or the WSFAILURE keyword on the JTOPTS initialization statement will be used as default.

STARTOPR (R | E | L)
This parameter is optional. When the workstation status is set to offline or failed, you can specify what HCL Workload Automation for Z should do with operations that are currently in started status at the workstation, where:
R
Restart operations automatically on the alternate workstation.
E
Set all started operations to ended-in-error.
L
Leave the operations in started status.

If this parameter is omitted, the value defined in either the WSOFFLINE or the WSFAILURE keyword on the JTOPTS initialization statement is used as default.

Note:
  1. If you select STARTOPR(E), a started job continues to run. HCL Workload Automation for Z never cancels jobs that have started.
  2. For remote engine workstations, this parameter supports only the value L. If you specify any other value, it is forced to L.
  3. If you set STARTOPR(R), a started job might be submitted again even if it is currently running, resulting in the same job being run twice.
STATUS (A | O | F)
The status you want to report for the workstation
A
Active
O
Offline
F
Failed

You must specify either this or one of the alternative parameters.

SUBSYS (subsystem name | MSTR | OPCA)
The name of the tracker subsystem that the WSSTAT command is directed to. This parameter can be up to 4 characters long. The first character must be alphabetic; the remaining characters must be alphanumeric. All lowercase characters are converted to uppercase.

If you specify MSTR, the WSSTAT command is directed to all tracker subsystems on the z/OS® system where the WSSTAT command is issued.

Note: If the tracker and controller in your configuration run on different subsystems, specify the name of the tracker subsystem in this parameter.
TRACE (level | 0)
Event tracing indicator. When a nonzero positive number is specified, a trace entry is created for each event generated by the WSSTAT command. The trace record is written to the message log file identified by ddname EQQMLOG. The record identifies the name of each receiving subsystem. The default value 0 will not generate trace records.
WSNAME (workstation name)
The name of the workstation to be updated. This parameter is required.

The WSSTAT parameters are checked for validity and consistency. The validity checks are carried out in the tracker where the command is executed. The validity check processes parameter names, length and type of parameter values.

If the input is valid, a workstation status event is generated and communicated to the controller. The processing of the event includes a consistency check of the values specified in the parameters. The following consistency checks are made:
  • The workstation name is checked for existence.
  • The alternate workstation is checked for existence.
  • If the value given in the STATUS parameter equals current status of the workstation, the command will be ignored.

Examples

The following two examples demonstrate how you can use WSSTAT in TSO, or in a batch job (using the batch program EQQEVPGM).

WSSTAT
Example 1 - TSO command 
ALLOC F(EQQMLIB) DA('OPC.MESSAGE.LIBRARY') SHR REUSE
 
WSSTAT SUBSYS(OPCB) WSNAME(AS4H) STATUS(O) START(R)
Example 2 - Batch job 
//CHSTATUS JOB (ACCOUNT),'Change WS status',CLASS=A
//STEP1    EXEC PGM=EQQEVPGM
//STEPLIB  DD DSN=OPC.LOAD.MODULE.LIBRARY,DISP=SHR
//EQQMLIB  DD DSN=OPC.MESSAGE.LIBRARY,DISP=SHR
//EQQMLOG  DD SYSOUT=A
//SYSIN    DD *
WSSTAT SUBSYS(OPCB) WSNAME(AS4H) STATUS(A)
/*

In the first example the status of workstation AS4H is set to offline. Started operations will be restarted on the alternate workstation.

In the second example the status of workstation AS4H will be set to active status.