Changes

=Services= A job can be registered as ''service'' by supplying the {{Code|service}} option to {{Function|Jobs|jobs:eval}}: <pre class="brush:xquery">(: register job as service; will be run every day at 1 am :)jobs:eval('db:drop("tmp")', (), map { 'id':'cleanup', 'start':'01:00:00', 'interval':'P1D', 'service': true() }), (: list registered services :)jobs:services(),(: result: <job base-uri="..." id="cleanup" interval="P1D" start="01:00:00">db:drop("tmp")</job> :) (: unregister job :)jobs:stop('cleanup', map { 'service': true() })</pre> '''Some more notes:''' * All job services will be scheduled for evaluation when the BaseX server or BaseX HTTP server is started.* If a job service is outdated (e.g. because a supplied end time has been exceeded), it will be removed from the jobs file at startup time.* Job services can be updated: If a new job is registered, and if there is already a job with the same id, the old entry will be replaced.* The job definitions are stored in a {{Code|jobs.xml}} file in the database directory. It can also be edited manually. =Basic Functions=

|Returns the ids of all jobs that are currently registered. The list includes scheduled, queued, running jobs, stopped, and finished jobs with cached jobsresults.

|* <code>jobs:list()</code> returns the same job id as [[#jobs:current{{Function|Jobs|jobs:current]] }} if no other job is registered.* <code>jobs:list()[. != jobs:current()] ! jobs:stop(.)</code> stops and invalidates all asynchronous queries and results except for the current one.

|Returns information on all jobs that are currently registered, or on a job with the specified {{Code|$id}} (or an empty sequence if this job is not found). The list includes scheduled, queued, running jobs, and cached jobs. A string representation of the job , or its URI, will be returned in the text nodeas value. The returned elements have additional attributes:

* <code>state</code>: current state of the job (: <code>scheduled</code>, <code>queued</code>, <code>running</code>, or <code>cached)</code>* <code>user</code>: the user who started the job* <code>duration</code>: evaluation time (for included if a job is running and or if the result was cached jobs)* <code>start</code>: dateTime string with next start of job (for jobs that included if a job will be executed repeatedly)* <code>time</code>: time when job was registered

|* <code>jobs:list-details()</code> returns information on the currently running job and possibly others:

==jobs:stopservices==

|{{Func|jobs:stopservices|$id as xs:string|empty-sequenceelement(job)*}}

|Triggeres the cancelation of Returns a job with the specified {{Code|$id}}, drops the cached result list of a query, or cancels a scheduled job. Unknown ids are ignored. All jobs are gracefully stopped; it is up to the process to decide when it is safe to shut down.|} ==jobs:wait== {| width='100%'|-| width='120' | '''Signatures'''|{{Func|all jobs:wait|$id that have been persistently registered as xs:string|empty-sequence()}}[[#Services|-| '''Summary'''|Waits for the completion of a job with the specified {{Code|$id}}. If the function is called with the id of a repeatedly executed job, it may never terminateServices]].

|{{Error|selfservices|#Errors}} if the current job is addressedRegistered services cannot be parsed.<br/>

=Asynchronous Execution=

Asynchronous query execution is recommendable if There are cases in which a client does not, or cannot, wait until a request is fully processed. This is e. g. the case with web browsersThe client may be a browser, which will usually cancel a sends an HTTP request after a specific timeout. In such cases, you can use asynchronous execution to trigger another the server-side process, which will in order to start the another time-consuming processquery job. The functions in this section allow you to register a new query job from a running query. Jobs can be executed immediately (i.e., and fetch the result later on as soon as the [[Transaction Management#Concurrency Control|Concurrency Control]] allows it is available) or scheduled for repeated execution. Each registered job gets a job id, and the id can be used to retrieve a query result, stop a job, or wait for its termination.

{{Mark|Updated with Version 89.62}}: <code>id</code> option addedFirst argument can be a URI (jobs:invoke was removed).

|{{Func|jobs:eval|$query as xs:stringanyAtomicItem|xs:string}}<br />{{Func|jobs:eval|$query as xs:stringanyAtomicItem, $bindings as map(*)?|xs:string}}<br />{{Func|jobs:eval|$query as xs:stringanyAtomicItem, $bindings as map(*)?, $options as map(xs:string, xs:string*)?|xs:string}}<br />

|Schedules the evaluation of the supplied {{Code|$query}} and returns a query id. The query will be queued, and the result will optionally be cached. Queries can be updating. Variables The query can be a URI or a string, and variables and context items can be declared via {{Code|$bindings}} (see [[XQuery Module#xquery:eval|xquery:eval]] for more details). The following {{Code|$options}} parameter contains scheduling optionscan be supplied:

** If a time is specified, the query will be executed at this time of the day. Examples for valid times are: <code>02:00:00</code> (2amlocal time), <code>12:00:0000Z</code> (noon, UTC). If the time lies in the past, the query will be executed the next day.

|{{Error|overflow|#Errors}} Query execution is rejected, because too many jobs are queued or being executed. {{Option|CACHETIMEOUT}} can be decreased if the default setting is too restrictive.<br/>{{Error|range|#Errors}} A specified time or duration is out of range.<br/>{{Error|id|#Errors}} The specified id is invalid or has already been assigned.<br/>{{Error|options|#Errors}} The specified options are conflicting.

* The following query demonstrates how the results of an asynchronously executed query can be returned within the same query(see below why you should avoid this pattern in practice):

let $query := jobs:eval('(1 to 10000000)[. = 1]', map{}, map{ 'cache': true() })

Please remember that Queries of this kind can cause deadlocks! If the original query and the new query perform updates on the same database, the second query will cause a deadlock if only be run after the asynchronously first one has been executed , and the first query will be queuedwait for the second query forever. In practice. In practice, you You should avoid this pattern and resort to [[XQuery Module#xquery:fork-join|xquery:fork-join]] if you want to do things in have full control on parallelquery execution.|} ==jobs:stop== {| width='100%'|-| width='120' | '''Signatures'''|{{Func|jobs:stop|$id as xs:string|empty-sequence()}}|-| '''Summary'''|Triggers the cancelation of a job with the specified {{Code|$id}}, drops the cached result of a query, or cancels a scheduled job. Unknown ids are ignored. All jobs are gracefully stopped; it is up to the process to decide when it is safe to shut down. The following {{Code|$options}} can be supplied:* {{Code|service}}: additionally removes the job from the [[#Services|job services]] list.|-| '''Examples'''| <code>jobs:list()[. != jobs:current()] ! jobs:stop(.)</code> stops and discards all jobs except for the current one.|} ==jobs:wait== {| width='100%'|-| width='120' | '''Signatures'''|{{Func|jobs:wait|$id as xs:string|empty-sequence()}}|-| '''Summary'''|Waits for the completion of a job with the specified {{Code|$id}}:* 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.|-| '''Errors'''|{{Error|self|#Errors}} The current job is addressed.<br/>

|{{Code|unknownoptions}}| The supplied query id is unknown or not available anymorespecified options are conflicting.

|{{Code|runningid}}| A query The specified id is still runninginvalid or has already been assigned.

|{{Code|idrunning}}| The specified A query is invalid or has already been assignedstill running.