ReplaceItemValue (NotesDocument - LotusScript®)
Replaces all items of the specified name with one new item, which is assigned the specified value. If the document does not contain an item with the specified name, the method creates a new item and adds it to the document.
Defined in
Syntax
Set notesItem = notesDocument .ReplaceItemValue( itemName$ , value )
Parameters
itemName$
String. The name of the item(s) you want to replace.
value
The value of the new item. The data type of the item depends upon the data type of the value, and does not need to match the data type of the old item.
| Data type of value |
Resulting NotesItem |
|---|---|
| String |
Text item containing the value |
| Array of String |
Text item containing each element of the value |
| Long, Integer, Double, Single, or Currency |
Number item containing the value |
| Array of Long, Integer, Double, Single, or Currency |
Number item containing each element of the value |
| Variant of type DATE, NotesDateTime, or NotesDateRange |
Date-time item containing the value |
| Array of Variant of type DATE, array of NotesDateTime, or array of NotesDateRange |
Date-time item containing each element of the value |
| NotesItem |
Item whose data type matches the NotesItem type and whose value(s) match the NotesItem value(s) |
Type conversion occurs as necessary. For example, floating-point numeric items are double precision so a value of type Single is converted to Double prior to storage.
Return value
notesItem
NotesItem. The new item, which replaces all previous items that had the specified name. The new item has a new value, which may be of a different data type than the old item.
Usage
To keep the new item in the document, you must call the Save method after calling ReplaceItemValue.
The IsSummary property of the new item defaults to True, which means that the item value can be displayed in a view or folder.
Do not use this method to replace the value of a rich text item (or MIME entity) unless you want to change it to a text item. To replace the contents of a rich text item, use NotesDocument.RemoveItem or NotesRichTextItem.Remove to delete the old item, NotesDocument.CreateRichTextItem to create a new one with the same name, and NotesRichTextItem.AppendText and other methods to provide the new content.
"Extended class" syntax
You can also change an item's value using the NotesDocument "extended class" syntax, which eliminates the need for ReplaceItemValue. For example, you have the following script:
Dim item As NotesItem
Set item = doc.ReplaceItemValue _
( "Subject", "Update on stock options" )
Call doc.Save( False, True )You can achieve the same result by doing the following:
doc.Subject = "Update on stock options"
Call doc.Save( False, True )This syntax lets you treat NotesDocument as an "extended class" by using an item name as if it were a property of NotesDocument. In the preceding example, "Subject" is used as if it is a property of the NotesDocument class. The result is the same as if you used ReplaceItemValue, except that ReplaceItemValue returns a NotesItem object representing the item you just created, and the IsSummary property defaults to True.
While this syntax may be adequate for one-time scripts, you should prefer ReplaceItemValue because:
- The extended syntax is easy to confuse with a method or property of NotesDocument for someone reading your code.
- Your code may fail if a method or property that conflicts with the item name is added in a future release.
- ReplaceItemValue preserves the case of the item name whereas creating a field with the extended class syntax makes the item name all uppercase.
- ReplaceItemValue is marginally more efficient.