Call: +1 (281) 989-6360

clearlocks: What Good Is It for Anyway?

The ‘clearlocks’ utility has been around, as a part of Teamcenter, for very long time. In my opinion, for Teamcenter DBAs and system administrators there never was (yes, I said ‘was’…read more) any other friendly and helpful utility than clearlocks; especially with –verbose argument.

If the clearlocks utility is still part of Teamcenter, then why did I use past tense? Is clearlocks no more a friendly or helpful utility? What happened? Well, there are some changes to Teamcenter and as a result, clearlocks utility has lost the status of most friendly and helpful utility (at-least in my book). Let’s see what’s happening.

Why Was clearlocks Needed?

When someone logs into Teamcenter, regardless of the client (i.e. 2-tier, 4-tier, SOA, ITK program, web client, etc.), database records that session and locks held by the session in its session and lock tables. Apart from that, Teamcenter has its own session tables to record its own information about the associated Teamcenter session. Teamcenter also has various tables to record locks obtained by those Teamcenter sessions. Those locks are obviously tied to the corresponding Teamcenter session. These Teamcenter session and lock tables are separate from database’s session and lock tables.

If the Teamcenter session dies for some reason (loss of network connectivity, memory error, session crash, etc.), then user doesn’t get chance to log out of the Teamcenter session. As a result the dead session entry and various locks held by the dead session would remain in Teamcenter session and lock tables. Any other user attempting to modify one of the objects locked by such dead session would experience an error.

The clearlocks utility attempted to identify such dead sessions (i.e. the Teamcenter process that created the session no longer exists), remove those sessions from session table, and remove all locks held by those dead sessions from various lock tables.

What I Used To Advice My Clients

Clearly, the clearlocks utility was of much use. I always advised my clients to:

  • Setup a cron job or scheduled job to run “clearlocks –verbose” every 15 to 30 minutes.
  • Additionally, edit tcserver.bat (or start_TcServer1.bat) and add “clearlocks –verbose” immediately prior-to and after the call to tcserver.exe. I preferred not to make this optional, because it ensured that each portal session started clean (i.e. removed any dead sessions and locks) and exited clean in case of any abnormal exits.
  • Additionally and optionally, add “clearlocks –verbose” in tc_profilevars.bat

What Changed?

New logic was added to Teamcenter to handle part of the clearlocks functionality. Now, if a Teamcenter session requests a lock on an object that is already locked by some other session, then Teamcenter would check if the other session holding the lock is dead. If it finds that the other session is dead then Teamcenter would remove that dead session and all locks held by that dead session. clearlocks is no longer needed to remove locks held by dead sessions.

I am not sure which Teamcenter version implemented this change. But, I can say that I first saw it in version 8.3 (Thanks to our good friend, Scott Pigman from The PLM Dojo, for politely pointing out the missing information).

So, What’s The Catch?

In rare circumstances, clearlocks can actually be detrimental. Now, with so many client options, it is possible for a Teamcenter session to enter into an idle state and get disconnected from database. When such a Teamcenter session comes out of idle state and becomes active again, it will attempt to reconnect to the database and reestablish its Teamcenter session and lock records. Database may mark such an idle Teamcenter session as a dead session. If clearlocks is run when a session is in idle state and disconnected from database, it will actually remove the session and its locks from the database. This will result into problems when such a session becomes active again and tries to reestablish its identity.

Teamcenter will attempt to clean dead process and its locks only when a lock is requested on an object that is already locked by the dead process. As a side effect, if the dead session does not hold any locks, it will never be cleared and will remain in the database indefinitely. These sessions don’t cause any issues as far as proper working of Teamcenter is concerned, except consuming unnecessary space in the database.

Although it was not clear from any official explanation from Siemens, but it would seem that if a Teamcenter session requests a lock on an object that has been locked by an idle but disconnected session then it too would result in clearing session record and locks of the idle session (even without running clearlocks).

My New Advice To My Clients

  • There is no need to run clearlocks actively (via cron job, or start_TcServer1.bat file, etc.) anymore.
  • At the same time it is essential to run “clearlocks –verbose” periodically to remove all dead session that are not holding any locks. This can be done when there is least amount of active Teamcenter sessions, such as on Sunday night or during scheduled database server shutdown.
  • Worst time to run clearlocks is after an unscheduled/unplanned database server restart, or after network outage, after power failure, etc. These are times when there would be lot of idle but disconnected sessions.

Final Thoughts

Until I was aware of this enhancement, I was running clearlocks per my original advice. And every once in a while I would encounter following error:

INTERNAL ERROR: ghost of modified object <ObjectTag> is NULL

Syslog would show following lines:

         This is probably because someone ran clearlocks on our process
         Please do not report any locking bugs or POM_i_am_a_zombie_process errors from
         this process until you are confident clearlocks abuse does not account for them.

I did not understand the cause of this error and then suddenly light bulb came on when I learned about this Teamcenter enhancement. clearlocks might still be a friend…it just is not as dear as it used to be.

Next Steps

Please feel free to comment on this topic. We also encourage you to explore our website to learn about products and services we offer. If you have any questions or wish to discuss this topic or any other topic with us in private, please contact us.

  1. Great information, Yogesh. (that’s a phrase that could easily become redundant 😉

    I really appreciate the extra effort you take to go into the technical explanation of how things like the session tables work, in addition to the best practices advice. It’s extremely helpful and educational.

    I’m curious what other utilities you recommend to run regularly?

    • Thanks Scott. Your comments are always appreciated.

      You also asked me about the Teamcenter version that implemented this change. Well, I am not exactly sure. I did not try TC2007. But I can say that I first saw it in version 8.3. I also edited the post to add this.

      As far as other utilities….that’s whole another topic:-)

  2. Hello Yogesh,
    Informative article again. Just to get myself clear here, clearlocks cleans up only the Teamcenter’s session & lock tables and not the database’s session & lock tables ???

    • I don’t think so. I think database would have its own session management/timeout policies that would handle cleaning up of its sessions. I will check and post my findings here.

      Thanks for the comment/question.

      • To my understanding, clearlocks will remove dead session from PPOM_SESSION table ( Teamcenter infodba schema table) comparing it with gv$session view ( in case of Oracle ).

  3. Great yogesh..thanks for sharing useful info….

  4. Nice info, Yogesh.
    Just few days back, I had same problem.

  5. Great info. Clearlock does not clear the lock hold by the DB session. For that you have options to set sqlnet.expire_time in sqlnet.ora file on database server, which at defined interval (in minutes) sends a dummy packet to client to check if client is still alive. If it detects client has disconnected, database session would be terminated as well.

  6. Hi Yogesh,

    If I’m understood you correctly, I should not ever see an error message that such-and-such object can’t be modified because it’s locked by another process if that process isn’t a valid, active, process that someone is using. Despite this, I do still get these errors from time to time. I know the locking process isn’t a valid process because it’s my own process — usually a program I wrote — that died unexpectedly. In the end the only way I can find to regain access to the data is to run clearlocks. Can you suggest an alternative?

    Perhaps the real question is, how and when does TC determine that a process is dead, and if is there a way to tell TC that a process is dead that it thinks is still alive? That way the new logic you describe should kick in and save me the trouble of running clearlocks.


    [Teamcenter 8.3]

    • I am not sure what the triggers are for marking any Teamcenter process dead.

      Which Teamcenter 8.3 do you use? May be this logic is not implemented…..or worse yet:-) there might be regression in the version that you are using.

  7. Can you tell me please, where did you get this information that clearlocks is not needed anymore. I can’t still really believe that this is the case. I have two customers at the moment both on Teamcenter 8.3, and they’re both running a clearlocks as “services”. I
    *know* we would have problems (e.g. when deleting data) if clearlocks wouldn’t be executed on a regular basis (15 or 30 minutes interval).

    • Thanks Extrala for the comment. I got that information from one of the Siemens presentations from 2007.

    • Which Teamcenter 8.3 version (MP?) are they using? I first observed this updated behavior in I don’t know which Teamcenter version actually implemented this change or if any TC patch had regression:-)

      We used to see the “INTERNAL ERROR: ghost of modified object is NULL” just about once a week when we were running clearlocks as scheduled job every 15 minutes. But since then we stopped doing that. We haven’t seen that error in last 2+ years.

  8. The clearlocks functionality is basically the same as it has been. What’s changed is the introduction of 4tier rich clients. Sessions can appear stale to the database yet a user can click some data in their stale session and a new tcserver will be added which enables the connection to the db again. If you run clearlocks while the tcserver session appears stale in the db then the locks are removed and the user can never reconnect.

    An excellent work-around is to use list users from the rich client menu as a DBA. You’ll be prompted to remove dead sessions. This process does not kill stale sessions (only dead ones) and is safe to use.

    Enjoy my friends!

Leave a Reply

SiOM Systems

Expertise in Teamcenter security & access management, configuration management, options & variant configuration, engineering change management, NX CAD data management, document management, workflow/process management, absolute occurrences, appearances, and data migration.

Our Philosopy

‘Siddhi’ means perfection, mastering a difficult skill, success. ‘Om’ is the source of all the energy; it is the source of the energy behind the creation, preservation and destruction of the universe. This philosophy guides us in providing perfect, flexible, future proof, high quality solutions to every customer.


... A true professional who can help guide Teamcenter implementations, mentor and teach staff new to Teamcenter, and architect and guide a client to the best practical solution. Read more