Sculptor debug record lock tool¶
Contents
From Sculptor 5.7 onwards, a tool to debug record locks is available. This tool is designed for use mainly in a test environment. It is not recommended for continuous use on a live site, as it will impact on performance.
Files and programs that must be installed¶
1 |
Sculptor server programs kfserver | kfservnt 5.6.0 or later on the server. |
2 |
If Sculptor programs on the server update Sculptor keyed files directly, i.e. not through kfserver, then the interpreter (sagewc | srepwc) must be 5.6.0 or later. Client programs that update files only through kfserver can use Sculptor 4.2 or later. |
3 |
The data dictionary files filetabl.d and locktabl.d must exist in the directory $SCULPTOR\debug on the server. |
4 |
The program viewlocks.q must exist on the server or on a Windows client. This program only runs on a Windows platform. The suggested location is $SCULPTOR\debug. |
Starting a debug session¶
1 |
Set the environment variable SC_DEBUG_LOCKS on the server. In the current release of this tool the actual value is not checked, but a non-zero value such a 1 as recommended. This must be set so that kfserver and any local Sculptor programs that run independently of kfserver will see it. On UNIX, the safest option is to set this variable in a start-up script and then reboot. On Windows, the safest option is to set this variable in the registry using the Sculptor program scconfig. Take care to select Sculptor version 5, not version 4, in scconfig. When using kfservnt it is not sufficient to set a system environment variable and then start the scconfig service. The system must be rebooted because a service inherits its environment from the Windows service manager and this has the environment defined when the system is booted. |
2 |
Start the Sculptor server. If SC_DEBUG_LOCKS has been set, new Sculptor files filetable.k and locktabl.k (index only) will be created in $SCULPTOR\debug. |
3 |
Start the program to view locks: On a Windows server, start srepwc viewlocks in $SCULPTOR\debug. On a Windows client, start srepwc viewlocks servername:path_to_debug_directory EXAMPLE: srepwc viewlocks myunixserver:/usr/SCULPTOR/debug
|
4 |
Run the programs to be tested. |
How the debug tool works¶
At the interval defined in the viewlocks.q program, a snapshot of all current file and record records is displayed. Since this is only a snapshot, short duration locks will not always be seen, but all locks that are in force when the snapshot is taken are displayed. The display can be stopped to examine the list, which is sorted by file name.
For each lock, the display shows the following information:
1 |
The connected client name and port number (or the process number of a local process that is not connected to kfserver). |
2 |
The ordinal number of the locked record in the Sculptor data file (blank if this is a file lock). This helps to differentiate different record locks in the same file, and to identify locks that are being held indefinitely. A possible future enhancement will be to display the record’s key. |
3 |
The lock type. |
4 |
The file name. |
IMPORTANT NOTE: When testing has finished, the environment variable SC_DEBUG_LOCKS must be removed, the system rebooted (if necessary) and the server restarted. If this is not done, the files that contain the lock information will continue to be updated and the system will run slowly.
Limitations¶
Locks that have been set by a program using network file system access, such as a mapped drive, will not be displayed.
A lock will remain displayed in the table after a process has been killed even though the operating system has removed the lock. The program must terminate normally for Sculptor to see that the lock has been released. If this situation occurs, kfserver should be restarted.