76 Logging and Debugging Errors

WebCenter Sites logs its activity in a log file, which in a new installation, is named sites.log, located in the logs folder. The type and volume of information that is written to the log file is controlled by the loggers that you choose to enable or define. WebCenter Sites also has a reserved variable that is used by JSP and XML tags for returning an error code if the tag did not successfully complete its task.

Topics:

76.1 About Writing Custom Messages to the WebCenter Sites Log File

You use the log ODL tool to view loggers and add new loggers. If you would like to write your own log messages to the WebCenter Sites log file, use the ics:logmsg tag.

WebCenter Sitesuses log ODL logging system. In log ODL, the loggingconfig.xml file specifies which information will be logged and how. The Admin interface provides the Configure Log ODL tool in the System Tools node, on the Admin tab. Using Configure Log ODL, you can configure log ODL and view loggers in the Admin interface. You can also dynamically add new loggers and change logger levels. Changes will persist upon system restart if you copy the text version of the loggers from the interface to the loggingconfig.xml file. See Using the Configure Log ODL Tool in Administering Oracle WebCenter Sites.

To define your own loggers or write your own messages to the WebCenter Sites log file, use the ics:logmsg tag. The following example writes a warning message to the WebCenter Sites log file.

<ics:logmsg msg="This is a warning message"
  name="com.fatwire.logging.cs.jsp" severity="warn"/>

For more information about ics:logmsg, see the Tag Reference for Oracle WebCenter Sites.

Note:

It is recommended that you set loggers to a level that agrees with the type of system on which logging is implemented. On development and content management systems, logging levels can be set to a greater severity (such as INFO or DEBUG), which provides a large amount of information. On delivery systems, loggers can be either disabled or set to low severity (WARN or ERROR) to avoid performance setbacks and making system information available on a publicly accessed environment.

76.2 Using Error Codes with Tags

You can use a reserved variable named Variables.errno in WebCenter Sites when the JSP and XML tags don’t successfully complete their task. Most JSP and XML tags use this variable for returning error codes (generally referred to as "errno").

For example, the <CALLELEMENT> XML tag sets Variables.errno as follows:

-10: If you specified a nonexistent element.
-12: If you specified an existing element that WebCenter Sites could not evaluate.

On success, <CALLELEMENT> does not modify the value of Variables.errno.

Note:

For revision tracking operations, the reserved variable named Variable.errdetails provides additional information about the error.

Use the following strategy with tags that use Variables.errno:

Initialize Variables.errno to 0 before calling the tag.
Call the tag.
Evaluate Variables.errno.

Tag Examples Using Error Codes

For example, the following code performs all three steps:

<SETVAR NAME="errno" VALUE="0"/>
<SETCOUNTER NAME="pi" VALUE="3.14159"/> 
  <IF COND="Variables.errno=-501">
    <THEN>
      <p>Bad value of pi</p>
    </THEN>
  </IF>

Running this code yields the following HTML because SETCOUNTER cannot handle floating-point values:

<p>Bad value of pi</p>

The ASSET, RENDER, and SITEPLAN tags clear errno before they execute. You do not have to set errno to 0 when you use these tags. For example, after you use an ASSET tag, just check the value of errno to determine whether it has changed:

<ASSET.LOAD NAME="topArticle" TYPE="Article" 
OBJECTID="Variables.cid"/>
  <IF COND="IsError.Variables.errno=false">
    <THEN>
      <ASSET.CHILDREN NAME="topArticle" LIST="listOfChildren"/>
    </THEN>
  </IF>

At the end of template elements, include error checking code such as this:

<IF rendermode="preview">
  <THEN>
    <IF COND="IsError.Variable.errno=true">
      <THEN>
        <FONT COLOR="#FF0000">
         Error <CSVAR NAME="Variables.errno"/>
         while rendering <CSVAR NAME="pagename"/> 
         with asset ID <CSVAR NAME ="Variables.cid"/>.
        </FONT>
      </THEN>
    </IF>
  </THEN>
</IF>

Java Interface

After making calls to WebCenter Sites, the String variable errno can be retrieved and tested for success or failure. Here's an example:

cs.clearErrno();

IList rslt = cs.SelectTo(SYSTEMUSERS_TABLE, ALL_FIELDS, USERNAME, 
             null, NO_LIMIT, null, CACHE_RESULTS, errstr);

errno = cs.GetVar("errno");

if (errno.compareTo(ERRNO_SUCCESS) == 0)
    {
     ...

Error Number Rules

Error numbers are always integers. This table summarizes error numbering rules for Variables.errno.

See the Tag Reference for Oracle WebCenter Sites for specific error numbers for each tag.

Table 76-1 Error Number Rules

Number	Significance
Negative integers	Failure
0 (zero)	Success
Positive integers in a tag other than a revision tracking tag.	Information
Positive integers in a revision tracking tag.	Failure