clearlocks

Clears dead process locks from the database. Dead process locks typically occur when a Teamcenter session terminates abnormally. Process locks are set on an object when it is being modified or deleted. If a Teamcenter session does not terminate gracefully (by logging out), these locks can remain in place. Dead process locks (locks held by dead sessions) can cause diverse problems that are often difficult to diagnose, and Teamcenter applications make every effort to eliminate or otherwise avoid them. Nevertheless, there are occasions when such dead process locks must be explicitly removed from the database, and the clearlocks utility is used for this purpose. Note To use the -assert_dead or -assert_all_dead options, you must specify the administrator's user name, password, and group. The clearlocks utility can only obtain general information about the processes in the lock table. Normally, the PID is pulled from the table and a kill is sent to the operating system. If the PID exists, the Alive count is incremented. If the PID does not exist, the Dead count is incremented. A Remote PID count indicates the process was started from a node other than the one that was used to run clearlocks. On some platforms, the kill returns a security violation and no specific information about the PID. If this occurs, the Other count is incremented. Syntax clearlocks [-verbose] [-node_names] [[-assert_dead -u=user-id {-p=password | -pf=password-file} -g=group] | [-assert_all_dead -u=user-id {-p=password | -pf=password-file} -g=group]] [-h] Caution The clearlocks utility can be run with active Teamcenter sessions, provided that the -assert_dead or -assert_all_dead arguments are not used. By default, the clearlocks utility discriminates between valid and dead process locks; the -assert_dead and -assert_all_dead arguments defeat this feature. Arguments -u Specifies the user ID. This is a user with Teamcenter administration privileges. Note If Security Services single sign-on (SSO) is enabled for your server, the -u and -p arguments are authenticated externally through SSO rather than being authenticated against the Teamcenter database. If you do not supply these arguments, the utility attempts to join an existing SSO session. If no session is found, you are prompted to enter a user ID and password. -p Specifies the password. This argument is mutually exclusive with the -pf argument. -pf Specifies the password file. For more information about managing password files, see Manage password files. This argument is mutually exclusive with the -p argument. One of the two mutually exclusive password elements is required. -g Specifies the group associated with the user. If used without a value, the user's default group is assumed. -verbose Displays a summary of processes and states (dead, alive, and unknown). Locks associated with dead processes are cleared by the clearlocks utility, live processes are not cleared, and the unknown processes are all other processes. -node_names Lists nodes upon which the known processes exist. -assert_dead Asserts that all processes on a particular node are dead and clears all process locks held by sessions running on that node with the exception of Multi-Site Collaboration transfer locks. If any of those sessions are alive and in use, the locks held by those sessions are compromised. Note To use this argument, you must enter the node name and the administrator’s user name, password, and group. To clear Multi-Site Collaboration transfer locks, use the export_recovery utility. -assert_all_dead Asserts that all processes in the database are dead and clears all process locks with the exception of Multi-Site Collaboration transfer locks. If any of those sessions are alive and in use, the locks held by those sessions will be compromised. Additionally, this option performs a complete cleanup of the database lock tables, the POM_TIMESTAMP table, and reports on the sessions that were asserted to be dead. Note To use this argument, you must enter the administrator’s user name, password, and group. To clear Multi-Site Collaboration transfer locks, use the export_recovery utility. -h Displays help for this utility. Environment As specified in Setting up a Teamcenter command-line environment. Files As specified in Log files produced by Teamcenter. Restrictions Do not run the clearlocks utility with the -assert_dead or -assert_all_dead arguments if there are any active Teamcenter sessions running. Any locks held by active sessions will be lost and these sessions can then potentially modify data for which they no longer hold modify locks. The -assert_dead and -assert_all_dead arguments are powerful and potentially destructive. Therefore, these arguments should only be used to clear process locks that cannot be cleared otherwise. For this reason, you must enter the administrator's user name, password, and group when using these arguments. The clearlocks utility cannot clear the Transfer lock type, only the Modify lock. To clear Transfer locks, use the export_recovery utility. This behavior is intended to prevent cases where objects that are being transferred are forcibly unlocked and thereby exposing them to the possibility of being modified when their ownership is being transferred. When running Clearlocks with the assert_all_dead or assert_dead option, you may see the message: Copy Notice: There are transfer locks detected indicating active Multi-Site transfer transactions. All transfers need to complete before the upgrade can safely continue. Ensure that ensure_site_consistency is successfully executed for any identified objects before running Clearlocks. This message also appears when upgrading a database to a new release if there are existing transfer locks in the database. Examples To clear process locks for dead sessions, enter the following command from that node: Copy $TC_ROOT/bin/clearlocks To obtain a list of all network nodes which have process locks set on the database, enter the following command: Copy $TC_ROOT/bin/clearlocks -node_names To clear all process locks (active and dead) on a single network node, in this example ntssun9, enter the following command: Copy $TC_ROOT/bin/clearlocks -assert_dead -u=Tc-admin-user -p=password -g=group ntssun9 In this example, Tc-admin-user is the administrator's user name and password, and group is the administrator's group. To clear all process locks (active and dead) on all nodes, enter the following command: Copy $TC_ROOT/bin/clearlocks -assert_all_dead -u=Tc-admin-user -p=password -g=group In this example, Tc-admin-user is the administrator's user name and password, and group is the administrator's group. The following is an example of a line message (report) produced by clearlocks -verbose: Copy Processes: 7, Alive: 1, Dead: 6, Remote: 0, Other: 0 Clearing Process Locks Perform the following steps to clear dead process locks using the clearlocks utility. Ensure that all Teamcenter and Teamcenter Integration for NX users are logged out of the system. When all users are logged out, all valid process locks are cleared. Create a report of all remaining process locks by entering the following command: Copy $TC_ROOT/bin/clearlocks -node_names The system displays a report listing network nodes that still have process locks set against the database. Because all users are logged off, these locks are dead and can be cleared. Run the following command: Copy $TC_ROOT/bin/clearlocks Create a report of all remaining process locks by entering the following command: Copy $TC_ROOT/bin/clearlocks -node_names The system displays a report listing network nodes that still have process locks set against the database. Because all users are logged off, these locks are dead and can be cleared. Any network nodes listed in this second report will require running the clearlocks utility with the -assert_dead argument to clear the difficult process locks. Run the following command to clear locks held by the session of the specified nodes: Copy $TC_ROOT/bin/clearlocks -assert_dead node-name1 node-name2 node-name3... node-name is a network node listed in the report. Create a report of all remaining process locks by entering the following command: Copy $TC_ROOT/bin/clearlocks -node_names This report should be clean (empty).