lsjob

Purpose

Use the lsjob command to obtain the status of scheduled backup and restore jobs. You can select which jobs to display by date, status, and the degree of detail to display.

Each job is assigned identifier consisting of the username of the logged in user, a slash, and a unique numerical identifier. An example of a job identifier is admin/15.

The lsjob command shows all active and pending jobs, with one line for each job:

Job-ID   Sched time  Contents   State

See Also:

"Job Commands" for related commands

Prerequisites

If you are attempting to list another user's jobs, then you must have the right to list any job, regardless of its owner. If you are attempting to list your own jobs, then you must have the right to list any jobs owned by user.

Syntax

lsjob::=

lsj•ob [ --active/-a ] [ --complete/-c ] [ --pending/-p ]
[ --inputrequest/-i ] [ --all/-A ]
[ { [ --from/-f date-time ] [ --to/-t date-time ] } | 
  [ --today/-T ] ] 
[ --timescheduled/-e ] [ --type/-Y job-type[,job-type]... ]...
[ --host/-h hostname ] [ --dataset/-D dataset-name ]
[ --system/-y | { --username/-u username } | --me/-m ]
[ --superseded/-S ] [ --subjobs/-j | --primary/-P ]
[ { --short/-s [ --oneperline/-1 ] } | --long/-l ] 
[ --noheader/-H ] [ --results/-r ] [ --requires/-R ] 
[ --times/-C ] [ --log/-L ]
job-id ...

Semantics

Use these options to select the jobs to be shown. If you specify no state-based options, then obtool displays only active and pending jobs. Multiple options are additive.

State-based job options

Use these options to filter jobs by status. Refer to Example 2-59 for an illustration.

--active/-a: Shows active jobs, that is, jobs that are currently being executed. By default the lsjob command displays active and pending jobs.
--complete/-c: Shows jobs that completed either successfully or unsuccessfully.
--pending/-p: Shows pending jobs, that is, jobs that are not running and are scheduled to be executed in the future. By default the lsjob command displays active and pending jobs.
--inputrequest/-i: Shows jobs currently requesting input. For example, a job might require input if you try to restore a backup from a multi-volume volume set while using a standalone tape drive or if a volume required for a restore operation is not available in a library.
--all/-A: Shows jobs in all states.
job-id ...: Specifies the job ID of the scheduled backup and restore job whose status you want to obtain.

Time-based job options

Use these options to filter jobs according to when their state was updated or when they were scheduled to run. Refer to Example 2-60 for an illustration.

--from/-f date-time: Shows only jobs whose state was updated at date-time or later. For example, show jobs that went from pending to active in the last day. Refer to "date-time" for the date-time placeholder.
--to/-t date-time: Shows only jobs whose state was updated at date-time or before. For example, show jobs that went from pending to active before yesterday. Refer to "date-time" for the date-time placeholder.
--today/-T: Shows only jobs whose state was updated today.
--timescheduled/-e: Uses scheduled time as a selection criteria instead of job modification time. Use either --today or --from to select the date-time range. If you specify neither option, then no constraint is applied to the date-time range.

Type/hostname/dataset-based job options

Use these options to filter jobs according to job type, host name, or dataset identifier. Refer to Example 2-61 for an illustration.

--type/-Y job-type[,job-type]...: Shows only job entries of the specified type. By default obtool displays all types. Refer to "job-type" for the job-type placeholder.
--host/-h hostname: Shows only job entries related to the specified host.
--dataset/-D dataset: Shows only job entries related to the specified dataset file. Execute the lsds command to display dataset file information.

Username-based job options

Use these options to filter jobs according to who initiated them. Refer to Example 2-62 for an illustration.

--system/-y: Shows jobs scheduled by Oracle Secure Backup.
--username/-u username: Shows jobs belonging to username. Execute the lsuser command to display all Oracle Secure Backup users.
--me/-m: Shows jobs belonging to the currently logged in user. Execute the id command to display the current Oracle Secure Backup user.

Miscellaneous job options

Use these options to filter jobs according to miscellaneous criteria. Refer to Example 2-63 for an illustration.

--superseded/-S

Shows jobs that were superseded before they were run.

A job is superseded when an identical job was scheduled after the initial job had a chance to run. For example, suppose you schedule an incremental backup scheduled every night at 9 p.m. On Wednesday morning you discover that the Tuesday night backup did not run because no tapes were available in the library. The incremental backup scheduled for Wednesday supersedes the backup from the previous night.

--subjobs/-j

Shows subordinate jobs if the selected job has them (default). For example, lsjob --primary shows sbt/25.1, sbt/25.2, and sbt/25.3 rather than just sbt/25.

--primary/-P

Shows only each primary job. For example, lsjob --primary shows sbt/25 rather than sbt/25.1, sbt/25.2, and sbt/25.3.

Format control job options

Use these options to control the display of job information. Refer to Example 2-64 for an illustration.

--short/-s: Shows only job IDs.
--long/-l: Shows job information in labeled rather than column format.
--noheader/-H: Does not display column headers.
--oneperline/-1: Shows one job ID for each line when used with the --short option.

Content level job options

Use these options to filter jobs based on how much content to include. Refer to Example 2-65 for an illustration.

--results/-r

Shows results for completed jobs when used in conjunction with the --completed option. For example, the results might look like the following:

saved 3.4 MB to VOL000003 (tag ADE202), file 12
ok:   /home

--requires/-R

Shows resources required to run each job. For example, jobs that can run on any device display "requires any device."

--times/-C

Shows all relevant times for each job. For example, the job times might look like the following:

introduced 2005/03/21.16:59, earliest exec 03/23.00:00, last update
2005/03/21.16:59, expires never

--log/-L

Shows the log associated with each job. The log shows data such as when the job was created, which host it was dispatched on, when it completed, and so forth.

Output

Table 2-11 describes the output of the lsjob command.

Table 2-11 lsjob Output

Label	Indicates
Job ID	Unique Oracle Secure Backup identifier assigned to a scheduled backup or restore job
Type	The type of job (`dataset` or `database`)
Scheduled time	Time job was scheduled to begin
Contents	Dataset that was used or host that was backed up
State	State of the job; setting is `processed`, `pending`, `completed successfully`, or `failed`
Priority	Priority level of the backup schedule; `1` is the highest priority
Privileged op	Whether job requires administrator privileges
Run on host	Host on which the job runs
Attempts	Number of times Oracle Secure Backup attempted to run the job

Examples

Example 2-59 shows jobs in all states: active, pending, completed, and awaiting input.

Example 2-59 Filtering Jobs by State

ob> lsjob --all
Job ID           Sched time  Contents                    State
---------------- ----------- --------------------------- ---------------------------------------
admin/1          none     dataset tbrset/entire_backup   completed successfully at 2005/03/21.10:17
admin/1.1        none     backup brhost2                 completed successfully at 2005/03/21.10:17
admin/2          none     restore 1 item to brhost2      completed successfully at 2005/03/21.10:17
admin/3          none     dataset fullbackup.ds          completed successfully at 2005/03/21.10:32
sbt/1            none     database ob (dbid=1557818382)  completed successfully at 2005/03/21.10:19
sbt/1.1          none     archivelog backup              completed successfully at 2005/03/21.10:19
sbt/2            none     database ob (dbid=1557818382)  completed successfully at 2005/03/21.10:19
sbt/2.1          none     controlfile autobackup         completed successfully at 2005/03/21.10:19
sbt/3            none     database ob (dbid=1557818382)  completed successfully at 2005/03/21.10:19
sbt/3.1          none     datafile backup                completed successfully at 2005/03/21.10:19
sbt/4            none     database ob (dbid=1557818382)  completed successfully at 2005/03/21.10:21
sbt/4.1          none     restore piece '03gfrui9_1_1'   completed successfully at 2005/03/21.10:21
sbt/5            none     database ob (dbid=1557818382)  completed successfully at 2005/03/21.10:21
sbt/5.1          none     incremental backup             completed successfully at 2005/03/21.10:21

Example 2-60 shows jobs that are active and pending today only.

Example 2-60 Filtering Jobs by Time

ob> lsjob --today
Job ID           Sched time  Contents                       State
---------------- ----------- ------------------------------ ----------------------
admin/13         03/23.00:00 dataset fullbackup.ds          future work

Example 2-61 shows jobs in all states on host brhost2.

Example 2-61 Filtering Jobs by Host

ob> lsjob --all --short --oneperline --host brhost2
admin/1.1
admin/2
admin/3.1
admin/4.1
admin/5.1
sbt/6.1
sbt/7.1

Example 2-62 shows active and pending jobs for user sbt.

Example 2-62 Filtering Jobs by User

ob> lsjob --user sbt
Job ID           Sched time  Contents                       State
---------------- ----------- ------------------------------ ---------------------
admin/13         03/23.00:00 dataset fullbackup.ds          future work

Example 2-63 shows active and pending jobs that have been superseded.

Example 2-63 Showing Superseded Jobs

ob> lsjob --superseded
Job ID           Sched time  Contents                       State
---------------- ----------- ------------------------------ ----------------------
admin/13         03/23.00:00 dataset fullbackup.ds          future work

Example 2-64 shows active and pending jobs in long format.

Example 2-64 Displaying Job Data in Long Format

ob> lsjob --long
admin/13:
    Type:                   dataset fullbackup.ds
    Level:                  full
    Family:                 (null)
    Scheduled time:         03/23.00:00
    State:                  future work
    Priority:               100
    Privileged op:          no
    Run on host:            (administrative server)
    Attempts:               0

Example 2-65 shows all time-related data for active and pending jobs.

Example 2-65 Displaying All Time-Related Data

ob> lsjob --times
Job ID           Sched time  Contents                       State
---------------- ----------- ------------------------------ ----------------------
admin/13         03/23.00:00 dataset fullbackup.ds          future work
    introduced 2005/03/21.16:59, earliest exec 03/23.00:00, last update 
    2005/03/21.16:59, expires never