Cancel user job
Component: | BS2000 |
Functional area: | Job processing |
Domain: | JOB |
Privileges: | STD-PROCESSING |
Routing code: | P |
Function
The CANCEL-JOB command cancels jobs running under the user’s own ID. The command can also be used to cancel batch jobs generated by the user’s own ID and running under a different user ID (extended access).
Resources occupied by the job are released (as for EXIT-JOB or LOGOFF). A job cannot use this command to terminate itself (only possible with EXIT-JOB or LOGOFF). If the job to be canceled has already been terminated, the CANCEL-JOB command is rejected and a message to this effect is displayed at the terminal. The CANCEL-JOB command cancels a job only when the job is in TU status or when processing of the next command is imminent. A job cannot be canceled in the following circumstances:
The job is waiting for an operator response. The command takes effect as soon as there has been a response (see the FORCE-JOB-CANCEL command to find out how to cancel jobs without waiting for a response).
The job terminates abnormally due to a system error
A HOLD-TASK command was issued for the job (by systems support personnel)
The job is already in job termination; e.g.: actions following EXIT-JOB or LOGOFF, or actions in the user program after ABEND has been signaled (for more on the ABEND-STXIT routine, see the “Executive Macros” manual [22].)
The job is in “PENDED INDEFINITELY” state
The job is a system task.
If a job is to be canceled in interactive mode with CANCEL-JOB, the system requests confirmation if the job to be canceled was started with the attribute
PROTECTION=*CANCEL (see ENTER-JOB, ENTER-PROCEDURE or SET-LOGON-PARAMETERS command).
Information on job termination
In the case of a job canceled with CANCEL-JOB, information about the originator of the CANCEL-JOB command is output to SYSOUT for that job. The output to SYSOUT contains an additional comment specified in the TEXT operand of the CANCEL-JOB command. If the job was terminated abnormally, i.e. the CANCEL-JOB command was issued with STEPS=*ALL (default), the status indicator of a monitoring job variable is set to the value '$A'. In addition, the information about the originator in abbreviated form and the comment from the TEXT operand are included in the system part (the first 128 bytes) of the monitoring job variable:
The originator information starts at byte 37 and consists of the character string CAN:'info', where info contains the first 27 bytes of the originator information supplied to SYSOUT.
The comment starts at byte 70 and consists of the character string TEXT:'text', where text contains the first 51 bytes of the comment specified in the operand.
For information on job monitoring, see the “Job Variables” manual [20].
Privileged functions
If the CANCEL-JOB command is issued at the operator terminal or under a user ID with TSOS or OPERATING privilege, it can be used to cancel a job issued under any user ID.
Format
CANCEL-JOB | Alias: CNJ | ||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||
Operands
JOB-IDENTIFICATION =
Type of job identification.
JOB-IDENTIFICATION = *TSN(...)
The job is identified by its task serial number (TSN).
TSN = <alphanum-name 1..4>
TSN of the job to be canceled.
Leading zeros may be omitted
HOST = *STD / <c-string 1..8>
Host system on which the job is running. The default is *STD, which means that the job is running on the local host. The host name of a remote system can only be specified for systems which are on a computer network (see the “HIPLEX MSCF” manual [25]).
JOB-IDENTIFICATION = *MONJV(...)
The job is identified by means of the monitoring job variable. The command is rejected if the JV is not accessible (no read permission or nonexistent JV) or is not monitoring a job.
For a job running on a remote host to be accessible via the monitoring JV, the MRSCAT of each host must contain the catalog ID of the pubset of the other host.
MONJV = <filename 1..54 without-gen-vers>
Name of the JV monitoring the job to be canceled.
The job to which this job variable is assigned is then canceled. This operand is available only to users who have the software product JV.
DUMP =
Defines whether a user dump is to be output for the job to be canceled or whether a user or area dump that is currently being processed is to be canceled.
DUMP = *NO
No memory dump.
DUMP = *STD
The definition currently made in the job that is to be canceled (see DUMP operand in the MODIFY-TEST-OPTIONS command) is interpreted as follows:
Specification for the job that is to be canceled | Effects |
|---|---|
DUMP=*NO | No memory dump. |
DUMP=*STD / *YES / *SYSTEM | A user dump is requested, for DUMP=*SYSTEM eventually a system dump is requested. |
DUMP = *CANCEL-RUNNING-DUMP
If a user or area dump is currently being created for the job that is to be canceled then dump creation should be canceled immediately and the dump file deleted.
SYSTEM-FILES =
Specifies whether the system files are to be output to printer or sent by email. Output to printer is not possible if the value NO-SPOOL was set for the system parameter SSMLGOF1.
SYSTEM-FILES = *STDOUT
Depending on the setting of the system parameter SSMOUT, the system files are output to the printer (see *PRINT) or sent by email (see *MAIL). In the case of cross-system command processing, the system parameter of the target system is evaluated.
SYSTEM-FILES = *PRINT
The system files are output to printer.
SYSTEM-FILES = *MAIL
The system files are sent by email with filename extension ".TXT". The receiver address(es) is/are taken over from the user entry of the user ID of the aborted job. How the receiver address is selected from an address list in accordance with the job name is described under the MAIL-FILE command. If transfer by email is not possible (e.g. no email address in the user ID), the system files are output to printer.
SYSTEM-FILES = *DELETE
Output of the system files is suppressed.
STEPS =
Specifies how the job is to be canceled. Information about the originator of the CANCEL-JOB command is always output to SYSOUT for a job that is to be canceled. The information output is supplemented by the comment specified by the originator in the TEXT operand of the CANCEL-JOB command.
STEPS = *ALL-STEPS
The specified job is canceled in its entirety. The status indicator of a monitoring job variable is set to ‘$A’. The information about the originator of the CANCEL-JOB command is included in abbreviated form in the system part (the first 128 bytes) of the monitoring job variable. In addition, a text specified in the TEXT operand is included in the system part of the monitoring job variable.
The effect depends on the batch job type of the specified job:
Repeat job: | Only the cancellation of the Type 1 follow-up job of a repeat job will result in the termination of all future job repetitions. |
Calendar job: | Cancellation of a calendar job affects only the current job which is still on the job queue or is executing. It does not affect subsequent repetitions of the calendar job. STEPS=*ALL-CALENDAR-REPETITIONS can be used to terminate the entire calendar job. |
STEPS = *CURRENT-STEP
The job is being processed:
In the specified job, only the current processing step is canceled: the spin-off mechanism or SDF-P error handling is triggered. No information is included in a monitoring job variable. The job can be terminated normally if no other reason for abnormal termination occurs. If a user program is currently loaded, it is first terminated abnormally. If an error handling facility is provided within the ENTER file (for method, see SET-JOB-STEP command), then the job is continued at the next processing step. If the next processing step is termination of the job (EXIT-JOB or LOGOFF command), the job ends normally and a monitoring job variable is then set to ‘$T’ (normal end of job).
NoteOn terminating a job with CANCEL-JOB and STEPS=*CURRENT-STEP, no abnormal end of job results.
The job is waiting to be processed:
The job is canceled in its entirety as with STEPS=*ALL-STEPS (see above).
STEPS = *ALL-CALENDAR-REPETITIONS
The specified job is canceled as with STEPS=*ALL-STEPS. If it is a calendar job, the entire calendar job (i.e. including any future repetitions) is removed from the job management system.
TEXT = *NO / <c-string 1..72>
Specifies whether and if so which text is to be output to SYSOUT as a comment in the specified job before abnormal termination. The text can be up to 72 characters long. If job monitoring is in use and the value *ALL-STEPS (default) or *ALL-CALENDAR-REPETITIONS was specified in the STEPS operand, the first 51 characters of the specified text are also included in the system part of the monitoring job variable.
Return codes
(SC2) | SC1 | Maincode | Meaning |
|---|---|---|---|
0 | CMD0001 | No errors | |
2 | 0 | CMD0002 | Command executed with a warning |
32 | CMD0221 | System error | |
64 | JMS0630 | Semantic error | |
64 | JMS0640 | MONJV error, illegal access or incorrect call time | |
64 | JMS0670 | Error in a REMOTE job | |
130 | JMS0620 | Memory saturation | |
130 | JMS0650 | MSCF or target computer not available | |
130 | JMS0660 | Retry command later |
If the command is issued for a print job, command return codes are returned by SPOOL (see also CANCEL-PRINT-JOB).
Notes
The CANCEL-JOB may be issued in batch or interactive mode or at the console.
With spoolout tasks, more than one may have the same task sequence number (TSN), as a result of a PRINT-DOCUMENT command for several files, for example. In that case, the CANCEL-JOB command applies to all print jobs which have the TSN specified in the command. A message is issued for each job that is canceled. The SHOW-USER-STATUS command outputs a list of jobs that have not yet been canceled. The jobs in question may be undergoing processing or may still be waiting for processing.
Notes on job monitoring (see also the “Job Variables” manual [ 20 ]):
If a job is monitored by a job variable (JV) is canceled, the JV job variable is set to “$A” provided that STEPS=*ALL-STEPS or *ALL-CALENDAR-REPETITIONS has been set. With a waiting job this also applies to STEP=*CURRENT-STEP. If a program executing within the job is being monitored by a job variable, the status indicator of the job variable monitoring the program is likewise set to “$A”.
If the job variable is not accessible or is not being used to monitor a job, the command is rejected.
If a calendar job is being monitored, the job variable doing the monitoring is assigned to the calendar job for as long as it exists. Monitoring ends only when the entire calendar job ends.
Example
Job cancellation with STEPS=*CURRENT-STEP and STEPS=*ALL-STEPS
/enter-proc proc.sort1,proc-par=(monjv-1='JV.JOB-A',
output-file-1='OUT.WORK1',
monjv-2='JV.JOB-B',
output-file-2='OUT.WORK2'),
monjv=jv.job-c,job-class=jcb00200,job-name=jobc,
logging=*yes,list=*yes,
ass-sys-file=*par( syslst=lst.jobc, sysout=out.jobc) ————— (1)
% JMS0066 JOB 'JOBC' ACCEPTED ON 12-01-26 AT 15:17, TSN = 3182
/show-job-status monjv(jv.job-c) —————————————————————————————————————— (2)
%TSN: 9VH1 TYPE: 2 BATCH NOW: 2012-01-26.151748 %JOBNAME: JOBC PRI: 9 225 SPOOLIN: 2012-01-26.1517 %USERID: USER1 JCLASS: JCB00200 LOGON: 2012-01-26.1517 %ACCNB: 89001 CPU-MAX: 200 CPU-USED:000000.1831 %REPEAT: NO RERUN: NO FLUSH: NO %MRSCAT: HOLD: NO START: SOON %TID: 003A0193 UNP/Q#: 17/012 %CMD: WAIT %ORIGFILE::2OSG:$USER1.PROC.SORT1 %CMD-FILE::2OSG:$USER1.S.E.9VC3.2012-01-26.15.17.37 %MONJV: :2OSG:$USER1.JV.JOB-C
/show-job-status monjv(jv.job-a) ——————————————————————————————————————
——— ——— — (3)
% JVS04D1 MONITORING JOB VARIABLE ':2OSG:$USER1.JV.JOB-A' NOT ASSIGNED TO JOB
/cancel-job monjv(jv.job-c),steps=*current,
text='Auftrag JOB-A wurde nicht gestartet; deshalb Abbruch von WORK-1' ——— (4)
% CAN00OK CANCEL PROCESSING STARTED FOR TSN '3182' WITH USER ID 'USER1'
/show-job-status monjv(jv.job-c) ————————————————————————————————————————————— (5)
%TSN: 9VH1 TYPE: 2 BATCH NOW: 2012-01-26.151943 %JOBNAME: JOBC PRI: 9 225 SPOOLIN: 2012-01-26.1517 %USERID: USER1 JCLASS: JCB00200 LOGON: 2012-01-26.1517 %ACCNB: 89001 CPU-MAX: 200 CPU-USED:000000.1942 %REPEAT: NO RERUN: NO FLUSH: NO %MRSCAT: HOLD: NO START: SOON %TID: 003A0193 UNP/Q#: 17/012 %CMD: WAIT %ORIGFILE::2OSG:$USER1.PROC.SORT1 %CMD-FILE::2OSG:$USER1.S.E.9VC3.2012-01-26.15.17.37 %MONJV: :2OSG:$USER1.JV.JOB-C
/show-jv jv=jv.job-c ———————————————————————————————————————————————————————— (6)
%$R 09VH11OSH J0312012-01-26141737
/show-job-status monjv(jv.job-b) ———————————————————————————————————————————— (7)
% JVS04D1 MONITORING JOB VARIABLE ':2OSG:$USER1.JV.JOB-B' NOT ASSIGNED TO JOB
/cancel-job monjv(jv.job-c),steps=*all,text='Auch JOB-B nicht gestartet! Deshalb
soll JOB-C abnormal beendet werden!' ———————————————————————————————————— (8)
% CAN00OK CANCEL PROCESSING STARTED FOR TSN '3182' WITH USER ID 'USER1'
/show-jv jv=jv.job-c ———————————————————————————————————————————————————————— (9)
%$A 09VH11OSH J0312012-01-26141737CAN:'DIAL 9VC3 USER1 ULF ' TEXT:'AUC H JOB-B NICHT GESTARTET! DESHALB SOLL JOB-C ABNO'
(1) | The S procedure PROC.SORT1 is started as a batch job via the ENTER-PROCEDURE command. The procedure comprises two work steps:
Both work steps can be performed independently. The batch job is monitored using the job variable JV.JOB-C. |
(2) | The started job JOB-C is waiting (WAIT-EVENT). |
(3) | The first monitoring job variable JV.JOB-A is not assigned to any job. |
(4) | So the section being processed is canceled with STEP=*CURRENT-STEP. |
(5) | JOB-C is waiting again (second WAIT-EVENT). |
(6) | The monitoring job variable of JOB-C has not been affected by CANCEL-JOB. |
(7) | The second monitoring job variable JV.JOB-B is not assigned to any job either. |
(8) | The entire JOB-C is not to be terminated normally since further processing does not make sense. |
(9) | The monitoring job variable indicates that the job has been abnormally terminated. It also contains the cause and the originator’s comment in abbreviated form. |
SYSOUT log with execution of JOB-C
/CALL-PROC NAME=:2OSG:$USER1.S.PROC.9VC3.2012-01-26.15.17.37 ,
PROCEDURE-PARAMETERS=(MONJV-1='jv.job-a',OUTPUT-FILE-1='out.work1',
MONJV-2='jv.job-b',OUTPUT-FILE-2='out.work2'),LOGGING=*YES
1 1 /BEG-PAR-DECL
2 1 /DECL-PAR MONJV-1 (INIT = *PROMPT)
3 1 /DECL-PAR OUTPUT-FILE-1 (INIT = *PROMPT)
4 1 /DECL-PAR MONJV-2 (INIT = *PROMPT)
5 1 /DECL-PAR OUTPUT-FILE-2 (INIT = *PROMPT)
6 1 /END-PAR-DECL
% SDP0116 PARENTHESIS MISSING
% SDP0014 WARNING IN LINE: 30 IN PROCEDURE ':2OSG:$USER1.S.PROC.9VC3.2012-0126.15.17.37'
7 1 /WORK-1:
8 1 /WAIT-EVENT JV(COND = ( (jv.job-a,1,2) = '$T' ),
TIME-LIMIT = 3600 )
% CJC0020 WAIT COMMAND: TASK ENTERED WAIT STATE AT 15:17:37
% CAN00BY CANCELLED BY 'DIAL 9VC3 USER1 ULF FIREBALL $$$06580'
% CAN0TXT TEXT: 'AUFTRAG JOB-A WURDE NICHT GESTARTET; DESHALB ABBRUCH VON WORK-1'
% SDP0004 ERROR DETECTED AT COMMAND LINE: 8 IN PROCEDURE
':2OSG:$USER1.S.PROC.9VC3.2012-01-26.15.17.37'
18 1 /WORK-1-ERROR:
18 1 / IF-BLOCK-ERROR
19 1 /WRITE-TEXT 'Fehler bei WORK-1 mit SC1 = 64'
Fehler bei WORK-1 mit SC1 = 64
20 1 /HELP-MSG CMD0205
% CMD0205 ERROR IN PRECEDING COMMAND OR PROGRAM AND PROCEDURE STEP TERMINATION: COMMANDS
WILL BE IGNORED UNTIL /SET-JOB-STEP OR /LOGOFF OR /EXIT-JOB IS RECOGNIZED
% ? The command issued is invalid or the program was terminated with the
% macro TERM UNIT=STEP or TERMJ.
% All commands following the invalid one will be ignored until a
% /SET-JOB-STEP or a /LOGOFF or an /EXIT-JOB command is received.
% In a procedure, the /END-PROCEDURE command will be accepted but the
% other commands will still be ignored.
% RESPONSE : NONE
23 1 /END-IF
24 1 /WORK-2:
25 1 /WAIT-EVENT JV(COND = ( (jv.job-b,1,2) = '$T' ),
TIME-LIMIT = 3600 )
% CJC0020 WAIT COMMAND: TASK ENTERED WAIT STATE AT 15:19:28
% CAN00BY CANCELLED BY 'DIAL 9VC3 USER1 ULF FIREBALL $$$06580'
% CAN0TXT TEXT: 'AUCH JOB-B NICHT GESTARTET! DESHALB SOLL JOB-C ABNORMAL BEENDET
WERDEN!'
% NRTT201 TASK TERMINATION DUE TO /CANCEL(-JOB) COMMAND
% EXC0419 /LOGOFF AT 1521 ON 12-01-26 FOR TSN '9VH1'
% EXC0421 CPU TIME USED: 0.1995
Contents of procedure file PROC.SORT1
/BEG-PAR-DECL
/ DECL-PAR MONJV-1 (INIT = *PROMPT)
/ DECL-PAR OUTPUT-FILE-1 (INIT = *PROMPT)
/ DECL-PAR MONJV-2 (INIT = *PROMPT)
/ DECL-PAR OUTPUT-FILE-2 (INIT = *PROMPT)
/END-PAR-DECL
/WORK-1: "Sorting file 1"
/ WAIT-EVENT JV(COND = ( (&(MONJV-1),1,2) = '$T' ),-
/ TIME-LIMIT = 3600 )
/ CRE-JV JV = #WORK1
/ MOD-JV JV = #WORK1, -
/ SET-VALUE = ( &(MONJV-1),129,54 )
/ ADD-FILE-LINK LINK=SORTIN, -
/ FILE-NAME= &(JV('#WORK1'))
/ ADD-FILE-LINK LINK=SORTOUT, -
/ FILE-NAME= &(OUTPUT-FILE-1)
/ SORT-FILE
/WORK-1-ERROR: IF-BLOCK-ERROR
/ WRITE-TEXT 'Error on WORK-1 with SC1 = &(SC1)'
/ HELP-MSG &(MC)
/ ELSE
/ WRITE-TEXT 'WORK-1 terminated without error'
/ END-IF
/WORK-2: "Sorting file 2"
/ WAIT-EVENT JV(COND = ( (&(MONJV-2),1,2) = '$T' ),-
/ TIME-LIMIT = 3600 )
/ CRE-JV JV = #WORK2
/ MOD-JV JV = #WORK2 , -
/ SET-VALUE = ( &(MONJV-2),129,54 )
/ ADD-FILE-LINK LINK=SORTIN, -
/ FILE-NAME= &(JV(#WORK2'))
/ ADD-FILE-LINK LINK=SORTOUT, -
/ FILE-NAME= &(OUTPUT-FILE-2)
/ SORT-FILE
/WORK-2-ERROR: IF-BLOCK-ERROR
/ WRITE-TEXT 'Error on WORK-2 with SC1 = &(SC1)'
/ HELP-MSG &(MC)
/ ELSE
/ WRITE-TEXT 'WORK-2 terminated without error'
/ END-IF