Mark Logic - XQuery Function Online Documentation

3.2

This page was generated

January 5, 2009

5:43 PM

XQuery Built-In and Modules Function Reference

All XQuery Functions

MarkLogic Server Built-In Functions

Extension (xdmp:)

Search (cts:)

cts:query Constructors (cts:)

Classifier (cts:)

Math (math:)

Document Conversion (xdmp:)

Update (xdmp:)

App Server (xdmp:)

Security (xdmp:)

Server Monitoring (xdmp:)

Profile (prof:)

Debug (dbg:)

XQuery Module Functions

Security (sec:)

Thesaurus (thsr:)

Spell (:)

Triggers (trgr:)

Content Processing Framework (cpf:)

Links (lnk:)

Domains (dom:)

Pipelines (p:)

Generic Conversion (cvt:)

MSWord Conversion (msword:)

Excel Conversion (excel:)

Powerpoint Conversion (ppt:)

PDF Conversion (pdf:)

DocBook Conversion (dbk:)

CSS Conversion (css:)

XHTML Conversion (xhtml:)

W3C Built-In Functions

Accessor (fn:)

AnyURI (fn:)

String (fn:)

Boolean (fn:)

Context (fn:)

DurationDateTime (fn:)

Node (fn:)

Numeric (fn:)

Sequence (fn:)

QName (fn:)

Error and Trace (fn:)

W3C XQuery Reference

W3C XQuery Functions

W3C XQuery Language

Built-In: Debug

Implements a library of functions which allow developers to build an IDE which will allow runtime debugging of query requests against MarkLogic Server. The debug functions allow you to build an application that does things like attach to a running server, set breakpoints in a query, examine the value of variables at a point in query execution, and so on. Note that the debug function library is not a debugger, but provides server-side support to build an application that can debug queries against MarkLogic Server.

Function Summary
dbg:attach	Attach to a request and stop it for debugging.
dbg:attached	Return the request ID's of attached requests in a given server.
dbg:break	Set a breakpoint at the given expression ID.
dbg:breakpoints	Returns a sequence of expression ID's representing existing breakpoints for the given request.
dbg:clear	Clear a breakpoint at the given expression ID.
dbg:connect	Connect to a Server (http, xdbc, or task) for debugging.
dbg:continue	Continue evaluation of the request.
dbg:detach	Detach from a stopped request.
dbg:disconnect	End the debugging of a server.
dbg:eval	Evaluate a string as an XQuery for debugging.
dbg:expr	Returns a description/representation of a given expression.
dbg:finish	Continue evaluation of the request until the end of the current function.
dbg:function	Returns the expression ID representing the function defined in a module with a given name.
dbg:invoke	Invoke a module for debugging.
dbg:line	Returns a sequence of expression ID's found on a given line of a stopped request.
dbg:next	Continue evaluation of the request until the beginning or end of an expression that is not a descendant of the current expression.
dbg:out	Continue evaluation of the request until the end of the current expression.
dbg:stack	Return the stack trace for a given request.
dbg:status	Return the debugging status of given requests.
dbg:step	Continue evaluation of the request until the beginning or end of an expression.
dbg:stop	Placing this call in XQuery will instruct the evaluator to stop a request for debugging.
dbg:stopped	Return the request ID's of stopped requests in a given server.
dbg:value	Evaluate an expression in the context of the identified stopped request.
dbg:wait	Wait until at least one of the given requests stops or all complete evaluating.

Function Detail

dbg:attach(
	$request-id as xs:unsignedLong
) as empty()

Summary:

Attach to a request and stop it for debugging.

Parameters:

$request-id : A request ID.

Required Privilege:

http://marklogic.com/xdmp/privileges/debug-my-requests or http://marklogic.com/xdmp/privileges/debug-any-requests

Example:

  dbg:attach(204928402983)
  => ()

dbg:attached(
	[$server as xs:unsignedLong]
) as xs:unsignedLong*

Summary:

Return the request ID's of attached requests in a given server. If server isn't supplied, returns a list of all attached requests on host.

Parameters:

$server (optional): Server ID.

Required Privilege:

http://marklogic.com/xdmp/privileges/debug-my-requests or http://marklogic.com/xdmp/privileges/debug-any-requests

Example:

  dbg:attached(204928402983)
  => (2298273928472, 20384203948)

dbg:break(
	$request as xs:unsignedLong,
	[$expression as xs:unsignedLong]
) as empty()

Summary:

Set a breakpoint at the given expression ID. If no expression ID is given, then the identified request is stopped.

Parameters:

$request : Request ID.

$expression (optional): Expression ID.

Required Privilege:

http://marklogic.com/xdmp/privileges/debug-my-requests or http://marklogic.com/xdmp/privileges/debug-any-requests

Example:

  dbg:break(204928402983, 28042309)
  => ()

dbg:breakpoints(
	$request as xs:unsignedLong
) as xs:usngignedLong*

Summary:

Returns a sequence of expression ID's representing existing breakpoints for the given request.

Parameters:

$request : Request ID.

Required Privilege:

http://marklogic.com/xdmp/privileges/debug-my-requests or http://marklogic.com/xdmp/privileges/debug-any-requests

Example:

  dbg:breakpoints(204928402983)
  => 28042309

dbg:clear(
	$request as xs:unsignedLong,
	$expression as xs:unsignedLong
) as empty()

Summary:

Clear a breakpoint at the given expression ID.

Parameters:

$request : Request ID.

$expression : Expression ID.

Required Privilege:

http://marklogic.com/xdmp/privileges/debug-my-requests or http://marklogic.com/xdmp/privileges/debug-any-requests

Example:

  dbg:clear(204928402983, 28042309)
  => ()

dbg:connect(
	$server as xs:unsignedLong
) as empty()

Summary:

Connect to a Server (http, xdbc, or task) for debugging. Any running requests will be stopped and new requests will stop at the first expression.

Parameters:

$server : A server ID.

Required Privilege:

http://marklogic.com/xdmp/privileges/debug-any-requests

Example:

  dbg:connect(4928402983)
  => ()

dbg:continue(
	$request as xs:unsignedLong
) as empty()

Summary:

Continue evaluation of the request.

Parameters:

$request : Request ID.

Required Privilege:

http://marklogic.com/xdmp/privileges/debug-my-requests or http://marklogic.com/xdmp/privileges/debug-any-requests

Example:

  dbg:continue(204928402983)
  => ()

dbg:detach(
	$request-id as xs:unsignedLong
) as empty()

Summary:

Detach from a stopped request. All breakpoints set will be cancelled and the request will continue evaluating.

Parameters:

$request-id : A request ID.

Required Privilege:

http://marklogic.com/xdmp/privileges/debug-my-requests or http://marklogic.com/xdmp/privileges/debug-any-requests

Example:

  dbg:detach(204928402983)
  => ()

dbg:disconnect(
	$server as xs:unsignedLong
) as empty()

Summary:

End the debugging of a server. Already stopped requests will remain stopped. New requests will evaluate without stopping at first expression.

Parameters:

$server : A server ID.

Required Privilege:

http://marklogic.com/xdmp/privileges/debug-any-requests

Example:

  dbg:disconnect(204928402983)
  => ()

dbg:eval(
	$xquery as xs:string,
	[$vars as item()*],
	[$options as node()]
) as xs:unsignedLong

Summary:

Evaluate a string as an XQuery for debugging. Module evaluation will be stopped at the start of the first expression. Returns the request-id after creating the request.

Parameters:

$xquery : The XQuery string to be evaluated. If the XQuery string contains double quotes ("), surround the string with single quotes (').

$vars (optional): The external variable values for this evaluation. This must be a sequence of even length, alternating QNames and items. Each QName and item pair specify a variable name and value.

$options (optional): The options node.

Required Privilege:

http://marklogic.com/xdmp/privileges/debug-my-requests or http://marklogic.com/xdmp/privileges/debug-any-requests

Example:

  dbg:eval("1+1")
  => 234928734928

dbg:expr(
	$request as xs:unsignedLong,
	$expression as xs:unsignedLong
) as element(dbg:expression)

Summary:

Returns a description/representation of a given expression.

Parameters:

$request : Request ID.

$expression : Expression ID.

Required Privilege:

http://marklogic.com/xdmp/privileges/debug-my-requests or http://marklogic.com/xdmp/privileges/debug-any-requests

Example:

  dbg:expr(20293482, 2348239487)
  => the dbg:expression element for this expression

dbg:finish(
	$request as xs:unsignedLong
) as empty()

Summary:

Continue evaluation of the request until the end of the current function. If evaluation is not inside of a function, this request is equivalent to continue().

Parameters:

$request : Request ID.

Required Privilege:

http://marklogic.com/xdmp/privileges/debug-my-requests or http://marklogic.com/xdmp/privileges/debug-any-requests

Example:

  dbg:finish(204928402983)
  => ()

dbg:function(
	$request as xs:unsignedLong,
	$uri as xs:string,
	$function as xs:QName
) as xs:unsignedLong

Summary:

Returns the expression ID representing the function defined in a module with a given name.

Parameters:

$request : Request ID.

$uri : Module URI.

$function : function name.

Required Privilege:

http://marklogic.com/xdmp/privileges/debug-my-requests or http://marklogic.com/xdmp/privileges/debug-any-requests

Example:

  dbg:function(20293482, "/security.xqy", $function)
  => 5032942

dbg:invoke(
	$uri as xs:string,
	[$vars as item()*],
	[$options as node()]
) as xs:unsignedLong

Summary:

Invoke a module for debugging. Module evaluation will be stopped at the start of the first expression. Returns the request-id after creating the request.

Parameters:

$uri : The path of the module to be executed. The path is resolved against the root of the request server evaluating the query. The path must resolve to a main module (not a library module).

$vars (optional): The external variable values for this evaluation. This must be a sequence of even length, alternating QNames and items. Each QName and item pair specify a variable name and value.

$options (optional): The options node.

Required Privilege:

http://marklogic.com/xdmp/privileges/debug-my-requests or http://marklogic.com/xdmp/privileges/debug-any-requests

Example:

  dbg:invoke("http://example.com/modules/foo.xqy")
  => 6423840

dbg:line(
	$request as xs:unsignedLong,
	$uri as xs:string,
	$line as xs:unsigned
) as xs:unsignedLong*

Summary:

Returns a sequence of expression ID's found on a given line of a stopped request.

Parameters:

$request : Request ID.

$uri : Module URI.

$line : Line number.

Required Privilege:

http://marklogic.com/xdmp/privileges/debug-my-requests or http://marklogic.com/xdmp/privileges/debug-any-requests

Example:

  dbg:line(20293482, "/security.xqy", 512)
  => (5032942, 9103982, 30802938)

dbg:next(
	$request as xs:unsignedLong
) as empty()

Summary:

Continue evaluation of the request until the beginning or end of an expression that is not a descendant of the current expression.

Parameters:

$request : Request ID.

Required Privilege:

http://marklogic.com/xdmp/privileges/debug-my-requests or http://marklogic.com/xdmp/privileges/debug-any-requests

Example:

  dbg:next(204928402983)
  => ()

dbg:out(
	$request as xs:unsignedLong
) as empty()

Summary:

Continue evaluation of the request until the end of the current expression.

Parameters:

$request : Request ID.

Required Privilege:

http://marklogic.com/xdmp/privileges/debug-my-requests or http://marklogic.com/xdmp/privileges/debug-any-requests

Example:

  dbg:out(204928402983)
  => ()

dbg:stack(
	$request as xs:unsignedLong
) as element(dbg:stack)

Summary:

Return the stack trace for a given request.

Parameters:

$request : Request ID.

Required Privilege:

http://marklogic.com/xdmp/privileges/debug-my-requests or http://marklogic.com/xdmp/privileges/debug-any-requests

Example:

  dbg:stack(204928402983)
  => 
    <stack xmlns="http://marklogic.com/xdmp/debug">
      <expression>
        <expr-id>16429173930674134530</expr-id>
        <expr-source>xdmp:sleep(1000)</expr-source>
        <uri>/long.xqy</uri>
        <line>11</line>
      </expression>
      <frame>
        <uri>/long.xqy</uri>
        <line>11</line>
        <operation>fn:sleep(18)</operation>
        <variables>
          <variable>
            <name xmlns="">x</name>
            <value>18</value>
          </variable>
        </variables>
      </frame>
      <frame>
        <uri>/long.xqy</uri>
        <line>18</line>
        <operation>fn:foo(18)</operation>
        <variables>
          <variable>
            <name xmlns="">x</name>
            <value>18</value>
            </variable></variables>
            </frame><frame>
            <uri>/long.xqy</uri>
            <line>26</line>
            <operation>fn:bar()</operation>
            <variables><variable>
            <name xmlns="">x</name>
            <value>18</value>
          </variable>
        </variables>
      </frame>
      <frame>
        <uri>/long.xqy</uri>
        <line>29</line>
      </frame>
    </stack>

dbg:status(
	$request-id as xs:unsignedLong*
) as element(dbg:requests)?

Summary:

Return the debugging status of given requests.

Parameters:

$request-id : Request id's.

Required Privilege:

http://marklogic.com/xdmp/privileges/debug-my-requests or http://marklogic.com/xdmp/privileges/debug-any-requests

Example:

  dbg:status(14096214104959794818)
  => 
   <requests xmlns="http://marklogic.com/xdmp/debug">
     <request>
       <request-id>14096214104959794818</request-id>
       <server-id>13141894694259521076</server-id>
       <request-status>stopped</request-status>
       <debugging-status>attached</debugging-status>
       <expr-id>16429173930674134530</expr-id>
       <where-stopped>begin</where-stopped>
     </request>
   </requests>

dbg:step(
	$request as xs:unsignedLong
) as empty()

Summary:

Continue evaluation of the request until the beginning or end of an expression.

Parameters:

$request : Request ID.

Required Privilege:

http://marklogic.com/xdmp/privileges/debug-my-requests or http://marklogic.com/xdmp/privileges/debug-any-requests

Example:

  dbg:step(204928402983)
  => ()

                   
                   dbg:stop( ) as empty()
                    

Summary:

Placing this call in XQuery will instruct the evaluator to stop a request for debugging.

Example:

  dbg:stop()
  => ()

dbg:stopped(
	[$server as xs:unsignedLong]
) as xs:unsignedLong*

Summary:

Return the request ID's of stopped requests in a given server. If server isn't supplied, returns a list of all stopped requests on host.

Parameters:

$server (optional): Server ID.

Required Privilege:

http://marklogic.com/xdmp/privileges/debug-my-requests or http://marklogic.com/xdmp/privileges/debug-any-requests

Example:

  dbg:stopped(204928402983)
  => (2298273928472, 20384203948)

dbg:value(
	$request as xs:unsignedLong,
	[$expr as xs:string]
) as item()*

Summary:

Evaluate an expression in the context of the identified stopped request. If no expression is given and the request is stopped at the end of an expression, then the expression's value is returned.

Parameters:

$request : Request ID.

$expr (optional): Expression string.

Required Privilege:

http://marklogic.com/xdmp/privileges/debug-my-requests or http://marklogic.com/xdmp/privileges/debug-any-requests

Example:

  dbg:value("$var")
  => 5

dbg:wait(
	$request-id as xs:unsignedLong*,
	$timeout as xs:unsignedLong
) as empty()

Summary:

Wait until at least one of the given requests stops or all complete evaluating. Wait will return the empty sequence after a requested timeout if none of the requests have stopped. Otherwise, it returns the request-id of a stopped (or finished) request.

Parameters:

$request-id : Request id's.

$timeout : Requested timeout (in seconds).

Required Privilege:

http://marklogic.com/xdmp/privileges/debug-my-requests or http://marklogic.com/xdmp/privileges/debug-any-requests

Example:

  dbg:wait((23424324342, 843285285))
  => ()