GetFieldChoiceList

Description

Returns the list of permissible values for the specified field.

The administrator specifies whether the legal values for a given field are restricted to the contents of the choice list. If there is a restriction, specifying a value not in the choice list causes a validation error. If there is no restriction, you may specify values not in the choice list. (Note that any values you specify must still be validated.)

If this method returns an Empty Variant, it does not imply that all values are permitted; it just means that the administrator has not provided any hints about the values permitted in the field.

If the administrator chose to use a hook to determine the values of the choice list, HCL Compass has already executed the hook and cached the resulting values in a HookChoices Object (Visual Basic only). You can use that object to retrieve the values.

If you have a choice list hook, which generates the set of choices for a field, it must return its results by filling in a collection that is passed into the hook procedure.

You can use the GetFieldNames method to obtain a list of valid names for the field_name parameter.

Note: When calling this method from an external Visual Basic program, this method throws an exception if the entity is not editable.

Syntax

VBScript


entity.GetFieldChoiceList field_name

Perl


$entity->GetFieldChoiceList(field_name);

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 that identifies a valid field name of entity.
Return value: For Visual Basic, a Variant containing an Array is returned. Each element of the array contains an acceptable value for the specified field. If a list of choices was not provided with the field, the returned Variant is Empty.
For Perl, a reference to an array of strings is returned.

Examples

VBScript


fieldValue = GetFieldValue("field1").GetValue 

' Check to see if the field's current value is in the choice list
fieldChoiceList = GetFieldChoiceList("field1") 
For Each fieldChoice in fieldChoiceList
   If fieldValue = fieldChoice Then
      ' This is a valid choice 
   End If 
Next

Perl


# If the field must have a value from a closed choice list, assign

# the first value in the list to the field by default. 



$choicetype = $entity->GetFieldChoiceType("field1");

if ($choicetype eq $CQPerlExt::CQ_CLOSED_CHOICE)

 {

 # Set the field to the first item in the choice list. 

 $fieldchoicelist = $entity->GetFieldChoiceList("field1");

 $entity->SetFieldValue("field1",@$fieldchoicelist[0]);

 } 
#Example 2: 
sub Dyn_choice_get_values 

{

   my $session;

   my $fieldchoicelist;   

   $session = $entity->GetSession();

   $fieldchoicelist = $entity->GetFieldChoiceList("Dyn_List_Example");

   $session->OutputDebugString(" CHOICELIST @$fieldchoicelist \n");

   return 0;

}