db-13: understanding vsts

DB-13:DB-13:Understanding VSTsUnderstanding VSTs

By Paul GuggenheimBy Paul Guggenheim

Copyright © 2005Copyright © 2005Paul Guggenheim & Paul Guggenheim & AssociatesAssociates

DB-13: Understanding VSTs 22

About PGAAbout PGA

Working in Progress since 1984 and training Progress Working in Progress since 1984 and training Progress programmers since 1986programmers since 1986

Designed six comprehensive Progress courses covering Designed six comprehensive Progress courses covering all levels of expertiseall levels of expertise

Major consulting clients include Major consulting clients include Foxwoods CasinoFoxwoods Casino, , Health InformaticsHealth Informatics, , Bank OneBank One, , Textron Fastening Textron Fastening SystemsSystems, and , and American Academy of Orthopaedic American Academy of Orthopaedic SurgeonsSurgeons



What are VSTs ?What are VSTs ?

VST stands for VST stands for Virtual System Table.Virtual System Table. VSTs provide 4GL access to information contained in the VSTs provide 4GL access to information contained in the

Progress Monitor (Progress Monitor (promonpromon) utility.) utility. VSTs are schema tables that are stored in memory.VSTs are schema tables that are stored in memory.



Why Use VSTs ?Why Use VSTs ?

VSTs may be easily integrated into existing Applications.VSTs may be easily integrated into existing Applications. Some startup parameters may be updated through Some startup parameters may be updated through

VSTs.VSTs. Statistical Database Performance Reporting can be Statistical Database Performance Reporting can be

easily accomplished.easily accomplished. The Databases can be constantly monitored from within The Databases can be constantly monitored from within

the Application.the Application. Additional information about locking conflicts may be Additional information about locking conflicts may be

provided to the end-user.provided to the end-user.



Accessing VSTsAccessing VSTs

VSTs are VSTs are metaschema tablesmetaschema tables Automatically included in Version 9Automatically included in Version 9 Must enable them in Version 8 with the following Must enable them in Version 8 with the following

command:command:

proutil proutil dbnamedbname –C enablevst –C enablevst To look at in GUI Dictionary, select:To look at in GUI Dictionary, select:

View->Show Hidden TablesView->Show Hidden Tables To look at in CHUI Dictionary, enter VST table nameTo look at in CHUI Dictionary, enter VST table name



Viewing VSTsViewing VSTs

VSTs are records in the VSTs are records in the _file_file metaschema table metaschema table _file-number_file-number range for VSTs (9.1D): range for VSTs (9.1D): -16385 to -16423-16385 to -16423 Two new tables were added to OpenEdge 10.Two new tables were added to OpenEdge 10.

_Code-Feature_Code-Feature _Database-Feature_Database-Feature

One new field is added to OpenEdge 10.One new field is added to OpenEdge 10. _server._server-pendconn_server._server-pendconn



VST InquiryVST Inquiry

In program In program vstinq.pvstinq.p, the , the VST schema VST schema may be may be viewed.viewed.



VST CharacteristicsVST Characteristics

Every VST has one field that ends in ‘id’.Every VST has one field that ends in ‘id’. This field serves as the VST’s unique index.This field serves as the VST’s unique index. This field is sequentially numbered from 1.This field is sequentially numbered from 1.

Exception is Exception is _TxeLock_TxeLock where Id field is where Id field is ??..




Many VSTs pre-allocate records based upon startup Many VSTs pre-allocate records based upon startup parameters. For example: parameters. For example:

proserve school proserve school -n 3 -Mn 3 -L 250 -B 500-n 3 -Mn 3 -L 250 -B 500

produces a produces a –n–n of of 44.. Progress adds an extra user for shutting down the Progress adds an extra user for shutting down the

database or database or promonpromon..




Let’s look at the Let’s look at the _Trans_Trans table: table:




The default initial values in most VST fields is unknown The default initial values in most VST fields is unknown (?).(?). TheThe –Mn–Mn value is 3. value is 3.

One record for each server and the one record for the One record for each server and the one record for the database broker is displayed.database broker is displayed.




Let’s look at Let’s look at _UserLock_UserLock table. It shows table. It shows which locks a which locks a particular user particular user currently holds.currently holds.




_UserLock-Id_UserLock-Id 1 is the broker, 2,3 and 4 are the servers, 1 is the broker, 2,3 and 4 are the servers, 5,6 and 7 are connected users and 8 is a 5,6 and 7 are connected users and 8 is a promonpromon session.session.

The formula for this table is:The formula for this table is:

––n + -Mn + 2n + -Mn + 2

where where –n–n is the startup number of users. is the startup number of users. Since the Since the –L–L is 250, Progress rounds it to the nearest is 250, Progress rounds it to the nearest

multiple of 32 which is 256.multiple of 32 which is 256.




The The _Lock_Lock file will look file will look like the like the following:following:



Resolving Locking Resolving Locking ConflictsConflicts

As a developer, you had 2 choices in resolving locking As a developer, you had 2 choices in resolving locking conflicts:conflicts:Option 1:Option 1: Let Progress handle it. Let Progress handle it.




As a developer, you had two choices in resolving locking As a developer, you had two choices in resolving locking conflicts:conflicts:Option 2:Option 2: Handling locking conflicts in the procedure Handling locking conflicts in the procedure

repeat:repeat: prompt-for student.student-id.prompt-for student.student-id. find student using student-id exclusive-lock no-wait no-error.find student using student-id exclusive-lock no-wait no-error. if available student then update sfirst-name slast-name.if available student then update sfirst-name slast-name. else if locked student then do:else if locked student then do: find student using student-id no-lock no-error.find student using student-id no-lock no-error. message "Student record is locked” skipmessage "Student record is locked” skip "Please wait until later." view-as alert-box."Please wait until later." view-as alert-box. end.end. else else message "Student number does not exist" view-as alert-box.message "Student number does not exist" view-as alert-box.end.end.




Problem with Option 1:Problem with Option 1: User has to undo their transaction.User has to undo their transaction. The stop key, unless trapped, forces the user to the The stop key, unless trapped, forces the user to the

beginning of the application.beginning of the application.

Problem with Option 2:Problem with Option 2: User doesn’t know who has locked the record…User doesn’t know who has locked the record…UNTIL UNTIL

VSTs!VSTs!




Adding the statements below now provides the user with Adding the statements below now provides the user with additional information about who has the record locked:additional information about who has the record locked:

find first _lock where _lock-recid = integer(recid(student)) no-error.find first _lock where _lock-recid = integer(recid(student)) no-error.message "Student record is locked by user:" _lock-name skipmessage "Student record is locked by user:" _lock-name skip "Please wait until later." view-as alert-box."Please wait until later." view-as alert-box.



Record Locking InquiriesRecord Locking Inquiries

For each user, Progress provides up to 512 locked For each user, Progress provides up to 512 locked records for display and lookup.records for display and lookup.




In In lockinq.plockinq.p, we start with the , we start with the _UserLock_UserLock table to show table to show available users in a browse.available users in a browse. For each user selected there is another browse that shows For each user selected there is another browse that shows

the locked records for that user, it’s table name, RECID the locked records for that user, it’s table name, RECID and lock flags.and lock flags.

To accomplish this, a temp-table is built storing the RECID To accomplish this, a temp-table is built storing the RECID and chain number from the corresponding array fields in and chain number from the corresponding array fields in the the _UserLock_UserLock table. table.




In In lockinq.plockinq.p, we start with the , we start with the _UserLock_UserLock table to show table to show available users in a browse.available users in a browse. The second query is opened using this RECID and chain The second query is opened using this RECID and chain

number to read the number to read the _Lock_Lock record to get the table number. record to get the table number. The table number is then used to read the The table number is then used to read the _file_file

metaschema table to get the table name for the browse.metaschema table to get the table name for the browse.




In In lockinq.plockinq.p, we start with the , we start with the _UserLock_UserLock table to show table to show available users in a browse.available users in a browse. For each locked record selected, the table name and For each locked record selected, the table name and

RECID are passed to the RECID are passed to the getfieldvaluesgetfieldvalues procedure which procedure which dynamically creates a query for that record.dynamically creates a query for that record.

It then calls the procedure It then calls the procedure showtableshowtable which displays the which displays the field names and values for that locked record using the field names and values for that locked record using the tfldtfld temp-table.temp-table.



4GL User Disconnect4GL User Disconnect

The next program, The next program, disuser.pdisuser.p, allows someone to , allows someone to disconnect a user from within the 4GL.disconnect a user from within the 4GL. The program uses the The program uses the _connect_connect and and _myconnection_myconnection

VSTs.VSTs.




The next program, The next program, disuser.pdisuser.p, allows someone to , allows someone to disconnect a user from within the 4GL.disconnect a user from within the 4GL. The The _connect_connect table is used for the query and browse for table is used for the query and browse for

connected users. connected users. The The _connect-usr_connect-usr values that are unknown and the values that are unknown and the

previously disconnected users (previously disconnected users (connect-disconnectconnect-disconnect = 1 = 1) ) are filtered out.are filtered out.

The The _myconnection_myconnection table is used to prevent someone table is used to prevent someone from disconnecting themselves. from disconnecting themselves.

This table was added to V9 to make it easy to identify This table was added to V9 to make it easy to identify which connection is the current session.which connection is the current session.




The next program, The next program, disuser.pdisuser.p, allows someone to , allows someone to disconnect a user from within the 4GL.disconnect a user from within the 4GL. The actual user disconnection is performed by the The actual user disconnection is performed by the

_mprshut_mprshut command using a temporary command text file command using a temporary command text file as standard input.as standard input.

Because a disconnection may take a few seconds, a Because a disconnection may take a few seconds, a pause of 15 seconds executes before re-opening the pause of 15 seconds executes before re-opening the query. The query. The _connect-disconnect_connect-disconnect field will be 1 when the field will be 1 when the disconnected process is finished.disconnected process is finished.



DB Area StatisticsDB Area Statistics

The The _DBStatus_DBStatus and the and the _AreaStatus_AreaStatus VSTs supply VSTs supply useful information about the database and database useful information about the database and database areas.areas.



DB Area StatisticsDB Area Statistics

In program In program dbareastat.pdbareastat.p, , the size of the the size of the bibi is is monitored along with the monitored along with the total number of locks, the total number of locks, the highest number of locks highest number of locks and highwater marks for and highwater marks for database areas.database areas. In V9, the multi-volume In V9, the multi-volume

bibi size is reported by size is reported by dividing the high water dividing the high water mark blocks by the mark blocks by the bibi block size.block size.



Record RequestsRecord Requests

PromonPromon provides a tremendous amount of database provides a tremendous amount of database and performance statistics.and performance statistics.

By using VSTs, this data can be processed any way By using VSTs, this data can be processed any way desired.desired.




For example, the program For example, the program userio.puserio.p shows the amount of shows the amount of activity for requests vs. record reads per user and in activity for requests vs. record reads per user and in summary.summary. The The _UserIO_UserIO table provides information on a per user table provides information on a per user

basis for reading and writing to the database, before-basis for reading and writing to the database, before-image and after-image files. This information may be found image and after-image files. This information may be found on the Block Access screen (3) in on the Block Access screen (3) in promonpromon..

The The _ActSummary_ActSummary table provides summary information table provides summary information and some of its data may be found on the Activity screen and some of its data may be found on the Activity screen (5) in (5) in promonpromon.. Some useful information provided by Some useful information provided by _ActSummary_ActSummary is the is the

number of checkpoints and database buffers flushed.number of checkpoints and database buffers flushed.



Table StatisticsTable Statistics

Table statistics are available through VSTs but not Table statistics are available through VSTs but not through through promonpromon..

Statistics on the number of times a table was read, Statistics on the number of times a table was read, updated, created and deleted are kept.updated, created and deleted are kept. Note that data that is undone does not reduce the Note that data that is undone does not reduce the

corresponding statistic.corresponding statistic.

Unfortunately, there is nothing in VSTs that link user Unfortunately, there is nothing in VSTs that link user access to specific records in tables.access to specific records in tables. For example, to show which records were read by a given For example, to show which records were read by a given

user would be useful for security or for application user would be useful for security or for application troubleshooting purposes.troubleshooting purposes.



Table StatisticsTable Statistics

The program The program tablestat.ptablestat.p is used show the tables with is used show the tables with the highest number of reads.the highest number of reads. The The RefreshRefresh

button may be button may be pressed to show pressed to show the latest data.the latest data.

Tablestat.pTablestat.p uses uses the the _TableStat_TableStat VST.VST.



Buffer StatusBuffer Status

One of the most important parameters to set is the One of the most important parameters to set is the database buffers parameter, database buffers parameter, –B–B.. Setting it too high can waste memory and could cause Setting it too high can waste memory and could cause

swapping.swapping. Setting it too low can cause increased disk access and Setting it too low can cause increased disk access and

performance degradation.performance degradation.

The The _BuffStatus_BuffStatus VST can be used to measure the VST can be used to measure the effectiveness of the effectiveness of the –B–B parameter. parameter.




In In buffstat.pbuffstat.p, the program opens the , the program opens the _bfstatus_bfstatus record in record in the query and displays it to the screen when the the query and displays it to the screen when the RefreshRefresh button is pressed.button is pressed. This is the same information that is shown in This is the same information that is shown in promonpromon

under under R&D->1 (Status Displays)-> 7 (Buffer Status)R&D->1 (Status Displays)-> 7 (Buffer Status)..




In In buffstat.pbuffstat.p, the program , the program opens the opens the _bfstatus_bfstatus record record in the query and displays it in the query and displays it to the screen when the to the screen when the RefreshRefresh button is pressed. button is pressed. With the –B set at 500, With the –B set at 500,

notice that the total buffers notice that the total buffers is 502.is 502. One extra buffer is for the Database Master Block.One extra buffer is for the Database Master Block. The 2The 2ndnd block included is called the Index Anchor Block and is block included is called the Index Anchor Block and is

not used in V9.not used in V9.




If a long report is run, such as:If a long report is run, such as:

for each registration:for each registration:

end.end.

then the unused buffers become filled from the report.then the unused buffers become filled from the report.



Setting Read Only Setting Read Only BuffersBuffers

Question: Question: How do we prevent all the buffers being used How do we prevent all the buffers being used up by a report?up by a report?

Answer:Answer: Set the read only buffers on the client. Set the read only buffers on the client. Two ways to do this:Two ways to do this:

1.1. At startup using the At startup using the –Bp–Bp parameter parameter

2.2. Updating the Updating the _MyConn-NumSeqBuffers_MyConn-NumSeqBuffers field in the field in the _MyConnection_MyConnection VST. VST.




Read only buffers (ROBs) are new to V9. The Read only buffers (ROBs) are new to V9. The –Bp–Bp parameter specifies the number of read-only blocks a parameter specifies the number of read-only blocks a client may have. client may have.

ROBs are part of the total ROBs are part of the total –B–B buffer pool, so that the buffer pool, so that the remaining buffers are available for modified buffers. remaining buffers are available for modified buffers.

Once a client has ROBs allocated to them, a large Once a client has ROBs allocated to them, a large report’s records will stay confined to the ROBs.report’s records will stay confined to the ROBs.




We will start a session with a We will start a session with a –Bp–Bp = 64. = 64. We will run a series of reports from the editor: We will run a series of reports from the editor:

for each student no-lockfor each student no-lock

for each registration no-lockfor each registration no-lock The used buffers increases slightly, but then remains The used buffers increases slightly, but then remains

fixed.fixed.




Next, we run Next, we run updrobuf.pupdrobuf.p, and set the read only buffers , and set the read only buffers equal to 0.equal to 0.

We then run the reports and notice that the used buffers We then run the reports and notice that the used buffers equal to the total buffers.equal to the total buffers.

The used buffers is a high water mark. It will not go down The used buffers is a high water mark. It will not go down even though the buffers may be re-used.even though the buffers may be re-used.



Customizing PRO*Tools Customizing PRO*Tools ToolbarToolbar

A convenient place to put the VST programs you created A convenient place to put the VST programs you created is on the PRO*Tools Toolbar.is on the PRO*Tools Toolbar.




It is fairly easy to add your own tools to this toolbar.It is fairly easy to add your own tools to this toolbar. Right-mouse-click on the toolbar and select Right-mouse-click on the toolbar and select Menu BarMenu Bar. A . A

pull-down menu bar will appear on the toolbar.pull-down menu bar will appear on the toolbar. Select Select File->Customize… File->Customize… then press the Add button to then press the Add button to

add your program.add your program. Select Run Persistent, Display on palette and supply an Select Run Persistent, Display on palette and supply an

image.image. Select “yes” to override protools.dat so that your tools will Select “yes” to override protools.dat so that your tools will

show up on every session.show up on every session.




Make sure that the PROPATH environment variable Make sure that the PROPATH environment variable contains the directory where your VST programs are contains the directory where your VST programs are located.located.

Two include files are required in order to be compatible Two include files are required in order to be compatible with the PRO*Tools toolbar.with the PRO*Tools toolbar. _adetool.i – contains a single internal procedure called _adetool.i – contains a single internal procedure called

ADEPersistentADEPersistent, which prevents the Progress Editor from , which prevents the Progress Editor from removing the instance when running other programs.removing the instance when running other programs.

_runonce.i – prevents multiple instances of the tool to be _runonce.i – prevents multiple instances of the tool to be run at the same time.run at the same time.




Each option also contains its own dynamic window and Each option also contains its own dynamic window and is parented to the PGA toolbar window.is parented to the PGA toolbar window.



AcknowledgementsAcknowledgements

I would like to thank Dan Foreman for writing the I would like to thank Dan Foreman for writing the Virtual Virtual System Tables GuideSystem Tables Guide. It was very helpful in creating . It was very helpful in creating this presentation.this presentation.



SummarySummary

VSTs provide 4GL access to information contained in VSTs provide 4GL access to information contained in promonpromon..

Many useful reports and tools may be created.Many useful reports and tools may be created.

db-13: understanding vsts

Documents

paul guggenheim associatesdb

use vsts

vst characteristicsevery

vsts unique index

vst schema

vst characteristicslets

vst fields

vst table namecopyright