metaonly module xdc.services.global.Trace
index URL

Trace support

This module allows system integrators to selectively enable trace statements, from within XDCscripts. Trace statements can be selected based on the file (capsule) and the package in which they are located. For example, trace statements from file Mod.xs in package myPkgs.pkgA' can be enabled either with Trace.capsuleEnable(["myPkgs/pkgA/Mod"]) or with Trace.packageEnable(["myPkgs.pkgA"])`. [ more ... ]
XDCscript usage meta-domain sourced in xdc/services/global/Trace.xdc
var Trace = xdc.useModule('xdc.services.global.Trace');
module-wide config parameters
    Trace.packageLoad// Enable trace of loaded packages = Bool false;
    Trace.useModule// Enable trace of used modules = Bool false;
module-wide functions
    Trace.addSupergroup// Add a group that contains other groups(String supergroup, String[] subgroups) returns Void
    Trace.capsuleEnable// Enable trace output from selected capsules(String[] capsules) returns String[]
    Trace.groupEnable// Enable trace output from selected groups(String[] groups) returns String[]
    Trace.packageEnable// Enable trace output from selected packages(String[] packages) returns String[]
    Trace.setLevel// Set the verbosity level(Int level) returns Int
 
DETAILS
This module allows system integrators to selectively enable trace statements, from within XDCscripts. Trace statements can be selected based on the file (capsule) and the package in which they are located. For example, trace statements from file Mod.xs in package myPkgs.pkgA' can be enabled either with Trace.capsuleEnable(["myPkgs/pkgA/Mod"]) or with Trace.packageEnable(["myPkgs.pkgA"])`.
Trace statements can also belong to groups, strings defined by package producers when they need to group related trace statements, distributed across different modules and packages, into trace units that can be disabled or enabled as a whole. If some of the trace statements from file Mod.xs are tagged to belong to a group "init", the following will activate them:
  Trace.groupEnable(["init"]);
Each trace statement by default belongs to the group "all". To activate all trace statements:
  Trace.setLevel(2);
  Trace.groupEnable(["all"]);
config Trace.packageLoad  // module-wide
index URL

Enable trace of loaded packages

XDCscript usage meta-domain
Trace.packageLoad = Bool false;
DETAILS
This setting enables the messages related to loading packages. If true, whenever a package is loaded, the following info is displayed:
  • name of a package loading another package
  • name of the loaded package
  • repository from which the package is being loaded
config Trace.useModule  // module-wide
index URL

Enable trace of used modules

XDCscript usage meta-domain
Trace.useModule = Bool false;
DETAILS
This setting enables the messages that inform when the function xdc.useModule() is invoked on a module, and when a module's module$use function is invoked.
Trace.addSupergroup()  // module-wide
index URL

Add a group that contains other groups

XDCscript usage meta-domain
Trace.addSupergroup(String supergroup, String[] subgroups) returns Void
ARGUMENTS
— supergroup name of the new group
subgroups array of the existing trace groups
DETAILS
This function allows giving a name to an array of existing trace groups.
Trace.capsuleEnable()  // module-wide
index URL

Enable trace output from selected capsules

XDCscript usage meta-domain
Trace.capsuleEnable(String[] capsules) returns String[]
DETAILS
Capsules are either XDCscript files or Java source files. The function parameter is treated as an array of JavaScript regular expressions, therefore it can contain partial capsule names.
If this function is invoked repeatedly, each new call replaces the array of currently enabled capsules with the array supplied as the parameter. The array of the currently enabled capsules is returned. If the function is invoked with a zero-length array, it returns the currently enabled capsules, but it also leaves them active. Therefore, the sequence of calls that would add new capsules instead of replacing the current ones is:
  var current = Trace.capsuleEnable([]);
  current[current.length++] = "pkg/ModA.xs";
  current[current.length++] = "pkg/ModB.xs";
  Trace.capsuleEnable(current);
To disable trace for all capsules, the function must be invoked with an empty string as the only element of the array.
  Trace.capsuleEnable([""]);
PARAMS
capsules array of capsule names
RETURN
array of currently enabled capsule names
Trace.groupEnable()  // module-wide
index URL

Enable trace output from selected groups

XDCscript usage meta-domain
Trace.groupEnable(String[] groups) returns String[]
DETAILS
A group is a string defined by package producers when they need to group related trace statements, distributed across different modules and packages, into trace units that can be disabled or enabled as a whole. The function parameter is treated as an array of JavaScript regular expressions, therefore it can contain partial group names.
If this function is invoked repeatedly, each new call replaces the array of currently enabled groups with the array supplied as the parameter. The array of the currently enabled groups is returned. If the function is invoked with a zero-length array, it returns the currently enabled groups, but it also leaves them active. Therefore, the sequence of calls that would add new groups instead of replacing the current ones is:
  var current = Trace.groupEnable([]);
  current[current.length++] = "libPkgs";
  Trace.groupEnable(current);
To disable trace for all groups, the function must be invoked with an empty string as the only element of the array.
  Trace.groupEnable([""]);
PARAMS
groups array of groups
RETURN
array of currently enabled groups
Trace.packageEnable()  // module-wide
index URL

Enable trace output from selected packages

XDCscript usage meta-domain
Trace.packageEnable(String[] packages) returns String[]
DETAILS
Packages that can be enabled through this function are RTSC packages and Java packages. The function parameter is treated as an array of JavaScript regular expressions, therefore it can contain partial package names.
If this function is invoked repeatedly, each new call replaces the array of currently enabled packages with the array supplied as the parameter. The array of the currently enabled packages is returned. If the function is invoked with a zero-length array, it returns the currently enabled packages, but it also leaves them active. Therefore, the sequence of calls that would add new packages instead of replacing the current ones is:
  var current = Trace.packageEnable([]);
  current[current.length++] = "ti.targets";
  Trace.packageEnable(current);
To disable trace for all packages, the function must be invoked with an empty string as the only element of the array.
  Trace.packageEnable([""]);
PARAMS
capsules array of package names
RETURN
array of currently enabled package names
Trace.setLevel()  // module-wide
index URL

Set the verbosity level

XDCscript usage meta-domain
Trace.setLevel(Int level) returns Int
DETAILS
This function limits trace output to trace statement tagged with level equal or lower than this function's parameter. By default, the verbosity level is set to 0, which is the least verbose level. The most verbose level is 2.
generated on Tue, 24 Aug 2010 15:39:25 GMT