trace Command

Server diagnostic tools allow the following trace information to be sent either to a file or to standard output (the “destination”).

This page discusses:

User Level

System Administrator

Syntax

The command uses this syntax. 

trace type TYPE{,TYPE}|filename FILENAME | [not full];
                      |on                |
                      |off               |
                      |text STRING       |

Or: 

trace |off   |
      |pause |
      |resume|

Type Clause

TYPE is the type of tracing to affect and is one of the following:

Type Value Additional Information 
access
 
ACL
 Enables the accesslist trace that creates entries for these actions:
  • Delete access rule
  • Delete user
  • Businessobject promote, demote, copy, revise
  • Delete business object
  • setOwner
  • setOrganization
  • setProject
  • Add or remove ownership
  • Change rel accessrule
  • Change user hierarchy
  • Change expression
  • Edit access rule
  • Change project maturity or organization category
  • Add or delete user credentials
  • Transaction commit
  • List accesslist modified after DATE select valid obsolete 
ds
 
fcs
 
FLOK
 Lists the locks when performing FCS operations. When enabled, the command outputs details about these locks:
  • locks on LXBO table
  • lock on lxFILE table
  • locks and inserts in mxFileAux

Traces are generated above the mxHandle level, so the same lines could be printed multiple times even if no new locks are made because of the kernel cache.

 
ftp
 
index
 
jpo
 Enables JPO compilation or invocation messages to be output. Enabling only the verbose keyword will not produce this particular output. 
ldap
 
logwriter
 Turns on Studio Customization Toolkit tracing. If no filename is included it will create ematrix.log in the MX_TRACE_FILE_PATH directory. Use of OTHER_TYPE is recommended over use of logwriter. 
memory
 Turns on memory manager tracing. You can enable more verbose memory tracing via an environment variable only. For more information, see Installation Guide: Server Diagnostics . 
mql
 
nul
 
OTHER_TYPE
 Allows the definition of a user-defined tracing type, for example , “My Trace.” Programmers can embed tracing messages in their implementation code to provide strings to be output to the trace file of type OTHER_TYPE using the following: 
trace type OTHER_TYPE text STRING;

With these types of messages within programs, you would then enable the tracing with one of the following: 

trace type OTHER_TYPE on;
trace type OTHER_TYPE filename FILENAME;

 
searchindex
 
smtp
 
sql
 This low level trace type is liable to generate a large amount of output data which will affect performance. 
store
 Use with the trace type command, so that when synchronizing or purging stores a log file can be created that indicates the success or failure of every file and business object. 
trigger
 
verbose
 This low level trace type is liable to generate a large amount of output data which will affect performance. For more information, see Verbose Keyword. 
verbose_origin
 Turns the ADK Origin Trace on or off using the MQL command. Verbose_origin is not a recognized environment variable. 
ws

To turn on or turn off the verbose trace and origin trace at the same time, use verbose_origin trace type with the following: 

trace type TYPE on/off/filename FILE

To configure ADK origin trace at start up, use MX_ADK_TRACEALL=TRUE and MX_VERBOSE_TRACE=XXXX features that you can set in mxEnv.sh / ENOVIA.ini.

This feature does not work for clients using XML ADK (matrix.db.Context with protocol set to http: which use MatrixXMLServlet.) You can generate stack trace information from the XML client side only if the XML client side calls one of the matrix.db.Context methods which enables stack trace generation.

Verbose Keyword

The keyword verbose enables more details to be output. It also enables Studio Customization Toolkit Origin tracing when classes to trace are defined with MX_ADK_TRACEALL environment variable or using the name as the keyword. The keyword logwriter can be used to turn on Studio Customization Toolkit tracing. If no filename is included it will create ematrix.log in the MX_TRACE_FILE_PATH directory. Use of OTHER_TYPE is recommended over use of logwriter. The output below shows the following calling stack to illustrate both the timing and automatic Studio Customization Toolkit origin tracing: a JSP page calls to the kernel using the Studio Customization Toolkit interface MQLCommand.executeCommand() with the command 'exec program JPOGetAttr'. The Java Program Object JPOGetAttr is called from within the kernel. The JPOGetAttr makes further Studio Customization Toolkit calls to:

  1. Context.reset to establish 'creator' as current context
  2. BusinessObject.open to open the object 't3 t3-1 0'
  3. BusinessObject.getAttributes to get the object's attributes
  4. Context.getClientTask to retrieve ClientTasks, if any.

For readability, the lengthy session id has been shortened, and the full path name of the JSP has been shortened from org.apache.jsp.common.emxRunMQL_jsp to show only the last level: 

19:04:27.902 VERB t@2672 stateless dispatch for executeCmd.bosMQLCommand
19:04:27.902 VERB t@2672 allocate context for session 49XX:mxYY:(emxRunMQL_jsp:521)
19:04:27.902 VERB t@2672   input params: cmd=exec prog  JPOGetAttr;
19:04:27.902 MQL  t@2672 Start MQLCommand: exec prog  JPOGetAttr;
19:04:27.912 MQL  t@2672 Session: 49XX:mxYY:(emxRunMQL_jsp:521)
19:04:27.912 MQL  t@2672 Program: JPOGetAttr
19:04:27.912 MQL  t@2672    args:

19:04:27.912 VERB t@2672 stateless dispatch for allocExternalContext.bosInterface
19:04:27.912 VERB t@2672   input params: sessionId=49XX:mxYY:(emxRunMQL_jsp:521), stackTrace=
19:04:27.912 VERB t@2672 dispatch complete since 19:04:27.912, 0.000 secs (0.000 direct 0.000 nested)

19:04:27.912 VERB t@2672 stateful dispatch for reset.bosContext
19:04:27.912 VERB t@2672   input params:   (session=49XX:mxYY:(emxRunMQL_jsp:521)), user=creator, passwd=, lattice=
19:04:27.922 VERB t@2672   output params: returnVal=creator
19:04:27.922 VERB t@2672 dispatch complete since 19:04:27.912, 0.010 secs (0.010 direct 0.000 nested)

19:04:28.012 VERB t@2672 stateless dispatch for openTNRV.bosBusinessObject
19:04:28.012 VERB t@2672 allocate context for session 49XX:mxYY:(emxRunMQL_jsp:521)
19:04:28.012 VERB t@2672   input params: name=t3, type=t3-1, rev=0, vault=unit1
19:04:28.012 VERB t@2672   output params: returnVal objectid=62869.36236.33703.1576
19:04:28.012 VERB t@2672 dispatch complete since 19:04:28.012, 0.000 secs (0.000 direct 0.000 nested
19:04:28.012 VERB t@2672 stateless dispatch for getAttributes.bosBusinessObject
19:04:28.012 VERB t@2672 allocate context for session 49XX:mxYY:(emxRunMQL_jsp:521)
19:04:28.012 VERB t@2672   input params: id=62869.36236.33703.1576, getHidden=0
19:04:28.032 VERB t@2672 dispatch complete since 19:04:28.012, 0.020 secs (0.020 direct 0.000 nested)

>>>> End of program execution: 
19:04:28.052 MQL  t@2672 End Program: JPOGetAttr since 19:04:27.912, 0.140 secs (0.110 direct 0.030 nested)
19:04:28.062 MQL  t@2672 End MQLCommand
>>>> End of invocation of MQLCommand.executeCommand: 
19:04:28.062 VERB t@2672 dispatch complete since 19:04:27.902, 0.160 secs (0.160 direct 0.000 nested)
19:04:28.062 VERB t@2672 stateful dispatch for getClientTask.bosContext
19:04:28.062 VERB t@2672   input params:   (session=49XX:mxYY:(emxRunMQL_jsp:521))
19:04:28.062 VERB t@2672   output params: returnVal length=0
19:04:28.062 VERB t@2672 dispatch complete since 19:04:28.062, 0.000 secs (0.000 direct 0.000 nested)

File Clause

Specifying a file with the file FILENAME clause turns the specified type of tracing on, and redirects the output to the specified file. There is no need to use the keyword “on”. If a filename has already been specified for another type of tracing within the current session, that filename will be used, and the one specified here will be ignored, but the tracing will be enabled.

If the filename specified for any tracing already exists in the directory MX_TRACE_FILE_PATH, that existing file will be copied to a backup whose name is constructed by prepending a time-specific prefix to the filename, in the form “yyyymmddhhmmss__FILENAME.”

On Clause

The on modifier will turn the specified tracing on and send the trace information to stdout, unless a trace file is already in use by another type of tracing.

The On clause for the Trace command is not supported in the Windows Studio version of MQL. This applies only to the 3DEXPERIENCE Platform (PC rich client). Tracing does work for UNIX and for the console version that is shipped together with the Server.

Off Clause

The off clause turns the specified type of tracing off. If other tracing types have been turned on, they will stay on. Tracing that is turned on via .ini file settings can only be turned off using the keyword all. For example: 

trace type SQL off;
trace type all off;

When all types of tracing directed at the same file are turned off, the file is closed. In order to resume tracing to a file, any subsequent command must specify a filename. If it doesn’t, tracing will be resumed with stdout as the destination.

Instead of having to turn trace types off type-by-type, you can use ‘off’ with no trace type specified to turn all currently active tracing off and to close and unset the destination. 

trace off [thread];

Pause/Resume Clause

You can use pause to make all the currently active trace types inactive. No tracing output will be produced until a ‘trace resume’ command is issued. Both the list of trace types and the destination are retained, so resume will pick up tracing the same types of information to the same place as it was before pausing. If tracing is not paused, trace resume has no effect. 

trace |pause  |;
      |resume |

Not Full Clause

Trace output includes timestamp information, which you can turn off with the notfull clause. You can also use !full. To re-enable, use the full clause. This is helpful with SQL tracing so that you can use the SQL without editing it.

Print Trace

The print trace command outputs information for all trace settings, as illustrated by the following trace commands. 

MQL<3>trace type mql,sql filename mqlsql.log;
MQL<4>trace pause;
MQL<5>print trace;
All thread trace:
   type = MQL,SQL
   pathname = c:\ematrix9\logs
   filename = mqlsql.log <paused>
   full = TRUE

In the above example, when tracing is paused, it is marked by <paused> after the filename.

If tracing is turned off, the type and filename fields will be empty.

Errors

If tracing is currently active with a defined destination and you turn on additional tracing with a different destination, the system will inform you of the current defined destination in a warning, and your added tracing will be streamed to the current destination as well. For example: 

MQL<16>trace type sql filename sql.log;
MQL<18>print trace;
Trace:
   type = SQL
   pathname = c:\ematrix9\logs
   filename = sql.log
   fulllabel = TRUE
MQL<19>trace type mql filename mql.log;
Warning: #1600078: Filename mql.log ignored. Tracing already active to file c:\ematrix9\logs/sql.log