[
https://issues.apache.org/jira/browse/DERBY-1520?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#action_12478624
]
A B commented on DERBY-1520:
----------------------------
Some initial review comments:
1 -- "Derby uses diagnostic table expressions to..."
I think this sentence, while only partial, is already misleading. Derby itself
doesn't "use" the diagnostic table expressions for anything (I don't think).
Rather, Derby provides diagnostic table expressions that a _user_ can use for
purposes of querying different "pieces" of Derby runtime state. Maybe rewrite
to something like:
Derby provides a set of system table expressions which allow a user to
obtain diagnostic information about database state and database sessions.
2 -- As illustrated by the split between DERBY-571 and DERBY-2152, the
diagnostic expressions fall into two categories:
a. diagnostic "tables" (DERBY-571): These are accessed just like any other
table in Derby. That is to say, the user can specify the diagnostic table name
anywhere a normal table name is allowed, with the exceptions as noted in the
document. Ex:
select * from SYSCS_DIAG.LOCK_TABLE
b. diagnostic "table functions" (DERBY-2152): These can take one or more
arguments and thus they must be accessed via the SQL-defined "table function"
syntax, which is:
TABLE (<table-function-name> (<arg-list>)) [ AS ] correlationName
So examples here would be:
SELECT * FROM TABLE (SYSCS_DIAG.ERROR_LOG_READER()) AS t0
SELECT * FROM TABLE (SYSCS_DIAG.ERROR_LOG_READER('somederby.log')) AS t1
SELECT * FROM TABLE (SYSCS_DIAG.SPACE_TABLE('MYTABLE')) AS t2
I think it would be good to mention this split and to divide up the diagnostic
expressions accordingly:
* Diagnostic tables:
- SYSCS_DIAG.ERROR_MESSAGES
- SYSCS_DIAG.LOCK_TABLE
- SYSCS_DIAG.STATEMENT_CACHE
- SYSCS_DIAG.TRANSACTION_TABLE
* Diagnostic table functions:
- SYSCS_DIAG.ERROR_LOG_READER
- SYSCS_DIAG.SPACE_TABLE
- SYSCS_DIAG.STATEMENT_DURATION
3 -- Replace all occurrences of "db2j" with "derby".
4 -- Change:
ErrorLogReader diagnostic table
to
SYSCS_DIAG.ERROR_LOG_READER diagnostic table function
5 -- Might be better to change:
The ErrorLogReader diagnostic table is a virtual table interface (VTI) that
contains...
to
The SYSCS_DIAG.ERROR_LOG_READER table function contains ...
6 -- Change
You can reference the ErrorLogReader diagnostic table directly in a
statement, for example:
SELECT * FROM SYSCS_DIAG.ERROR_LOG_READER()
to
You can access the ERROR_LOG_READER table function by using the table
function syntax and specifying "SYSCS_DIAG.ERROR_LOG_READER" as the
function name. For example:
SELECT * FROM TABLE (SYSCS_DIAG.ERROR_LOG_READER()) AS T1
Note that "T1" here is just some user-specified table name (can be any valid
identifier). Similarly, change
SELECT * FROM SYSCS_DIAG.ERROR_LOG_READER(derbyerrors.log)
to
SELECT * FROM TABLE (SYSCS_DIAG.ERROR_LOG_READER('derbyerrors.log')) AS T1
Note the use of single quotes in the above line since the argument must be a
string. Without the quotes the argument is not a string and the example would
throw a syntax error.
7 -- The following sentence is incorrect:
To specify a log file, you must set the parameter
db2j.language.logStatementText=true
and the log file name must be an expression that evaluates to a STRING data
type.
There are three reasons. First, "db2j" should be "derby" (see #3 above).
Second, derby.language.logStatementText is not a "parameter", it's a
"property". And third, you do *not* need to set that property in order to
specify a log file.
Maybe rewrite this to something like the following:
The SYSCS_DIAG.ERROR_LOG_READER table function takes an optional log file
name.
The file name must be an expression whose type maps to a Java string.
Note that a log file by default contains only boot, shutdown, and error
messages.
See http://db.apache.org/derby/docs/dev/tuning/rtunproper26985.html and
http://db.apache.org/derby/docs/dev/tuning/rtunproper43517.html for details
on how to print more information to Derby log files. You can then query that
information by using the SYSCS_DIAG_ERROR_LOG_READER diagnostic table
function.
8 -- Might be better to change
The ErrorMessage diagnostic table is a virtual table that shows ...
to
The SYSCS_DIAG.ERROR_MESSAGES table shows ...
Note the "s" at the end of ERROR_MESSAGES.
I think you can then apply comments #4 thru #8 to the remaining tables (and
table functions) in the document where appropriate, based on the separation
mentioned in #2. Does that sound reasonable?
And of course, feel free to ask if you have any questions about what I've
written above...
Thanks Laura!
> Document new SYSCS_DIAG tables
> ------------------------------
>
> Key: DERBY-1520
> URL: https://issues.apache.org/jira/browse/DERBY-1520
> Project: Derby
> Issue Type: Sub-task
> Components: Documentation
> Affects Versions: 10.2.1.6
> Reporter: Stan Bradbury
> Assigned To: Laura Stewart
> Attachments: derby1520_1.diff, rrefsyscsdiagtables.html
>
>
> See comments for DERBY-571 for initial documentation discussion. The new
> tables (mapped to the old Diagnostic VTIs) are:
> The old style syntax will remain in place for 10.2, but become deprecated.
> The tables to be implemented in this change are:
> SYSCS_DIAG.LOCK_TABLE replaces org.apache.derby.diag.LockTable
> SYSCS_DIAG.STATEMENT_CACHE replaces org.apache.derby.diag.StatementCache
> SYSCS_DIAG.TRANSACTION_TABLE replaces org.apache.derby.diag.TransactionTable
> SYSCS_DIAG.ERROR_MESSAGES replaces org.apache.derby.diag.ErrorMessages
> The information about the tables can be found in the javadoc for the class
> listed above.
> That can be found at:
> http://db.apache.org/derby/javadoc/engine/
> click on the org.apache.derby.diag link in the Packages table, then select
> each class, e.g. LockTable to see the info.
--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.
