<apidoc:module name="AdminBuiltins" category="AdminBuiltins" lib="xdmp" xmlns:apidoc="http://marklogic.com/xdmp/apidoc"><apidoc:function name="forest-backup" type="builtin" lib="xdmp" category="AdminBuiltins" hidden="false" bucket="MarkLogic Built-In Functions">
    <apidoc:summary>
  Backs up forest data files.
</apidoc:summary>
    <apidoc:params>
      <apidoc:param name="forestID" type="unsignedLong" optional="false">
    A forest ID.
  </apidoc:param>
      <apidoc:param name="pathname" type="xs:string" optional="false">
    A forest backup pathname.  If the directory does not exist, it is
    created when you run this function.  The filesystem permissions must be
    such that the directory is writable by the 
    operating system user under which MarkLogic Server is running.  The 
    directory cannot be the MarkLogic Server install directory or the
    MarkLogic Server data directory. 
  </apidoc:param>
    </apidoc:params>
    <apidoc:privilege>
  <p xmlns="http://www.w3.org/1999/xhtml"><code>http://marklogic.com/xdmp/privileges/xdmp-forest-backup</code></p>
</apidoc:privilege>
    <apidoc:usage>
  <p xmlns="http://www.w3.org/1999/xhtml">Reindexing will stop while a backup or restore is in progress. </p>
</apidoc:usage>
    <apidoc:return>empty-sequence()</apidoc:return>
    <apidoc:example><pre xml:space="preserve" xmlns="http://www.w3.org/1999/xhtml">
  xdmp:forest-backup(11183608861595735720,"/backups/Data/Forests/Documents")
</pre></apidoc:example>
  </apidoc:function><apidoc:function name="forest-restore" type="builtin" lib="xdmp" category="AdminBuiltins" hidden="false" bucket="MarkLogic Built-In Functions">
    <apidoc:summary>
  Restores forest data files.
  Restarts the forest to complete the restoration.
</apidoc:summary>
    <apidoc:params>
      <apidoc:param name="forestID" type="unsignedLong" optional="false">
    A forest ID.
  </apidoc:param>
      <apidoc:param name="pathname" type="xs:string" optional="false">
    A forest backup pathname.
  </apidoc:param>
    </apidoc:params>
    <apidoc:privilege>
  <p xmlns="http://www.w3.org/1999/xhtml"><code>http://marklogic.com/xdmp/privileges/xdmp-forest-restore</code></p>
</apidoc:privilege>
    <apidoc:usage>
  <p xmlns="http://www.w3.org/1999/xhtml">Reindexing will stop while a backup or restore is in progress.</p>
</apidoc:usage>
    <apidoc:return>empty-sequence()</apidoc:return>
    <apidoc:example><pre xml:space="preserve" xmlns="http://www.w3.org/1999/xhtml">
  xdmp:forest-restore(11183608861595735720,"/backups/Data/Forests/Documents")
</pre></apidoc:example>
  </apidoc:function><apidoc:function name="forest-clear" type="builtin" lib="xdmp" category="AdminBuiltins" hidden="false" bucket="MarkLogic Built-In Functions">
    <apidoc:summary>
  Clears forest data files.
</apidoc:summary>
    <apidoc:params>
      <apidoc:param name="forestIDs" type="unsignedLong*" optional="false">
    The IDs of the forests to clear. If a forest has replica forests, the
    replicas are cleared as well.
  </apidoc:param>
    </apidoc:params>
    <apidoc:privilege>
  <p xmlns="http://www.w3.org/1999/xhtml"><code>http://marklogic.com/xdmp/privileges/xdmp-forest-clear</code></p>
</apidoc:privilege>
    <apidoc:return>empty-sequence()</apidoc:return>
    <apidoc:example><pre xml:space="preserve" xmlns="http://www.w3.org/1999/xhtml">
  xdmp:forest-clear(11183608861595735720)
</pre></apidoc:example>
  </apidoc:function><apidoc:function name="forest-restart" type="builtin" lib="xdmp" category="AdminBuiltins" hidden="false" bucket="MarkLogic Built-In Functions">
    <apidoc:summary>
  Restarts a forest. If multiple forest IDs are specified, the restarts
  occur in parallel.
</apidoc:summary>
    <apidoc:params>
      <apidoc:param name="forestIDs" type="unsignedLong*" optional="false">
    A forest ID.
  </apidoc:param>
    </apidoc:params>
    <apidoc:privilege>
  <p xmlns="http://www.w3.org/1999/xhtml"><code>http://marklogic.com/xdmp/privileges/xdmp-forest-restart</code></p>
</apidoc:privilege>
    <apidoc:return>empty-sequence()</apidoc:return>
    <apidoc:example><pre xml:space="preserve" xmlns="http://www.w3.org/1999/xhtml">
  xdmp:forest-restart((11183608861595735720,29382837261839278))
</pre></apidoc:example>
  </apidoc:function><apidoc:function name="forest-rollback" type="builtin" lib="xdmp" category="AdminBuiltins" hidden="false" bucket="MarkLogic Built-In Functions">
    <apidoc:summary>
  Rolls forests back to a previous point in time, marking any fragment
  newer than the specified timestamp as deleted.  Also, any fragments that
  were created before the specified timestamp and deleted after will be
  rolled back (un-deleted).
</apidoc:summary>
    <apidoc:params>
      <apidoc:param name="forestIDs" type="unsignedLong*" optional="false">
    A sequence of forest IDs. 
  </apidoc:param>
      <apidoc:param name="timestamp" type="unsignedLong" optional="false">
    The system timestamp to which you want to roll back.
  </apidoc:param>
    </apidoc:params>
    <apidoc:privilege>
  <p xmlns="http://www.w3.org/1999/xhtml"><code>http://marklogic.com/xdmp/privileges/xdmp-forest-rollback</code></p>
</apidoc:privilege>
    <apidoc:return>empty-sequence()</apidoc:return>
    <apidoc:usage>
<p xmlns="http://www.w3.org/1999/xhtml">If the timestamp specified is greater than the current system timestamp 
(that is, greater than the value of <code>xdmp:request-timestamp()</code>), 
then an exception is thrown.</p>
<p xmlns="http://www.w3.org/1999/xhtml">If the specified timestamp is less than (earlier) then the the oldest 
timestamp in the specified forest(s), then an exception is thrown.</p>
<p xmlns="http://www.w3.org/1999/xhtml">You should not have any updates occurring on a forest while it is being
rolled back; the best practice is for the forest to be quiesced during
a rollback operation.</p>
<p xmlns="http://www.w3.org/1999/xhtml">If you have failover replication configured for a forest, the replica
forest(s) will be rolled back at the same time as the specified forest(s).</p>
<p xmlns="http://www.w3.org/1999/xhtml">If MarkLogic Server restarts during a rollback operation, the rollback will
complete when the forest comes back online.</p>
<p xmlns="http://www.w3.org/1999/xhtml">You can only roll back a forest that is in the "Open" state.</p>
<p xmlns="http://www.w3.org/1999/xhtml">The <code>updates-allowed</code> setting must be set to 
 <code>all</code> in order to successfully roll a forest back 
to a previous timestamp.</p>
<p xmlns="http://www.w3.org/1999/xhtml">As part of the <code>xdmp:forest-rollback</code> operation, the 
specified forest(s) are restarted.</p>
<p xmlns="http://www.w3.org/1999/xhtml">As a consequence of the forest(s) restarting, if 
the forest is a failover forest and it is failed over to another host, 
the system will attempt to mount the forest on the original host 
(that is, it will un-failover the forest).</p>
<p xmlns="http://www.w3.org/1999/xhtml">If you perform an <code>xdmp:forest-rollback</code> operation on a
forest attached to the context database or any of its auxilliary databases (the security, modules, or triggers databases for that database), then the
rollback is performed asyncronously in the background, and any exceptions 
that occur will not be reported back to the program; in this case, if an
exception occurs it might be reported to the <code>ErrorLog.txt</code> file.  
Additionally, because the rollback of forests in the context database (or in
its auxilliary databases) is run asyncronously, there might be a small delay 
between when the rollback is issued and when the forest is restarted, and
the rollback state is not reflected until the forest restart is completed.
Therefore, it is best practice to call <code>xdmp:forest-rollback</code> 
against forests not attached to the context database.  </p>
<p xmlns="http://www.w3.org/1999/xhtml">After an <code>xdmp:forest-clear</code> operation on a forest, you will 
no longer be able to roll that forest back (because the forest clear deletes
all of the stands in the forest).</p>
<p xmlns="http://www.w3.org/1999/xhtml">The forest rollback operation cannot be undone (except by restoring from 
backup); that is, after rolling a forest back to a point in time, you cannot 
roll the forest "forward" to where you started.  </p>
</apidoc:usage>
    <apidoc:example><pre xml:space="preserve" xmlns="http://www.w3.org/1999/xhtml">
  xdmp:forest-rollback(11183608861595735720, 12345623)
</pre></apidoc:example>
    <apidoc:example><pre xml:space="preserve" xmlns="http://www.w3.org/1999/xhtml">
   (: 
   Run this against a different database context then
   the my-db database.
   :)
  xdmp:forest-rollback(
     xdmp:database-forests(xdmp:database("my-db")), 12345623)
</pre></apidoc:example>
  </apidoc:function><apidoc:function name="database-backup-validate" type="builtin" lib="xdmp" category="AdminBuiltins" hidden="false" bucket="MarkLogic Built-In Functions">
    <apidoc:summary>
  Validates that the specified list of forests can be backed up to the
  backup data directory.  Returns a database backup set node.
</apidoc:summary>
    <apidoc:params>
      <apidoc:param name="forestIDs" type="unsignedLong*" optional="false">
    A sequence of forest IDs.
  </apidoc:param>
      <apidoc:param name="pathname" type="xs:string" optional="false">
    A backup data directory pathname.
  </apidoc:param>
      <apidoc:param name="include-replicas" type="xs:boolean?" optional="true">
    Whether or not to include replica forests
  </apidoc:param>
    </apidoc:params>
    <apidoc:privilege>
  <p xmlns="http://www.w3.org/1999/xhtml"><code>http://marklogic.com/xdmp/privileges/xdmp-database-backup-validate</code></p>
</apidoc:privilege>
    <apidoc:return>element()</apidoc:return>
    <apidoc:example><pre xml:space="preserve" xmlns="http://www.w3.org/1999/xhtml">
  xdmp:database-backup-validate((11183608861595735720,898513504988507762), 
    "/backups/Data", fn:false())
  =&gt; 
&lt;bp:backup-plan 
   xsi:schemaLocation="http://marklogic.com/xdmp/backup-plan backup-plan.xsd"
   xmlns:bp="http://marklogic.com/xdmp/backup-plan" 
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance";&gt;
  &lt;bp:forest&gt;
    &lt;bp:forest-name&gt;Documents&lt;/bp:forest-name&gt;
    &lt;bp:forest-id&gt;9157142760003704384&lt;/bp:forest-id&gt;
    &lt;bp:forest-status&gt;okay&lt;/bp:forest-status&gt;
    &lt;bp:directory-path&gt;/tmp&lt;/bp:directory-path&gt;
    &lt;bp:directory-status&gt;okay&lt;/bp:directory-status&gt;
    &lt;bp:action&gt;backup&lt;/bp:action&gt;
  &lt;/bp:forest&gt;

  &lt;bp:forest&gt;
    &lt;bp:forest-name&gt;Security&lt;/bp:forest-name&gt;
    &lt;bp:forest-id&gt;5999952135320153149&lt;/bp:forest-id&gt;
    &lt;bp:forest-status&gt;okay&lt;/bp:forest-status&gt;
    &lt;bp:directory-path&gt;/tmp&lt;/bp:directory-path&gt;
    &lt;bp:directory-status&gt;okay&lt;/bp:directory-status&gt;
    &lt;bp:action&gt;backup&lt;/bp:action&gt;
  &lt;/bp:forest&gt;

  &lt;bp:forest&gt;
    &lt;bp:forest-name&gt;Schemas&lt;/bp:forest-name&gt;
    &lt;bp:forest-id&gt;10012970808570479716&lt;/bp:forest-id&gt;
    &lt;bp:forest-status&gt;okay&lt;/bp:forest-status&gt;
    &lt;bp:directory-path&gt;/tmp&lt;/bp:directory-path&gt;
    &lt;bp:directory-status&gt;okay&lt;/bp:directory-status&gt;
    &lt;bp:action&gt;backup&lt;/bp:action&gt;
  &lt;/bp:forest&gt;

  &lt;bp:forest&gt;
    &lt;bp:forest-name&gt;Triggers&lt;/bp:forest-name&gt;
    &lt;bp:forest-id&gt;17114437544213719134&lt;/bp:forest-id&gt;
    &lt;bp:forest-status&gt;okay&lt;/bp:forest-status&gt;
    &lt;bp:directory-path&gt;/tmp&lt;/bp:directory-path&gt;
    &lt;bp:directory-status&gt;okay&lt;/bp:directory-status&gt;
    &lt;bp:action&gt;backup&lt;/bp:action&gt;
  &lt;/bp:forest&gt;
&lt;/bp:backup-plan&gt;</pre>
</apidoc:example>
  </apidoc:function><apidoc:function name="database-backup" type="builtin" lib="xdmp" category="AdminBuiltins" hidden="false" bucket="MarkLogic Built-In Functions">
    <apidoc:summary>
  Starts an asynchronous backup of the specified list of forests to the
  backup data directory.  Returns a job ID that uniquely identifies the
  backup task.
</apidoc:summary>
    <apidoc:params>
      <apidoc:param name="forestIDs" type="unsignedLong*" optional="false">
    A sequence of forest IDs.
  </apidoc:param>
      <apidoc:param name="pathname" type="xs:string" optional="false">
    A backup data directory pathname.  The directory must exist and be
    writable by the operating system user under which MarkLogic Server 
    is running.  The directory cannot be the MarkLogic Server install 
    directory or the MarkLogic Server data directory. 
  </apidoc:param>
    </apidoc:params>
    <apidoc:privilege>
  <p xmlns="http://www.w3.org/1999/xhtml"><code>http://marklogic.com/xdmp/privileges/xdmp-database-backup</code></p>
</apidoc:privilege>
    <apidoc:usage>
  <p xmlns="http://www.w3.org/1999/xhtml">You cannot restore to a read-only forest.</p> 
  <p xmlns="http://www.w3.org/1999/xhtml">Reindexing will stop while a backup or restore is in progress.</p>
  <p xmlns="http://www.w3.org/1999/xhtml">The backup directory must exist on each host that has a forest 
  specified in the database backup call (that is, the d-nodes in which the 
  forests being backed up are hosted). </p>
</apidoc:usage>
    <apidoc:return>xs:unsignedLong</apidoc:return>
    <apidoc:example><pre xml:space="preserve" xmlns="http://www.w3.org/1999/xhtml">
  xdmp:database-backup((11183608861595735720,898513504988507762), 
    "/backups/Data")
  =&gt; 33030877979801813489</pre>
</apidoc:example>
    <apidoc:example><pre xml:space="preserve" xmlns="http://www.w3.org/1999/xhtml">
  xdmp:database-backup(xdmp:database-forests(xdmp:database("Documents")),
    "/backups/Data")
  =&gt; 437302857479804813287</pre>
</apidoc:example>
  </apidoc:function><apidoc:function name="database-backup-status" type="builtin" lib="xdmp" category="AdminBuiltins" hidden="false" bucket="MarkLogic Built-In Functions">
    <apidoc:summary>
  Checks the status of the outstanding backup job with the specified
  job ID.  Returns a database backup status node defined in the 
  <code xmlns="http://www.w3.org/1999/xhtml">job-status.xsd</code> schema.
</apidoc:summary>
    <apidoc:params>
      <apidoc:param name="jobid" type="unsignedLong" optional="false">
    A backup job ID.
  </apidoc:param>
      <apidoc:param name="hostid" type="unsignedLong" optional="true">
    The ID of the host that the backup was started on.
  </apidoc:param>
    </apidoc:params>
    <apidoc:privilege>
  <p xmlns="http://www.w3.org/1999/xhtml"><code>http://marklogic.com/xdmp/privileges/xdmp-database-backup-status</code></p>
</apidoc:privilege>
    <apidoc:return>element()</apidoc:return>
    <apidoc:usage schema="job-status.xsd" element-name="job-status"> </apidoc:usage>
    <apidoc:example><pre xml:space="preserve" xmlns="http://www.w3.org/1999/xhtml">
  xdmp:database-backup-status(33030877979801813489, 16529920850295602277)
  =&gt; 
&lt;job:job-status 
   xsi:schemaLocation="http://marklogic.com/xdmp/job-status job-status.xsd" 
   xmlns:job="http://marklogic.com/xdmp/job-status" 
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"&gt;
  &lt;job:forest&gt;
    &lt;job:forest-name&gt;Documents&lt;/job:forest-name&gt;
    &lt;job:forest-id&gt;9157142760003704384&lt;/job:forest-id&gt;
    &lt;job:status&gt;in-progress&lt;/job:status&gt;
  &lt;/job:forest&gt;
&lt;/job:job-status&gt;</pre>
</apidoc:example>
  </apidoc:function><apidoc:function name="database-backup-cancel" type="builtin" lib="xdmp" category="AdminBuiltins" hidden="false" bucket="MarkLogic Built-In Functions">
    <apidoc:summary>
  Cancels an outstanding backup job with the specified job ID, returning 
  true if the cancel operation is successful, false if the cancel operation
  is not successful.
</apidoc:summary>
    <apidoc:params>
      <apidoc:param name="jobid" type="unsignedLong" optional="false">
    A backup job ID.
  </apidoc:param>
    </apidoc:params>
    <apidoc:privilege>
  <p xmlns="http://www.w3.org/1999/xhtml"><code>http://marklogic.com/xdmp/privileges/xdmp-database-backup-cancel</code></p>
</apidoc:privilege>
    <apidoc:return>xs:boolean</apidoc:return>
    <apidoc:example><pre xml:space="preserve" xmlns="http://www.w3.org/1999/xhtml">
  xdmp:database-backup-cancel(33030877979801813489)
  =&gt; true
</pre></apidoc:example>
  </apidoc:function><apidoc:function name="database-restore-validate" type="builtin" lib="xdmp" category="AdminBuiltins" hidden="false" bucket="MarkLogic Built-In Functions">
    <apidoc:summary>
  Validates that the specified list of forests can be restored from the
  backup data directory.  Returns a database restore set node.
</apidoc:summary>
    <apidoc:params>
      <apidoc:param name="forestIDs" type="unsignedLong*" optional="false">
    A sequence of forest IDs.
  </apidoc:param>
      <apidoc:param name="pathname" type="xs:string" optional="false">
    A backup data directory pathname.
  </apidoc:param>
      <apidoc:param name="restoreToTime" type="xs:dateTime" optional="true">
    The date and time to restore the forest data to.
  </apidoc:param>
      <apidoc:param name="include-replicas" type="xs:boolean?" optional="true">
    Whether to include replica forests
  </apidoc:param>
    </apidoc:params>
    <apidoc:privilege>
  <p xmlns="http://www.w3.org/1999/xhtml"><code>http://marklogic.com/xdmp/privileges/xdmp-database-restore-validate</code></p>
</apidoc:privilege>
    <apidoc:return>element()</apidoc:return>
    <apidoc:example><pre xml:space="preserve" xmlns="http://www.w3.org/1999/xhtml">
  xdmp:database-restore-validate((11183608861595735720,898513504988507762), 
    "/backups/Data")
  =&gt; ..database restore set node</pre>
</apidoc:example>
  </apidoc:function><apidoc:function name="database-restore" type="builtin" lib="xdmp" category="AdminBuiltins" hidden="false" bucket="MarkLogic Built-In Functions">
    <apidoc:summary>
  Starts an asynchronous restore of the specified list of forests from the
  backup data directory.  Returns a job ID that uniquely identifies the
  restore task.
</apidoc:summary>
    <apidoc:params>
      <apidoc:param name="forestIDs" type="unsignedLong*" optional="false">
    A sequence of forest IDs.
  </apidoc:param>
      <apidoc:param name="pathname" type="xs:string" optional="false">
    A backup data directory pathname.
  </apidoc:param>
      <apidoc:param name="restoreToTime" type="xs:dateTime?" optional="true">
    The date and time to restore the forest data to.
  </apidoc:param>
    </apidoc:params>
    <apidoc:privilege>
  <p xmlns="http://www.w3.org/1999/xhtml"><code>http://marklogic.com/xdmp/privileges/xdmp-database-restore</code></p>
</apidoc:privilege>
    <apidoc:usage>
  <p xmlns="http://www.w3.org/1999/xhtml">Reindexing will stop while a backup or restore is in progress.</p>
</apidoc:usage>
    <apidoc:return>xs:unsignedLong</apidoc:return>
    <apidoc:example><pre xml:space="preserve" xmlns="http://www.w3.org/1999/xhtml">
  xdmp:database-restore((11183608861595735720,898513504988507762),
    "/backups/Data")
  =&gt; 33030877979801813489</pre>
</apidoc:example>
  </apidoc:function><apidoc:function name="database-restore-status" type="builtin" lib="xdmp" category="AdminBuiltins" hidden="false" bucket="MarkLogic Built-In Functions">
    <apidoc:summary>
  Checks the status of the outstanding restore job with the specified
  job ID.  Returns a database restore status node.
</apidoc:summary>
    <apidoc:params>
      <apidoc:param name="jobid" type="unsignedLong" optional="false">
    A restore job ID.
  </apidoc:param>
    </apidoc:params>
    <apidoc:privilege>
  <p xmlns="http://www.w3.org/1999/xhtml"><code>http://marklogic.com/xdmp/privileges/xdmp-database-restore-status</code></p>
</apidoc:privilege>
    <apidoc:return>element()</apidoc:return>
    <apidoc:example><pre xml:space="preserve" xmlns="http://www.w3.org/1999/xhtml">
xdmp:database-restore-status(33030877979801813489)
=&gt;
&lt;job:job-status xsi:schemaLocation="http://marklogic.com/xdmp/job-status 
   job-status.xsd" xmlns:job="http://marklogic.com/xdmp/job-status" 
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"&gt;
  &lt;job:forest&gt;
    &lt;job:forest-name&gt;docapp&lt;/job:forest-name&gt;
    &lt;job:forest-id&gt;7521617173471751251&lt;/job:forest-id&gt;
    &lt;job:status&gt;in-progress&lt;/job:status&gt;
  &lt;/job:forest&gt;
&lt;/job:job-status&gt;
</pre>
</apidoc:example>
  </apidoc:function><apidoc:function name="database-restore-cancel" type="builtin" lib="xdmp" category="AdminBuiltins" hidden="false" bucket="MarkLogic Built-In Functions">
    <apidoc:summary>
  Cancels an outstanding restore job with the specified job ID, returning 
  true if the cancel operation is successful, false if the cancel operation
  is not successful.
</apidoc:summary>
    <apidoc:params>
      <apidoc:param name="jobid" type="unsignedLong" optional="false">
    A restore job ID.
  </apidoc:param>
    </apidoc:params>
    <apidoc:privilege>
  <p xmlns="http://www.w3.org/1999/xhtml"><code>http://marklogic.com/xdmp/privileges/xdmp-database-restore-cancel</code></p>
</apidoc:privilege>
    <apidoc:return>xs:boolean</apidoc:return>
    <apidoc:example><pre xml:space="preserve" xmlns="http://www.w3.org/1999/xhtml">
  xdmp:database-restore-cancel(33030877979801813489)
  =&gt; true
</pre></apidoc:example>
  </apidoc:function><apidoc:function name="shutdown" type="builtin" lib="xdmp" category="AdminBuiltins" hidden="false" bucket="MarkLogic Built-In Functions">
    <apidoc:summary>
  Shutdown servers on hosts.
</apidoc:summary>
    <apidoc:params>
      <apidoc:param name="hostIDs" type="unsignedLong*" optional="false">
    A sequence of host IDs, or empty sequence for the local host.
  </apidoc:param>
      <apidoc:param name="reason" type="xs:string" optional="false">
    Prepositional phrase describing the reason to shutdown.
  </apidoc:param>
    </apidoc:params>
    <apidoc:privilege>
  <p xmlns="http://www.w3.org/1999/xhtml"><code>http://marklogic.com/xdmp/privileges/xdmp-shutdown</code></p>
</apidoc:privilege>
    <apidoc:return>empty-sequence()</apidoc:return>
    <apidoc:example><pre xml:space="preserve" xmlns="http://www.w3.org/1999/xhtml">
  xdmp:shutdown((), "for software upgrade")
</pre></apidoc:example>
  </apidoc:function><apidoc:function name="restart" type="builtin" lib="xdmp" category="AdminBuiltins" hidden="false" bucket="MarkLogic Built-In Functions">
    <apidoc:summary>
  Restart servers on hosts.
</apidoc:summary>
    <apidoc:params>
      <apidoc:param name="hostIDs" type="unsignedLong*" optional="false">
    A sequence of host IDs, or empty sequence for the local host.
  </apidoc:param>
      <apidoc:param name="reason" type="xs:string" optional="false">
    Prepositional phrase describing the reason to restart.
  </apidoc:param>
    </apidoc:params>
    <apidoc:privilege>
  <p xmlns="http://www.w3.org/1999/xhtml"><code>http://marklogic.com/xdmp/privileges/xdmp-restart</code></p>
</apidoc:privilege>
    <apidoc:return>empty-sequence()</apidoc:return>
    <apidoc:example><pre xml:space="preserve" xmlns="http://www.w3.org/1999/xhtml">
  xdmp:restart((), "to reload server.xml")
</pre></apidoc:example>
  </apidoc:function><apidoc:function name="filesystem-directory" type="builtin" lib="xdmp" category="AdminBuiltins" hidden="false" bucket="MarkLogic Built-In Functions">
    <apidoc:summary>
  Performs a directory listing of the given file pathname.
</apidoc:summary>
    <apidoc:params>
      <apidoc:param name="pathname" type="xs:string" optional="false">
    Pathname of the directory to be listed.
  </apidoc:param>
    </apidoc:params>
    <apidoc:privilege>
  <p xmlns="http://www.w3.org/1999/xhtml"><code>http://marklogic.com/xdmp/privileges/xdmp-filesystem-directory</code></p>
</apidoc:privilege>
    <apidoc:return>element(dir:directory)</apidoc:return>
    <apidoc:usage>
  <p xmlns="http://www.w3.org/1999/xhtml">The user under which MarkLogic Server is running must have permissions
  to read the specified directory.  For example, on Windows systems, 
  MarkLogic Server typically runs as the SYSTEM user, and therefore the 
  SYSTEM user must have permissions to read the directory (even a
  mapped network drive directory).  Similarly, on UNIX systems, 
  MarkLogic Server typically runs as the daemon user, and that user
  needs to have read permission to the specified directory.  If the user
  in which MarkLogic Server runs does not have the needed permissions, then 
  a an error such as SVC-DIROPEN or SVC-FILOPEN is thrown when you 
  attempt to call <code>xdmp:filesystem-directory</code>.</p>
</apidoc:usage>
    <apidoc:example><pre xml:space="preserve" xmlns="http://www.w3.org/1999/xhtml">
  xdmp:filesystem-directory("/etc")
  =&gt; ..directory listing node
</pre></apidoc:example>
  </apidoc:function><apidoc:function name="filesystem-file" type="builtin" lib="xdmp" category="AdminBuiltins" hidden="false" bucket="MarkLogic Built-In Functions">
    <apidoc:summary>
  Reads a file from the filesystem.  The file at the specified path 
  must be UTF-8 encoded.
</apidoc:summary>
    <apidoc:params>
      <apidoc:param name="pathname" type="xs:string" optional="false">
    Pathname of the file to be read.
  </apidoc:param>
    </apidoc:params>
    <apidoc:privilege>
  <p xmlns="http://www.w3.org/1999/xhtml"><code>http://marklogic.com/xdmp/privileges/xdmp-filesystem-file</code></p>
</apidoc:privilege>
    <apidoc:return>xs:string</apidoc:return>
    <apidoc:example><pre xml:space="preserve" xmlns="http://www.w3.org/1999/xhtml">
  xdmp:filesystem-file("/etc/motd")
  =&gt; contents of /etc/motd
</pre></apidoc:example>
  </apidoc:function><apidoc:function name="castable-as" type="builtin" lib="xdmp" category="Extension" subcategory="Extension" hidden="false" bucket="MarkLogic Built-In Functions">
    <apidoc:summary>
  Returns true if a value is castable.
  This is similar to the "castable as" XQuery predicate, except that the 
  type is determined at runtime.
</apidoc:summary>
    <apidoc:params>
      <apidoc:param name="namespace-uri" type="xs:string" optional="false">
    The namespace URI of the type.
  </apidoc:param>
      <apidoc:param name="local-name" type="xs:string" optional="false">
    The local-name of the type.
  </apidoc:param>
      <apidoc:param name="item" type="item()" optional="false">
    The item to be cast.
  </apidoc:param>
    </apidoc:params>
    <apidoc:return>xs:boolean</apidoc:return>
    <apidoc:example><pre xml:space="preserve" xmlns="http://www.w3.org/1999/xhtml">
  xdmp:castable-as(
    "http://www.w3.org/2001/XMLSchema",
    "integer",
    "12")
    =&gt; true()</pre>
</apidoc:example>
  </apidoc:function><apidoc:function name="merge-cancel" type="builtin" lib="xdmp" category="AdminBuiltins" hidden="false" bucket="MarkLogic Built-In Functions">
    <apidoc:summary>
  Cancel the merge with the specified merge ID on a forest with the 
  specified forest ID.
</apidoc:summary>
    <apidoc:params>
      <apidoc:param name="forest-ID" type="xs:unsignedLong" optional="false">
    A forest ID.
  </apidoc:param>
      <apidoc:param name="merge-ID" type="xs:unsignedLong" optional="false">
    A merge ID, which is available from the output of 
    <code xmlns="http://www.w3.org/1999/xhtml">xdmp:forest-status</code>.
  </apidoc:param>
    </apidoc:params>
    <apidoc:privilege>
  <p xmlns="http://www.w3.org/1999/xhtml"><code>http://marklogic.com/xdmp/privileges/request-my-requests</code>
  or
  <code>http://marklogic.com/xdmp/privileges/request-any-requests</code></p>
</apidoc:privilege>
    <apidoc:usage>
  To cancel a merge on a database, find all of the forests in the database
  and use <code xmlns="http://www.w3.org/1999/xhtml">xdmp:merge-cancel</code> on each forest.
</apidoc:usage>
    <apidoc:return>empty-sequence()</apidoc:return>
    <apidoc:example><pre xml:space="preserve" xmlns="http://www.w3.org/1999/xhtml">
  xdmp:merge-cancel(98394839084390843,3838938902783)
   =&gt; ()
</pre></apidoc:example>
  </apidoc:function><apidoc:function name="request-cancel" type="builtin" lib="xdmp" category="Server Monitoring" hidden="false" bucket="MarkLogic Built-In Functions">
    <apidoc:summary>
  Cancel the request with the given host, server, and request IDs.
</apidoc:summary>
    <apidoc:params>
      <apidoc:param name="hostID" type="xs:unsignedLong" optional="false">
    The ID of the host on which the request is running.  Typically, you
    get the ID of a host by executing code similar to: 
    <blockquote xmlns="http://www.w3.org/1999/xhtml">
    <code><pre xml:space="preserve">
    xdmp:host("myhost")</pre></code></blockquote>
  </apidoc:param>
      <apidoc:param name="serverID" type="xs:unsignedLong" optional="false">
   The ID of the App Server in which the request is running.   Typically, you
    get the ID of an App Server by executing code similar to: 
    <blockquote xmlns="http://www.w3.org/1999/xhtml">
    <code><pre xml:space="preserve">
    xdmp:server("myAppServerName")</pre></code></blockquote>
  </apidoc:param>
      <apidoc:param name="requestID" type="xs:unsignedLong" optional="false">
    The ID of the request.  You can access the request IDs in the 
    <code xmlns="http://www.w3.org/1999/xhtml">request</code> elements of the <code xmlns="http://www.w3.org/1999/xhtml">xdmp:server-status</code> 
    output. You get the request ID by executing code similar to:
    <blockquote xmlns="http://www.w3.org/1999/xhtml">
    <code><pre xml:space="preserve">
    declare namespace status=
        "http://marklogic.com/xdmp/status/server"
    
    xdmp:server-status( xdmp:host("myhost"), 
      xdmp:server("myAppServerName") )//status:request</pre></code></blockquote>
  </apidoc:param>
    </apidoc:params>
    <apidoc:privilege>
  <p xmlns="http://www.w3.org/1999/xhtml"><code>http://marklogic.com/xdmp/privileges/xdmp-request-cancel</code>
  and 
  <code>http://marklogic.com/xdmp/privileges/cancel-any-request</code>
  or 
  <code>http://marklogic.com/xdmp/privileges/cancel-my-requests</code></p>
</apidoc:privilege>
    <apidoc:return>empty-sequence()</apidoc:return>
    <apidoc:usage>
  <p xmlns="http://www.w3.org/1999/xhtml">To find out the status of the request after it has been canceled,
  you can call <code>xdmp:server-status</code>, which has information
  about each request active or being canceled on the server.  Once a request
  has completed canceling, it will no longer appear in the output of
  <code>xdmp:server-status</code>.</p>
</apidoc:usage>
    <apidoc:example><pre xml:space="preserve" xmlns="http://www.w3.org/1999/xhtml">
  xdmp:request-cancel(xdmp:host("myhost"), 
                      xdmp:server("myAppServerName"),
		      98394839084390843)
   =&gt; ()
</pre></apidoc:example>
  </apidoc:function><apidoc:function name="database-backup-purge" type="builtin" lib="xdmp" category="AdminBuiltins" hidden="false" bucket="MarkLogic Built-In Functions">
    <apidoc:summary>
  Purge old backups from a directory.
</apidoc:summary>
    <apidoc:params>
      <apidoc:param name="dir" type="xs:string" optional="false">
    The directory under which to look for backups.
  </apidoc:param>
      <apidoc:param name="keep-num-backups" type="xs:unsignedInt" optional="false">
    The maximum number of old backups to keep.
  </apidoc:param>
    </apidoc:params>
    <apidoc:privilege>
  <p xmlns="http://www.w3.org/1999/xhtml"><code>http://marklogic.com/xdmp/privileges/xdmp-database-backup-purge</code></p>
</apidoc:privilege>
    <apidoc:return>empty-sequence()</apidoc:return>
  </apidoc:function></apidoc:module>