[jira] Commented: (DERBY-1520) Document new SYSCS_DIAG tables

["Laura Stewart (JIRA)" <ji...@apache.org>]

    [ https://issues.apache.org/jira/browse/DERBY-1520?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#action_12472953 ] 

Laura Stewart commented on DERBY-1520:
--------------------------------------

I am preparing the topic in the Reference Guide that will describe these tables
and need some clarification.  I will be summarizing what is in the JavaDoc and 
the text used in the JavaDoc concerns me.  For example, for LockTable the text says:

****************************************************
LockTable is a virtual table that shows all of the locks currently held in the database.
This virtual table can be invoked by calling it directly
select * from SYSCS_DIAG.LOCK_TABLE
The LockTable virtual table takes a snap shot of the lock table while the
system is in flux, so it is possible that some locks may be in transition
state while the snap shot is taken. We choose to do this rather then impose
extranous timing restrictions so that the use of this tool will not alter
the normal timing and flow of execution in the application. 
****************************************************

1)  When a user issues a statement that references the SYSCS_DIAG.LOCK_TABLE, is that when the "snap shot" is taken?
2) I am concerned with the phrase "invoked by calling it directly"  because this can be interpreted as a CALL statement.  
I would prefer to say something like "invoked by referencing the table directly".  
3) The text refers to a "tool" but really means the virtual table... yes?  There really isn't a tool (aka utility) that is used?
4) Is it more correct to refer to this as the Lock Table diagnostic table or the Lock Table virtual table?
5) What impact on the user/application is there as a result of the fact that some of the locks will be in transition state?  Any action that should be taken by the user/application?

In describing the LockTable diagnostic table, I drafted the following text. I would appreciate any comments on incorrect/inaccurate terms/phrases:

****************************************************
The LockTable diagnostic table is a virtual table that shows all of the locks currently held in the database.
You invoke this diagnostic table by specifing the table name in statement, for example:

SELECT * FROM SYSCS_DIAG.LOCK_TABLE

When the LockTable diagnostic table is referenced in a statement, a snap shot of the lock table is taken. 
A snap shot is used so that referencing the diagnostic table, does not alter
the normal timing and flow of execution in the application. 
It is possible that some locks will be in a transition state when the snap shot is taken. 
****************************************************


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