Job Functions

Instead of a query, a function item can be supplied, which is invoked with the arguments of the $bindings array.

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

Deadlocks: A deadlock error is raised if the registered query requires database locks that the calling query holds: the registered query cannot start before the calling query completes, while the calling query waits infinitely for its result. This happens, for example, if the registered query updates a database that the calling query has already locked. Instead of blocking, the call fails with an error that reports the locks required by the registered job.

It is safe to use the function if the calling query does not lock the databases addressed by the registered query. See Transaction Management for further details.

Updating function items: An updating function item always raises this error. The locks of a function item are known to the calling query, which therefore write-locks the databases the job will update before the job is registered. Supply an updating query as string instead.

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
}

Instead of a query, a function item can be supplied, which is invoked with the arguments of the $bindings array. A function item can neither be registered as service, because services are written to disk, nor be scheduled with start, interval or cron, because a scheduled job outlives the query that created it.

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

job:eval(fn($name) { 'Hello ' || $name }, [ 'World' ], { '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(xs:anyURI('report.xq'), (), { 'cron': '0 6 * * MON-FRI' })

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)
};

• The information is only available if the job was started with the info option.
• It is dropped together with the result, so it must be requested before job:result is called.
• If no information has been cached or if it has been dropped, an empty sequence is returned.

The returned map holds the information that is output if the QUERYINFO option is enabled, one entry per section. The keys are lower case (timing, result, optimized-query, …), and only the sections that apply to a query are returned.

let $id := job:eval('1 + 2', (), { 'cache': true(), 'info': true() })
return (job:wait($id), job:info($id)?timing?total)

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 of a 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)
• interval, cron: repetition of the job (included if the corresponding option was supplied)
• time: time when job was registered
• read: read locks ((global): global locking, (none): no locking)
• write: write locks ((global): global locking, (none): no locking)

Fewer than $count values are returned if the expression stops matching; the result is empty if it will never match again.

The results are relative to fn:current-dateTime, and are therefore stable: repeated calls within a single query return the same points in time.

job:next('0 8 * * MON-FRI', 3)

job:next('0 0 30 2 *')

• false indicates that the job is queued or currently running.
• true will be returned if the job has finished, if it is scheduled for a later time or waiting for its next repetition, or if the ID is unknown (because the IDs of all finished jobs will not be cached).