synchronized()
synchronized(string)Parameters
synchronized() takes a single required parameter that is a user-defined name for a lock object. This lock object name can be used in multiple TurboIntegrator processes in order to serialize their execution as a group.
lockNameValue=String
Required?=Yes
Default-none
Semantics
A TurboIntegrator process may make any number of calls to synchronized(), with any number of lock objects. Serializing is effective from the time synchronized() is called, until the containing transaction completes.
For example, if synchronized() is called from a subprocess (Ps) of primary process (Pp) or primary chore (Cp), the Lock Object is "released" when Pp or Cp completes. The exception is that a SaveDataAll (SDA) prematurely "ends" a transaction mid-process execution; this applies to Lock Objects as well.
The synchronized() call may be placed anywhere within a TurboIntegrator script, but serialization applies to the entire TurboIntegrator process when it is encountered.
Consider a TurboIntegrator process with a synchronized() call somewhere in the "middle" of its script, and an operation O1 preceding that call. Two instances of this TurboIntegrator process may start at the same time. It is possible for one instance to run to completion, including its call to synchronized(), before the second instance reaches its synchronized() call. In this case, the two processes appear to the user to have run concurrently. If, instead, the second process does reach its synchronized() call before the first completes, it will undo any work it had done (O1) and wait for the first to complete. In this case, the two processes appear to the user to have serialized.
To avoid such confusion, and to optimize the use of synchronized(), it is recommended (but not enforced) that synchronized() calls be the first statements of a TurboIntegrator process.
Example
Consider that TurboIntegrator process P needs to update two cubes, Cube_1 and Cube_2.
Other TurboIntegrator processes may also need to update Cube_1 or Cube_2.
To cause all TurboIntegrator processes that will update Cube_1 or Cube_2, to run one at a time, P could call synchronized() in the following way:
sCube_1='Cube_1';
sCube_2='Cube_2';
sE1='Elm1';
sE2='Elm2';
sE4='Units';
sE5='Price';
Synchronized( sCube_1 );
Synchronized( sCube_2 );
CellPutn( 111, sCube_1, sE1, sE2 );
CellPutn( 9.99, sCube_2, sE4, sE5 );
# ...
Other TurboIntegrator processes that will update Cube_1
or Cube_2 must also call synchronized( sCube_1 ) and/or
synchronized( sCube_2 ) in a similar way.
In this example, the two lock objects' names were chosen to be the same as the cubes' names. But a lock object's name does not have to be the same as other Cognos TM1 objects (cubes, dimensions, subsets, etc.).
Lock object maintenance and naming
Lock objects are managed internally by Cognos TM1 . No explicit creation or deletion is required of the user. Simply specify a lock object by name in a synchronized() call.
Lock object names are insensitive to case or embedded
blanks. For example, if there is a lock object with the name 'Abc
Def', that lock object can be referred to using the names 'ABCDEF',
'ab cd ef' etc. In other words, the execution of a TurboIntegrator
process with a call to synchronized( ‘Abc Def' ) will
serialize with the execution of a process with a call to synchronized(
‘ABCDEF' ). Lock object names may not exceed 1023 characters
in length.
Order of execution
A group of TurboIntegrator processes containing synchronized() calls to the same lock object are prevented from concurrently executing. However, their actual order of execution is unaffected. As long as they do not execute concurrently, the order in which they execute is determined by many other factors, including application design and operating system level scheduling. If order of execution is important, for example, if one TurboIntegrator process is dependent on updates made by another process, then it is up to the application designer to use other methods to ensure the desired order of execution.
MaximumTIObjectLocks configuration parameter
The MaximumTILockObjects parameter restricts the size of the object locked list. See IBM Planning Analytics Installation and Configuration for more information.