SRSTAT

Purpose

The SRSTAT command lets you change the overriding (global) availability, quantity, and deviation of a special resource. You can do this to prevent operations from allocating a particular resource, or to request the ETT function to add an application occurrence to the current plan.

Usage

You can invoke SRSTAT as a TSO command or by using a batch job which executes program EQQEVPGM. If you invoke SRSTAT 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 SRSTAT command can be restricted with fixed resource code SR and subresource SR.SRNAME. 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 SRSTAT 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.

See Creating special resources for information about special resources, how to connect them to workstations, and how to specify intervals.

Format


1 SRSTAT
2  ' resource name '
2?  AVAIL (
3.1! KEEP
3.1 RESET
3.1 NO
3.1 YES
2 )
2?  CREATE (
3.1! YES
3.1 NO
2 )
2?  DEVIATION (
3.1! KEEP
3.1 amount
3.1 RESET
2 )
2?  LIFESPAN (
3.1 interval, new availability value
2 )
2?  QUANTITY (
3.1! KEEP
3.1 amount
3.1 RESET
2 )
2?  SUBSYS (
3.1! OPCA
3.1 subsystem name
3.1 MSTR
2 )
2?  TRACE (
3.1! 0
3.1 trace level
2 )

Parameters

'resource name'
The name of the resource whose availability or quantity you want to change. This parameter must be contained within single quotation marks and can be up to 44 characters in length. All lowercase characters are converted to uppercase.

You must supply this parameter.

AVAIL (RESET | NO | YES | KEEP)
YES indicates that the availability status of the resource should be set to YES. Operations requiring the resource can start, as long as there are no other conditions preventing them from starting. For example, if two operations both require a resource for exclusive (X) use, HCL Workload Automation for Z lets only one of them start.

NO indicates that the availability status of the resource should be set to NO. Any operation that requires the resource will be prevented from starting, regardless of whether it was specified for shared (S) or exclusive (X) use.

RESET sets the overriding availability to blank so that the interval or default value is used.

KEEP, the default, does not change the availability status.

When you set the availability with SRSTAT (or other interfaces such as the EQQUSIN subroutine or the MCP panel), the specified availability lasts over interval boundaries, even though the next interval can specify a different availability, and persists after a daily planning job. Specify RESET to restore the planned availability.

CREATE (NO| YES)
NO indicates that the resource is not to be added to the current plan of the receiving HCL Workload Automation for Z subsystem, if it does not exist in the database. If the resource exists in the database, CREATE(NO) does not have any effect. You can specify CREATE(NO) if the resource is being used only as a means to generate an event for ETT—the event is generated even if the resource does not exist.
If YES is specified or defaulted, and the DYNAMICADD keyword of the RESOPTS initialization statement is set to YES or EVENT, HCL Workload Automation for Z adds the resource to the current plan of the receiving HCL Workload Automation for Z subsystem, if the resource is not in the database. It uses the following default values:
Text
Blank.
Specres group ID
Blank.
Hiperbatch
No.
Used for
Control.
On error
Blank. If an error occurs, HCL Workload Automation for Z uses the value specified in the operation details or, if that is also blank, the value of the ONERROR keyword of RESOPTS.
On Complete
Blank.
When the operation completes, the On Complete value is considered according to the following order:
  1. The On Complete value set at operation definition level, if not blank.
  2. The On Complete value set at special resource definition level, if not blank.
  3. The ONCOMPLETE or DYNONCOMPLETE keyword value, respectively set for the not dynamically added resources or the dynamically added resources, in all the other cases.
Max Usage Limit
0.
Max Usage Type
Reset.
Usage Counter
0.
Overriding availability, quantity, and deviation
The value specified by SRSTAT, or blank.
Default quantity
1. The default quantity is automatically increased if contention occurs.
Default availability
Yes.
Intervals
No intervals are created.
Workstations
* (all workstations can allocate the resource).
DEVIATION (RESET | amount | KEEP)
To make a temporary change to the quantity, you can specify a deviation, which is an amount to be added to (positive number) or subtracted from (negative number) the current quantity. A specified amount can be from -999 999 to +999 999. The default, KEEP, does not alter the deviation.
Note: The effect of deviation is cumulative. If you issue two SRSTAT commands with DEVIATION(-1), for example, this subtracts two from the deviation.

When the deviation is not zero, the value lasts over interval boundaries and persists after a daily planning job. Specify RESET or zero (0) to set the deviation to zero.

LIFESPAN (interval, new availability value)
The interval of time, in minutes, after which the global availability of the special resource is changed according to the value specified as new availability value. When you specify this parameter, a pending LIFESPAN action (the one specified as new availability value) comes into effect for the resource. The controller runs that action as soon as the LIFESPAN interval of time expires.

Only one pending LIFESPAN action can exist for one resource. This means that issuing an SRSTAT command with LIFESPAN replaces any existing pending LIFESPAN action.

To cancel a pending LIFESPAN action, issue an SRSTAT command with an interval of 0. When the interval of time is 0, no LIFESPAN action is run.

Interval can be an integer from 0 to 99999. New availability value can be one of the following (you must always specify one, because no default is provided):
YES
The global availability is changed to Yes
NO
The global availability is changed to No
RESET
The global availability is changed to blank
QUANTITY (RESET | amount | KEEP)
To change the overriding (global) quantity, specify the amount, from 1 to 999 999.

RESET sets the overriding quantity to blank so that the interval or default value is used. KEEP does not alter the quantity.

When you set the quantity with SRSTAT (or other interfaces such as the EQQUSIN subroutine or the MCP panel), the specified quantity lasts over interval boundaries, even though the next interval can specify a different quantity, and persists after a daily planning job. Specify RESET to restore the planned quantity.

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

Note: If the trackers 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 positive number is specified, a trace entry is created for each event generated by the SRSTAT 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.

Examples

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

SRSTAT
Example 1 - TSO command 
ALLOC F(EQQMLIB) DA('OPC.MESSAGE.LIBRARY') SHR REUSE
 
SRSTAT 'IMS.DATA.BASE' SUBSYS(OPCB) AVAIL(YES)
Example 2 - Batch job 
//CHSTATUS JOB (ACCOUNT),'Change DB 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 *
SRSTAT 'IMS.DATA.BASE' SUBSYS(OPCB) AVAIL(YES)
/*
Example 3 - Reduce tape pool 
ALLOC F(EQQMLIB) DA('OPC.MESSAGE.LIBRARY') SHR REUSE
 
SRSTAT 'TAPES' SUBSYS(OPCB) DEV(RESET) Q(6)
SRSTAT 'TAPES' SUBSYS(OPCB) DEV(-1)
SRSTAT 'TAPES' SUBSYS(OPCB) DEV(-1)
SRSTAT 'TAPES' SUBSYS(OPCB) DEV(0)

In examples 1 and 2, the availability status of the resource IMS™.DATA.BASE is changed to YES. In example 3, the number of tapes is set to 6, 5, 4, and then back to 6 (a deviation of 0 is a special value and means the same as reset).