• Create BookmarkCreate Bookmark
  • Create Note or TagCreate Note or Tag
  • PrintPrint
Share this Page URL
Help

Part III: Appendixes > Functions

Functions

The built-in functions provided with VBScript are shown in Table A.4.

Table A.4. VBScript Functions
Function Remarks
Abs(value) Returns the absolute value of a numeric argument.
Array(arglist) Creates an array and assigns its elements the values passed as arguments.
Asc(string) Returns the ANSI value of the first character in a string argument. (ANSI values are the same as ASCII for letters, numbers, and the standard punctuation characters.)
Ascb(string) Returns the first byte of a string argument.
Ascw(string) Returns the first character code of a Unicode string.
Atn(number) Returns the arctangent of a number (uses radians).
CBool(expr) Converts any numeric expression or string to Boolean. Numeric 0 returns False; nonzero returns True. The strings "true" and "false" in any case are also accepted.
CByte(expr) Converts any numeric expression or string to a byte (8-bit) value.
CCur(expr) Converts any numeric expression or string to a Currency value. At most four decimal places are retained.
CDate(expr) Converts a string date or numeric expression to a Date value. String arguments must match the locale specific format. Numeric values are interpreted with the integer part equaling date and the fraction part equaling the time. (You can use the IsDate function to validate a string representation before attempting to convert it.)
CDbl(expr) Converts any numeric expression or string to a double-precision floating-point value. (Not useful in WSH.)
Chr(value) Returns a single-character string corresponding to the ANSI value.
CInt(value) Converts any numeric expression or string to a short (16-bit) integer value. Input numbers outside the range –32768 to 32767 will cause an error.
CLng(value) Converts any numeric expression or string to a long (32-bit) integer value. Numbers are rounded to the nearest integer.
Cos(number) Returns the trigonometric cosine of number, specified in radians. If given degrees, use cos(number*atn(1)/45).
CreateObject(servername.typename_
  [, location])

Creates an object of type servername.typename. The optional location specifies a network node.
CSng(value) Converts any expression to a single-precision floating-point value. (Not useful in WSH.)
CStr(value) Converts any expression to a string representation. Works with Boolean, Date, and all numeric types.
Date Returns the current date.
DateAdd(interval, number, date) Adds a number of specified interval units to a date. Interval is a string with one of the values listed in “Date Function Intervals,” later in this appendix.
DateDiff(interval, date1,_
  date2 [, firstdayofweek [,_
  firstweekofyear]])

Returns the number of intervals between two dates, where interval is a string with one of the values listed in “Date Function Intervals,” later in this appendix. When asking for the result in periods of a week or more, you may wish to specify the day that the week is considered to start on (the default is Sunday) as well as the week that the year is considered to start on (the default is January 1). For further information, see the section “Date and Time Constants,” later in this appendix.
DatePart(interval, date [,_
  firstdayofweek [,_
  firstweekofyear]])

Returns the specified part of the given date, where interval is one of the string values listed under “Date Function Intervals,” later in this appendix. When asking for the day of the week or the week of the year, you may wish to specify the starting day or week. For further information, see the section “Date and Time Constants,” later in this appendix.
DateSerial(year, month, day) Returns a Date value given a year, month, and day. Month is a number from 1 to 12.
DateValue(date) Returns a Date value, given a string representation of a date or date and time. If the string specifies a date and a time, the time portion is ignored. Can also be passed Date values.
Day(date) Returns the day number (1–31) of a date.
Eval(expression) Evaluates a string containing a valid VBScript expression as text and returns the result.
Exp(value) Returns evalue, where e is the base of natural logarithms.
Filter(InputStrings, Value [,_
  Include [, Compare]])

Returns an array containing those elements of string array inputstrings that match value. Here are the other arguments:

value— The substring to search for. The filter looks for elements of inputstrings that equal or contain value.

include— If passed and False, this argument returns those strings that do not contain a value.

compare— Specifies the type of comparison to make: vbBinaryCompare or vbTextCompare. The default is text. See “String Constants,” later in this appendix.

Fix(value) Truncates the fractional part of a numeric value and returns the integer portion only. In contrast to Int(), with a negative value Fix(), this function returns the negative integer value with the smallest magnitude (for example, Fix(-3.3) = -3).
FormatCurrency(value [,_
  NumDigitsAfterDecimal [,_
  IncludeLeadingDigit [,_
  UseParensForNegativeNumbers [,_
  GroupDigits]]]])

Returns the value of expression formatted as a string using the currency symbol defined in the Windows Locale settings. Optional arguments include the following:

NumDigitsAfterDecimal— The number of decimal places to display. The default is locale specific.

IncludeLeadingDigit— A tristate constant specifying whether a leading zero is to be displayed with fractional values. See “Tristate Settings,” later in this appendix, for the values permitted.

UseParensForNegativeNumbers— A tristate constant specifying whether to indicate negative numbers with - or ( ).

GroupDigits— A tristate constant specifying whether to group digits in large numbers with commas (or another local-specific character).

FormatDateTime(DateVal[, Format]) Formats a Date or Date-Time as a string. One of the constants listed in “Date Formatting Constants,” later in this appendix, may be specified to ensure a particular output format.
FormatNumber(value [,_
  NumDigitsAfterDecimal [,_
  IncludeLeadingDigit [,_
  UseParensForNegativeNumbers [,_
  GroupDigits]]]])

Returns a numeric value formatted as a string. The optional arguments are the same as those listed under FormatCurrency.
FormatPercent(value [,_
  NumDigitsAfterDecimal [,_
  IncludeLeadingDigit [,_
  UseParensForNegativeNumbers [,_
  GroupDigits]]]])

Returns a numeric value multiplied by 100, formatted as a string and followed with the % character. The optional arguments are the same as those listed under FormatCurrency.
GetLocale() Returns the current locale identifier value. The locale ID values are listed in the Microsoft Windows Scripting documentation file under “Locale ID (LCID) Chart.”
GetObject([filename] [, class]) Like New but this function obtains an object using either the application's data file filename, implying the application and object type, or an object moniker. If filename is specified, the application is instructed to open the file. The name may be followed with !subpart when only a part of the original file is desired (for example, in Excel workbooks).
 If the filename is omitted, the class name must be specified.
GetRef(procname) Used in HTML scripts (not applicable to WSH).
Hex(value) Formats the integer part of value to a hexadecimal string. Uppercase letters are used.
Hour(time) Returns the hour of the time value—an integer from 0–23.
InputBox(prompt [, title [,_
  default][, xpos, ypos] [,_
  helpfile, context])

Displays a dialog box with an input field into which the user may type a string. Returns the string entered by the user.

The only required argument is prompt, which specifies text to display to the user, up to about 1,024 characters. The text is word-wrapped if necessary. Line breaks can be forced by inserting vbCr, vbLf, or vbCrLf in the string.

Here are the optional parameters:

title— Text to display in the title bar of the dialog box. The default is “VBScript.”

default— The default text to put in the input field when the box is first displayed.

xpos, ypos— The location to display the dialog box, in 1/1440-inch units from the left and top edges of the screen. The default is centered.

helpfile, context— If you have created a Windows help file for your application, this is the full path and numeric context identifier for the associated help text.

InStr([start,] string1,_
  string2 [, compare])

Returns the starting position of string2 if found in string1, or 0 if string2 cannot be found. The optional argument start indicates the starting position in string1 to begin the search. Compare indicates the type of string search to perform; the default is text. See “String Constants,” later in this appendix.
InStrRev([start,] string1,_
  string2 [, compare])

Like InStr but searches starting at the right end of the string. For example, InStrRev("ABCAB","AB") = 4.
Int(value) Truncates the fractional part of a numeric value and returns the integer portion only. Negative fractional values are reduced to the next lower negative number. For example, Int(-3.3) = -4.
IsArray(varname) Returns True if the variable varname is an array. Otherwise, it returns False.
IsDate(expr) Returns True if the value expr is a Date or Date-Time value or can be interpreted as a Date. Otherwise, it returns False.
IsEmpty(expr) Returns True if the variable or expression is the Empty (uninitialized) value. Otherwise, it returns False. The test If variable = Empty also works.
IsNull(expr) Returns True if the variable or expression is the Null value. The test if variable = Null causes an error.
IsNumeric(expr) Returns True if the expression is a numeric value or can be interpreted as a numeric value. Otherwise, it returns False.
IsObject(varname) Returns True if the variable is an object reference. Otherwise, it returns False.
Join(array [, delimiter]) Returns a string consisting of all the elements of the array, joined with the delimiter string, which defaults to " ". The entries are converted to strings if necessary.
LBound(arrayname [, dimension]) Returns the array index lower bound of the specified dimension. Always returns 0 in VBScript.
LCase(string) Returns the string expression with all the characters in lowercase.
Left(string, length) Returns the leftmost length characters of the string expression. If the string has fewer than length characters, the return value is the entire string.
Len(string) Returns the length of the string expression in characters.
LoadPicture(picturename) Used in HTML scripts (not applicable to WSH).
Log(value) Returns the natural logarithm of the numeric value. Value must greater than 0. To get log base n, use log(value)/log(n).
LTrim(string) Returns the string expression less any leading spaces.
Mid(string, start[, length]) Returns length characters from the string expression, starting at position start. If the string has fewer than start characters, the zero-length ("") string is returned. If the string has fewer than length characters after the starting position, the return value is whatever's available.
Minute(time) Returns the minute of the hour of the time or Date-Time value (an integer between 0 and 59).
Month(date) Returns the number of the month of the date value (an integer from 1 to 12).
Monthname(month, [abbrev]) Returns the text name of the month (a number from 1 to 12). If abbrev is passed and is True, the returned month name is abbreviated, for example, “Oct”).
MsgBox(prompt [, buttons [,_
  title [, helpfile, context]]])

Displays a pop-up message box with at least one button the user must select before the script proceeds. The return value indicates which button the user selected; see “MsgBox Constants,” later in this appendix. The only required argument is prompt, which specifies the text to display to the user, up to about 1,024 characters. The text is word-wrapped if necessary. Line breaks can be forced by inserting vbCr, vbLf, or vbCrLf in the string. Here are the optional parameters:

buttons— A number indicating what types of buttons and possibly which icon to display. The value is the sum of one or more of the values listed in “MsgBox Constants,” later in this appendix.

title— The text to display in the title bar of the dialog box. The default is “VBScript.”

helpfile, context— If you have created a Windows help file for your application, this parameter specifies the full path and numeric context identifier for the associated help text.

Now Returns the current date and time.
Oct(value) Formats the integer part of value to an octal string.
Replace(expr, find,_
  replacewith [, start_
  [, count [, compare]]])

Returns the string expr with occurrences of the string find replaced by the string replacewith. Here are the optional arguments:

start— The starting position in expr to begin replacing occurrences of find.

count— The maximum number of occurrences to replace. The default is -1, which means make all possible replacements.

compare— The type of comparison to make: vbBinaryCompare or vbTextCompare. The default is text. See “String Constants,” later in this appendix.

RGB(red, green, blue) Returns a long integer representing an RGB color value: red, green, and blue are numbers from 0 to 255.
Right(string, length) Returns the rightmost length characters of the string expression. If the string has fewer than length characters, the return value is the entire string.
Rnd[(value)] Returns a random number in the range 0 <= Rnd < 1. The optional value argument indicates how to select the number.

If value is less than 0, the name number is returned every time using value as the seed.

If value is equal to 0, the most recently generated number is returned again.

If value is greater than 0 or not supplied, the next number in the sequence is returned.

Each returned value is kept as the seed for the next call. See Randomize.

To get a random integer between A and B, inclusive, use int(A+Rnd*(B-A+1))
Round(value [, nplaces]) Rounds the numeric value to nplaces decimal places. The default for nplaces is 0. This is helpful for financial calculations.
RTrim(string) Returns the string expression less any trailing spaces.
ScriptEngine Returns “VBScript.”
ScriptEngineBuildVersion Returns the VBScript build number (for example, 6626).
ScriptEngineMajorVersion Returns the major version number of the current version of VBScript (for example, 5).
ScriptEngineMinorVersion Returns the minor version number of the current version of VBScript (for example, 6).
Second(time) Returns the second of the minute of the time or date-time value (a number between 0 and 59).
SetLocale(localeid) Sets the VBScript locale to the specified identifier value and returns the previous value. For a list of values, see the Microsoft Windows Scripting documentation file under “Locale ID (LCID) Chart.”
Sgn(value) Returns an integer indicating the sign of the numeric value. The return value is -1 if value is less than 0, 0 if value is equal to 0, or 1 if value is greater than 0.
Sin(value) Returns the trigonometric sine of number, specified in radians. If given degrees, use sin(number*atn(1)/45).
Space(number) Returns a string consisting of number blanks.
Split(string [, delimiter [,_
  count [, compare]]])

Returns an array consisting of substrings of the string argument, divided at occurrences of the delimiter string. The default for delimiter is " ". Here are the optional arguments:

count— The maximum number of substrings to return. The default is -1, which means as many as can be found.

compare— The type of comparison to make when searching for delimiter: vbBinaryCompare or vbTextCompare. The default is text. See “String Constants,” later in this appendix.

Sqr(value) Returns the square root of the numeric value, which must be greater than or equal to 0.
StrComp(string1 [, string2 [,_
  compare]])

Compares string1 and string2 in a case-sensitive, lexicographic sense and returns -1 if string1 is less than (before) string2, 0 if string1 is equal to string2, or 1 if string1 is greater than string2. The optional argument is compare, which specifies the type of comparison to make when searching for delimiter: vbBinaryCompare or vbTextCompare. The default is text. See “String Constants,” later in this appendix.
String(number, char) Returns a string consisting of number repetitions of the specified character. Char can be a numeric character code or a string. If char is a string, only its first character is used.
StrReverse(string) Returns the string argument with its characters reversed, left to right.
Tan(value) Returns the trigonometric tangent of number, specified in radians. If given degrees, use tan(number*atn(1)/45).
Time Returns the current time of day as a Time value.
Timer Returns the number of seconds since midnight.
TimeSerial(hour, minute, second) Returns a Time value given an hour (023), minute (059) and second (059).
TimeValue(expr) Returns a Time value given a date-time or string representation of a time. (Should have been named CTime, because it acts like the other conversion functions.)
Trim(string) Returns the string expression less any leading or trailing spaces.
TypeName(varname) Returns a string description of the variant subtype of the specified variable. Like VarType but returns, for example, "String" instead of 8.
UBound(arrayname [, dimension]) Returns the upper bound of the specified dimension of an array.
UCase(string) Returns the string expression with all the characters in uppercase.
VarType(varname) Returns a value indicating the Variant subtype of a variable. The return value is one of those listed under “Variable Type Constants,” later in this appendix.
Weekday(date [, firstday]) Returns a number (17) indicating the day of the week of the date value. You may specify which day is the first (1) day with firstday, which must be one of the values listed in “Date and Time Constants,” later in this appendix. The default is vbSunday.
WeekdayName(number, abbrev,_
  firstday)

Returns a string containing the name of the day specified by the day number (17). If abbrev is passed and is True, the returned name is an abbreviated form (for example, “Wed”). See Weekday for a description of firstday.
Year(date) Returns the year of the date value as an integer (for example, 2002).



PREVIEW

                                                                          

Not a subscriber?

Start A Free Trial


  
  • Creative Edge
  • Create BookmarkCreate Bookmark
  • Create Note or TagCreate Note or Tag
  • PrintPrint