@Text(value; "*") - undocumented parameter "*" for @Text() function

Hi

Recently I needed to work with ReplicaID item from Catalog documents (catalog.nsf) and discovered that ReplicaID item contained Date-Time value instead of 16-character combination of letters and numbers that I used to work with.

Of course, I knew that there is some dependency of ReplicaID/DocumentUniqueID on its creation date-time but I had never focused on that too much.

But now I realized that I would like to know more.

I didn't find too much information about that in Internet though.
What I found out so far:

• There is an undocumented parameter "*" for @Text() formula function that allows to convert date-time value to something else. This "something else" looks like a database Replica ID or as a second half of a document universal ID

• Standard Catalog database uses this way to convert a value of ReplicaID item (that contains Date-Time value) to a usual format of ReplicaID

• It is possible to handle all these conversions of date-time to ReplicaID using lotusscripts but it is a tricky area. 

I suggest you to pay attention to:

1) ReplicaID item from Catalog document contains some special date-time, probably with milliseconds, created/updated by nCatalog task that works closer to NotesAPI date-time functions than to NotesDateTime lotusscript class.
You cannot reproduce the same value using NotesDateTime lotusscript class because it is less accurate I guess.To prove it I have created an agent in Catalog.nsf with the folowing script: 

It evaluates @Text(DateTimeValue; "*") in two ways: 

- using existing value from ReplicaID item (created/updated by nCatalog)
- using "the same" date-time value built by NotesDateTime class though

As you see below, conversion results are different:

2) If you lose TimeZone infromation, then a first character of ReplicaID will be changed. So always, when you do any conversions, keep an eye on TimeZone. Otherwise your local TimeZone will be taken and it will affect on your result. I found an example, written by Rod Whiteley on IBM dev. forum, that probably may handle all required conversion via NotesAPI but I personally didn't check it

Const wAPIModule = "NNOTES" ' Windows/32

Declare Private Function NSFDbOpen Lib wAPIModule Alias "NSFDbOpen" _
( Byval P As String, hDB As Long) As Integer
Declare Private Function NSFDbClose Lib wAPIModule Alias "NSFDbClose" _
( Byval hDB As Long) As Integer
Declare Private Function NSFNoteOpen Lib wAPIModule Alias "NSFNoteOpen" _
( Byval hDB As Long, Byval NoteID As Long, Byval F As Integer, hNT As Long) As Integer
Declare Private Function NSFNoteClose Lib wAPIModule Alias "NSFNoteClose" _
( Byval hNT As Long) As Integer
Declare Private Function NSFNoteUpdate Lib wAPIModule Alias "NSFNoteUpdate" _
( Byval hNT As Long, Byval F As Integer) As Integer
Declare Private Function NSFItemSetTime Lib wAPIModule Alias "NSFItemSetTime" _
( Byval hNT As Long, Byval N As String, T As Long) As Integer
Declare Private Function OSPathNetConstruct Lib wAPIModule Alias "OSPathNetConstruct" _
( Byval zP As Long, Byval S As String, Byval F As String, Byval N As String) As Integer


Sub CreateReplicaIDItem(doc As NotesDocument, itemname As String, rid As String)
db$ = Space(1024)
With doc.ParentDatabase
OSPathNetConstruct 0, .Server, .FilePath, db$
End With

Dim T(1) As Long ' TIMEDATE
T(0) = Clng("&H" & Mid$(rid, 9))
T(1) = Clng("&H" & Left$(rid, 8))

Dim hDB As Long
NSFDbOpen db$, hDB
If hDB = 0 Then Exit Sub

Dim hNT As Long
NSFNoteOpen hDB, Clng("&H" & doc.NoteID), 0, hNT
If Not hNT = 0 Then
NSFItemSetTime hNT, itemname & Chr$(0), T(0)
NSFNoteUpdate hNT, 0
NSFNoteClose hNT
End If

NSFDbClose hDB
End Sub