Value Object

The Value variable provides storage for an arbitrary type of data (string, numeric, boolean, data, array, etc.) and has the following methods and properties:

The object is exposed through the ITargetVar interface.

Properties

value

The value property provides access to the value of the variable.

Read/Write property

Type: variant

VB Sample

To get the variable's value:

   Dim val

   val = UserVar.value

To set the variable's value:

   UserVar.value = "New value" 'string value

   UserVar.value = 127   'numeric value

   UserVar.value = Now()  'date value

   UserVar.value = Array( "string1", "string2", "string3" ) 'an array of string values

Methods

FormatDate

Formats a date contained in the value according to the specified format.

Function FormatDate( format(optional), time(optional) )

Parameters:

variant format (optional, default value = false) - either a string containing the desired date format (See date formats) or a boolean (false: default date format, true: SQL compatible date format.)

boolean time (optional, default value = false) - applicable if the first parameter is a boolean; true: include the time part in the return value, false: do not include the time part in the return value

Return value:

string - text representation of the date value according to the specified format

VB Sample

Dim val

UserVar.value = CDate( "11/16/2005 13:34:12" )

val = UserVar.FormatDate( "DDDD, MMMM DD, YYYY" ) ' the return value: Wednesday, November 16, 2005

val = UserVar.FormatDate( "MM/DD/YYYY h:m:s p" ) ' the return value: 11/16/2005 1:34:12 PM

FormatNumeric 

Formats a numeric value according to a specified format.

Function FormatNumeric( format )

Parameters:

string format - a numeric format to use (See numeric formats.)

Return value:

string - text representation of the numeric value according to the specified format

VB Sample

Dim val

UserVar.value = CDbl( "4123.26" )

val = UserVar.FormatNumeric( "#,###" ) ' the return value: 4,123

val = UserVar.FormatNumeric( "#,###.#" ) ' the return value: 4,123.3

val = UserVar.FormatNumeric( "E" ) ' the return value: 4.12326E+003 

GetAt

Returns an element in the contained array using its index.  Applicable only if the contained variable is a one dimensional array.

Function GetAt( index )

Parameters:

integer index - an index of an element in the array; this parameter should be larger or equal to 0 and less than or equal to UBound()

Return value:

variant - array element located at the index position

VB Sample

Dim val

UserVar.value = Array( "string1", "string2", "string3" )

val = UserVal.GetAt( 2 ) ' return value: string3

IsArray

The method checks if the variables value is an array. GetAt, SetAt and UBound methods can be called on this variable if it is an array.

Function IsArray()

Parameters:

none

Return value:

variant - true: the value is an array; false: the value is not an array

VB Script

Dim val

UserVar.value = Array( "string1", "string2", "string3" )

If UserVar.IsArray() Then

   val = UserVar.GetAt( 0 )

Else val = Empty

End If 

IsEmpty

Checks if the value is Empty, Null or has a zero length.

Function IsEmpty()

Parameters:

none

Return value:

boolean - true: the value is empty, false otherwise

VB Sample

If UserVar.IsEmpty Then Target.Message( "The variable is empty" ) 

SetAt

Sets an element in the array using its index. Expands an array as needed.

Function SetAt( index, value )

Parameters:

integer index - an index of an element in the array; the parameter should be larger than or equal to 0. If index is less or equal to UBound(), an appropriate element of the array is set; if index is larger than UBound(), the array is expanded to accommodate the new value

Return value:

none

VB Sample

UserVar.SetAt 0, "string1"  ' a new array with a single element is created

UserVar.SetAt 2, "string3"  ' an array is expended, it has 3 elements now

UserVar.SetAt 1, "string2"  ' sets a second element of an array to string2

UBound

Returns the number of elements in the array.

Function UBound()

Parameters:

none

Return value:

integer - the number of elements in the array if the variable' value is an array. otherwise -1 is returned

VB Sample

Dim array(5), n

UserVar.value = array

n = UserVar.UBound() ' n = 5