<?xml version="1.0" encoding="UTF-8"?><api:function-page xml:base="/apidoc/8.0/xdmp.eval.xml" generated="2015-10-07T16:36:00.016766-07:00" mode="javascript" xmlns:api="http://marklogic.com/rundmc/api"><api:function-name>xdmp.eval</api:function-name><api:suggest>xdmp.eval</api:suggest><api:suggest>xdmp</api:suggest><api:suggest>eval</api:suggest><api:function-link mode="xquery" fullname="xdmp:eval">/apidoc/8.0/xdmp:eval.xml</api:function-link><api:function mode="javascript" name="eval" type="builtin" lib="xdmp" category="Extension" subcategory="XQuery Context" hidden="false" bucket="MarkLogic Built-In Functions" prefix="xdmp" namespace="http://marklogic.com/xdmp" fullname="xdmp.eval"><api:summary class="javascript">
  Returns the result of evaluating a string as a Javascript program.
</api:summary><api:params><api:param name="javascript" type="xs:string" class="javascript"><api:param-description>
    The Javascript string to be evaluated.  If the Javascript string contains
    double quotes ("), surround the string with single quotes (').
  </api:param-description><api:param-name>javascript</api:param-name><api:param-type>String</api:param-type></api:param><api:param name="vars" type="Object" optional="true" class="javascript"><api:param-description>
    The external variable values for this evaluation.
    This can either be a sequence of map:map objects, or a sequence of even
    length, alternating QNames and items.
    <p xmlns="http://www.w3.org/1999/xhtml">Each key in the map(s) is a string representing the name of the parameter
    in Clark notation: "{namespaceURI}localname". The function
    <a href="./xdmp.keyFromQName">xdmp.keyFromQName</a>
    is a convenient way to generate these keys.
    Each entry in the map is the value of the corresponding external 
    variable.</p>
    <p xmlns="http://www.w3.org/1999/xhtml">Alternatively, the alternating sequence should contain QName and item
    pairs that specify a variable name and value for an external variable.</p>
  </api:param-description><api:param-name>vars</api:param-name><api:param-type>Object</api:param-type></api:param><api:param name="options" type="(element()|map:map)?" optional="true"><api:param-description>
    
    <span class="javascript" xmlns="http://www.w3.org/1999/xhtml">The options object. The default value is null.
    The following is a sample options object:
    <pre xml:space="preserve">
    {
      "isolation" : "different-transaction",
      "preventDeadlocks" : true
    } </pre></span>
    
    <p class="javascript" xmlns="http://www.w3.org/1999/xhtml">The <code>xdmp.eval</code> options include:</p>
    <blockquote xmlns="http://www.w3.org/1999/xhtml"><dl>
    
    <dt class="javascript"><p>database</p></dt>
    <dd>The database ID,
    from <code class="xqury">xdmp:database("db_name")</code>
    <code class="javascript">xdmp.database("db_name")</code>,
    
    <code class="javascript">xdmp.securityDatabase()</code>,
    or 
    <code class="javascript">xdmp.schemaDatabase()</code>.
    To specify a database other than the context database, the
    <code>http://marklogic.com/xdmp/privileges/xdmp-eval-in</code> privilege
    is required.</dd>
    
    <dt class="javascript"><p>modules</p></dt>
    <dd>The modules database ID for processing module imports.
        Specifying no <code>module</code> option specifies the current modules database.
        Specifying <code>0</code> specifies using the file system to process
	      module imports. You must have the
        <code>http://marklogic.com/xdmp/privileges/xdmp-eval-modules-change</code>
        (for <code class="javascript">xdmp.eval</code>),
        <code>http://marklogic.com/xdmp/privileges/xdmp-invoke-modules-change</code>
        (for ),
        or the
        <code>http://marklogic.com/xdmp/privileges/xdmp-spawn-modules-change</code>
        (for <code class="javascript">xdmp.spawn</code>)
        privilege to change either the modules database to another database
        or to change the root to another path.  You must have the
        <code>http://marklogic.com/xdmp/privileges/xdmp-eval-modules-change-file</code>
        (for <code class="javascript">xdmp.eval</code>),
        <code>http://marklogic.com/xdmp/privileges/xdmp-invoke-modules-change-file</code>
        (for <code class="javascript">xdmp.invoke</code>),
        or the
        <code>http://marklogic.com/xdmp/privileges/xdmp-eval-modules-change-file</code>
        (for <code class="javascript">xdmp.spawn</code>)
        privilege to change the modules database to the file
	      system or to change a root on the filesystem.</dd>
    
    <dt class="javascript"><p>root</p></dt>
    <dd>The root path for modules.  
        Specifying no <code>root</code> option specifies the current root.
        You need the same privilege to modify the root as you need to change
        the <code>module</code> option.</dd>
    
    <dt class="javascript"><p>timestamp</p></dt>
    <dd>The system timestamp to use for this evaluation.  Specifying
        no <code>timestamp</code> options specifies the most recent timestamp.
        You may only specify a timestamp for a query statement, not for an
	      update statement.  The timestamp is a number that is incremented by
	      1 each time any configuration or content change is made to the system.
       	Specifying a timestamp of 0 uses the current system timestamp (the
	      value returned by 
	      <code class="javascript">xdmp.requestTimestamp()</code>). Specifying
	      a timestamp requires the
	      <code>http://marklogic.com/xdmp/privileges/xdmp-timestamp</code> execute
	      privilege.</dd>
    
    <dt class="javascript"><p>ignoreAmps</p></dt>
    <dd>(Only valid with
    <code class="javascript">xdmp.eval</code>,
    <code class="javascript">xdmp.invoke</code>,
    <code class="javascript">xdmp.xsltEval</code>,
    <code class="javascritp">xdmp.xsltInvoke</code>;
    does not apply to
    <code class="javascript">xdmp.spawn</code>,
    <code class="javascript">dbg.eval</code> or
    <code class="javascript">dbg.invoke</code>).
    Either <code>true</code> or <code>false</code>. When set to <code>true</code>,
    the statement is evaluated without using any Amps from the caller.
    The default value for this option is <code>false</code>.</dd>
    
    <dt class="javascript"><p>isolation</p></dt>
    <dd>(Only valid with
    <code class="javascript">xdmp.eval</code>
    or <code class="javascript">xdmp.invoke</code>;
    does not apply to
    <code class="javascript">xdmp.spawn</code>.)
    Either <code>same-statement</code> or <code>different-transaction</code>. When set to
    <code>same-statement</code>, the statement is evaluated in the same
    transaction as the one from which it is called, and subsequent
    expressions in the calling statement will not see any updates performed
    in the eval/invoke/spawn. You can only use <code>same-statement</code>
    isolation with update statements; query statements with
    <code>same-statement</code> isolation will throw an exception.  When set to
    <code>different-transaction</code>, the statement is evaluated in
    a separate transaction from the one in which it is called, making those
    updates available to  subsequent expressions in the calling statement
    (assuming the calling statement is an update statement; if the calling
    statement is not an update, then subsequent expressions will see the
    version of the database at the system timestamp when the calling statement
    begins its evaluation).
    When using <code>different-transaction</code> in an update statement that
    calls another update statement, do not update the same document as
    the calling statement is updating; doing so can cause a deadlock.
    You cannot evaluate a statement in a different database with the
    <code>isolation</code> option set to <code>same-statement</code>.
    The default value for the <code>isolation</code> option
    is <code>different-transaction</code>. For more details, see the
    "Understanding Transactions in MarkLogic Server" chapter of the
    <a href="http://developer.marklogic.com/pubs">Developer's Guide</a>.
    </dd>
    
    <dt class="javascript"><p>staticCheck</p></dt>
    <dd>
    Specify <code>true</code> to only perform static checks on the module, and not to
    actually execute it. The default is <code>false</code>, which means the the code
    is fully evaluated.
    </dd>
    
    <dt class="javascript"><p>preventDeadlocks</p></dt>
    <dd>(Only valid with
    <code class="javascript">xdmp.eval</code> or
    <code class="javascript">xdmp.invoke</code>;
    does not apply to
    <code class="javascript">xdmp.spawn</code>.)
    Specify <code>true</code> for the server to disallow update requests
    from an update transaction.  Only has an effect when the
    <code>isolation</code> option is set to <code>different-transaction</code>
    as there is no possibility of a deadlock if the <code>isolation</code>
    option is set to <code>same-statement</code>.
    When set to <code>true</code> in an update request calling another
    update request, MarkLogic Server throws the
    <code>XDMP-PREVENTDEADLOCKS</code>
    exception.  Setting this option to <code>true</code> prevents
    the possibility of deadlocks occurring when running eval/invoke of
    an update transaction from another update transaction. The default value
    for the this option is <code>false</code>.
    </dd>
    
    <dt class="javascript"><p>defaultXqueryVersion</p></dt>
    <dd>The default XQuery language version to use for the query, if the query
    does not contain an explicit version declaration.  If this option is not
    provided, the defaults are:
      <ul><li>
        <code class="javascript">xdmp.eval</code>:
        The XQuery language version of the module that called eval.  This version may
        vary module-by-module if a query consists of modules written in multiple language
        versions. It may also vary from run to run if the app-server default is changed.
        </li><li>
        <code class="javascript">xdmp.invoke</code>:
        The default XQuery version for the app server that the invocation occurs on.
        Note that this may be different than the XQuery version of the module that calls
        <code class="javascript">xdmp.invoke</code>.
        </li><li>
        <code class="javascript">xdmp.spawn</code>:
        The XQuery version default set on the app server that called
        <code class="javascript">xdmp.spawn</code>.
        The Task Server has no default XQuery version, the version to use is passed
        as a part of the task request.
        </li></ul>
    Allowable values for this option are "0.9-ml", "1.0-ml", "1.0" and
    the special value "app-server".  The first three are XQuery language
    versions.  The last indicates that the default XQuery language
    version set on this app-server should be used.  This is useful if code
    written in an older XQuery version needs to call
    <code class="javascript">xdmp.eval</code>
    on strings that may have been passed as parameters, but should be
    interpreted in the app-server's default language version.  A module
    may discover its own XQuery language version with
    
    <code class="javascript">xdmp.xqueryVersion()</code>.
    </dd>
    
    <dt class="javascript"><p>timeLimit</p></dt>
    <dd>Override the default time limit with this time limit, in seconds,
    for this evaluation.  You can set the
    value up to the maximum-time-limit value for the App Server in which
    the request is evaluated or to a lower value than the default time
    limit.  This option only applies to
    <code class="javascript">xdmp.spawn</code>,
    not to
    <code class="javascript">xdmp.invoke</code> or
    <code class="javascript">xdmp.eval</code>.</dd>
    
    <dt class="javascript"><p>userId</p></dt>
    <dd>Specifies the user ID for the user to run the request being
    evaluated (the request specified in the <code>$xquery</code> parameter). 
    If this option is specified, then the
    request is run as the current user.  You need to have the
    <code class="javascript">xdmp.login</code>
    (<code>http://marklogic.com/xdmp/privileges/xdmp-login</code>)
    privilege to use this option.  Be aware that this
    is a very privileged operation, as it allows a user with this
    privilege to evaluate requests as any other user. For an example,
    see the <a href="#eval-ex4">fourth example</a> below.</dd>
    
    <dt class="javascript"><p>defaultCollation</p></dt>
    <dd>Specifies the collation to use for this context, unless a collation is
    explicitly specified in the XQuery prolog or in a function call that
    allows you to specify a collation.
    </dd>
    
    <dt class="javascript"><p>priority</p></dt>
    <dd>Specify the priority of the spawned task.
    Allowable values for this option are "normal" and "higher".
    This option only applies to
    <code class="javascript">xdmp.spawn</code>,
    not to
    <code class="javascript">xdmp.invoke</code>
    or
    <code class="javascript">xdmp.eval</code>.</dd>
    
    <dt class="javascript"><p>result</p></dt>
    <dd>Return a value future for the result of the spawned task.
    This value future can bound be to a variable without waiting so
    that work can proceed concurrently with the spawned task. 
    When the calling request uses the value future in any operation,
    it will automatically wait for the spawned task to complete and it will
    use the result.
    This option only applies to
    
    <a class="javascript" href="./xdmp.spawn"><code>xdmp.spawn</code></a>, not to
    <code class="javascript">xdmp.invoke</code>
    or <code class="javascript">xdmp.eval</code>.
    For an example, see
    <a href="./xdmp:spawn#spawnresultex">The second example.</a></dd>
    
    <dt class="javascript"><p>transactionMode</p></dt>
    <dd>Explicitly set the transaction mode for this context. 
    Valid values are <code>auto</code>, <code>query</code>, 
    <code>update-auto-commit</code>, and <code>update</code>.  
    The default is <code>auto</code>.
    <p>For simple updates to be implicitly committed, specify a transaction 
    mode of update-auto-commit.
    A transaction mode of update creates a new multi-statement update 
    transaction and requires an explicit commit in the code.</p>
    <p>Within a session there can be only one active multi-statement 
    transaction at a time.  
    If a new multi-statement transaction is specified nested inside a 
    multi-statement transaction, an <code>XDMP-NESTEDMULTI</code> error
    is returned.
    If a new multi-statement transaction is specified but another has 
    already been concurrently created in the same session by another request, 
    an <code>XDMP-SESSIONTXN</code> error is returned and the current request
    is retried.</p>
    <p>An <code>xdmp:transaction-mode</code> prolog option in evaluated 
    XQuery will override any transaction mode specified with this 
    option.</p></dd>
    </dl></blockquote>
  </api:param-description><api:param-name>options</api:param-name><api:param-type>Object?</api:param-type></api:param></api:params><api:return>ValueIterator</api:return><api:privilege>
<p xmlns="http://www.w3.org/1999/xhtml"><code>http://marklogic.com/xdmp/privileges/xdmp-eval</code></p>
<p xmlns="http://www.w3.org/1999/xhtml">You must have the
<code>http://marklogic.com/xdmp/privileges/xdmp-eval-in</code> privilege to
specify the <code>database</code> option with a database other than the context database.</p>
<p xmlns="http://www.w3.org/1999/xhtml">You must have the
  <code>http://marklogic.com/xdmp/privileges/xdmp-eval-modules-change</code>
  (for <code class="javascript">xdmp.eval</code>),
  <code>http://marklogic.com/xdmp/privileges/xdmp-invoke-modules-change</code>
  (for <code class="javascript">xdmp.invoke</code>), or the
  <code>http://marklogic.com/xdmp/privileges/xdmp-spawn-modules-change</code>
  (for <code class="javascript">xdmp.spawn</code>)
        privilege to change either the modules database to another database
       	or to change the root to another path.  You must have the
<code>http://marklogic.com/xdmp/privileges/xdmp-eval-modules-change-file</code>
  (for <code class="javascript">xdmp.eval</code>),
<code>http://marklogic.com/xdmp/privileges/xdmp-invoke-modules-change-file</code>
  (for <code class="javascript">xdmp.invoke</code>), or the
<code>http://marklogic.com/xdmp/privileges/xdmp-eval-modules-change-file</code>
  (for <code class="javascript">xdmp.spawn</code>)
        privilege to change the modules database to the file
	system or to change a root on the filesystem.</p>
	<p xmlns="http://www.w3.org/1999/xhtml">You must have the
	<code>http://marklogic.com/xdmp/privileges/xdmp-login</code>
	privilege to use the 
	<code class="javascript">userId</code> option. </p>
</api:privilege><api:example class="javascript"><pre xml:space="preserve" xmlns="http://www.w3.org/1999/xhtml">
xdmp.eval("1+1")
=&gt; 2
</pre>
</api:example><api:example class="javascript"><pre xml:space="preserve" xmlns="http://www.w3.org/1999/xhtml">
xdmp.eval("fn.doc('/docs/mydoc.xml')",  null,
  {
    "database" : xdmp.database("otherdb")
  })
=&gt; The '/docs/mydoc.xml' document from the
   otherdb database.
</pre>
</api:example><api:example class="javascript"><a id="eval-ex4" xmlns="http://www.w3.org/1999/xhtml"></a>
<pre xml:space="preserve" xmlns="http://www.w3.org/1999/xhtml">
xdmp.eval('xdmp.getCurrentUser()', null,
  {
    "userId" : xdmp.user("someuser")
  })
=&gt;
  returns "someuser", assuming "someuser" exists in the
  security database and the user running the eval request has the
  xdmp:login privilege.
</pre>
</api:example></api:function></api:function-page>