JavaBlog.fr / Java.lu API DCTM,DEVELOPMENT,Documentum,DQL DCTM,TOOLS DCTM Documentum : freeze, checkin, checkout, lock,…

Documentum : freeze, checkin, checkout, lock,…

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:
1r_object_id                : 09xxxxxxxxxxxxxx5
2r_modify_date              : 07/05/2017 09:05:26
3r_modifier                 : myuser123
4r_immutable_flag           : F
5r_frozen_flag              : F
6i_vstamp                   : 0

Document after freeze:
1r_object_id                : 09xxxxxxxxxxxxxx5
2r_modify_date              : 04/06/2017 09:39:03
3r_modifier                 : myuser123
4r_immutable_flag           : F
5r_frozen_flag              : F
6i_vstamp                   : 1

It is not possible to freeze a frozen document:
01freeze,c,09xxxxxxxxxxxxxx5
02save,c,09xxxxxxxxxxxxxx5
03 
04  r_object_id                : 09xxxxxxxxxxxxxx5
05  r_modify_date              : 04/06/2017 09:45:15
06  r_modifier                 : myuser123
07  r_immutable_flag           : T
08  r_frozen_flag              : T
09  i_vstamp                   : 1
10 
11API> freeze,c,09xxxxxxxxxxxxxx5
12...
13[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:
1r_object_id                : 09xxxxxxxxxxxxxx5
2r_modify_date              : 04/06/2017 09:45:15
3r_modifier                 : myuser123
4r_immutable_flag           : T
5r_frozen_flag              : T
6i_vstamp                   : 1

Document after freeze:
1r_object_id                : 09xxxxxxxxxxxxxx5
2r_modify_date              : 04/06/2017 11:45:15
3r_modifier                 : myuser123
4r_immutable_flag           : F
5r_frozen_flag              : F
6i_vstamp                   : 2

It is not possible to unfreeze a not frozen document:
01unfreeze,c,09xxxxxxxxxxxxxx5
02save,c,09xxxxxxxxxxxxxx5
03 
04  r_object_id                : 09xxxxxxxxxxxxxx5
05  r_modify_date              : 04/06/2017 09:45:15
06  r_modifier                 : myuser123
07  r_immutable_flag           : F
08  r_frozen_flag              : F
09  i_vstamp                   : 1
10 
11API> unfreeze,c,09xxxxxxxxxxxxxx5
12...
13[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.
1API> retrieve,c,dm_document where r_object_id = '090xxxxxxxxxx4f'
2...
3090xxxxxxxxxx4f
4API> destroy,c,l
5...
6[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.
01API> retrieve,c,my_type_document where r_object_id = '09xxxxxxxxxxxxxx5'
02...
0309xxxxxxxxxxxxxx5
04API> set,c,l,object_name
05my_document_name_1049
06...
07OK
08API> save,c,l
09...
10[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.
01API> checkout,c,090xxxxxxxxxxxxf5
02...
03090xxxxxxxxxxxxf5
04 
05  r_object_id                : 090xxxxxxxxxxxxf5
06  r_modify_date              : 04/06/2017 16:39:02
07  r_lock_owner               : myadminuser
08 
09  r_lock_date                : 04/06/2017 16:48:33
10 
11  r_lock_machine             : myhost123
12  r_version_label         [0]: 3.1
13                          [1]: CURRENT
14  r_immutable_flag           : T
15  r_frozen_flag              : T
16  i_vstamp                   : 2
17 
18API> checkout,c,090xxxxxxxxxxxxf5
19...
20090xxxxxxxxxxxxf5
21 
22  r_object_id                : 090xxxxxxxxxxxxf5
23  r_modify_date              : 04/06/2017 16:40:48
24  r_lock_owner               : myadminuser
25 
26  r_lock_date                : 06/06/2017 09:09:11
27 
28  r_lock_machine             : myhost123
29  r_version_label         [0]: 3.1
30                          [1]: CURRENT
31  r_immutable_flag           : T
32  r_frozen_flag              : T
33  i_vstamp                   : 3


TEST : CHECKOUT/CHECKIN a frozen document
DQL/API myadminuser : CHECKOUT/CHECKIN of frozen document is possible.
01API> checkout,c,090xxxxxxxxxxxxf5
02...
03090xxxxxxxxxxxxf5
04 
05API> set,c,090xxxxxxxxxxxxf5,object_name
06my_document_name_1045
07...
08OK
09 
10API> checkin,c,090xxxxxxxxxxxxf5
11...
12090xxxxxxxxxxxxxx69

Before CHECKOUT / CHECKIN
01r_object_id                : 090xxxxxxxxxxxxf5
02object_name                : my_document_name_0957
03r_modify_date              : 04/06/2017 16:40:48
04r_lock_owner               :
05 
06r_lock_date                : nulldate
07r_lock_machine             :
08r_version_label         [0]: 3.1
09                        [1]: CURRENT
10r_immutable_flag           : T
11r_frozen_flag              : T
12i_has_folder               : T
13i_latest_flag              : T
14i_direct_dsc               : F
15i_vstamp                   : 3
After CHECKOUT
01r_object_id                : 090xxxxxxxxxxxxf5
02object_name                : my_document_name_0957
03r_modify_date              : 04/06/2017 16:40:48
04r_lock_owner               : myadminuser
05r_lock_date                : 05/06/2017 11:00:21
06r_lock_machine             : myhost123
07r_version_label         [0]: 3.1
08                        [1]: CURRENT
09r_immutable_flag           : T
10r_frozen_flag              : T
11i_has_folder               : T
12i_latest_flag              : T
13i_direct_dsc               : F
14i_vstamp                   : 4
After CHECKIN : the document is still FROZEN
01r_object_id                : 090xxxxxxxxxxxxf5
02object_name                : my_document_name_0957
03r_modify_date              : 04/06/2017 16:40:48
04r_lock_owner               :
05 
06r_lock_date                : nulldate
07r_lock_machine             :
08r_version_label         [0]: 3.1
09r_immutable_flag           : T
10r_frozen_flag              : T
11i_has_folder               : F
12i_latest_flag              : F
13i_direct_dsc               : F
14i_vstamp                   : 5
After CHECKIN : NEW VERSION UNFROZEN of document after CHECKOUT / CHECKIN : 090xxxxxxxxxxxxxx69
01r_object_id                : 090xxxxxxxxxxxxxx69
02object_name                : my_document_name_1045
03r_modify_date              : 06/06/2017 10:46:38
04r_lock_owner               :
05 
06r_lock_date                : nulldate
07 
08r_lock_machine             :
09 
10r_version_label         [0]: 3.2
11 
12                        [1]: CURRENT
13 
14r_immutable_flag           : F
15 
16r_frozen_flag              : F
17i_has_folder               : T
18i_latest_flag              : T
19i_direct_dsc               : F
20i_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).
01API> lock,c,090xxxxxxxxxx4f
02...
03[DM_API_E_CANT_WITHOUT_OPEN_TRAN]error:  "You cannot perform 'lock' operation without an open transaction in this session."
04 
05API> begintran,c
06...
07OK
08API> lock,c,090xxxxxxxxxx4f
09...
10OK
11API> commit,c
12...
13OK
14 
15API> unlock,c,090xxxxxxxxxx4f
16...
17OK

The lock and unlock mechanism don’t modify any attribute of document:
01r_object_id                : 090xxxxxxxxxx4f
02object_name                : my_document_name_1045
03r_modify_date              : 06/06/2017 11:35:10
04r_lock_owner               :
05r_lock_date                : nulldate
06r_lock_machine             :
07r_version_label         [0]: 3.3
08                        [1]: CURRENT
09r_immutable_flag           : F
10r_frozen_flag              : F
11i_vstamp                   : 0

The UPDATE of a database LOCKED document is possible:
01API> retrieve,c,my_type_document where r_object_id = '090xxxxxxxxxx4f'
02...
03090xxxxxxxxxx4f
04API> set,c,l,object_name
05my_document_name_1338
06...
07OK
08API> save,c,l
09...
10OK


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:
1DQL: update dm_document object set r_lock_owner='', set r_lock_machine='', set r_lock_date=date('nulldate') where r_object_id='090xxxxxxxxxxxxf5'
2 
3API: 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:
01############# CANCEL CHECKOUT : OK
02#set,c,09xxxxxxxxxxxxxc8,r_immutable_flag
03#0
04#save,c,09xxxxxxxxxxxxxc8
05#
06#update dm_document object set r_lock_owner='', set r_lock_machine='', set r_lock_date=date('nulldate') where r_object_id='09xxxxxxxxxxxxxc8'
07#
08unlock,c,09xxxxxxxxxxxxxc8,F
09 
10 
11 
12 
13############# CHECKOUT and CHECKIN : OK
14begintran,c
15checkout,c,090xxxxxxxxxxxxecb
16 
17insert,c,090xxxxxxxxxxxxecb,r_aspect_name[0]
18aspect_huo
19set,c,090xxxxxxxxxxxxecb,object_name
20new document name
21set,c,090xxxxxxxxxxxxecb,my_date
2226/01/2021 00:00:00
23set,c,090xxxxxxxxxxxxecb,my_doc_type_label
24Value1
25set,c,090xxxxxxxxxxxxecb,my_doc_type_id
2611
27set,c,090xxxxxxxxxxxxecb,doctype
28Contract
29checkin,c,090xxxxxxxxxxxxecb
30 
31 
32##### UPDATE aspect fields : OK
33retrieve,c,my_document where i_chronicle_id = '090xxxxxxxxxxxxecb'
34set,c,l,aspect_huo.currency
35EUR
36set,c,l,aspect_huo.amount
37121212
38set,c,l,aspect_huo.indexation
391
40set,c,l,aspect_huo.notice
413
42set,c,l,aspect_huo.automatic_renewal
431
44set,c,l,aspect_huo.renewal_duration
4512
46set,c,l,aspect_huo.contract_start_date
4701/01/2021 00:00:00
48set,c,l,aspect_huo.contract_end_date
4931/01/2021 00:00:00
50save,c,l
51 
52commit,c

Best regards,


Huseyin OZVEREN

Leave a Reply

Your email address will not be published.

Time limit is exhausted. Please reload CAPTCHA.

Related Post