Create
Object

Returns a reference to an Automation/COM/ActiveX object. The object is created using COM object creation services.

Syntax

CreateObject(servername.typename[, location])

servername is the name of the application that provides the object.

typename is the object's type or class that you want to create.

location (Optional) is the name of the network server you want the object created on. If missing the object is created on the local machine.

Note

An Automation/COM/ActiveX object always contains at least one type or class, but usually several types or classes are contained within. servername
and typename are often referred to as progid. Please note that a progid is not always a two part one, like servername.typename. It can have several parts, like servername.typename.version.

Example

Dim objRemote
Dim objLocal

' Create an object from class
' MyClass contained in the
' COM object MyApp on a
' remote server named FileSrv

Set objRemote = CreateObject( "MyApp.MyClass", "FileSrv")

' Create an object from class
' LocalClass contained in the
' COM object LocalApp on the
' local macine
Set objLocal = CreateObject( "LocalApp.LocalClass)

See Also

GetObject

Dim

Declares a variable of type Variant and allocates storage space.

Syntax

Dim varname[([subscripts])][, varname[([subscripts])]]...

varname is the name of the variable

subscripts (Optional) indicates the dimensions when you declare an array variable. You can declare up to 60 multiple dimensions using the following syntax:

upperbound[, upperbound]...

upperbound specifies the upper bounds of the array. Since the lower bound of an array in VBScript is always zero, upperbound is one less than the number
of elements in the array.

If you declare an array with empty subscripts, you can later resize it with ReDim; this is called a dynamic array.

Note

This statement is scope specific, i.e. you need to consider when and where you want to declare your variables. Variables that are only used in a specific procedure should be declared in this procedure. This will make the variable invisible and inaccessible outside the procedure. You can also declare your variables with script scope. This means that the variables will be accessible to
all procedures within the script. This is one way of sharing data between different procedures.

Dim statements should be put at the top of a procedure to make the procedure easier to read.

Example

' Declare a dynamic array
Dim arrstrDynamic()
' Declare a fixed size array
' with 5 elements
Dim arrstrFixed(4)
' Declare a non-array variable
Dim vntTest

See Also

ReDim and Set

Eval

Evaluates and returns the result of an expression.

Syntax

result = Eval(expression)

result (Optional) is the variable you want to assign the result of the evaluation to. Although result is optional, you should consider using the Execute statement, if you don't want to specify it.

expression is a string containing a valid VBScript expression.

Note

Because the assignment operator and the comparison operator is the same
in VBScript, you need to be careful when using them with Eval. Eval always uses the equal sign (=) as a comparison operator, so if you need to use it as an assignment operator, you should use the Execute statement instead.

Example

Dim blnResult
Dim lngX, lngY

' Initialize the variables
lngX = 15: lngY = 10
' Evaluate the expression
blnResult = Eval( "lngX = lngY")

blnResult holds the value false, because 15 is not equal to 10.

See Also

Execute statement

Execute

Executes one or more statements in the local namespace.

Syntax

Execute statement

statement is a string containing the statement(s) you want executed. If you include more than one statement, you must separate them using colons or embedded line breaks.

Note

Because the assignment operator and the comparison operator is the same in VBScript, you need to be careful when using them with Execute. Execute always uses the equal sign (=) as an assignment operator, so if you need to use it as a comparison operator, you should use the Eval function instead.

All in-scope variables and objects are available to the statement(s) being executed, but you need to be aware of the special case when your statements create a procedure:

Execute "Sub ExecProc: MsgBox ""In here"": End Sub"

The ExecProc's scope is global and thus everything from the global scope
is inherited. The context of the procedure itself is only available within the scope it is created. This means that if you execute the above shown Execute statement in a procedure, the ExecProc procedure will only be accessible within the procedure where the Execute statement is called. You can get around this by simply moving the Execute statement to the script level or using the ExecuteGlobal statement.

Example

Dim lngResult
Dim lngX, lngY

' Initialize the variables
lngX = 15: lngY = 10
' Execute the statement
Execute( "lngResult = lngX + lngY")

lngResult holds the value 25.

See Also

Eval and ExecuteGlobal statement

ExecuteGlobal

Executes one or more statements in the global namespace.

Syntax

ExecuteGlobal statement

statement is a string containing the statement(s) you want executed. If you include more than one statement, you must separate them using colons or embedded line breaks.

Note

Because the assignment operator and the comparison operator is the same in VBScript, you need to be careful when using them with ExecuteGlobal. ExecuteGlobal always uses the equal sign (=) as an assignment operator, so if you need to use it as a comparison operator, you should use the Eval function instead.

All variables and objects are available to the statement(s) being executed.

Example

Dim lngResult
Dim lngX, lngY

' Initialize the variables
lngX = 15: lngY = 10
' Execute the statement
ExecuteGlobal( "lngResult = lngX + lngY")

lngResult holds the value 25.

See Also

Eval and Execute

Filter

Returns an array that contains a subset of an array of strings. The array is zero-based as are all arrays in VBScript and it holds as many elements as are found in the filtering process The subset is determined by specifying a criteria.

Syntax

Filter(inputstrings, value[, include[, compare]])

inputstrings is a one dimensional string array that you want to search.

value is the string you want to search for.

include (Optional) is a boolean value indicating if you want to include (true) or exclude (false) elements in inputstrings that contains value.

compare (Optional) indicates the comparison method used when evaluating.
Use one of the following constants:

vbBinaryCompare – 0 (Default) Performs a binary comparison, i.e. a case
sensitive comparison.
vbTextCompare – 1 Performs a textual comparison, i.e. a non-case sensitive
comparison.

Note

An empty array is returned if no matches are found. A runtime error occurs
if inputstrings is not a one-dimensional array or if it is Null.

Example

Dim arrstrColors(3)
Dim arrstrFilteredColors

' Fill the array
arrstrColors(0) = "Red"
arrstrColors(1) = "Green"
arrstrColors(2) = "Blue"

' Filter the array
arrstrFilteredColors = Filter(arrstrColors, "Red")

arrstrFilteredColors now holds one element (0) which has the value Red.

See Also

See the String Function Replace

GetObject

Returns a reference to an Automation object.

Syntax

GetObject([pathname][, class]])

pathname (Optional) is a string specifying the full path and name of the file that contains the object you want to retrieve. You need to specify class if you omit this argument.

class (Optional) is a string that indicates the class of the object. You need to specify pathname if you omit this argument. The following syntax is used for class:

appname.objecttype

appname is a string indicating the application that provides the object.

objecttype is a string specifying the object's type or class that you want created.

Note

You can use this function to start the application associated with pathname and activate/return the object specified in the pathname. A new
object is returned if pathname is a zero-length string ("") and the currently active object of the specified type is returned if pathname is omitted. Please note, that if the object you want returned has been compiled with Visual Basic, you cannot
obtain a reference to an existing object by omitting the
pathname argument. A new object will be returned instead. The opposite is true for objects that are registered as single-instance objects; the same instance will always be returned. However, you should note the above-mentioned problems with ActiveX DLL's compiled using Visual Basic.

Some applications allow you to activate part of a file and you can do this by suffixing pathname with an exclamation mark (!)
and a string that identifies the part of the object you want.

You should only use this function when there is a current instance of the object you want to create, or when you want
the object to open up a specific document. Use CreateObject to create a new instance of an object.

Example

Dim objAutomation

' Create a reference to an
' existing instance of an
' Excel application (this
' call will raise an error
' if no Excel.Application
' objects already exists)
Set objAutomation = GetObject(, "Excel.Application")

' Create a reference to a
' specific workbook in a new
' instance of an Excel
' application
Set objAutomation = GetObject( "C:\Test.xls ")

See Also

CreateObject

GetRef

Returns a reference to a procedure. This reference can be bound to
an object event. This will let you bind a VBScript procedure to a DHTML event.

Syntax

Set object.eventname = GetRef(procname)

object is the name of the object in which eventname is placed.

eventname is the name of the event to which the procedure is to be bound.

procname is the name of the procedure you want to bind to eventname.

Example

Sub NewOnFocus()
' Do your stuff here
End Sub

' Bind the NewOnFocus
' procedure to the
' Window. OnFocus event
Set Window.OnFocus = GetRef("NewOnFocus ")

InputBox

Displays a dialog box with a custom prompt and a text box. The content of the text box is returned when the user clicks OK.

Syntax

InputBox(prompt[, title][, default][, xpos][, ypos][, helpfile, context])

prompt is the message you want displayed in the dialog box. The string can contain up to 1024 characters, depending on the width of the characters you use. You can separate the lines using one of these VBScript constants:

vbCr, vbCrLf, vbLf or vbNewLine

title (Optional) is the text you want displayed in the dialog box title bar.
The application name will be displayed, if this argument is omitted.

default is the default text that will be returned, if the user doesn't type in
any data. The text box will be empty if you omit this argument.

xpos (Optional) is a numeric expression that indicates the horizontal
distance of the left edge of the dialog box measured in twips (1/20 of a printer's point, which is 1/72 of an inch) from the left edge of the screen.
The dialog box will be horizontally centered if you omit this argument.

ypos (Optional) is a numeric expression that indicates the vertical distance
of the upper edge of the dialog box measured in twips from the upper edge of the screen. The dialog box will be vertically positioned approximately
one-third of the way down the screen, if you omit this argument.

helpfile (Optional) is a string expression that indicates the help file to use when providing context-sensitive help for the dialog box. This argument must be used in conjunction with context. This is not available on 16-bit platforms.

context (Optional) is a numeric expression that indicates the help context number that makes sure that the right help topic is displayed. This
argument must be used in conjunction with helpfile. This is not available
on 16-bit platforms.

Note

A zero-length string will be returned if the user clicks Cancel or presses
ESC.

Example

Dim strInput

strInput = InputBox( "Enter User Name:", "Test")

MsgBox strInput

The MsgBox will display either an empty string or whatever the user
entered into the text box.

See Also

MsgBox

IsEmpty

Returns a boolean value indicating if a variable has been initialized.

Syntax

IsEmpty(expression)

expression is the variable you want to check has been initialized.

Note

You can use more than one variable as expression. If for Example, you concatenate two Variants and one of them is empty, the IsEmpty function will return false, because the expression is not empty.

Example

Dim strTest
Dim strInput

strInput = "Test"

MsgBox IsEmpty(strTest) ' true
MsgBox IsEmpty(strInput & strTest) ' false

See Also

IsArray, IsDate, IsNull, IsNumeric, IsObject and VarType

IsNull

Returns a boolean value indicating if a variable contains Null or valid data.

IsNull(expression)

expression is any expression.

Syntax

This function returns true if the whole of expression evaluates to Null. If you have more than one variable in expression, all of them must be Null for the function to return true.

Please be aware that Null is not the same as empty (a variable that hasn't been initialized) or a zero-length string (""). Null means no valid value!

You should always use the IsNull function when checking for Null values, because using the normal operators will return false even if
one variable is Null.

Example

Dim strInput

strInput = "Test"
MsgBox IsNull( strInput & Null) ' false
MsgBox IsNull(Null) ' true

See Also

IsArray, IsDate, IsEmpty, IsNumeric, IsObject and VarType

IsNumeric

Returns a boolean value indicating if an expression can be evaluated as a number.

Syntax

IsNumeric(expression)

expression is any expression.

Note

This function returns true if the whole expression evaluates to a number. A Date expression is not considered a numeric expression.

Example

MsgBox IsNumeric(55.55) ' true
MsgBox IsNumeric("55.55") ' true
MsgBox IsNumeric("55.55aaa") ' false
MsgBox IsNumeric( "March 1, 1999") ' false
MsgBox IsNumeric(vbNullChar) ' false

See Also

IsArray, IsDate, IsEmpty, IsNull, IsObject and VarType

IsObject

Returns a boolean value indicating if an expression is a reference to a valid Automation object.

Syntax

IsObject(expression)

expression is any expression.

Note

This function returns true only if expression is in fact a variable of Variant subtype Object (9) or a user-defined object.

Example

Dim objTest

MsgBox IsObject(objTest) ' false

Set objTest = CreateObject( "Excel.Application")

MsgBox IsObject(objTest) ' true

See Also

IsArray, IsDate, IsEmpty, IsNull, IsNumeric, Set and VarType

LoadPicture

Returns a picture object.

Syntax

LoadPicture(picturename)

picturename is a string expression that indicates the file name of
the picture you want loaded.

Note

This function is only available on 32-bit platforms. The following graphic formats are supported:

Bitmap .bmp
Icon .ico
Run-length encoded .rle
Windows metafile .wmf
Enhanced metafile .emf
GIF .gif
JPEG .jpg

A runtime error occurs if picturename doesn't exist or if it is not a valid picture file. Use LoadPicture("") to return an "empty" picture object in order to clear a particular picture.

Example

Dim objPicture

' Load a picture into objPicture
objPicture = LoadPicture( "C:\Test.bmp")
' Clear objPicture
objPicture = LoadPicture( "")

MsgBox

Displays a dialog box with a custom message and a custom set of command buttons. The value of the button the user clicks is returned as the result of this function.

Syntax

MsgBox(prompt[, buttons][, title [, helpfile, context])

prompt is the message you want displayed in the dialog box. The string can contain up to 1024 characters, depending on the width of the characters you use. You can separate the lines using one of these VBScript constants:

vbCr, vbCrLf, vbLf or vbNewLine

buttons (Optional) is the sum of values indicating the number and type of button(s) to display, which icon style to use, which button is the default and if the MsgBox is modal. The settings for this
argument are:

vbOKOnly

vbOKCancel

vbAbortRetryIgnore

vbYesNoCancel

0

1

2

3

Displays OK button.

Displays OK and Cancel buttons.

Displays Abort, Retry, and Ignore buttons.

Displays Yes, No, and Cancel buttons.

vbYesNo

vbRetryCancel

vbCritical

vbQuestion

vbExclamation

vbInformation

vbDefaultButton1

vbDefaultButton2

vbDefaultButton3

vbDefaultButton4

vbApplicationModal

vbSystemModal

4

5

16

32

48

64

0

256

512

768

0

4096

Displays Yes and No buttons.

Displays Retry and Cancel buttons.

Displays critical icon.

Displays query icon.

Displays warning icon.

Displays information icon.

Makes the first button the default one.

Makes the second button the default one.

Makes the third button the default one.

Makes the fourth button the default one

When the MsgBox is application modal,
the user must respond to the message
box, before he/she can continue.

The same effect as vbApplicationModal.
Presumably this is a "left-over" from the
good old 16-bit Windows days. The
dialog box will stay on top of other
windows though.

Please note how the values are grouped:

Buttons (values 0-5)

Icon (values 16, 32, 48 and 64)

Default button (values 0, 256, 512 and 768)

Modal (values 0 and 4096)

You should only pick one value from each group when creating your MsgBox.

title (Optional) is the text you want displayed in the dialog box title bar. The application name will be displayed if this argument is omitted.

helpfile (Optional) is a string expression that indicates the help file to use when providing context-sensitive help for the dialog box. This argument must be
used in conjunction with context. This is not available on 16-bit platforms.

context (Optional) is a numeric expression that indicates the help context number that makes sure that the right help topic is displayed. This argument must be used in conjunction with helpfile.

Note

The following values can be returned:

vbOK (1)
vbCancel(2)
vbAbort (3)
vbRetry (4)
vbIgnore (5)
vbYes (6)
vbNo (7)

The ESC key has the same effect as the Cancel button. Clicking the Help
or pressing F1 will not close the MsgBox.

Example

Dim intReturn

intReturn = MsgBox( "Exit the application?", vbYesNoCancel + _
vbQuestion)

The MsgBox will display the message "Exit the application?", the buttons Yes, No and Cancel, and the question mark icon. This MsgBox will be application modal.

See Also

InputBox

RGB

Returns an integer that represents an RGB color value. The RGB color value specifies the relative intensity of red, green, and blue to cause a specific color
to be displayed.

Syntax

RGB(red, green, blue)

red is the red part of the color. Must be in the range 0-255.

green is the green part of the color. Must be in the range 0-255.

blue is the blue part of the color. Must be in the range 0-255.

Note

255 will be used, if the value for any of the arguments is larger than 255. A runtime error occurs if any of the arguments cannot be evaluated to a numeric value.

Example

' Returns the RGB number for white
RGB(255, 255, 255)

ScriptEngine

Returns a string indicating the scripting language being used.

Syntax

ScriptEngine

Note

The following scripting engine values can be returned:

VBScript MS VBScript

JScript MS JScript

VBA MS Visual Basic for Applications

Other third-party ActiveX Scripting Engines can also be returned, if you have installed one.

See Also