Deleting Xi-Batch Jobs in Bulk

Xi-BatchXi-Batchhousekeepingjob-controlpermissionsbtjdelbtjlist

You have a set of Xi-Batch jobs to remove in one go. This article gives the commands, says what happens to jobs that have already started, and shows how to pick the jobs out of the queue.

What a deletion removes

A job that runs once and carries no repeat time takes itself out of the queue as soon as it finishes, so what accumulates in the queue is the site's timed and repeating work. Deleting one of those jobs is irreversible: the scheduler unlinks the job's SP script file in the spool directory as it removes the queue entry, and that file is the only copy of the job's script. Take a copy first with btjdel -u -k, as shown below.

Deleting a job that has started

btjdel refuses to touch a job that has started, and says so:

btjdel: Job 123456 is running - use "-y" argument to force kill.

The force flag is -y (-Y and --force are the same flag). It changes what happens to those started jobs:

• Every started job named on the command line is signalled: SIGTERM (15) by default, or the signal number given with -K.
• The signal goes to the job's whole process group, so the job script's children are signalled too.
• btjdel then sleeps once for the -S time, which defaults to 4 seconds, and re-reads the queue.
• Jobs that have stopped by then are deleted. Jobs still going are reported as did not die in 4 seconds - try -K9, are left in the queue, and make btjdel exit 1.

Force applies only to jobs that have started. The permission checks stay in place: the scheduler requires delete permission on each job, and kill permission as well to signal a running one, and otherwise answers You are not permitted to perform the requested operation on job .... Those permissions come from the job's own mode bits combined with the user's entry in btufile, so root's power over other users' jobs is whatever its btufile entry carries. By default root and the batch account are given every privilege, which lets them delete other users' jobs.

Where a job outlives the wait, raise it with -S and then escalate the signal with -K 9.

Deleting a list of jobs

btjdel accepts a list of job numbers in one call (btjdel [args] job [job...]), so no loop is needed. Job arguments are plain numbers, optionally prefixed with a host name as host:1234 for a remote job. Ranges, wildcards and patterns are rejected with Job argument ... is not numeric.

# Collect the job numbers of the local jobs you can see, one per line.
# -F "%N" prints only the job number, -N suppresses any header,
# -L excludes jobs belonging to other hosts.
btjlist -N -L -F "%N" > /tmp/job_ids.txt

# Look at what you are about to remove before you remove it
btjlist -N -L -H -F "%N %U %H %P"

# Take a copy of each job first. -u writes a pair of files named
# C and J followed by the job number into the current directory;
# -k keeps the jobs in the queue while you do it.
xargs btjdel -u -k < /tmp/job_ids.txt

# Delete the jobs that are only waiting
xargs btjdel < /tmp/job_ids.txt

# Kill and delete the jobs that had already started, giving them
# 30 seconds to finish rather than the default 4
xargs btjdel -y -S 30 < /tmp/job_ids.txt

# Confirm what is left
btjlist -H

btjdel reports each failure on standard error and carries on with the rest of the list. A job skipped because it was running, and a job refused on permissions, both leave the exit status at 0. It returns 13 when a job number could not be found and 1 when a signalled job outlived the wait. Check the queue afterwards with btjlist.

Name the format with -F and suppress the header with -N in a script. btjlist takes its defaults from the BTJLIST environment variable and from the per-user configuration files on the batch configuration path, so the format and the header of a bare btjlist are whatever the site has set. In the shipped default format, %N %U %H %I %p %L %t %c %P, the job number is the first column, padded with leading zeroes to the width of the longest job number in the list, and remote jobs appear as host:number.

Selecting the jobs to delete

Let btjlist do the selecting:

# Jobs belonging to one user, or one group
btjlist -N -L -u fred -F "%N"
btjlist -N -L -g devel -F "%N"

# Jobs in one named job queue
btjlist -N -L -q nightly -F "%N"

To select on state, put a separator in the format string. The progress column is the last field of the default format, has no trailing space, and is empty for a job waiting to run, so a filter such as grep " Run " matches nothing:

# Jobs that are actually executing
btjlist -N -L -F "%N|%P" | awk -F'|' '$2 == "Run" { print $1 }'

The progress values are: empty for a job waiting to run, then Done, Err, Abrt, Canc, Init, Strt, Run and Fin. btjdel treats Init, Strt, Run and Fin alike as "running" and needs -y for all four.

Selecting by job number as a proxy for age gives wrong answers. A job number is the process id of the command that submitted the job, raised by 80000 whenever that number is already in use, so job numbers neither increase over time nor stay within a range. Select on the time columns instead:

# Job number and the full date and time each job is next due
btjlist -N -L -F "%N|%T"

What is left in the queue afterwards

• The waiting jobs you listed have gone from the queue, along with their script files
• Jobs that had started have been signalled, and those that stopped within the wait have gone too
• Jobs that outlived the wait are still in the queue and still named in the btjdel output
• Jobs you lacked permission on are still in the queue, each with its own error line
• Copies of anything unqueued with -u are in the directory you ran the command from

Captured standard output and error are mailed or written to the job's owner when the job ends, then removed. A job killed with -y still delivers what it had written by then.

Related articles

All articles · Release notes · Contact support