$C Group - Cancel a job group

Function

Cancels a job group. The job group status is set to COMPLETE after all active jobs in the job group are canceled and all other jobs in the job group that have not started are flushed. The PURGE operand can be used to mark the job group for purge processing once the cancel of the job group has completed.

Parameters

Age|DAys<days | Age|DAys>days

Specifies the age of affected job groups in days. Only job groups more (with DAYS>nn) or less (with DAYS<nn) than the specified number of days in age are affected. The days are counted from the current hour.

Age is computed by subtracting the job group's "begin time" from the current time. That is, the time that the job group was initially added to its current queue is the "begin time" except:

• The "begin time" for job groups that are actively running is the same as the time the command was entered. That is, the age for running job groups is always zero days and hours.
• The "begin time" for job groups in the OUTPUT or HARDCPY queue is the time that the job group ended execution. If the job group does not run, then the time is the time that the job group was placed in its prior queue.

CARDS=cards

Specifies the number of input cards that are associated with the job group.

CC=(ABEND|ABENDED|CANcelled|COMPleted|FLUSHED|JCLerror| SECurity_failure)

Specifies the completion information that is associated with the job group.

The job group completion code keyword provides a quick method for checking the status of the execution of dependent jobs in the job group. As a dependent job in the job group completes execution, the completion information of the job is evaluated to determine if it affects the CC value of the job group. If the return code of the dependent job is higher than the value currently tracked by the job group, then the job group completion code is updated to match the return code of that dependent job. If a dependent job terminates with an ABEND code, the job group completion code is updated to that ABEND code. At that point, the job group completion code field only reports an ABEND code, and reports the last ABEND code returned by the termination of a dependent job. In addition, if the job group becomes FLUSHED because of job group processing, the job group completion code field still reports the highest return code or last ABEND code reported by terminating dependent jobs.

ABEND

Specifies the last ABEND code reported by the termination of a dependent job in the job group.

ABENDED

Specifies only job groups that abnormally ended.

CANcelled

Specifies only job groups that were canceled by the operator.

COMPleted

Specifies only job groups that completed.

FLUSHED

Specifies only job groups that were flushed by job group processing.

JCLerror

Specifies only job groups that did not complete input processing successfully due to a JCL error.

SECurity_failure

Specifies only job groups that failed security validation.

CMDauth=(auth1{,auth2})

Only the job groups that can be affected from the specified remotes or nodes are canceled. The valid specifications are as follows:

LOCAL|ANYLOCAL

Only the local devices at the local node can affect the output.

Nnnnn|nodename

Only local devices at the specified node can affect the output.

Rnnnn

Only the specified remote device can affect the output.

NnnnnRnnnn|nodename.Rnnnn

Only the specified remote device at the specified remote node can affect the output.

destid

A destid corresponding to any of the above remote devices.

Note: Specification of the CMDAUTH filter does not override the authority of the console from which the command is issued; both the authority of the console and the specified CMDAUTH filter must match for the job group to be affected.

DELAY={BUSY_ON_HOLD|HOLD|LOCKED| No|QUEUE_ERROR|SCHENV|SECLABEL|SPOOLS_NOT_AVAILABLE|SYSAFF| MEMBER_STATUS|Yes}

Specifies reasons why a pre-execution job group does not enter execution:

BUSY_ON_DEVICE

The job group does not execute because it is busy on a device (such as an offload job transmitter).

HOLD

The job group does not execute because it is held.

LOCKED

The job group does not execute because it's being updated by JES2.

SECLABEL

The security label (SECLABEL) assigned to the job group is not defined as active on any member that is active.

SYSAFF

Each of the members for which the job group has affinity (SYSAFF) is inactive, or the job group has specified independent state, and the JES2 member is not independent (IND=NO).

SCHENV

The job group's scheduling environment is not available on any member, or is available only on systems where JES2 is inactive. Use the $DG'groupname',LONG command to find out what scheduling environment a job group requires. Then use the D WLM,SCHENV=schenv-name command to find out the current status of the scheduling environment on each system in the sysplex.

The SCHENV state masks other reasons why the job group might be ineligible to run, such as the $P and $P XEQ commands having been issued. Also, the SCHENV delay is detected only after a job group goes through conversion. If a job group is delayed before conversion because of system affinity requirements, scheduling environments are not considered in determining delay status.

MEMBER_STATUS

A combination of system affinity, scheduling environment, and SECLABEL restrictions is preventing the job group from running or other member events prevent the job group from running on systems where the job group is otherwise eligible. These events on other members include the following:

• $P command has been issued.
• $P XEQ command has been issued.
• BOSS=NO (used in a poly-JES environment only).

When used as a command filter, the string MEMBER_STATUS matches job groups that are delayed for SYSAFF, SCHENV, SECLABEL, or MEMBER_STATUS. To get detail on why a job group is delayed, display job group status with the $DG'groupname', LONG command or display member status with the $DMEMBER(member-name) command.

Yes

Specifies only job groups that are delayed for any of the preceding reasons.

No

Specifies only job groups that are not delayed for any of the preceding reasons.

HOLD=

Specifies the hold status of the job group.

JOB

Specifies job groups that are held by the $H G command, TYPRUN=HOLD, TYPRUN=JCLHOLD, or held due to error.

NONE

Specifies job groups that are not held.

Hours=hours

Specifies the age of affected job groups in hours. Only job groups more (with HOURS>nn) or less (with HOURS<nn) than the specified number of hours in age are affected.

JC | JOBCORR=job correlator

Specifies a combination of 1-64 alphanumeric, special (colon, period, or underscore) and wildcard characters that can be used to select a subject of job groups that have a matching job correlator.  For a description of using wildcards, see Using wildcards.

JM|JOBMASK=jobmask

Specifies 1 to 8 alphanumeric, special ($, #, or @) or wildcard characters (or a combination of them) that can be used to select a subset of job groups whose job group name matches this combination of characters (mask). For a description of using wildcards, see Using wildcards.

group

Specifies 1 to 8 alphanumeric, special ($, #, or @) or wildcard characters. (or a combination of them) that can be used to select a subset of job groups whose job group name matches this combination of characters (mask). For a description of using wildcards, see Using wildcards.

‘group'

The name of the job group that is canceled. This name must appear as coded on the JOBGROUP statement and must be enclosed in apostrophes. If more than one job group exists with this name, no action is taken.

Group

A job group or range of job groups that is to be canceled.

OWNER=userid

Specifies the user ID that is associated with the job group.

Purge

JES2 purges the job group output.

Notes:

1. The P operand must be specified to terminate job groups that are already in the output phase.
2. $C with the P operand does not purge a job group with affinity to an inactive processor until the job group's affinity has been changed with the $TJ,S= command.
3. If the TSO/E user has affinity to an inactive member, the TSO/E notify message is not issued when you specify the P operand.
4. $C with the P operand is ignored for output that is active on an FSS printer.

Queue={CNV|INPUT|OUT|PPU|PURGE|RCV| SETUP|SPIN|XEQ|XMT}

Only job groups on the specified job group queue are to be canceled.

CNV

Only job groups awaiting conversion are to be canceled.

INPUT

Only job groups on the JES2 $INPUT queue are to be canceled.

OUT

Only job groups awaiting output processing are to be canceled.

PPU

Only job groups awaiting print/punch processing are to be canceled.

PURGE

Only job groups awaiting purge processing are to be canceled.

RCV

Only job groups on the JES2 $RECEIVE queue are to be canceled.

SETUP

Only job groups on the JES2 $SETUP queue are to be canceled.

SPIN

Only job groups awaiting spin processing are to be canceled.

XEQ

All job groups awaiting execution and in execution are to be canceled.

XMT

Only job groups queued for network transmission are to be canceled.

SCHENV=schenv

Specifies the scheduling environment that is associated with the job group.

SCHENV_AFF=member

Specifies the JES2 MAS members on which the scheduling environment for this job group is available.

SECLABEL_AFF=member

Specifies the JES2 MAS members on which the SECLABEL for this job group is available but only if the RACF® SECLABEL_BY_SYS is also active.

SECLABEL=seclabel

Specifies the security label that is associated with the job group.

SPL|SPOOL={Percent|%|Tgs|Volumes}

Only job groups with specific SPOOL characteristics are to be canceled:

Percent|%

Only job groups using more (with %>nn) or less (with %<nn) than the specified percentage of the total available spool space are to be canceled.

Tgs

Only job groups using more (with Tgs>nn) or less (with Tgs<nn) than the specified number of track groups are to be canceled.

Volumes=(v1,v2,...)

Only job groups that have allocated spool space on the specified spool volumes are to be canceled.

Sysaff

Specifies job groups to process based on this system affinity. Up to 33 entries can be coded by using a combination of the following values:

memname

Specifies the identifier (one to four characters using A-Z, 0-9, $, #, and @) of a member in the JES2 multi-access spool configuration that a job group has in its system affinity list.

ANY

Specifies job groups that are eligible to run on any member in the JES2 multi-access spool configuration. If you specify ANY followed by the IND parameter, they must be separated by a comma and the list must be enclosed in parentheses, for example, (ANY,IND).

IND

Specifies the job group that is selected and must be executed on a processor operating in independent mode.

XEQNode=xeqnode

Only job groups that are destined to execute at the specified node, or that have already executed at the specified node, are to be canceled. The node name can be specified using the decimal node number (Nnnnnn) or an EBCDIC node name.

Authority Required

This command requires job authority. The description of the $T RDRnn command explains how to ensure that the authority of the appropriate MVS™ system command group is assigned.

This command requires update security access authority. For a description of assigning command input authority, see z/OS JES2 Initialization and Tuning Guide.

Processing Considerations

• If the job group does not cancel, reenter the command.
• $C cannot cancel messages that are either being spooled for a remote or being printed by a remote.
• When canceling job groups in execution, the $C command results in an MVS CANCEL command. This allows other subsystems to monitor the canceling of job groups and, if necessary, take appropriate action.

  The MVS CANCEL command can also be used to cancel job groups in execution but the MVS command must be entered on the system where the job is running; therefore, using the $C command gives you more flexibility.

• For additional capabilities, refer to the descriptions of MVS CANCEL and STOP in z/OS MVS System Commands.

Scope

MAS-wide. This command has an effect across the entire MAS.

Messages

The $HASP890 message displays the characteristics of the canceled job group.