SetFieldValue

Description

Places the specified value in the named field.

If the field can be changed, this method sets its new value, regardless of whether that value is valid, and returns the empty String. To determine whether a field contains a valid value, obtain the FieldInfo Object for that field and call the ValidityChangedThisSetValue method of the FieldInfo object to validate the field.

If the field cannot be changed, the returned String indicates why the field cannot be changed. Typical values include "no such field", "record is not being edited", and "field is read-only".

If the field can have multiple values instead of just one, use the AddFieldValue method to add each new value. It is still legal to use SetFieldValue; however, using SetFieldValue on a field that already contains a list of values replaces the entire list with the single new value.

You can call this method only if the Entity object is editable. To make an existing Entity object editable, call the EditEntity method of the Session object.

Note: After a hook changes a field property or value, you may need to refresh any local variables that correspond to the changed field or any other field. Setting a field value can cause hooks to fire which may change the value or requiredness of any field in the record. Hooks or scripts may need to refresh local variables to keep them current with the values in the record. Refresh local variables when current values are needed.

Syntax

VBScript


entity.SetFieldValue field_name, new_value

Perl


$entity->SetFieldValue(field_name, new_value);

Identifier: Description
entity: An Entity object representing a user data record. Inside a hook, if you omit this part of the syntax, the Entity object corresponding to the current data record is assumed (VBScript only).
field_name: A String containing a valid field name of this Entity object.
new_value: For VBScript, a Variant containing the new value for the field. For Perl, a string containing the new value.
Return value: If changes to the field are permitted, this method returns an empty String; otherwise, this method returns a String containing an explanation of the error.

Examples

VBScript


' Set two field values, but only check errors for 
' the second field. 
entity.SetFieldValue "field1", "new value" 
returnVal = SetFieldValue("field2", "100")

Perl


# Set two field values for the entity

# Perform error checking on the second field

$entity->SetFieldValue("field1","new value");

$returnval = $entity->SetFieldValue("field2","100");