Tracing levels
Documentum job scheduler
Xense Session Manager
Job scheduler
Job selection query
Tracing job
Documentum job scheduler
Job selection query

Let's have a closer look at the query that the job scheduler executes:

1 SELECT ALL r_object_id, a_next_invocation
2 FROM dm_job
4        (run_now = 1)
5   OR (    (is_inactive = 0)
6        AND (            ( a_next_invocation <= DATE('now')
7                     AND   a_next_invocation IS NOT NULLDATE )
8               OR        ( a_next_continuation <= DATE('now')
9                     AND   a_next_continuation IS NOT NULLDATE )
10       AND ( (expiration_date > DATE('now'))
11              OR (expiration_date IS NULLDATE))
12       AND ( (max_iterations = 0)
13              OR (a_iterations < max_iterations) )
16 AND (i_is_reference = 0 OR i_is_reference is NULL)
17 AND (i_is_replica = 0 OR i_is_replica is NULL)
18 ORDER BY a_next_invocation, r_object_id

Again I have labelled each line with red numbers. This daunting query can be made less intimidating by suitable formatting. From lines 1 and 2 we are querying on dm_job objects. Recall that the dm_job type defines the scheduling of a job. Lines 3 to 17 define some query predicates to filter the jobs that might be ready to execute. Line 18 is the order by clause; note that results are ordered first by a_next_invocation.
By breaking down the query predicate into smaller chunks we can understand the query logic. At the highest level, the predicate is 3 complex expressions ANDed together:

(lines 4 to 13) AND (line 16) AND (line 17)

So all 3 expressions must evaluate to TRUE for the job object to be considered for execution. The 2nd and 3rd expressions (Lines 16 & 17) cause the query to ignore mirror and replica dm_job objects. These could possibly be created in distributed docbase designs but usually these attributes would not be set for dm_job objects - the 2nd and 3rd expressions should always evaluate to TRUE and we will not consider them further.

So looking at lines 4 to 13 we can breakdown this expression - the predicate is 2 expressions ORed together:

(line 4) OR (line 5 to 13)

At least 1 of those 2 expressions must evaluate TRUE for the job object to be considered for execution. Looking at the first expression if we set run_now = 1 then the lines 4 to 13 evaluate TRUE. run_now is the attribute that is set when you select Tools | Run in Documentum Administrator. We simply have to wait until the next time the job scheduler polls the docbase (by default every 60 seconds if there are no other jobs to be executed) and the job is executed.

Lines 5 to 13 are the heart of the scheduling logic. Breaking it down into manageable chunks we get 4 expressions ANDed together:

(line 5) AND (line 6-9) AND (line 10-11) AND (line 12-13)

All 4 of these expression must evaluate TRUE for the job to be scheduled to run (as opposed to being run due to the run_now attribute being set). Line 5 is the rather contorted logic required to only run Active jobs (I bet Documentum wished they had called it is_active). Remember that in Documentum Administrator you can set a job Active or Inactive, if the job is Inactive it will only executed if the job is run using Tools | Run. i_is_inactive is the attribute that will be affected by the Active/Inactive radio button.

Lines 6 to 9 deal with the scheduling requirements for the a_next_invocation (lines 6 and 7) and a_next_continuation attributes (lines 8 and 9). The a_next_invocation attribute is maintained and updated by the scheduler after every invocation according to the schedule defined by the run_mode and run_interval attributes (the details are in the Content Server Administrator's Guide). I must confess that the a_next_continuation attribute is something of a mystery, according to the Object Reference it is 'Date of next automatic invocation of the job' which sounds like the same thing as the a_next_invocation. One thing to notice about lines 6 to 9 is the logical construct:

'date attribute' <= date(NOW) AND 'date attribute' IS NOT NULLDATE

This is required because NULLDATE always evaluates to less than any other date (on Oracle platforms at least). I say always, in fact if you look at the values stored in the database for NULLDATE it is actually the date 01 January 0001! Be very careful with NULLDATEs.

Lines 10 and 11 deal with the requirement not to execute beyond the expiration_date attribute. Notice that in this case we have ... OR (expiration_date IS NULLDATE). If no expiration_date is set then we can allow the job to execute. One irritation with all the WDK versions of Documentum Administrator is that it is not possible to set a job with no expiration date. One work around is to set the expiration_date to NULLDATE manually using DQL or the API.

Finally lines 12 and 13 deal with the requirement not to exceed the max_iterations attribute. The a_iterations attribute is incremented by the scheduler after every execution.

There you have it - the DQL that the job scheduler uses to select jobs for execution. When I have to debug a system where a job doesn't appear to run one technique I use is to run the job selection DQL manually. If the problem job does not appear in the result set then you need to look at exactly what attributes have been set on the job. next