Hello,
Just a post concerning the freeze, unfreeze mechanism of documentum which allows to mark an object and, optionally, its components (if the object is a virtual document), as unchangeable.
There is also the lock/unlock mechanism which places a database lock on an object.
FREEZE DOCUMENT
The content server modifies these following attributes of the object when freezing an object :
• r_immutable_flag to true : This attribute indicates that the object is unchangeable.
• r_frozen_flag to true : This attribute indicates that the object is unchangeable because it was specifically frozen.
• i_vstamp incemented.
• r_modify_date, r_modifier.
+ API : freeze,session,object_id[,freeze_components]
+ DFC : IDfSysObject.freeze()
Document before freeze:
r_object_id : 09xxxxxxxxxxxxxx5 r_modify_date : 07/05/2017 09:05:26 r_modifier : myuser123 r_immutable_flag : F r_frozen_flag : F i_vstamp : 0
Document after freeze:
r_object_id : 09xxxxxxxxxxxxxx5 r_modify_date : 04/06/2017 09:39:03 r_modifier : myuser123 r_immutable_flag : F r_frozen_flag : F i_vstamp : 1
It is not possible to freeze a frozen document:
freeze,c,09xxxxxxxxxxxxxx5 save,c,09xxxxxxxxxxxxxx5 r_object_id : 09xxxxxxxxxxxxxx5 r_modify_date : 04/06/2017 09:45:15 r_modifier : myuser123 r_immutable_flag : T r_frozen_flag : T i_vstamp : 1 API> freeze,c,09xxxxxxxxxxxxxx5 ... [DM_SYSOBJECT_E_FROZEN]error: "The my_document_name_0957 sysobject is frozen."
UNFREEZE DOCUMENT
The content server modifies these following attributes of the object when freezing an object :
• r_immutable_flag to false: This attribute indicates that the object is unchangeable. Note that if the object has been versioned, unfreezing the object does not unset this attribute; it remains set to T.
• r_frozen_flag to false: This attribute indicates that the object is unchangeable because it was specifically frozen.
• i_vstamp incemented.
• r_modify_date, r_modifier.
+ API : unfreeze,session,object_id[,thaw_components]
+ DFC : IDfSysObject.unfreeze()
Document before unfreeze:
r_object_id : 09xxxxxxxxxxxxxx5 r_modify_date : 04/06/2017 09:45:15 r_modifier : myuser123 r_immutable_flag : T r_frozen_flag : T i_vstamp : 1
Document after freeze:
r_object_id : 09xxxxxxxxxxxxxx5 r_modify_date : 04/06/2017 11:45:15 r_modifier : myuser123 r_immutable_flag : F r_frozen_flag : F i_vstamp : 2
It is not possible to unfreeze a not frozen document:
unfreeze,c,09xxxxxxxxxxxxxx5 save,c,09xxxxxxxxxxxxxx5 r_object_id : 09xxxxxxxxxxxxxx5 r_modify_date : 04/06/2017 09:45:15 r_modifier : myuser123 r_immutable_flag : F r_frozen_flag : F i_vstamp : 1 API> unfreeze,c,09xxxxxxxxxxxxxx5 ... [DM_SYSOBJECT_E_NOT_FROZEN]error: "The my_document_name_0957 sysobject is not frozen."
ACTIONS on FROZEN DOCUMENT
TEST : DELETE/DESTROY a frozen document
DQL/API myadminuser : Delete/destroy of frozen document is impossible.
API> retrieve,c,dm_document where r_object_id = '090xxxxxxxxxx4f' ... 090xxxxxxxxxx4f API> destroy,c,l ... [DM_SYSOBJECT_E_FROZEN]error: "The my_document_name_1338 sysobject is frozen."
TEST : UPDATE a frozen document
DQL/API myadminuser : Update of frozen document is impossible.
API> retrieve,c,my_type_document where r_object_id = '09xxxxxxxxxxxxxx5' ... 09xxxxxxxxxxxxxx5 API> set,c,l,object_name my_document_name_1049 ... OK API> save,c,l ... [DM_SYSOBJECT_E_CANT_SAVE_IMMUTABLE]error: "Cannot save my_document_name_1049 since it is immutable."
TEST : CHECKOUT a frozen document
DQL/API myadminuser : CHECKOUT of frozen document is possible. The CHECKOUT action sets the attributes r_lock_owner, r_lock_date, r_lock_machine, i_vstamp. The attributes r_modify_date and r_modifier are not modified.
API> checkout,c,090xxxxxxxxxxxxf5
...
090xxxxxxxxxxxxf5
r_object_id : 090xxxxxxxxxxxxf5
r_modify_date : 04/06/2017 16:39:02
r_lock_owner : myadminuser
r_lock_date : 04/06/2017 16:48:33
r_lock_machine : myhost123
r_version_label [0]: 3.1
[1]: CURRENT
r_immutable_flag : T
r_frozen_flag : T
i_vstamp : 2
API> checkout,c,090xxxxxxxxxxxxf5
...
090xxxxxxxxxxxxf5
r_object_id : 090xxxxxxxxxxxxf5
r_modify_date : 04/06/2017 16:40:48
r_lock_owner : myadminuser
r_lock_date : 06/06/2017 09:09:11
r_lock_machine : myhost123
r_version_label [0]: 3.1
[1]: CURRENT
r_immutable_flag : T
r_frozen_flag : T
i_vstamp : 3
TEST : CHECKOUT/CHECKIN a frozen document
DQL/API myadminuser : CHECKOUT/CHECKIN of frozen document is possible.
API> checkout,c,090xxxxxxxxxxxxf5 ... 090xxxxxxxxxxxxf5 API> set,c,090xxxxxxxxxxxxf5,object_name my_document_name_1045 ... OK API> checkin,c,090xxxxxxxxxxxxf5 ... 090xxxxxxxxxxxxxx69
Before CHECKOUT / CHECKIN
r_object_id : 090xxxxxxxxxxxxf5
object_name : my_document_name_0957
r_modify_date : 04/06/2017 16:40:48
r_lock_owner :
r_lock_date : nulldate
r_lock_machine :
r_version_label [0]: 3.1
[1]: CURRENT
r_immutable_flag : T
r_frozen_flag : T
i_has_folder : T
i_latest_flag : T
i_direct_dsc : F
i_vstamp : 3
After CHECKOUT
r_object_id : 090xxxxxxxxxxxxf5
object_name : my_document_name_0957
r_modify_date : 04/06/2017 16:40:48
r_lock_owner : myadminuser
r_lock_date : 05/06/2017 11:00:21
r_lock_machine : myhost123
r_version_label [0]: 3.1
[1]: CURRENT
r_immutable_flag : T
r_frozen_flag : T
i_has_folder : T
i_latest_flag : T
i_direct_dsc : F
i_vstamp : 4
After CHECKIN : the document is still FROZEN
r_object_id : 090xxxxxxxxxxxxf5 object_name : my_document_name_0957 r_modify_date : 04/06/2017 16:40:48 r_lock_owner : r_lock_date : nulldate r_lock_machine : r_version_label [0]: 3.1 r_immutable_flag : T r_frozen_flag : T i_has_folder : F i_latest_flag : F i_direct_dsc : F i_vstamp : 5After CHECKIN : NEW VERSION UNFROZEN of document after CHECKOUT / CHECKIN : 090xxxxxxxxxxxxxx69
r_object_id : 090xxxxxxxxxxxxxx69
object_name : my_document_name_1045
r_modify_date : 06/06/2017 10:46:38
r_lock_owner :
r_lock_date : nulldate
r_lock_machine :
r_version_label [0]: 3.2
[1]: CURRENT
r_immutable_flag : F
r_frozen_flag : F
i_has_folder : T
i_latest_flag : T
i_direct_dsc : F
i_vstamp : 0
LOCK/UNLOCK DOCUMENT
It is possible to place a database lock on an object (lock) and remove this intention lock without saving any changes that may have been made to the locked object (unlock).
API> lock,c,090xxxxxxxxxx4f ... [DM_API_E_CANT_WITHOUT_OPEN_TRAN]error: "You cannot perform 'lock' operation without an open transaction in this session." API> begintran,c ... OK API> lock,c,090xxxxxxxxxx4f ... OK API> commit,c ... OK API> unlock,c,090xxxxxxxxxx4f ... OK
The lock and unlock mechanism don’t modify any attribute of document:
r_object_id : 090xxxxxxxxxx4f
object_name : my_document_name_1045
r_modify_date : 06/06/2017 11:35:10
r_lock_owner :
r_lock_date : nulldate
r_lock_machine :
r_version_label [0]: 3.3
[1]: CURRENT
r_immutable_flag : F
r_frozen_flag : F
i_vstamp : 0
The UPDATE of a database LOCKED document is possible:
API> retrieve,c,my_type_document where r_object_id = '090xxxxxxxxxx4f' ... 090xxxxxxxxxx4f API> set,c,l,object_name my_document_name_1338 ... OK API> save,c,l ... OK
Unlock (i.e., Cancel Checkout) of an Object
It is possible to cancel checkout (Unlock) on the document which is locked by another user. The above api command to unlock the document which is checked out by another user, to execute the command the user must have minimum of Administrator access.
When a user makes a checkout on a sysobject (opens to edit), Documentum automatically applies a lock on the object, preventing other users from modifying it. Only the lock owner or a superuser can unlock the object by making a checkin or cancel the checkout. As sometimes users forget to unlock documents, you might need to do this as a superuser.
You can unlock an object in 2 ways:
DQL: update dm_document object set r_lock_owner='', set r_lock_machine='', set r_lock_date=date('nulldate') where r_object_id='090xxxxxxxxxxxxf5'
API: unlock,c,090xxxxxxxxxxxxf5,F
The last argument is a boolean flag specifying if a mail notification will be sent to the lock owner.
IMPORTANT POINT :
+ We have remark that during a checkin on a document having no aspect, if the checkin includes the attachment of new aspect and the set of DATE attributes THEN there is an unexpected error related to a BUG in the DFS or DFC layer of Documentum. “Bad attribute name aspect_huo.my_start_date for document/object.”.
+ In fact, there is no attachment of the aspect despite the presence of {r_aspect_name =; aspect_huo} and this causes an error {[DM_API_E_BADATTRNAME] error: “Bad attribute name ‘aspect_huo.my_start_date’ for document / object.”}
+ This error only occurs with DATE attributes (eg: “aspect_huo.my_start_date” / “aspect_huo.my_end_date” of aspect “aspect_huo”).
+ The problem never arises if the aspect is already associated with the document.
+ SOLUTION: The solution found is during a CHECKIN to:
o delete the “[ASPECT] .DATE” fields from the list of PROPERTIES to update with CHECKIN,
o do the CHECKIN without the “[ASPECT] .DATE” fields,
o do an UPDATE (if the current user has WRITE permission) or do an automatic CHECKOUT / CHECKIN to update only the “[ASPECT] .DATE” fields,
Here, an example of CHECKOUT/CHECKIN followed by UPDATE in API:
############# CANCEL CHECKOUT : OK
#set,c,09xxxxxxxxxxxxxc8,r_immutable_flag
#0
#save,c,09xxxxxxxxxxxxxc8
#
#update dm_document object set r_lock_owner='', set r_lock_machine='', set r_lock_date=date('nulldate') where r_object_id='09xxxxxxxxxxxxxc8'
#
unlock,c,09xxxxxxxxxxxxxc8,F
############# CHECKOUT and CHECKIN : OK
begintran,c
checkout,c,090xxxxxxxxxxxxecb
insert,c,090xxxxxxxxxxxxecb,r_aspect_name[0]
aspect_huo
set,c,090xxxxxxxxxxxxecb,object_name
new document name
set,c,090xxxxxxxxxxxxecb,my_date
26/01/2021 00:00:00
set,c,090xxxxxxxxxxxxecb,my_doc_type_label
Value1
set,c,090xxxxxxxxxxxxecb,my_doc_type_id
11
set,c,090xxxxxxxxxxxxecb,doctype
Contract
checkin,c,090xxxxxxxxxxxxecb
##### UPDATE aspect fields : OK
retrieve,c,my_document where i_chronicle_id = '090xxxxxxxxxxxxecb'
set,c,l,aspect_huo.currency
EUR
set,c,l,aspect_huo.amount
121212
set,c,l,aspect_huo.indexation
1
set,c,l,aspect_huo.notice
3
set,c,l,aspect_huo.automatic_renewal
1
set,c,l,aspect_huo.renewal_duration
12
set,c,l,aspect_huo.contract_start_date
01/01/2021 00:00:00
set,c,l,aspect_huo.contract_end_date
31/01/2021 00:00:00
save,c,l
commit,c
Best regards,
Huseyin OZVEREN