@SetField (Formula Language)

Assigns a value to a field stored within a document (use @Set for temporary variables). This is similar to using the FIELD keyword, except that @SetField can be used within another @function. If the field does not exist, this command creates it and applies the specified value to it.

Syntax

@SetField( fieldName ; value )

Parameters

fieldName

The name of the field whose value you want to set, enclosed in quotation marks.

value

Text, number, time-date, time-date range, or list thereof. The value you want to give to fieldName.

Usage

This function is most useful in agents, hotspot buttons, actions, and toolbar buttons. It does not work in column, selection, hide-when, window title, or form formulas.

With Release 6, you no longer need to declare the field receiving the assignment prior to setting its value with @SetField. For R5 or earlier clients, declare the field at the beginning of the formula, as follows:

FIELD Fieldname:=Fieldname;

The field that @SetField creates and assigns the specified value to if the specified field does not exist in the document is not visible to the user. You can remove a field added to a form this way using the @DeleteField function.

The value can be anything and does not have to match the type of the field as defined on a form. This function does not reset flags on an existing field and does not set flags for a newly stored field. For example, a Readers field does not become plain text by assigning a text value; and a newly stored field cannot be made a Readers field. The LotusScript® and Java™ classes allow this manipulation through NotesItem and Item.

Examples

  1. This formula checks the value of the Priority field; if the Priority is Low or Medium, the Status field is set to Closed; otherwise, the Status is set to Open. Before @SetField is encountered in the formula, the Status field is declared using the FIELD keyword.
    FIELD Status:=Status;
@If(Priority="Low"|Priority="Medium";@SetField("Status";"Closed");
@SetField("Status";"Open"))
  2. This code, when used in a view action button, deletes fields x_1 through x_20 in the selected document.
    @For(i := 1; i <= 20; i := i + 1;
@SetField("x_" + @Text(i);@DeleteField));
  3. This button formula sets the value of the name field to a list containing Joseph and Riley:
    @SetField("name"; "Joseph" : "Riley")