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

NotesDocument

Syntax

Set notesItem = notesDocument.ReplaceItemValue( itemName$, value )

Parameters

itemName$

String. The name of the item(s) you want to replace.

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.

Note ReplaceItemValue method takes the NotesDateTime object as input directly.

	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.

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.

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 )

doc.Subject = "Update on stock options"
Call doc.Save( False, 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.

replaceItemValue method in Java Document class

@SetField function in formula language

@SetDocField function in formula language

FIELD keyword in formula language

Example
See Also

Creating an item and assigning values in LotusScript classes

Glossary