Job Functions

The function is helpful for scripting. It can be used to run multiple XQuery expressions one after another.

Warning: Registering an updating queries can cause deadlocks. For example, if the newly registered query is to update a database that is opened by the calling query, it cannot be started before the calling query is completed, whereas the calling query will wait infinitely for the result of the registered query.

It is usually safe to use the function if the calling query does not lock anything. If a deadlock occurs, both the calling and and the registered jobs can be stopped with job:remove. See Transaction Management for further details.

job:execute('db:create("test")'),
job:execute('db:put-value("test", 1 to 10, "numbers")')

for $n in 1 to 8
let $script := xs:anyURI('script' || $n || '.xq')
return try {
  job:execute($script, { 'n': $n })
} catch * {
  '* ' || $script || ': ' || $err:description
}

job:eval("1 + 3", (), { 'cache': true() })

job:eval(
  "import module namespace mail='mail'; mail:send('Happy birthday!')",
  (),
  { 'start': '2018-09-01T06:00:00' }
)

declare
  %rest:POST("{$query}")
  %rest:path('/start-scheduling')
function local:start($query) {
  job:eval($query, (), { 'start': '02:00:00', 'interval': 'P1D' })
};

declare
  %rest:path('/stop-scheduling/{$id}')
function local:stop($id) {
  job:remove($id)
};

job:eval("prof:sleep(1500)", (), { 'interval': 'PT1S', 'end': 'PT10S' })

job:eval(xs:anyURI('cleanup.xq'))

job:eval(static-base-uri(), options := { 'start': 'PT5S' })

• If the original job has raised an error, the cached error will be raised instead.
• The cached result or error will be dropped after it has been retrieved.
• If the result has not been cached or if it has been dropped, an empty sequence is returned.

The following $options are available:

declare
  %rest:path('/result/{$id}')
function local:result($id) {
  job:result($id)
};

job:list()[. != job:current()] ! job:remove(.)

job:remove(job:current())

• The function will terminate immediately if the job ID is unknown. This is the case if a future job has not been queued yet, or if the ID has already been discarded after job evaluation.
• If the function is called with the ID of a queued job, or repeatedly executed job, it may stall and never terminate.

job:list()

• id: job ID
• type: type of the job (command, query, REST, RESTXQ, etc.)
• state: current state of the job: scheduled, queued, running, cached
• user: user who started the job
• duration: evaluation time (included if a job is running or if the result was cached)
• start: next start of job (included if a job will be executed repeatedly)
• time: time when job was registered

• false indicates that the job ID is scheduled, queued, or currently running.
• true will be returned if the job has either finished, or if the ID is unknown (because the IDs of all finished jobs will not be cached).