<apidoc:module name="AppServerBuiltins" category="AppServerBuiltins" lib="xdmp" xmlns:apidoc="http://marklogic.com/xdmp/apidoc"><apidoc:summary access="public">
  The application server built-in functions are XQuery functions for many 
  HTTP application server functions.  Many of the application server 
  functions (for example, <code xmlns="http://www.w3.org/1999/xhtml">xdmp:get-request-field</code>, 
  <code xmlns="http://www.w3.org/1999/xhtml">xdmp:login</code>, etc.) are 
  executable only on HTTP servers; those functions all have 
  no effect and return the empty sequence when run from an XDBC server. 
</apidoc:summary><apidoc:function name="url-encode" type="builtin" lib="xdmp" category="AppServerBuiltins" hidden="false" bucket="MarkLogic Built-In Functions">
    <apidoc:summary>
  Converts plaintext into URL-encoded string.
</apidoc:summary>
    <apidoc:params>
      <apidoc:param name="plaintext" type="xs:string" optional="false">
    Plaintext to be encoded.
  </apidoc:param>
      <apidoc:param name="noSpacePlus" type="xs:boolean?" optional="true">
    True to encode space as "%20" instead of "+".
  </apidoc:param>
    </apidoc:params>
    <apidoc:return>xs:string</apidoc:return>
    <apidoc:example><pre xml:space="preserve" xmlns="http://www.w3.org/1999/xhtml">
  xdmp:url-encode("Why not?")
  =&gt; "Why+not%3f"
</pre></apidoc:example>
  </apidoc:function><apidoc:function name="url-decode" type="builtin" lib="xdmp" category="AppServerBuiltins" hidden="false" bucket="MarkLogic Built-In Functions">
    <apidoc:summary>
  Converts URL-encoded string to plaintext.
</apidoc:summary>
    <apidoc:params>
      <apidoc:param name="encoded" type="xs:string" optional="false">
     Encoded text to be decoded.
  </apidoc:param>
    </apidoc:params>
    <apidoc:return>xs:string</apidoc:return>
    <apidoc:example><pre xml:space="preserve" xmlns="http://www.w3.org/1999/xhtml">
  xdmp:url-decode("Why+not%3f")
  =&gt; "Why not?"
</pre></apidoc:example>
  </apidoc:function><apidoc:function name="login" type="builtin" lib="xdmp" category="AppServerBuiltins" hidden="false" bucket="MarkLogic Built-In Functions">
    <apidoc:summary>
  <p xmlns="http://www.w3.org/1999/xhtml">Logs in a user on an application server that is using 
  application-level authentication and sends a session cookie containing
  the session ID to the user's browser.  
  Returns true on success, false on failure.</p>
  <p xmlns="http://www.w3.org/1999/xhtml">
  If the user calling this function has the <code>xdmp:login</code>
  privilege, this function can be called without a password or with the empty 
  sequence as the password.  In this case, login will succeed if 
  the specified user exists.  Therefore, use the <code>xdmp:login</code> 
  privilege carefully, as any user with that
  privilege will be able to execute code that uses the <code>xdmp:login</code>
  function to log in as any user.</p>
</apidoc:summary>
    <apidoc:params>
      <apidoc:param name="name" type="xs:string" optional="false">
    The username of the user to be logged in.
  </apidoc:param>
      <apidoc:param name="password" type="xs:string?" optional="true">
    The user's password.  The password is not needed if the user
    calling the function has the xdmp:login execute privilege.
  </apidoc:param>
      <apidoc:param name="set-session" type="xs:boolean?" optional="true">
    A boolean value specifying whether to set a session variable for the 
    login.  The default is true.  Set to false to not set the 
    session variable to maintain the user logged in.
  </apidoc:param>
    </apidoc:params>
    <apidoc:return>xs:boolean</apidoc:return>
    <apidoc:usage>
  <p xmlns="http://www.w3.org/1999/xhtml">
  The session exists in the E-node on which it was created; you cannot 
  access that session from a different E-node.
  </p>
  <p xmlns="http://www.w3.org/1999/xhtml">
  You can use the <code>xdmp:set-session-field</code> function to
  set a named value in the session and the <code>xdmp:get-session-field</code>
  function to return a value set in a session field.  
  The user session expires when the session reaches its timeout limit.  
  The session cookie remains on the browser until the browser exits or the 
  cookie is explicitly removed by the user.
  </p>
</apidoc:usage>
    <apidoc:example><pre xml:space="preserve" xmlns="http://www.w3.org/1999/xhtml">
  xdmp:login("mark","secret")
  =&gt; true() -- if user "mark" has password "secret"
</pre></apidoc:example>
    <apidoc:example><pre xml:space="preserve" xmlns="http://www.w3.org/1999/xhtml">
  xdmp:login("username") or xdmp:login("username", ()) 
  =&gt; true() -- if user calling the function has the 
               xdmp:login privilege
</pre></apidoc:example>
    <apidoc:example><pre xml:space="preserve" xmlns="http://www.w3.org/1999/xhtml">
  xdmp:login("username") or xdmp:login("username", ()) 
  =&gt; SEC-PRIV exception if the user calling the function does 
              not have the xdmp:login privilege
</pre></apidoc:example>
    <apidoc:example><pre xml:space="preserve" xmlns="http://www.w3.org/1999/xhtml">
  xdmp:login("username")
  =&gt; true() -- if current user has the xdmp:login privilege
</pre></apidoc:example>
    <apidoc:example><pre xml:space="preserve" xmlns="http://www.w3.org/1999/xhtml">
  xdmp:login("username")
  =&gt; SEC-PRIV exception if current user does not have the 
              xdmp:login privilege
</pre></apidoc:example>
  </apidoc:function><apidoc:function name="logout" type="builtin" lib="xdmp" category="AppServerBuiltins" hidden="false" bucket="MarkLogic Built-In Functions">
    <apidoc:summary>
  Logs the current user out of the session on the server.
  The result is that the current user is set to the default user defined in 
  application-level authentication.  The session remains on the server
  until it expires.
</apidoc:summary>
    <apidoc:params/>
    <apidoc:return>empty-sequence()</apidoc:return>
    <apidoc:example><pre xml:space="preserve" xmlns="http://www.w3.org/1999/xhtml">
  xdmp:logout()
  =&gt; ()
</pre></apidoc:example>
  </apidoc:function><apidoc:function name="get-request-field-names" type="builtin" lib="xdmp" category="AppServerBuiltins" hidden="false" bucket="MarkLogic Built-In Functions">
    <apidoc:summary>
  Returns a sequence of the request field names.
</apidoc:summary>
    <apidoc:params/>
    <apidoc:return>xs:string*</apidoc:return>
    <apidoc:example><pre xml:space="preserve" xmlns="http://www.w3.org/1999/xhtml">
  xdmp:get-request-field-names()
  =&gt; ("section", "name", ...)
</pre></apidoc:example>
  </apidoc:function><apidoc:function name="get-request-field" type="builtin" lib="xdmp" category="AppServerBuiltins" hidden="false" bucket="MarkLogic Built-In Functions">
    <apidoc:summary>
  Returns the value of a named request field.  If the request field
  is a <code xmlns="http://www.w3.org/1999/xhtml">multipart/form-data</code> type in a POST form, you can 
  use <code xmlns="http://www.w3.org/1999/xhtml">xdmp:get-request-field</code> for file upload applications
  (see the <a href="#grf2" xmlns="http://www.w3.org/1999/xhtml">second example</a> below).
</apidoc:summary>
    <apidoc:params>
      <apidoc:param name="name" type="xs:string" optional="false">
    Request field name.
  </apidoc:param>
      <apidoc:param name="default" type="xs:string?" optional="true">
    A default value to return if there is no request field.
  </apidoc:param>
    </apidoc:params>
    <apidoc:return>xs:string*</apidoc:return>
    <apidoc:example><pre xml:space="preserve" xmlns="http://www.w3.org/1999/xhtml">
  xdmp:get-request-field("index")
  =&gt; "10"
</pre></apidoc:example>
    <apidoc:example><pre xml:space="preserve" xmlns="http://www.w3.org/1999/xhtml"><a id="grf2"></a> 
Consider a form.xqy XQuery module with the following content:

  &lt;html xmlns="http://www.w3.org/1999/xhtml"&gt;
    &lt;body&gt;
    &lt;form name="test" action="upload.xqy?uid={xdmp:random()}" method="post"
          enctype="multipart/form-data"&gt;
    &lt;p&gt;&lt;label&gt;File to upload:
    &lt;input type="file" class="name" name="upload" size="50"/&gt;&lt;/label&gt;&lt;/p&gt;
    &lt;p&gt;&lt;input type="submit" value="Upload and Get Results"/&gt;&lt;/p&gt;
    &lt;/form&gt;
    &lt;/body&gt;
  &lt;/html&gt; 

Then have an upload.xqy XQuery module as follows:

 let $filename := xdmp:get-request-field-filename("upload")
 let $disposition := fn:concat("attachment; filename=""",$filename,"""")
 let $x := xdmp:add-response-header("Content-Disposition", $disposition)
 let $x:= xdmp:set-response-content-type(
             xdmp:get-request-field-content-type("upload"))
 return
 xdmp:get-request-field("upload")

Execute the form.xqy file, select a file, and click the 
"Upload and Get Results" button.  The file you uploaded
will open according to the mime type the browser.  If you
wanted to save it to the database, you could use 
xdmp:document-insert to do so.

</pre></apidoc:example>
  </apidoc:function><apidoc:function name="get-request-field-filename" type="builtin" lib="xdmp" category="AppServerBuiltins" hidden="false" bucket="MarkLogic Built-In Functions">
    <apidoc:summary>
  Returns a list of filenames from a multipart request for the field name 
  specified. Returns an empty sequence for a field that does not exist.
</apidoc:summary>
    <apidoc:params>
      <apidoc:param name="field-name" type="xs:string" optional="false">
    The name of the request field with the multipart request.
  </apidoc:param>
    </apidoc:params>
    <apidoc:return>xs:string*</apidoc:return>
    <apidoc:usage>
  This function is useful for file upload applications.  For an example, see
  the <a href="#grf2" xmlns="http://www.w3.org/1999/xhtml">second example in the
  <code>xdmp:get-request-field</code></a> documentation.
</apidoc:usage>
    <apidoc:example><pre xml:space="preserve" xmlns="http://www.w3.org/1999/xhtml">
  (: 
     Returns the filename of the files loaded in the 
     "upload" input form element.
  :)
  xdmp:get-request-field-filename("upload")
  =&gt; "myfile.doc"
</pre></apidoc:example>
  </apidoc:function><apidoc:function name="get-request-field-content-type" type="builtin" lib="xdmp" category="AppServerBuiltins" hidden="false" bucket="MarkLogic Built-In Functions">
    <apidoc:summary>
  This function is used to extract the content type from the request field.
  It returns a sequence of content types, one for each filename, in the 
  same order as the filenames returned from 
  <code xmlns="http://www.w3.org/1999/xhtml">xdmp:get-request-field-filename</code>. 
</apidoc:summary>
    <apidoc:params>
      <apidoc:param name="field-name" type="xs:string" optional="false">
    The name of the request field with the multipart request.
  </apidoc:param>
    </apidoc:params>
    <apidoc:return>xs:string*</apidoc:return>
    <apidoc:usage>
  This function is useful for file upload applications.  For an example, see
  the <a href="#grf2" xmlns="http://www.w3.org/1999/xhtml">second example in the
  <code>xdmp:get-request-field</code></a> documentation.
</apidoc:usage>
    <apidoc:example><pre xml:space="preserve" xmlns="http://www.w3.org/1999/xhtml">
  (: 
     Returns the content type of the files loaded in the 
     "upload" input form element.
  :)
  xdmp:get-request-field-content-type("upload")
  =&gt; "application/msword"
</pre></apidoc:example>
  </apidoc:function><apidoc:function name="get-request-header-names" type="builtin" lib="xdmp" category="AppServerBuiltins" hidden="false" bucket="MarkLogic Built-In Functions">
    <apidoc:summary>
  Returns a sequence of request header names.
</apidoc:summary>
    <apidoc:params/>
    <apidoc:return>xs:string*</apidoc:return>
    <apidoc:example><pre xml:space="preserve" xmlns="http://www.w3.org/1999/xhtml">
  xdmp:get-request-header-names()
  =&gt; ("A", "B", ...)
</pre></apidoc:example>
  </apidoc:function><apidoc:function type="builtin" lib="xdmp" name="get-request-header" category="AppServerBuiltins" hidden="false" bucket="MarkLogic Built-In Functions">
    <apidoc:summary>
  Returns the value of a named request header.
</apidoc:summary>
    <apidoc:params>
      <apidoc:param name="name" type="xs:string" optional="false">
    Request header name.
  </apidoc:param>
      <apidoc:param name="default" type="xs:string?" optional="true">
    A default value to return if there is no request header.
  </apidoc:param>
    </apidoc:params>
    <apidoc:return>xs:string*</apidoc:return>
    <apidoc:example><pre xml:space="preserve" xmlns="http://www.w3.org/1999/xhtml">
  xdmp:get-request-header("A")
  =&gt; "foo"
</pre></apidoc:example>
  </apidoc:function><apidoc:function type="builtin" lib="xdmp" name="get-request-username" category="AppServerBuiltins" hidden="false" bucket="MarkLogic Built-In Functions">
    <apidoc:summary>
  Returns the username from the <code xmlns="http://www.w3.org/1999/xhtml">Authorization</code> header of
  this App Server request.
</apidoc:summary>
    <apidoc:return>xs:string</apidoc:return>
    <apidoc:example><pre xml:space="preserve" xmlns="http://www.w3.org/1999/xhtml">
  xdmp:get-request-username()
  =&gt; "fred"
</pre></apidoc:example>
  </apidoc:function><apidoc:function type="builtin" lib="xdmp" name="get-request-method" category="AppServerBuiltins" hidden="false" bucket="MarkLogic Built-In Functions">
    <apidoc:summary>
  Returns the HTTP request method.
</apidoc:summary>
    <apidoc:return>xs:string</apidoc:return>
    <apidoc:example><pre xml:space="preserve" xmlns="http://www.w3.org/1999/xhtml">
  xdmp:get-request-method()
  =&gt; "GET"
</pre></apidoc:example>
  </apidoc:function><apidoc:function type="builtin" lib="xdmp" name="get-request-path" category="AppServerBuiltins" hidden="false" bucket="MarkLogic Built-In Functions">
    <apidoc:summary>
  Returns the HTTP request path.
</apidoc:summary>
    <apidoc:return>xs:string</apidoc:return>
    <apidoc:example><pre xml:space="preserve" xmlns="http://www.w3.org/1999/xhtml">
  xdmp:get-request-path()
  =&gt; "/example.xqy"
</pre></apidoc:example>
  </apidoc:function><apidoc:function type="builtin" lib="xdmp" name="get-request-url" category="AppServerBuiltins" hidden="false" bucket="MarkLogic Built-In Functions">
    <apidoc:summary>
  Returns the portion of the URL following the host_name:port_number.  The
  output does not include any fragment identifier supplied with the URL (that
  is, it does not include the # sign or anything following the # sign).
</apidoc:summary>
    <apidoc:return>xs:string</apidoc:return>
    <apidoc:example><pre xml:space="preserve" xmlns="http://www.w3.org/1999/xhtml">
  xdmp:get-request-url()
  =&gt; "/example.xqy?name=foo&amp;year=2006"
</pre></apidoc:example>
  </apidoc:function><apidoc:function name="get-session-field-names" type="builtin" lib="xdmp" category="AppServerBuiltins" hidden="false" bucket="MarkLogic Built-In Functions">
    <apidoc:summary>
  Returns a sequence of the HTTP session field names from the session
  created by the <code xmlns="http://www.w3.org/1999/xhtml">xdmp:login</code> function.  
</apidoc:summary>
    <apidoc:params/>
    <apidoc:privilege>
  <p xmlns="http://www.w3.org/1999/xhtml"><code>http://marklogic.com/xdmp/privileges/xdmp-get-session-field-names</code></p>
</apidoc:privilege>
    <apidoc:return>xs:string*</apidoc:return>
    <apidoc:usage>
  You can use the <code xmlns="http://www.w3.org/1999/xhtml">xdmp:set-session-field</code> function to
  set a named value in a session and the <code xmlns="http://www.w3.org/1999/xhtml">xdmp:get-session-field</code>
  function to return a value set in a session field. 
</apidoc:usage>
    <apidoc:example><pre xml:space="preserve" xmlns="http://www.w3.org/1999/xhtml">
  xdmp:get-session-field-names()
  =&gt; ("user", "role", "action", "index")
</pre></apidoc:example>
  </apidoc:function><apidoc:function name="get-session-field" type="builtin" lib="xdmp" category="AppServerBuiltins" hidden="false" bucket="MarkLogic Built-In Functions">
    <apidoc:summary>
  Returns the value of a named session field from the session
  created by the <code xmlns="http://www.w3.org/1999/xhtml">xdmp:login</code> function.
</apidoc:summary>
    <apidoc:params>
      <apidoc:param name="name" type="xs:string" optional="false">
    The name of the session field.
  </apidoc:param>
      <apidoc:param name="default" type="item()*" optional="true">
    A default value to return if there is no session field.
  </apidoc:param>
    </apidoc:params>
    <apidoc:privilege>
  <p xmlns="http://www.w3.org/1999/xhtml"><code>http://marklogic.com/xdmp/privileges/xdmp-get-session-field</code></p>
</apidoc:privilege>
    <apidoc:return>item()*</apidoc:return>
    <apidoc:usage>
  You can use the <code xmlns="http://www.w3.org/1999/xhtml">xdmp:set-session-field</code> function to
  set a named value in a session and the <code xmlns="http://www.w3.org/1999/xhtml">xdmp:get-session-field-names</code>
  function to return the names of the fields in the session.  
</apidoc:usage>
    <apidoc:example><pre xml:space="preserve" xmlns="http://www.w3.org/1999/xhtml">
  xdmp:get-session-field("user")
  =&gt; "marklogic"
</pre></apidoc:example>
  </apidoc:function><apidoc:function name="set-session-field" type="builtin" lib="xdmp" category="AppServerBuiltins" hidden="false" bucket="MarkLogic Built-In Functions">
    <apidoc:summary>
  Sets the value of a named session field for the session created 
  by the <code xmlns="http://www.w3.org/1999/xhtml">xdmp:login</code> function.  
</apidoc:summary>
    <apidoc:params>
      <apidoc:param name="name" type="xs:string" optional="false">
    The name of the session field.</apidoc:param>
      <apidoc:param name="value" type="item()*" optional="false">
    The value of the session field.</apidoc:param>
    </apidoc:params>
    <apidoc:privilege>
  <p xmlns="http://www.w3.org/1999/xhtml"><code>http://marklogic.com/xdmp/privileges/xdmp-set-session-field</code></p>
</apidoc:privilege>
    <apidoc:return>item()*</apidoc:return>
    <apidoc:usage>
  You can use the <code xmlns="http://www.w3.org/1999/xhtml">xdmp:get-session-field-names</code> function 
  to return the names of the fields in the session and the
  <code xmlns="http://www.w3.org/1999/xhtml">xdmp:get-session-field</code> function
  to return a value set in a session field. 
</apidoc:usage>
    <apidoc:example><pre xml:space="preserve" xmlns="http://www.w3.org/1999/xhtml">
  xdmp:set-session-field("user", "marklogic")
  =&gt; "marklogic"
</pre></apidoc:example>
  </apidoc:function><apidoc:function name="get-server-field-names" type="builtin" lib="xdmp" category="AppServerBuiltins" hidden="false" bucket="MarkLogic Built-In Functions">
    <apidoc:summary>
  Returns a sequence of the server field names.
</apidoc:summary>
    <apidoc:params/>
    <apidoc:privilege>
  <p xmlns="http://www.w3.org/1999/xhtml"><code>http://marklogic.com/xdmp/privileges/xdmp-get-server-field-names</code></p>
</apidoc:privilege>
    <apidoc:return>xs:string*</apidoc:return>
    <apidoc:usage>
  This functions returns the server field names of the fields for which you
  have privileges to see. Users with the <code xmlns="http://www.w3.org/1999/xhtml">admin</code> role have 
  privileges to see all of the server fields.  Information Studio uses several 
  protected server fields, each having a name that starts with "plugin".
  Therefore, if you are a user with the <code xmlns="http://www.w3.org/1999/xhtml">admin</code> role, you will see 
  all of those fields when you call <code xmlns="http://www.w3.org/1999/xhtml">xdmp:get-server-field-names</code>.
</apidoc:usage>
    <apidoc:example><pre xml:space="preserve" xmlns="http://www.w3.org/1999/xhtml">
xdmp:get-server-field-names()
 =&gt;
("name1","name2")

</pre></apidoc:example>
  </apidoc:function><apidoc:function name="get-server-field" type="builtin" lib="xdmp" category="AppServerBuiltins" hidden="false" bucket="MarkLogic Built-In Functions">
    <apidoc:summary>
  Returns the value of a named server field.  A server field is created with
  <code xmlns="http://www.w3.org/1999/xhtml">xdmp:set-server-field</code> and stores a name/value
  pair in memory.  The server field is available on the App Server in which
  it is set on the host in which the App Server runs, via 
  <code xmlns="http://www.w3.org/1999/xhtml">xdmp:get-server-field</code>; a server field that is set on one 
  App Server is not available on other App Servers on that host or on the same 
  App Server running on another host.  Server fields are commonly used
  with the system Plugin Framework.
</apidoc:summary>
    <apidoc:params>
      <apidoc:param name="name" type="xs:string" optional="false">
    The name of the server field.
  </apidoc:param>
      <apidoc:param name="default" type="item()*" optional="true">
    A default value to return if there is no server field.
  </apidoc:param>
    </apidoc:params>
    <apidoc:privilege>
  <p xmlns="http://www.w3.org/1999/xhtml"><code>http://marklogic.com/xdmp/privileges/xdmp-get-server-field</code></p>
</apidoc:privilege>
    <apidoc:return>item()*</apidoc:return>
    <apidoc:example><pre xml:space="preserve" xmlns="http://www.w3.org/1999/xhtml">
  xdmp:get-server-field("foo")
  =&gt; "bar"
</pre></apidoc:example>
  </apidoc:function><apidoc:function name="set-server-field" type="builtin" lib="xdmp" category="AppServerBuiltins" hidden="false" bucket="MarkLogic Built-In Functions">
    <apidoc:summary>
  Sets the value of a named server field. A server field is created with
  <code xmlns="http://www.w3.org/1999/xhtml">xdmp:set-server-field</code> and stores a name/value
  pair in memory.  The server field is available on the App Server in which
  it is set on the host in which the App Server runs, via 
  <code xmlns="http://www.w3.org/1999/xhtml">xdmp:get-server-field</code>; a server field that is set on one 
  App Server is not available on other App Servers on that host or on the same 
  App Server running on another host.
</apidoc:summary>
    <apidoc:params>
      <apidoc:param name="name" type="xs:string" optional="false">
    The name of the server field.</apidoc:param>
      <apidoc:param name="value" type="item()*" optional="false">
    The value of the server field.</apidoc:param>
    </apidoc:params>
    <apidoc:privilege>
  <p xmlns="http://www.w3.org/1999/xhtml"><code>http://marklogic.com/xdmp/privileges/xdmp-set-server-field</code></p>
</apidoc:privilege>
    <apidoc:return>item()*</apidoc:return>
    <apidoc:usage>
    <p xmlns="http://www.w3.org/1999/xhtml">If you use a server field with the Plugin Framework (by placing
    the <code>xdmp:set-server-field</code> code in a main module under 
    the <code>Plugins</code> directory on a host), then the server field 
    will be populated for each App Server on the host before the first request 
    against each App Server is run.</p>
</apidoc:usage>
    <apidoc:example><pre xml:space="preserve" xmlns="http://www.w3.org/1999/xhtml">
  xdmp:set-server-field("foo", "bar")
  =&gt; "bar"
</pre></apidoc:example>
  </apidoc:function><apidoc:function name="set-server-field-privilege" type="builtin" lib="xdmp" category="AppServerBuiltins" hidden="false" bucket="MarkLogic Built-In Functions">
    <apidoc:summary>
  Sets the privilege of a named server field.
</apidoc:summary>
    <apidoc:params>
      <apidoc:param name="name" type="xs:string" optional="false">
    The name of the server field.</apidoc:param>
      <apidoc:param name="privilege" type="xs:string?" optional="false">
    The privilege action URI for the server field.</apidoc:param>
    </apidoc:params>
    <apidoc:privilege>
  <p xmlns="http://www.w3.org/1999/xhtml"><code>http://marklogic.com/xdmp/privileges/xdmp-set-server-field-privilege</code></p>
</apidoc:privilege>
    <apidoc:return>empty-sequence()</apidoc:return>
    <apidoc:usage>
  <p xmlns="http://www.w3.org/1999/xhtml">Changing the server field value on a field being used with a plugin 
  will change the behavior of the plugin.  Therefore, if you are using a 
  server field in a plugin, it is a good practice to set a privilege on the 
  server field to protect it from malicious or accidental updates.  </p>
</apidoc:usage>
    <apidoc:example><pre xml:space="preserve" xmlns="http://www.w3.org/1999/xhtml">
  xdmp:set-server-field-privilege("foo", "http://mydomain.com/privileges/foo-server-field")
</pre></apidoc:example>
  </apidoc:function><apidoc:function name="redirect-response" type="builtin" lib="xdmp" category="AppServerBuiltins" hidden="false" bucket="MarkLogic Built-In Functions">
    <apidoc:summary>
  Redirects the App Server response to a given location.
</apidoc:summary>
    <apidoc:params>
      <apidoc:param name="name" type="xs:string" optional="false">
    The redirect URL.</apidoc:param>
    </apidoc:params>
    <apidoc:return>empty-sequence()</apidoc:return>
    <apidoc:example><pre xml:space="preserve" xmlns="http://www.w3.org/1999/xhtml">
  xdmp:redirect-response("http://marklogic.com/howtobuy.xqy")
</pre></apidoc:example>
  </apidoc:function><apidoc:function name="set-response-code" type="builtin" lib="xdmp" category="AppServerBuiltins" hidden="false" bucket="MarkLogic Built-In Functions">
    <apidoc:summary>
  Sets the response code and message.
</apidoc:summary>
    <apidoc:params>
      <apidoc:param name="code" type="xs:integer" optional="false">
    The response code.</apidoc:param>
      <apidoc:param name="message" type="xs:string" optional="false">
    The response message.</apidoc:param>
    </apidoc:params>
    <apidoc:return>empty-sequence()</apidoc:return>
    <apidoc:example><pre xml:space="preserve" xmlns="http://www.w3.org/1999/xhtml">
  xdmp:set-response-code(204,"No Content")
</pre></apidoc:example>
  </apidoc:function><apidoc:function name="get-response-code" type="builtin" lib="xdmp" category="AppServerBuiltins" hidden="false" bucket="MarkLogic Built-In Functions">
    <apidoc:summary>
  Returns two nodes, the first containing the HTTP response code and the
  second containing the HTTP response message.
</apidoc:summary>
    <apidoc:params/>
    <apidoc:usage>
  You can use this with an HTTP Server error handler to create custom error
  pages.
</apidoc:usage>
    <apidoc:return>item()*</apidoc:return>
    <apidoc:example><pre xml:space="preserve" xmlns="http://www.w3.org/1999/xhtml">
  xdmp:response-code()
  =&gt; 200
     OK
</pre></apidoc:example>
  </apidoc:function><apidoc:function name="set-response-content-type" type="builtin" lib="xdmp" category="AppServerBuiltins" hidden="false" bucket="MarkLogic Built-In Functions">
    <apidoc:summary>
  Sets the response content-type.
</apidoc:summary>
    <apidoc:params>
      <apidoc:param name="name" type="xs:string" optional="false">
    The content type.</apidoc:param>
    </apidoc:params>
    <apidoc:return>empty-sequence()</apidoc:return>
    <apidoc:example><pre xml:space="preserve" xmlns="http://www.w3.org/1999/xhtml">
  xdmp:set-response-content-type("text/html")
</pre></apidoc:example>
  </apidoc:function><apidoc:function name="set-response-encoding" type="builtin" lib="xdmp" category="AppServerBuiltins" hidden="false" bucket="MarkLogic Built-In Functions">
    <apidoc:summary>
  Sets the response encoding.
</apidoc:summary>
    <apidoc:params>
      <apidoc:param name="encoding" type="xs:string" optional="false">
    The desired response encoding.</apidoc:param>
    </apidoc:params>
    <apidoc:return>empty-sequence()</apidoc:return>
    <apidoc:example><pre xml:space="preserve" xmlns="http://www.w3.org/1999/xhtml">
  xdmp:set-response-encoding("ISO-8859-1")
</pre></apidoc:example>
  </apidoc:function><apidoc:function name="get-response-encoding" type="builtin" lib="xdmp" category="AppServerBuiltins" hidden="false" bucket="MarkLogic Built-In Functions">
    <apidoc:summary>
  Returns the encoding that the response from this server is in.
</apidoc:summary>
    <apidoc:params/>
    <apidoc:return>xs:string</apidoc:return>
  </apidoc:function><apidoc:function name="set-request-time-limit" type="builtin" lib="xdmp" category="AppServerBuiltins" hidden="false" bucket="MarkLogic Built-In Functions">
    <apidoc:summary>
  Changes the time limit for an actively running request to the specified
  value.  If you do not supply values for the last three parameters, the 
  function sets the time limit for the current request.
</apidoc:summary>
    <apidoc:params>
      <apidoc:param name="time-limit" type="xs:unsignedInt" optional="false">
    The desired time limit, in seconds.
  </apidoc:param>
      <apidoc:param name="hostID" type="xs:unsignedLong?" optional="true">
    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="true">
   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="true">
    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-set-request-time-limit-any</code>
  or 
  <code>http://marklogic.com/xdmp/privileges/xdmp-set-request-time-limit-my</code></p>
</apidoc:privilege>
    <apidoc:return>empty-sequence()</apidoc:return>
    <apidoc:example><pre xml:space="preserve" xmlns="http://www.w3.org/1999/xhtml">
  xdmp:set-request-time-limit(10000)
</pre></apidoc:example>
  </apidoc:function><apidoc:function name="add-response-header" type="builtin" lib="xdmp" category="AppServerBuiltins" hidden="false" bucket="MarkLogic Built-In Functions">
    <apidoc:summary>
  Adds an HTTP response header field.
</apidoc:summary>
    <apidoc:params>
      <apidoc:param name="name" type="xs:string" optional="false">
    The response header name.</apidoc:param>
      <apidoc:param name="value" type="xs:string" optional="false">
    The value to set for this response header.</apidoc:param>
    </apidoc:params>
    <apidoc:privilege>
  <p xmlns="http://www.w3.org/1999/xhtml"><code>http://marklogic.com/xdmp/privileges/xdmp-add-response-header</code></p>
</apidoc:privilege>
    <apidoc:return>empty-sequence()</apidoc:return>
    <apidoc:example><pre xml:space="preserve" xmlns="http://www.w3.org/1999/xhtml">
  xdmp:add-response-header("meta", "description")
</pre></apidoc:example>
  </apidoc:function><apidoc:function name="uri-is-file" type="builtin" lib="xdmp" category="AppServerBuiltins" hidden="false" bucket="MarkLogic Built-In Functions">
    <apidoc:summary>
  Returns true if a given URI refers to a
  file which exists on the current application server.
  Returns false if the file does not exist.
  Returns the empty sequence if the URI is the empty sequence.
</apidoc:summary>
    <apidoc:params>
      <apidoc:param name="uri" type="xs:string" optional="false">
    The URI to check.
    If the URI begins with a "/", it is relative to the root directory 
    of the application server.  
    Otherwise, it is relative to the current request URI.
  </apidoc:param>
    </apidoc:params>
    <apidoc:return>xs:boolean?</apidoc:return>
    <apidoc:example><pre xml:space="preserve" xmlns="http://www.w3.org/1999/xhtml">
  xdmp:uri-is-file("apppages/test.xml")
  =&gt; true if test.xml exists in "apppages" sub-directory 
  relative to the directory of the file containing the request.</pre>
</apidoc:example>
    <apidoc:example><pre xml:space="preserve" xmlns="http://www.w3.org/1999/xhtml">
  xdmp:uri-is-file("/sub-directory/test.xml")
  =&gt; true if test.xml exists in "sub-directory" relative 
  to the root directory of the application server.</pre>
</apidoc:example>
  </apidoc:function><apidoc:function name="get-request-client-address" type="builtin" lib="xdmp" category="AppServerBuiltins" hidden="false" bucket="MarkLogic Built-In Functions">
    <apidoc:summary>
  Returns as a string the internet address of the 
  client from which the HTTP server request is issued.

  <p xmlns="http://www.w3.org/1999/xhtml">Returns the empty sequence if it is not called from an HTTP server.</p>
</apidoc:summary>
    <apidoc:params/>
    <apidoc:return>xs:string?</apidoc:return>
    <apidoc:usage>
  Use this function if you need to get the internet protocol (IP) address of 
  the requesting client.  For example, you can create an application that 
  contains conditional code based on IP addresses (see the example below). 
</apidoc:usage>
    <apidoc:example>
  <p xmlns="http://www.w3.org/1999/xhtml">The following example shows logic which checks if the request was 
  submitted from the "localhost" IP address (127.0.0.1).</p> 
  <pre xml:space="preserve" xmlns="http://www.w3.org/1999/xhtml">
  if (xdmp:get-request-client-address() eq "127.0.0.1")
  then "Submitted from localhost."
  else "Only localhost access is allowed for this application."
</pre></apidoc:example>
    <apidoc:example><pre xml:space="preserve" xmlns="http://www.w3.org/1999/xhtml">
  xdmp:get-request-client-address()
  =&gt; "127.0.0.1"
</pre></apidoc:example>
  </apidoc:function><apidoc:function name="get-request-protocol" type="builtin" lib="xdmp" category="AppServerBuiltins" hidden="false" bucket="MarkLogic Built-In Functions">
    <apidoc:summary>
  Returns as a string the request protocol (either "http" or "https")

  <p xmlns="http://www.w3.org/1999/xhtml">Returns the empty sequence if it is not called from an HTTP server.</p>
</apidoc:summary>
    <apidoc:params/>
    <apidoc:return>xs:string?</apidoc:return>
    <apidoc:usage>
  Use this function if you need to determine whether the client connection
  is HTTP or HTTPs. 
</apidoc:usage>
    <apidoc:example>
  <p xmlns="http://www.w3.org/1999/xhtml">The following example shows logic which checks if the request was 
  submitted via https.</p> 
  <pre xml:space="preserve" xmlns="http://www.w3.org/1999/xhtml">
  if (xdmp:get-request-protocol() eq "https")
  then "Submitted via https."
  else "Application requires secure connections only."
</pre></apidoc:example>
    <apidoc:example><pre xml:space="preserve" xmlns="http://www.w3.org/1999/xhtml">
  xdmp:get-request-protocol()
  =&gt; "https"
</pre></apidoc:example>
  </apidoc:function><apidoc:function name="get-request-client-certificate" type="builtin" lib="xdmp" category="AppServerBuiltins" hidden="false" bucket="MarkLogic Built-In Functions">
    <apidoc:summary>
  Returns the PEM encoded client certificate if one was presented.

  <p xmlns="http://www.w3.org/1999/xhtml">Returns the empty sequence if it is not called from an HTTP server, if
  SSL is not enabled for the HTTP server, or if no certificate is available.
  A clients will not send its certificate unless the server requests it.</p>
</apidoc:summary>
    <apidoc:params/>
    <apidoc:return>xs:string?</apidoc:return>
    <apidoc:usage>
  Use this function if you need to examine a client's certificate.
</apidoc:usage>
    <apidoc:example>
  <p xmlns="http://www.w3.org/1999/xhtml">The following example returns an XML representation
  of a client certificate if one is available.</p> 
  <pre xml:space="preserve" xmlns="http://www.w3.org/1999/xhtml">
  for $p in xdmp:get-request-client-certificate()
  return xdmp:x509-certificate-extract($p)
</pre></apidoc:example>
  </apidoc:function><apidoc:function name="get-request-body" type="builtin" lib="xdmp" category="AppServerBuiltins" hidden="false" bucket="MarkLogic Built-In Functions">
    <apidoc:summary>
  For PUT requests, returns the body of the request.
  For POST requests, returns the body of the request if it is not of 
  content-type application/x-www-form-urlencoded.

  <p xmlns="http://www.w3.org/1999/xhtml">Returns the empty sequence if it is not called from an application 
  server.</p>
</apidoc:summary>
    <apidoc:params>
      <apidoc:param name="format" type="xs:string?" optional="true">
    The format ("xml", "text", or "binary") to interpret the body as.  If not supplied, 
    the format associated with the content-type header in mimetypes.xml is used.  If no 
    content-type header exists, the default format is "binary".
  </apidoc:param>
    </apidoc:params>
    <apidoc:return>item()*</apidoc:return>
    <apidoc:usage>
  <p xmlns="http://www.w3.org/1999/xhtml">If the content-type of the POST body is application/x-www-form-urlencoded,
  it is not available here, but instead is available in its decoded form 
  through <code>xdmp:get-request-field-names()</code> and 
  <code>xdmp:get-request-field()</code>.</p>

  <p xmlns="http://www.w3.org/1999/xhtml">If there is no content-type header in the request, then the request
  body defaults to application/x-www-form-urlencoded, and therefore 
  <code>xdmp:get-request-body</code> will return the empty sequence. If
  you want to read the request body, then the POST must include a 
  content-type header.</p>

  <p xmlns="http://www.w3.org/1999/xhtml">You can use this function to process certain types of web service 
  SOAP requests with MarkLogic Server.</p>

  <p xmlns="http://www.w3.org/1999/xhtml">The output of an <code>xdmp:get-request-body</code> call is 
  typically a document node, so if you want to get the contents of 
  the POST, you should add a <code>/node()</code> XPath step to
  the output.  The contents of the document node could be a text node,
  an element node, or a binary node.</p>
</apidoc:usage>
    <apidoc:example><pre xml:space="preserve" xmlns="http://www.w3.org/1999/xhtml">
  xdmp:get-request-body()/node()
  =&gt; "&lt;a&gt;Contents of POST body.&lt;/a&gt;"
</pre></apidoc:example>
  </apidoc:function><apidoc:function name="get-url-rewriter-path" type="builtin" lib="xdmp" category="AppServerBuiltins" hidden="false" bucket="MarkLogic Built-In Functions">
    <apidoc:summary>
  Returns the URL of the URL rewriter handler for this application server.
  An empty string is returned if there is no rewrite handler.
</apidoc:summary>
    <apidoc:params/>
    <apidoc:return>xs:string</apidoc:return>
    <apidoc:usage>
  <p xmlns="http://www.w3.org/1999/xhtml">This function is useful for implementing a rewrite handler where you may
  want to resolve a location relative to the rewrite handler rather than to
  the specific request. This may be the case if the rewrite handler is acting
  as a delegator to known modules.
  </p>
</apidoc:usage>
    <apidoc:example><pre xml:space="preserve" xmlns="http://www.w3.org/1999/xhtml">
  fn:resolve-uri("special-handler.xqy", xdmp:get-url-rewriter-path())
</pre></apidoc:example>
  </apidoc:function></apidoc:module>