| XQUERY/XSLT API DOCUMENTATION 4.2 |
All XQuery & XSLT Functions MarkLogic Built-In Functions Admin (xdmp:) AppServer (xdmp:) Classifier (cts:) Debug (dbg:) Document Conversion (xdmp:) Extension (xdmp:) Documents, Directories, Properties, and Locks Functions Extension Functions Function Values Functions HTTP Functions JSON Functions MarkLogic Server Functions Search Functions XML Functions XQuery Context Functions XSLT Functions map (map:) Math (math:) Profile (prof:) Search (cts:) cts:query Constructors Functions Geospatial Functions Geospatial Lexicon Functions Lexicon Functions Search Functions Search Clustering Functions Security (xdmp:) Server Monitoring (xdmp:) Spell (spell:) Update (xdmp:) XQuery Library Modules Admin Library (admin:) Actions Functions Appserver Functions Database Functions Forest Functions Group Functions Host Functions Mimetypes Functions Scheduler Functions Alerting (alert:) Elastic Compute Cloud (ec2:) Entity Enrichment (entity:) Flexible Replication (flexrep:) Geospatial Supporting Functions GEO Functions GeoRSS Functions GML Functions KML Functions MCGM Functions Information Studio (info:) Information Studio Developer (infodev:) Library Services (dls:) cts:query Constructor Functions Document Management Functions Document Update Functions Retention Policy Functions XInclude Functions Modular Documents XInclude Functions XPointer Functions PKI (pki:) Plugin (plugin:) Search (search:) Security-sec (sec:) Spelling Dictionary Management (spell:) Thesaurus (thsr:) Triggers (trgr:) Triggers Library (trgr:) WordProcessingML (ooxml:) ZIP Package (ooxml:) CPF Functions Content Processing Framework (cpf:) CSS Conversion (css:) DocBook Conversion (dbk:) Domains (dom:) Excel Conversion (excel:) Generic Conversion (cvt:) Links (lnk:) MSWord Conversion (msword:) PDF Conversion (pdf:) Pipelines (p:) Powerpoint Conversion (ppt:) XHTML Conversion (xhtml:) W3C-Standard Functions Accessor (fn:) AnyURI (fn:) Boolean (fn:) Context (fn:) DurationDateTime (fn:) Error and Trace (fn:) Node (fn:) Numeric (fn:) QName (fn:) Sequence (fn:) String (fn:) XSLT (fn:) W3C XQuery/XSLT Reference W3C XQuery Functions W3C XQuery Language W3C XSLT Language
This page was generated September 12, 2012 6:01 AM | XQuery & XSLT Built-In & Modules Function Reference
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:connected | Return the ID's of servers that are connected by the debugger.
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-sequence()
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-sequence()
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-sequence()
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-sequence()
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:connected( ) as xs:unsignedLong*
Summary: Return the ID's of servers that are connected by the debugger.
Required Privilege: http://marklogic.com/xdmp/privileges/debug-any-requests
Example:
      dbg:connected()
      => (2298273928472, 20384203948)
dbg:continue(
| $request as xs:unsignedLong
) as empty-sequence()
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-sequence()
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-sequence()
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. Requests evaluated for debugging with `dbg:eval` are evaluated on the task server, not on the App Server in which they are initiated.
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. The default value is (). The node for the `dbg:eval` options must be in the `xdmp:eval` namespace. See the `xdmp:eval` section for a list of options.
Required Privilege: http://marklogic.com/xdmp/privileges/debug-my-requests or http://marklogic.com/xdmp/privileges/debug-any-requests
Example:
      dbg:eval("1+1")

    => The ID of the request stopped for debugging
       (for example, 1767394036047154157).  The
       request is evaluated on the task server, and
       you can use the ID to pass into one of the other
       debug functions (for example, dbg:continue or
       dbg:step) to debug the request.
Example:
    xquery version "1.0-ml";

    dbg:eval("xdmp:log(xs:string(xdmp:estimate(doc())))", (),
      <options xmlns="xdmp:eval">
        <database>{xdmp:database("Documents")}</database>
      </options>
    )

    => The ID of the request stopped for debugging
       (for example, 13942194686892174312).  The
       request is evaluated on the task server, and
       this request will use the "Documents" database
       as its context database.  You can use the ID to
       pass into one of the other debug functions
       (for example, dbg:continue or dbg:step) to
       debug the request.
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-sequence()
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. The default value is (). The node for the `dbg:eval` options must be in the `xdmp:eval` namespace. See the `xdmp:eval` section for a list of options.
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-sequence()
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-sequence()
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">
          <expr>
            <expr-id>16429173930674134530</expr-id>
            <expr-source>xdmp:sleep(1000)</expr-source>
            <uri>/long.xqy</uri>
            <line>11</line>
          </expr>
          <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-sequence()
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-sequence()
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(13334971433974783708, "$var")
      => 5
      where 5 is the value of the $var variable for the stopped request
dbg:wait(
| $request-id as xs:unsignedLong*,
| $timeout as xs:unsignedLong
) as xs:unsignedLong?
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))
      => ()

© Copyright 2002-2012 MarkLogic Corporation. All rights reserved.