Creates a new item in a document and sets the item value.

Note In general, ReplaceItemValue is favored over AppendItemValue. If an item of the same name already exists in a document, AppendItemValue creates a second item of the same name, and the duplicate items are not accessible except through a work-around. If you are creating a new document, AppendItemValue is safe.

Defined in

NotesDocument

Syntax

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

Parameters

itemName$

String. The name of the new item.

The value of the new item. The data type of the new item depends upon the data type of the value that you place in it.

	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 or NotesDateTime	Date-time item containing the value
	Array of Variant of type DATE or array of NotesDateTime	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

A NotesItem. The new item.

To keep the new item in the document, you must call the Save method after calling AppendItemValue.

If the document already has an item called itemName$, AppendItemValue does not replace it. Instead, it creates another item of the same name, and gives it the value you specify.

The IsSummary property of the new item defaults to True, which means that the item value can be displayed in a view or folder.

"Extended class" syntax

You can also create an item in a document using the NotesDocument "extended class" syntax, which eliminates the need for AppendItemValue. For example, you have the following script:

Dim item As NotesItem
Set item = doc.AppendItemValue _
( "Subject", "Update on stock options" )
Call doc.Save( False, True )

doc.Subject = "Update on stock options"
Call doc.Save( False, True )

• If an item of the specified name already exists, AppendItemValue creates a new item with the same name. The extended class syntax, however, acts like the ReplaceItemValue method; it replaces all existing occurrences of the item with a single occurrence of the item containing the new value.
• AppendItemValue returns a NotesItem object representing the item you just created.

appendItemValue 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.
• AppendItemValue is marginally more efficient.

appendItemValue method in Java Document class

Example
See Also

Creating an item and assigning values in LotusScript classes

Glossary