OPSTAT

Purpose

The OPSTAT command lets you set the status of an operation at any workstation, except workstations that have the nonreporting attribute. Events generated by OPSTAT are matched against operations on the ready list. Events received for operations in waiting (W), suppressed by condition (X), or complete (C) status are ignored. Jobs and started tasks that are running are always allowed to finish; for rules governing the changing of operation status, see the READY LIST panel description in Using the ready list .

You need update authority to resource code RL to use this command. Resource codes are described in Customization and Tuning.

The OPSTAT command gives you a portable method of using automatic event reporting (AER) facility. AER can help you coordinate many tasks that are not normally seen by HCL Workload Automation for Z. For example, you can use AER to trigger the start of an operation when a particular step in a job is complete, or as acknowledgment that a file has been received across the network.

The OPSTAT command also gives you the facility to automatically report the status of work executing in operating environments that do not support a tracker.

Usage

You can invoke OPSTAT as a TSO command or by using a batch job that executes program EQQEVPGM. If you invoke OPSTAT as a TSO command, 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.

OPSTAT is an alternative to the EQQUSIN subroutine for implementing automatic event reporting for general workstations.

With the OPSTAT command, you must specify the WSNAME parameter to identify the workstation at which the operation is changing status. HCL Workload Automation for Z then changes the status of the operation at that workstation to the status you have specified.

If there is more than one operation at the workstation, you can optionally specify the ADID, IA, OPNUM, or JOBNAME parameters to identify the particular operation whose status is to be changed. Also, for printer workstations, you can specify the CLASS and FORM parameters to identify an operation.

If you do not provide enough information to uniquely identify the operation and HCL Workload Automation for Z finds more than one operation which matches the criteria you specified, HCL Workload Automation for Z determines the most appropriate operation to update. HCL Workload Automation for Z chooses the most appropriate operation by investigating its characteristics in this order:
  1. The operation has priority 9.
  2. Earliest latest start time.
  3. Priority 8-1.
  4. Input arrival time specified for the operation, or the occurrence input arrival if the operation does not have input arrival specifically defined.
Therefore, if you define only the WSNAME parameter and HCL Workload Automation for Z determines that there is more than one operation in the current plan for that workstation in status R, A, *, S, I, or E, the operation with priority 9 is updated. If more than one operation specifies priority 9, or there are no priority 9 operations, the operation with the earliest latest-start time is updated. If you add the operation using the MCP panel, the latest start time is blank. If latest start is equal, the operation with the highest priority is updated. If priority is equal, the operation which specifies the earliest input arrival time is updated. If input arrival is also equal, the update is performed on a first-in-first-out basis.
The parameter SORTIA can be specified among OPSTAT input parameters to automatically choose the oldest eligible operation in the ready list, in terms of occurrence input arrival time. SORTIA is processed and effectively used by the event manager when all the following conditions occur:
  • Workstation, application name and operation number are all specified as input parameters for OPSTAT.
  • Neither input arrival time nor token are specified as input parameters to OPSTAT.
In any different situation the keyword SORTIA will be ignored.

Use of the OPSTAT command can be restricted with fixed resource code RL and the subresource RL.WSNAME. 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 OPSTAT command is issued will attempt to verify the authority of the requester before an event is generated. You might 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.

Format


1  OPSTAT?  ADID (
2.1 application description ID
1 )?  CLASS (
2.1 printer sysout class
1 )?  COMPLCODE (
2.1 completed operation return code
1 )?  DURATION (
2.1 hhmm
1 )?  ERRORCODE (
2.1! OSIN
2.1 operation error code
1 )?  EVDATE (
2.1 yymmdd
1 )?  EVTIME (
2.1 hhmm
1 )?  FORM (
2.1 printer form name
1 )?  IA (
2.1 yymmddhhmm
1 )?  JOBNAME (
2.1 job name
1 )?  NUMJOB (
2.1 job number
1 )?  OPNUM (
2.1 operation number
1 )?  SORTIA?  TOKEN (
2.1 token value
1 )?  STATUS (
2.1! C
1 )?  SUBSYS (
2.1! OPCA
2.1 MSTR
2.1 subsystem name
1 )?  TRACE (
2.1! 0
2.1 trace level
1 )  WSNAME (
2.1 workstation name
1 )

Parameters

ADID (application description identifier)
The application identifier of the operation whose status you want to change.
CLASS (printer sysout class)
For a printer workstation, specifies the printer SYSOUT class of the operation whose status you want to change.
COMPLCODE (completed operation return code)
If you are specifying STATUS(C) to set the operation status to complete, you can optionally specify a return code for the completed operation. It can be any 4 characters.
DURATION (hhmm)
If you are specifying STATUS(C) to set the operation status to complete, you can optionally specify a duration for the completed operation. You specify the duration in hours and minutes, in the format hhmm.
ERRORCODE (operation error code | OSIN)
If you are specifying STATUS(E) to set the operation status to ended-in-error, it is required that you specify an error code for the operation. The error code can be any 4 characters. The default value is OSIN.
EVDATE (yymmdd)
The date of this operation status event. You must specify the date in the format yymmdd.

See the comments under the following parameter, EVTIME.

EVTIME (hhmm)
The time of this operation status event. You must specify the time in the format hhmm.

You can use the EVDATE and EVTIME parameters if you want to indicate that the operation changed status at a time other than the current time. If you do not supply these parameters, the operation is considered to have changed status at the time HCL Workload Automation for Z processes the OPSTAT command.

FORM (printer form name)
For a printer workstation, specifies the printer FORM name of the operation whose status you want to change.
IA (yymmddhhmm)
The input arrival date and time of the occurrence containing the operation whose status you want to change. You must specify this in the format yymmddhhmm.
Note: HCL Workload Automation for Z interprets the yy part as follows:
YY
Year
72 - 99
1972 - 1999
00 - 71
2000 - 2071
JOBNAME (job name)
The job name associated with the operation whose status you want to change.
NUMJOB (job number)
Use this optional parameter to specify a job number for an operation on a user-defined computer automatic workstation. Specify a number from 0 to 999999. HCL Workload Automation for Z builds a job number in the format USRnnnnn or Unnnnnnn, depending on the value and padding the number with zeros on the left.
OPNUM (operation number)
The operation number of the operation whose status you want to change.
SORTIA
Makes the code to automatically choose the oldest eligible operation in the ready list, in terms of occurrence input arrival time. It applies when both the following conditions occur:
  • Workstation, application name and operation number are all specified as input parameters for OPSTAT.
  • Neither input arrival time nor token are specified as input parameters to OPSTAT.
In any different situation the keyword SORTIA will be ignored.
TOKEN (token value)
The token assigned for the operation whose status you want to change. A token is automatically assigned for operations started on workstations that specify a user-defined destination ID. The token can be used to uniquely identify the operation.

When TOKEN is used in conjunction with the ADID, IA, JOBNAME, or OPNUM parameters, all values must match the target operation. For example, if the token identifies the operation but OPNUM is also specified and does not match, the event will be rejected and message EQQE091E written to the controller message log.

Specify the token as a hexadecimal value in the format TOKEN(X'00ABCDEF').

STATUS ( C)
Use the default value to set the new operation status as successfully completed at the workstation.
Changes to operation status using OPSTAT follow the same rules as status changes in the Ready List. In particular:
  • You cannot change an operation status from W to C. This is because predecessor jobs might not be completed.
  • You cannot change an operation status from X (suppressed by condition) or to X.
  • To change the status of an operation to the previous logical status, specify STATUS(X). As from the previous point, do not use it to change the operation status to suppressed by condition.

For more information, refer to Using the ready list.

SUBSYS (MSTR | subsystem name | OPCA)
Name of the tracker subsystem that the OPSTAT command is directed to. The name 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 OPSTAT command is directed to all tracker subsystems on the z/OS® system where the OPSTAT command is issued.

Note: If the trackers and controller run on different subsystems in your configuration, specify the name of the tracker subsystem in this parameter.
TRACE (level | 0)
Event tracing indicator. When a positive number is specified, a trace entry is created for each event generated by the OPSTAT 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)
You must supply the name of the workstation that you are reporting the status of an operation for.

Examples

These examples demonstrate how you can use the OPSTAT command in TSO, or in a batch job (using the batch program EQQEVPGM).

OPSTAT
Example 1 - TSO command 
ALLOC F(EQQMLIB) DA('OPC.MESSAGE.LIBRARY') SHR REUSE
 
OPSTAT W(BDEC) ST(C) J(DNCD3000) A(ACLMSDLY)
Example 2 - Batch job 
//OPSTATUS JOB (ACCOUNT),'Set completed',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 *
OPSTAT W(BDEC) ST(C) J(DNCD3000) A(ACLMSDLY)
/*

In both of these examples, an operation for application ACLMSDLY at workstation BDEC is reported as completed.