AppendItemValue (NotesDocument - LotusScript®)

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.

value

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	Multivalued text item with a value corresponding to each element of the array
	Long, Integer, Double, Single, or Currency	Number item containing the value
	Array of Long, Integer, Double, Single, or Currency	Multivalued number item with a value corresponding to each element of the array
	Variant of type DATE or NotesDateTime	Date-time item containing the value
	Array of Variant of type DATE or array of NotesDateTime	Multivalued date-time item with a value corresponding to each element of the array
	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

A NotesItem. The new item.

Usage

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 )

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 AppendItemValue, but note these differences in behavior:

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.

While this syntax may be adequate for one-time scripts, you should prefer

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.

Example