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