=head1 NAME

backup jobs - Lists pending and running operations in interactive mode

=head1 SYNOPSIS

jobs  [B<-help>]

j [B<-h>]

=head1 DESCRIPTION

The C<(backup) jobs> command lists the job ID number and status of each
B<backup> operation running or pending in the current interactive
session.

This command can be issued in interactive mode only. If the issuer of
the C<backup (interactive)> command included the B<-localauth> flag, the
B<-cell> argument, or both, those settings apply to this command also.

To terminate operations that appear in the output, issue the C<(backup)
kill> command and identify the operation to cancel with the job ID
number from this command's output.

To check the status of a Tape Coordinator, rather than of a certain
operation, use the C<backup status> command.

=head1 OPTIONS

=over 4

=item B<-help>

Prints the online help for this command. All other valid
options are ignored.

=back

=head1 OUTPUT

The output always includes the expiration date and time of the tokens
that the C<backup> command interpreter is using during the current
interactive session, in the following format:

I<date>   I<time>: TOKEN EXPIRATION

If the execution date and time specified for a scheduled dump
operation is later than I<date time>, then its individual line (as
described in the following paragraphs) appears below this line to
indicate that the current tokens will not be available to it.

If the issuer of the C<backup> command included the B<-localauth> flag when
entering interactive mode, the line instead reads as follows:

:  TOKEN NEVER EXPIRES

The entry for a scheduled dump operation has the following format:

Job I<job_ID>:  I<timestamp>:  dump  I<volume_set>  I<dump_level>

where

=over

=item B<I<job_ID>>

Is a job identification number assigned by the Backup System.

=item B<I<timestamp>>

Indicates the date and time the dump operation is to begin, in
the format I<month>/I<date>/I<year> I<hours>:I<minutes> (in 24-hour format)

=item B<I<volume_set>>

Indicates the volume set to dump.

=item B<I<dump_level>>

Indicates the dump level at which to perform the dump
operation.

=back

The line for a pending or running operation of any other type has the
following format:

Job I<job_ID>:  I<operation>  I<status>

where

=over

=item B<I<job_ID>>

Is a job identification number assigned by the Backup System.

=item B<I<operation>>

Identifies the operation the Tape Coordinator is performing,
which is initiated by the indicated command:

=over

=item B<C<Dump> (I<dump name>)>

Initiated by the C<backup dump> command. The I<dump name> has
the following format:

I<volume_set_name>.I<dump_level_name>

=item B<C<Restore>>

Initiated by the C<backup diskrestore>, C<backup volrestore>,
or C<backup volsetrestore> command.

=item B<C<Labeltape> (I<tape_label>)>

Initiated by the C<backup labeltape> command. The I<tape_label>
is the name specified by the C<backup labeltape> command's
B<-name> or B<-pname> argument.

=item B<C<Scantape>>

Initiated by the C<backup scantape> command.

=item B<C<SaveDb>>

Initiated by the C<backup savedb> command.

=item B<C<RestoreDb>>

Initiated by the C<backup restoredb> command.

=back

=item B<I<status>>

Indicates the job's current status in one of the following
messages. If no message appears, the job is either still
pending or has finished.

=over

=item B<I<number> Kbytes, volume I<volume_name>>

For a running dump operation, indicates the number of
kilobytes copied to tape or a backup data file so far,
and the volume currently being dumped.

=item B<I<number> Kbytes, restore.volume>

For a running restore operation, indicates the number of
kilobytes copied into AFS from a tape or a backup data
file so far.

=item B<[abort requested]>

The C<(backup) kill> command was issued, but the termination
signal has yet to reach the Tape Coordinator.

=item B<[abort sent]>

The operation is canceled by the C<(backup) kill> command.
Once the Backup System removes an operation from the
queue or stops it from running, it no longer appears at
all in the output from the command.

=item B<[butc contact lost]>

The C<backup> command interpreter cannot reach the Tape
Coordinator. The message can mean either that the Tape
Coordinator handling the operation was terminated or
failed while the operation was running, or that the
connection to the Tape Coordinator timed out.

=item B<[done]>

The Tape Coordinator has finished the operation.

=item B<[drive wait]>

The operation is waiting for the specified tape drive to
become free.

=item B<[operator wait]>

The Tape Coordinator is waiting for the backup operator
to insert a tape in the drive.

=back

=back

=head1 EXAMPLES

The following example shows that two restore operations and one dump
operation are running (presumably on different Tape Coordinators) and
that the C<backup> command interpreter's tokens expire on 22 April 1999
at 10:45 am:

   backup> jobs
   Job 1: Restore, 1306 Kbytes, restore.volume
   Job 2: Dump (user.sunday1), 34 Kbytes, volume user.pat.backup
   Job 3: Restore, 2498 Kbytes, restore.volume
          04/22/1999 10:45: TOKEN EXPIRATION

=head1 PRIVILEGE REQUIRED

None. However, queuing any operation requires privilege, and it is
possible to issue this command only within the interactive session in
which the jobs are queued.

=head1 COPYRIGHT

IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.

Converted from html to pod by Alf Wachsmann <alfw@slac.stanford.edu>, 2003,
and Elizabeth Cassell <e_a_c@mailsnare.net>, 2004,
Stanford Linear Accelerator Center, a department of Stanford University.

=head1 SEE ALSO

L<backup(1)>,
L<backup_interactive(1)>,
L<backup_kill(1)>,
L<backup_quit(1)>

=cut
