db-derby-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "A B (JIRA)" <j...@apache.org>
Subject [jira] Commented: (DERBY-1520) Document new SYSCS_DIAG tables
Date Tue, 06 Mar 2007 23:20:24 GMT

    [ 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.


Mime
View raw message