|
Troubleshooting
Record Builder Errors
Contents
Introduction
Document Conventions
Log Files
Using Record Builder Logs
Troubleshooting Example
Checking for Database Corruption
For Additional Assistance
Introduction
This document describes
how to identify and correct the source of errors in the Record
Builder application included with OCLC Database Builder. Record Builder
documents many errors in its log files. After discussing the types and
locations of Record Builder's log files, the topic presents a generic
procedure for using the log files to diagnose errors and an example of
troubleshooting an error that occurred at a customer's site.
Document
Conventions
- <WebZ_root>
is the location of the SiteSearch environment that contains the Record
Builder application.
- database_dir
is a database's top-level directory.
- Examples from
logs or configuration files may contain continuation characters ("\")
for readability. These characters do not appear in the actual files.
Log
Files
When Record Builder
staff receive errors when they try to view, edit, copy, or delete records,
the Record Builder application's log files often contain information that
will help you find and then correct the source of the problem. There are
two places to look for log files – the database's log directory
and the Record Builder server and user logs.
Database Log Files
Each local database
has its own update_logs directory, <WebZ_root>/dbbuilder/dbs/database_dir/updatelogs.
If an error occurs when a
staff member tries to submit an online update to the database (adding
a new record or modifying, deleting, or copying an existing record), Record
Builder may create a record of the error within this directory. Record
Builder creates a new directory named editsession_id (where editsession_id
is the numeric identifier of the edit session where
the error occurred), and puts two files in this directory – online_update.log
and update.ber, as shown in the following example of the directory structure:
| <WebZ_root>/dbbuilder/dbs/database_dir/updatelogs/ |
| | |
editsession_id/ |
|
| |
|
| |
online_update.log
update.ber |
|
update.ber is the
BER record that triggered the error. online_update.log is a text file
that contains specific information about the error. Click
here to see an example of an online_update.log file.
Server and
User Log Files
Each server's configuration
(.ini) file contains variables that specify the name and location of its
log files. The Record Builder application's server and user logs reside
in <WebZ_root>/logs by default. All Record Builder server
and user logs contain the characters "_rb" in their names.
The JaSSIRB user
and server log files are generally the most useful log files for troubleshooting
Record Builder system errors.
Tips
for Navigating WebZ Log Files
The following
are recommendations for identifying the section of a log file where a
problem was recorded.
- Limit the
number of databases. Only configure databases in the databases_rb.ini
file that are directly related to the problem. Comment out the remaining
databases in the databases_rb.ini file to make them inactive, making
sure that the remaining active database variables contain asterisks
or are configured in numerical order. Record Builder does not have to
load and initialize any databases that are not configured in the databases_rb.ini
file, shortening the length of the JaSSIRB server and user log files.
- Search the
log file for the word "Exception." Whenever Record Builder displays
an error HTML page (<WebZ_root>/rbv0/htdocs/error) in
the interface, an exception has been thrown in the Open SiteSearch Java
code. Finding the word "Exception" in the log file locates the point
in the session where the problem occurred, listing the specific Java
classes that did not work correctly or as expected.
- Search the
log file for the term. Locate the actual search term you used to
perform a search in the Record Builder interface during your user session
when re-creating the problem. The search term may isolate the location
in the log file where the problem is documented.
- Search the
log file for a specific HTML page or Java class. If you suspect
you know where the problem is occurring, search the log file for the
name of the HTML page or Java class to isolate the location in the log
file that documents the problem.
Using
Record Builder Logs
The following
procedure describes how to use the Record Builder application's log files
to recreate, isolate, and track a problem with the Record Builder application
by tracing and logging each action completed by the system and/or a user
in the Record Builder interface.
|
1. Shut
down the Record Builder application.
|
|
2. In the
<WebZ_root>/logs directory, make backup copies of
existing Record Builder log files (those that with "_rb"
in their names) you want to keep in a separate directory and remove
the remaining log files.
|
| 3. If the error
is confined to a specific database or appears to occur in all databases,
consider limiting the number of databases
running while you generate new log files. |
|
4.
Restart the Record Builder application.
|
|
5. Before
completing any other tasks, set logging for one or more Record Builder
servers to "TRACE_ALL" using the settrace
command in the ssadmin interface.
By default upon installation, the Record Builder application tracks
minimal system activity and stores it in the <WebZ_root>/logs
directory. By setting the settrace command to "TRACE_ALL" for a
specific log file(s), Record Builder tracks more detailed information
about system and user activity. Below is a list of each type of
log file that Record Builder can create and maintain:
- access_rb.serverLog
- jassi_rb.serverLog
- jassi_rb.userLog
- opserve_rb.serverLog
- zbase_rb.serverLog
In most
instances, the JaSSRB user and server log files are the most useful
log files for troubleshooting the system.
|
|
6. Recreate
the problem in the WebZ interface (perform the same search (exactly)
again, move to a specific HTML page to check what information is
being sent through the URL, etc.).
|
|
7. Exit
your session and log off immediately after the problem occurs.
|
|
8. Shut
down the Record Builder application.
|
|
9. Move
to the <WebZ_root>/logs directory and review the
log files to locate information about the problem. See Tips
for Navigating Record Builder Log Files for recommendations
on how to navigate through the log files to quickly find the problem.
|
| 10. Restart
the Record Builder application after
you isolate and correct the source of the problem. |
Troubleshooting
Example
The following example
illustrates the troubleshooting process in a Record Builder problem that
occurred at a customer site. It includes selected portions of from log
files. Particular lines of interest in the log files appear in bold,
blue text.
Problem
Record Builder displays
the error page <WebZ_root>/htdocs/rbv0/error/failurepage.html
when a staff member conducts a search to locate a record and then clicks
a record's title to view a record in full format or clicks the Edit Record
icon beside a record's title to edit the record on the Search Results
screen:
System
Failure Page: Unable to successfully complete
transaction.
Problem Resolution
| 1. Record Builder
writes an exception message to the jassi_rb.serverLog whenever it
displays an error page. Therefore, start by searching the jassi_rb.serverLog
in <WebZ_root>/logs for the term "Exception". |
|
2. The search
yields the following exception entry:
[D20000120.T135202.322] [Thread:9483943214567252] \
[ORG.oclc.jassi.RequestManager]
Class Execution Error : Exception thrown executing class: \
'ORG.oclc.mantis.obi.mantisscreen'.
java.lang.StringIndexOutOfBoundsException: String index out of range:0
at java.lang.Throwable.<init>(Compiled Code)
at java.lang.Exception.<init>(Compiled Code)
at java.lang.RuntimeException.(Compiled Code)
at java.lang.IndexOutOfBoundsException.<init>(Compiled Code)
at java.lang.StringIndexOutOfBoundsException.<init>(Compiled Code)
at java.lang.String.charAt(Compiled Code)
at ORG.oclc.jassi.RequestManager.doEntitySubstitution(Compiled Code)
at ORG.oclc.jassi.RequestManager.doEntitySubstitution(Compiled Code)
at ORG.oclc.jassi.RequestManager.doEntitySubstitution(Compiled Code)
at ORG.oclc.jassi.RequestManager.executeCommand(Compiled Code)
at ORG.oclc.jassi.RequestManager.processCommand(Compiled Code)
at ORG.oclc.jassi.JaSSI.doCommands(Compiled Code)
at ORG.oclc.jassi.JaSSI.runUser(Compiled Code)
at ORG.oclc.jassi.JaSSI.run(Compiled Code)
This exception
occurred during entity substitution while the mantisscreen class
(ORG.oclc.mantis.obi.mantisscreen)
was running after the View Record screen,
<WebZ_root>/htdocs/rbv0/html/display.html, called it
via an <oclc-app> tag.
|
| 3. To see what
entity is causing this problem, change tracing for the JaSSIRB user
log to TRACE_ALL with
the settrace command
in the ssadmin interface.
|
|
4. Duplicate
the error:
|
|
5. Examine
entity substitution for the mantisscreen class in the JaSSIRB user
log (in <WebZ_root>/logs) near the place where Record
Builder displayed the system failure page.
In the log
sample shown, starting from the Action
Object for failurepage.html [1],
and working backward, there is an entry for the entity 'StyleTable.i'
[2]. Again, working backward,
you can see that this is part of the PrevRec entity [3].
[D20000120.T135202.309] [RequestManager.doEntitySubstitution()]
Exit method.
Entity type = ';'
Entity = 'PrevRec' <---- [3]
Entity Value = '<a href="&StyleTable.DEFAULTS.NAMESPACE;MDISPLAY?&context; \
&recno=&prevrecno;&resultset=&resultset; \
&format=F&next=&StyleTable.pages.fullDisplay; \
&bad=&StyleTable.pages.badfetch;" &styletable.targets.recorddisplay;> \
<img border=0 src="&StyleTable.im'
[D20000120.T135202.311] [RequestManager.doEntitySubstitution()]
Enter method.
Entity type = ';'
Entity = 'StyleTable.DEFAULTS.NAMESPACE'
Entity Value = '/WebZ/'
Entity type = ';'
Entity = 'context'
Entity Value = 'sessionid=01-32867-898106160'
Entity type = '&'
Entity = 'recno='
Entity Value = 'null'
Entity type = ';'
Entity = 'prevrecno'
Entity Value = '1'
Entity type = '&'
Entity = 'resultset='
Entity Value = 'null'
....
Entity type = ''
Entity = 'StyleTable.targets.recordDisplay'
Entity Value = ''
Entity type = ''
Entity = 'StyleTable.i' <---- [2]
Entity Value = ''
[D20000120.t135202.343] [RequestManager.executeCommand()]
Exit method.
[D20000120.t135202.345] [Action.init()]
Enter method.
[D20000120.t135202.346] [Action.init()]
---------------
Action Object
---------------
uri = /WebZ/error/failurepage.html
documentRoot = /sswork/recbuilder410/htdocs/rbv0/
nameSpace = /WebZ/
nextCmd =
className = /webz/error/failurepage.html <---- [1]
mimeTypeExt = html
rawWidgets =
widgets = []
[D20000120.T135202.347] [Action.init()]
Exit method.
|
|
6. Because
the entity is a style table entity, look in Record Builder's interface
configuration file style files for the PrevRec entity. The [InterfaceStyles]
section of JaSSIServer_rb.ini indicates that <WebZ_root>/ini/interface/rbv0/RBStyle.ini
is Record Builder's interface style file. While RBStyle.ini refers
to a number of other configuration files, it turns out that RBStyle.ini
contains the PrevRec entity:
prevrec = <a href="&StyleTable.DEFAULTS.NAMESPACE;MDISPLAY?&context; \
&recno=&prevrecno;&resultset=&resultset; \
&format=F&next=&StyleTable.pages.fullDisplay; \
&bad=&StyleTable.pages.badfetch;" \
&styletable .targets.recorddisplay;><img border=0 src="&StyleTable.im
ages.prev;" ALT="Previous Record"></a>
The problem
is that there is a line break (carriage return) in the entity reference
&StyleTable.images.prev;.
In entity references, a line break without a continuation character
(\) signals the end of the entity, so the prevrec entity became
truncated in Record Builder's style table. When JaSSIRB performed
entity substitution on the entities within prevrec, it looked in
the style table for an [im] section, which doesn't exist. This caused
the exception in JaSSIRB's server log and sent the System Failure
Page to the user.
|
| 7. Remove the
line break in RBStyle.ini to correct the problem. Then verify that
the error no longer exists. |
Checking
for and Resolving Database Corruption
If the errors that
you receive seem to indicate that the database may be corrupted, use the
SiteSearch Database Operations Tool
(SSDOT) to validate the database.
If the messages in the validation log confirm that the database is corrupted,
see Recovering a Corrupted Record Builder
Database for a recovery procedure.
For
Additional Assistance
If you cannot resolve
Record Builder errors after following the procedures described in this
document, contact SiteSearch
Support.
See Also
Record
Builder Administration
ssadmin Command Reference
|