Profit and Value from Information Technology
Ecommerce & Extranets : Client Systems : Enterprise Applications : Application Development

Search the site:
EXPERT SEARCH

| Programming Languages
| Databases
| Security
| Web Services
| Network Services
| Middleware
| Components
| Operating Systems
| User Interfaces
| Groupware & Collaboration
| Content Management
| Productivity Applications
| Hardware
| Fun & Games

EarthWeb sites
Crossnodes
Datamation
Developer.com
DICE
EarthWeb.com
EarthWeb Direct
ERP Hub
Gamelan
GoCertify.com
HTMLGoodies
Intranet Journal
IT Knowledge
IT Library
JavaGoodies
JARS
JavaScripts.com
open source IT
RoadCoders
Y2K Info

# Appendix A

# VBScript Language Reference

CONTENTS

- Variables, Constants, and Expressions
- Operators
  - Arithmetic Operators
  - Concatenation Operators
  - Logical Operators
  - Comparison Operators
- Statements
- Functions
  - Variable and Conversion Functions
  - Date/Time Functions
  - Conditional Functions
  - String Functions
  - Input Functions
  - Mathematical Functions

## Variables, Constants, and Expressions

Variables and constants are similar in that they both refer to a location in memory that contains a value. A constant has a value that remains the same throughout the execution of the program. A variable, on the other hand, is modified during the execution. Every constant and variable is assigned a name that uniquely identifies it and must follow the conventions listed here:

- Must begin with an alphabetic character
- Cannot contain an embedded period or type-declaration character
- Must be unique in the same scope
- Must not exceed 255 characters

A constant may be a string or numeric literal, another constant, or any combination that includes arithmetic or logical operators. For example:

>     Const Ident = "This is Freds script"

Possible variable subtypes as well as their data ranges are shown in Table A.1. Other reserved terms when describing data types are shown in Table A.2.

Table A.1. `Variant` subtypes.

Subtype | Range
`Byte` | 0 to 255.
`Boolean` | `True` or `False`.
`Integer` | -32,768 to 32,767.
`Long` | -2,147,483,648 to 2,147,483,647.
`Single` | -3.402823E38 to -1.401298E-45 for negative values; 1.401298E-45 to 3.402823E38 for positive values.
`Double` | -1.79769313486232E308 to -4.94065645841247E-324 for negative values; 4.94065645841247E-324 to 1.79769313486232E308 for positive values.
`Currency` | -922,337,203,685,477.5808 to 922,337,203,685,477.5807.
`Date` | January 1, 100 to December 31, 9999, inclusive.
`Object` | Any Object reference.
`String` | Variable-length strings may range in length from 0 to approximately 2 billion characters (approximately 65,535 for Microsoft Windows version 3.1 and earlier).

Table A.2. Data type reserved terms.

Term | Description
`Nothing` | A value that indicates that an object variable is no longer associated with any actual object.
`Null` | A value indicating that a variable contains no valid data.
`Empty` | A value that indicates that no beginning value has been assigned to a variable (0 for a numeric subtype or a zero-length string).

## Operators

When several operations occur in an expression, each part is evaluated and resolved in a predetermined order known as operator precedence. (See Table A.3.) Parentheses can be used to override this order. When the precedence is equal (that is, addition and subtraction, multiplication and division, all comparison operators), the expressions are evaluated from left to right.

Table A.3. Operator precedence.

Symbol | Description | Type
`^` | Exponentiation | Arithmetic
`-` | Negation | Arithmetic
`*` | Multiplication | Arithmetic
`/` | Division | Arithmetic
`\` | Integer division | Arithmetic
`Mod` | Modulo arithmetic | Arithmetic
`+` | Addition | Arithmetic
`-` | Subtraction | Arithmetic
`&` | String concatenation | Arithmetic
`=` | Equality | Comparison
`<>` | Inequality | Comparison
`<` | Less than | Comparison
`>` | Greater than | Comparison
`<=` | Less than or equal to | Comparison
`>=` | Greater than or equal to | Comparison
`IS` | Same object | Comparison
`NOT` | Negation | Logical
`AND` | Bitwise conjunction | Logical
`OR` | Bitwise disjunction | Logical
`XOR` | Bitwise exclusion | Logical
`EQV` | Bitwise equivalence | Logical
`IMP` | Bitwise implication | Logical

### Arithmetic Operators

Arithmetic operators are used in expressions to perform mathematical calculations. The following general rules are involved in the operations:

- If one or both operands are `Null` expressions, the result is `Null`.
- If an operand is `Empty`, it is treated as a `0`.

#### `+` (Addition) Operator

This operator determines the sum of two numbers. Its usage is

>     sum = expr1 + expr2

where `sum` is a numeric variable, and `expr1` and `expr2` are any expressions.

NOTE
Though the `+` operator can be used to concatenate two character strings, its usage as a concatenation operator is discouraged. The `&` operator should be used for that purpose.

If both expressions in the operation are strings, a concatenation of these strings will occur. Otherwise, an addition will be performed.

The general rules apply. If both expressions are `Empty`, the result is an `Integer` subtype equal to `0`.

#### `-` (Subtraction) Operator

The subtraction operator will yield the difference between two numbers when used as

>     result = number1 - number2

where `result` is a numeric variable, and `number1` and `number2` are numeric expressions.

This operator can also be used as the unary negation operator to change to the negative value of a numeric expression. In this case its usage is

>     -number

where `number` is a numeric expression.

The general rules apply.

#### `*` (Multiplication) Operator

The multiplication operator will yield the product of two numbers. Its usage is

>     result = multiplier1 * multiplier2

where `result` is a numeric variable, and `multiplier1` and `multiplier2` are numeric expressions.

The general rules apply.

#### `/` (Division) Operator

The division operator will yield the quotient of two numbers. Its usage is

>     quotient = dividend / divisor

where `quotient` is a numeric floating-point variable, and `dividend` and `divisor` are numeric expressions.

The general rules apply.

#### `\` (Integer Division) Operator

The integer division operator divides two numbers and return an integer result. Its usage is

>     quotient = dividend \ divisor

where `quotient` is a numeric variable, and `dividend` and `divisor` are numeric expressions.

Numeric expressions are rounded to `Byte`, `Integer`, or `Long` subtype expressions. Then the general rules apply.

#### `^` (Exponentiation) Operator

The exponentiation operator will yield the power of a number raised to an exponent. Its usage is

>     result = number ^ exponent

where `result` is a numeric variable, and `number` and `exponent` are numeric expressions.

As well as the general rules, `exponent` must be an integer if `number` is a negative value.

#### `Mod` (Modulus) Operator

The modulus operator determines the remainder from the division of two numbers. Its usage is

>     result = dividend Mod divisor

where `result` is any numeric variable, and `dividend` and `divisor` are numeric expressions. If the dividend or divisor is a floating-point number, it is rounded to an integer before the operation. The general rules apply.

### Concatenation Operators

Concatenation operators combine strings. The general rules are

- Any non-string operands are converted to a `String` subtype before the operation.
- Any operand that is `Null` or `Empty` is treated as a zero-length string.
- If both operands are `Null`, the result is `Null`.

#### `&` (Concatenation) Operator

The `&` concatenation operator will combine two expressions into a string result. Its usage is

>     result = expr1 & expr2

where `result` is any variable, and `expr1` and `expr2` are any expressions.

#### `+` (Concatenation) Operator

The `+` concatenation operator functions in the same manner as the `&` concatenation operator when either operand is a `String` subtype. Its usage is

>     result = expr1 + expr2

where `result` is any variable, and either `expr1` or `expr2` is a `String` variable.

NOTE
Use of the `+` concatenation operator is not recommended. Use the `&` operator to eliminate ambiguity.

### Logical Operators

Logical operators perform logical comparison and algebraic bitwise operations. Some general rules are

- A `Null` expression is treated as a numeric zero in these operations.
- A nonzero value (or bit) is `True`.
- A zero value (or bit) is `False`.

#### `AND` Operator

The `AND` operator can perform a logical conjunctive comparison on two expressions as well as perform a bitwise algebraic conjunctive operation. Its usage is

>     result = expr1 AND expr2

where `result` is any numeric variable, and `expr1` and `expr2` are any expressions. When the `AND` operator performs a bitwise comparison of two numeric expressions, it sets the corresponding bit in `result` according to the truth table in Figure A.1. When used as a logical comparison operator, `result` is set according to the truth table in Figure A.1 also.

Figure 1. : AND operator truth tables.

#### `OR` Operator

The `OR` operator can perform a logical disjunctive comparison on two expressions as well as perform a bitwise algebraic disjunctive operation. Its usage is

>     result = expr1 OR expr2

where `result` is any numeric variable, and `expr1` and `expr2` are any expressions. When the `OR` operator performs a bitwise comparison of two numeric expressions, it sets the corresponding bit in `result` according to the truth table in Figure A.2. When used as a logical comparison operator, `result` is set according to the truth table in Figure A.2 also.

Figure 2. : OR operator truth tables.

#### `XOR` Operator

The `XOR` operator can perform a logical exclusive comparison of two expressions as well as perform a bitwise exclusive algebraic operation. Its usage is

>     result = expr1 XOR expr2

where `result` is any numeric variable, and `expr1` and `expr2` are any expressions. When the `XOR` operator performs a bitwise comparison of two numeric expressions, it sets the corresponding bit in `result` according to the truth table in Figure A.3. When used as a logical comparison operator, `result` is set according to the truth table in Figure A.3 also.

Figure 3. : XOR operator truth tables.

#### `EQV` Operator

The `EQV` operator can perform a logical equivalence comparison of two expressions as well as perform a bitwise equivalence algebraic operation. Its usage is

>     result = expr1 EQV expr2

where `result` is any numeric variable, and `expr1` and `expr2` are any expressions. When the `EQV` operator performs a bitwise comparison of two numeric expressions, it sets the corresponding bit in `result` according to the truth table in Figure A.4. When used as a logical comparison operator, `result` is set according to the truth table in Figure A.4 also.

Figure 4. : EQV operator truth tables.

#### `IMP` Operator

The `IMP` operator can perform a logical implication comparison of two expressions as well as perform a bitwise implication algebraic operation. Its usage is

>     result = expr1 IMP expr2

where `result` is any numeric variable, and `expr1` and `expr2` are any expressions. When the `IMP` operator performs a bitwise comparison of two numeric expressions, it sets the corresponding bit in `result` according to the truth table in Figure A.5. When used as a logical comparison operator, `result` is set according to the truth table in Figure A.5 also.

Figure 5. : EQV operator truth tables.

#### `-` (Negation) Operator

The negation operator can indicate the negative value of a numeric expression. Its usage is

>     -number

where `number` is any numeric expression.

NOTE
The syntax of the usage distinguishes between the negation operator and the subtraction operator.

#### `NOT` Operator

The `NOT` operator can perform a logical negation of an expression as well as an algebraic bitwise reversal of an expression. Its usage is

>     result = NOT expr

where `result` is a numeric variable and `expr` is any expression. When used as a negation operator, if `expr` is `True`, `result` will be `False`. If expr is `False`, `result` will be `True`. If `expr` is `Null`, `result` will be `Null`.

When used as an algebraic operator, each bit in `result` will be cleared if set in `expr` or set if clear in `expr`.

### Comparison Operators

Comparison operators match two expressions and provide alternative program execution flow. Their usage is

>     result = expr1 op expr2

>     result = obj1 IS obj2

>     result = string LIKE pattern

where `op` is the comparison operator, `result` is a numeric variable, `expr1` and `expr2` are expressions, `obj1` and `obj2` are objects, `string` is a string variable, and `pattern` is a string expression.

NOTE
The logical operators can also be used as comparison operators.

The general rules for comparisons are

- If both expressions are numeric, a numeric comparison is performed.
- If both expressions are strings, a string comparison is performed.
- When comparing a string to a numeric, the numeric expression is always the lesser of the two.
- If one expression is `Empty` and the other is a numeric expression, the `Empty` expression is treated as a numeric `0`. If both are `Empty`, then they are both treated as numeric `0` and are equal.
- If one expression is `Empty` and the other is a string expression, the `Empty` expression is treated as a `Null` string.
- If either expression is `Null`, the result is `Null`.
- If both expressions are `Empty`, the expressions are equal.

#### `<` (Less than) Operator

The less than operator's usage is

>     expr1 < expr2

and a `True` result is yielded when `expr1` is arithmetically less than `expr2`.

#### `<=` (Less than or equal to) Operator

The less than or equal to operator's usage is

>     expr1 <= expr2

and a `True` result is yielded when `expr1` is arithmetically less than or equal to `expr2`.

#### `>` (Greater than) Operator

The greater than operator's usage is

>     expr1 > expr2

and a `True` result is yielded when `expr1` is arithmetically greater than `expr2`.

#### `>=` (Greater than or Equal to) Operator

The greater than or equal to operator's usage is

>     expr1 >= expr2

and a `True` result is yielded when `expr1` is arithmetically greater than or equal to `expr2`.

#### `=` (Equal to) Operator

The equal to operator's usage is

>     expr1 = expr2

and a `True` result is yielded when `expr1` is arithmetically equal to `expr2`.

#### `<>` (Not Equal to) Operator

The not equal to operator's usage is

>     expr1 <> expr2

and a `True` result is yielded when `expr1` is arithmetically not equal to `expr2`.

#### `Is` Operator

The `Is` operator compares two object reference variables. Its usage is

>     obj1 Is obj2

where `obj1` and `obj2` are object names. If `obj1` and `obj2` both refer to the same object, the condition is `True`. Two variables can be made to refer to the same object by using the `Set` statement.

## Statements

This section describes the statement syntax for the VBScript language. In the descriptions the use of brackets ([]) indicates an optional entry or keyword.

#### `Call` Statement

The `Call` statement transfers control to a `Sub` procedure or `Function` procedure. Its usage is

>     Call name ([[ByVal] arg1, [ByVal] arg2, ... [ByVal] argn])

>     [result =] name [[ByVal] arg1, [ByVal] arg2, ... [ByVal] argn]

where `name` is the name of the procedure to call, `arg1` through `argn` are a comma-delimited list of expressions to pass to the procedure, and `result` is any numeric variable. If the `ByVal` keyword precedes a variable in the argument list , the argument is being passed to the procedure by value and the procedure being called may change the value of the variable. In the first syntax, the argument list must be enclosed in parentheses and a result is not available.

#### `Dim` Statement

The `Dim` statement declares variables and allocates storage space. Its usage is

>     Dim var1[([subs])][, var2[([subs])]] . . .

where `var1` and `var2` are names of variables to be declared and `subs` are upper-bound dimensions for an array variable. An array can have up to 60 dimensions. The lower bound of an array is always 0. Scoping rules will apply to the variables declared. When variables are initialized, a numeric variable is initialized to 0 and a string is initialized to a zero-length string (`""`).

If the `subs` fields are not specified (empty parentheses), a dynamic array is indicated. In this case the `ReDim` statement can be used later to define the number of dimensions and elements in the array.

#### `Do...Loop` Statement

The `Do` loop repeats a block of statements while a condition is `True` or until a condition becomes `True`. The two possible usages are

>     Do [{While | Until} condition]

>         [statements]

>     Loop

>     Do

>         [statements]

>     Loop [{While | Until} condition]

where `condition` is an expression that can be evaluated to `True` or `False`. `Statements` are various statements that are repeated while or until `condition` is `True`. To exit the loop immediately, use the `Exit Do` statement.

#### `Erase` Statement

The `Erase` statement will free the storage used by a dynamic array. If the array is fixed size, the elements in the array will be reset. Its usage is

>     Erase array

where `array` is the name of the array to be erased.

#### `Exit` Statement

The `Exit` statement is used to escape from a block of code. The statement varies depending on the type of block involved. Its usages are

>     Exit Do

>     Exit For

>     Exit Function

>     Exit Sub

#### `For...Next` Statement

The `For...Next` loop repeats a group of statements a specified number of times and optionally varies a variable within the loop. Its usage is

>     For count = start To end [Step step]

>         [statements]

>     Next

where `count` is a numeric variable used as a loop counter, `start` is the beginning value for `count`, `end` is the ending value, and `step` is the amount `count` is to change (defaulting to 1) for each iteration of the loop. `Statements` is the block of code to be executed on each iteration. The sequence of loop iterations can be either positive or negative, depending upon the step value.

The `Exit For` statement can be used to escape from the loop.

#### `For Each...Next` Statement

The `For Each...Next` statement is a variation of the `For` loop that can repeat a block of code for each element in an array. Its usage is

>     For Each entry In array

>         [statements]

>     Next [entry]

where `entry` is a variable used to iterate through the elements of the array, `array` is the name of a collection or array, and `statements` is a block of code to be executed on each iteration. An `Exit For` can be used to escape from the loop.

#### `Function` Statement

The `Function` statement defines the block of code that makes up a function procedure. It encompasses the name and arguments of that procedure. Its usage is

>     Function name [[ByVal] arg1, [ByVal] arg2, ... [ByVal] argn]

>         [statements]

>         [name = expression]

>     End Function

where `name` is the name of the function, `arg1` through `argn` is a list of variables passed to the procedure, and `statements` is a block of code to be executed. The `name = expression` optional line returns a value to the caller of the function. The `ByVal` keyword indicates an argument whose value may be changed during the procedure.

An `Exit Function` statement can be used to escape from the function at any point.

#### `If...Then` Statement

The `If...Then` statement provides alternative statement execution depending upon varying conditions that may be present. Its usage is

>     If condition-1 Then

>         [statements]

>     [ElseIf condition-2 Then

>         [elifstatements]]

>     [Else

>         [elstatements]]

>     End If

where `condition-1` and `condition-2` are conditional expressions (see comparison and logical operators above), `statements` is a block of code executed when `condition-1` is `True`, `elifstatements` is a block of code executed when `condition-1` is `False` and `condition-2` is `True`, and `elstatements` is a block of code that is executed when neither `condition-1` nor `condition-2` is `True`.

NOTE
A single line form of the `If` statement is available; however, its use is discouraged for readability reasons.

#### `On Error` Statement

The `On Error` statement identifies an error-handling routine and specifies the location of the routine within a procedure. It can also be used to disable an error-handling routine. Its usage is

>     On Error Resume Next

#### `Randomize` Statement

The `Randomize` statement sets a new seed value into the random-number generator. Its usage is

>     Randomize [number]

where `number` is a numeric expression.

#### `ReDim` Statement

The `ReDim` statement declares dynamic-array variables and allocates or reallocates storage space. Its usage is

>     ReDim [Preserve] name(subs) [,name(subs)] . . .

where `Preserve` indicates that the existing values in an array are to be saved when changing the size of the last dimension, `name` is the name of a variable, and `subs` are the redimensions of an array variable.

#### `Rem` Statement

The `Rem` statement is a nonexecutable statement and provides documentary remarks in a program. Its usages are

>     Rem comment

or

>     ' comment

where `comment` is the text of any remarks you want to include.

#### `Select` `Case` Statement

`Select Case` executes one of several groups of statements, depending on the value of an expression. Its usage is

>     Select Case testexpr

>         [Case expr1

>             [statements1]]

>         [Case expr2

>             [statements2]]

>           .

>           .

>           .

>         [Case exprn

>             [statementsn]]

>         [Case Else

>             [elstatements]]

>     End Select

where `testexpr` is any expression; `expr1`, `expr2`,`...`, and `exprn` are alternative values for `testexpr`; and `statements1`, `statements2`,`...`, and `statementsn` are blocks of code that are executed when the value of `testexpr` matches the respective case expression. `elstatements` is a block of code that is executed when `testexpr` doesn't match any of the case expressions.

#### `Set` Statement

The `Set` statement assigns an object reference to a variable or property. Its usage is

>     Set objectvar = { objectexpr | Nothing}

where `objectvar` is the name of a variable and `objectexpr` is the name of an object, a variable of an object type, or a function that returns an object of an object type. If `Nothing` is specified, the name of the object is disassociated from `objectvar`.

#### `Sub` Statement

The `Sub` statement defines the block of code that makes up a subroutine. It encompasses the name and arguments of that routine. Its usage is

>     Sub name [[ByVal] arg1, [ByVal] arg2, ... [ByVal] argn]

>         [statements]

>     End Sub

where `name` is the name of the subroutine, `arg1` through `argn` is a list of variables passed to the procedure, and `statements` is a block of code to be executed. Unlike a procedure, a subroutine cannot be used on the right side of a statement and does not return a value. The `ByVal` keyword indicates an argument whose value may be changed during the procedure.

An `Exit Sub` statement can be used to escape from the function at any point.

#### `While...Wend` Statement

The `While` statement is similar to the `Do While` statement and executes a block of code while a condition is `True`. Its usage is

>     While condition

>         [statements]

>     Wend

where `condition` is a comparison or logical expression that can be evaluated to `True` or `False` and `statements` is the block of code to be executed.

## Functions

The VBScript language offers a number of built-in procedures that are used to extend the functionality of the language. These are implemented as functions and as such will return a value that can be used in expressions. For convenience these functions can be grouped by purpose.

### Variable and Conversion Functions

The variable and conversion functions deal directly with the types of variables and offer ways to convert these variables from one type to another. Refer to Table A.1 for more information.

#### `CBool` Function

The `CBool` function returns a `Boolean` value that depends on the value of the argument. Its usage is

>     result = CBool(expr)

where `result` is an expression that is a `Variant` of subtype `Boolean` and `expr` is a valid expression that can be evaluated to a numeric value. If `expr` is `0`, the function returns `False`; otherwise, it returns `True`. If `expr` cannot be evaluated to a numeric value, the function causes a runtime error.

#### `CByte` Function

The `CByte` function converts an expression into a byte value. Its usage is

>     result = CByte(expr)

where `result` is a `Variant` of subtype `Byte` and `expr` is a valid expression with a value in the byte range. If `expr` is not in the byte range, an error occurs.

#### `CDbl` Function

The `CDbl` function returns an expression that has been converted to a `Variant` of subtype `Double`. Its usage is

>     result = CDbl(expr)

where `result` is a `Variant` of subtype `Double` and `expr` is a valid expression with a value in the double range.

#### `Chr` Function

The `Chr` function converts an ANSI character code into a character. Its usage is

>     result = Chr(charcode)

where `result` is a character and `charcode` is a number that identifies an ANSI character.

NOTE
Another function (`ChrB`) is provided for use with byte data contained in a string. Instead of returning a character, which may be one or two bytes, `ChrB` always returns a single byte. `ChrW` is provided for 32-bit platforms that use Unicode characters. Its argument is a Unicode (wide) character code, thereby avoiding the conversion from ANSI to Unicode.

#### `ChrB` Function

The `ChrB` function converts an ANSI character code into a single byte. Its usage is

>     result = ChrB(charcode)

where `result` is a byte subtype and `charcode` is a number that identifies an ANSI character.

#### `ChrW` Function

The `ChrW` function converts an ANSI character code into a Unicode character. Its usage is

>     result = ChrW(charcode)

where `result` is a Unicode character (2 byte) and `charcode` is a number that identifies an ANSI character.

NOTE
This function is valid only on platforms that support Unicode characters.

#### `CInt` Function

The `CInt` function converts an expression to a `Variant` of subtype `Integer`. Its usage is

>     result = CInt(expr)

where `result` is an `Integer` subtype and `expr` is a valid expression. If `expr` is not within an integer range, a runtime error occurs. During the operation, `expr` is rounded to the nearest whole number.

#### `CLng` Function

The `CLng` function converts an expression to a `Variant` of subtype `Long`. Its usage is

>     result = CLng(expr)

where `result` is a `Long` subtype and `expr` is a valid expression. If `expr` is outside the range for a `Long`, a runtime error occurs. During the operation, `expr` is rounded to the nearest whole number.

#### `CSng` Function

The `CSng` function converts an expression to a `Variant` of subtype Single. Its usage is

>     result = CSng(expr)

where `result` a `Variant` of subtype `Single` and `expr` is a valid expression. If `expr` is not in the range for a `Single`, a runtime error occurs.

#### `CStr` Function

The `CStr` function converts an expression into a string. Its usage is

>     result = CStr(expr)

where `result` is a `Variant` of subtype `String` and `expr` is a valid expression. The value of `result` will vary depending on the subtype of `expr` as shown in the following table:

`Expr` Subtype | Result
`Boolean` | `True` or `False`.
`Date` | A date in short-date format.
`Error` | The word `Error` and the error number.
Any numeric | The number in string format.

If `expr` is `Null`, a runtime error occurs. If it is `Empty`, `result` is a zero-length string (`""`).

#### `Hex` Function

The `Hex` function converts a number into a string representing the hexadecimal value of that number. Its usage is

>     str = Hex(number)

where `str` is a string variable containing a hexadecimal representation and `number` is any valid numeric expression. The limit of the number is 8 hexadecimal characters (4 bytes).

#### `LBound` Function

The `LBound` function identifies the smallest subscript for the particular dimension of an array. Its usage is

>     result = LBound(arrayname[, dimension])

where `result` is the smallest subscript, `arrayname` is the name of the array, and `dimension` indicates the desired dimension.

#### `Oct` Function

The `Oct` function converts a number into a string representing the octal value of that number. Its usage is

>     str = Oct(number)

where `str` is a string variable containing an octal representation and `number` is any valid numeric expression. The limit of the number is 11 octal characters (4 bytes).

#### `UBound` Function

The `UBound` function identifies the largest subscript for the particular dimension of an array. Its usage is

>     result = UBound(arrayname[, dimension])

where `result` is the largest subscript, `arrayname` is the name of the array, and `dimension` indicates the desired dimension.

#### VarType Function

The `VarType` function returns an integer indicating the subtype of a variable. Its usage is

>     result = VarType(varname)

where `result` is an integer and `varname` is the name of a variable. Possible values for `result` are as follows.

Result | `varname` Type
`0` | `Empty` (uninitialized).
`1` | `Null` (no valid data).
`2` | `Integer`.
`3` | `Long` integer.
`4` | Single-precision floating-point number.
`5` | Double-precision floating-point number.
`6` | `Currency`.
`7` | `Date`.
`8` | `String`.
`9` | Automation object.
`10` | `Error`.
`11` | `Boolean`.
`12` | `Variant` (used only with arrays of `Variant`s).
`13` | Non-automation object.
`17` | `Byte.`
`8192` | `Array` (added to value above).

### Date/Time Functions

The date and time functions deal with various procedures that support conversions of these values. Within these routines, the days of the week have the following coded values:

Value | Day of Week
`1` | Sunday
`2` | Monday
`3` | Tuesday
`4` | Wednesday
`5` | Thursday
`6` | Friday
`7` | Saturday

#### `CDate` Function

The `CDate` function converts an expression that has been converted to a `Date` subtype. Its usage is

>     result = CDate(expr)

where result is a `Variant` of subtype `Date` and `expr` is a valid date expression.

NOTE
The `IsDate` function can be used to determine if the expression to be converted is valid.

#### `Date` Function

The `Date` function retrieves the current system date. Its usage is

>     result = Date

where `result` is a `Variant` of subtype `Date`.

#### `DateSerial` Function

The `DateSerial` function sets a date value in a Date variable. Its usage is

>     result = DateSerial(year, month, day)

where `result` is a `Variant` of subtype `Date`, `year` is a number between 100 and 9999, `month` is a number between 1 and 12, and `day` is a number between 1 and 31. A numeric expression in the correct range may be used as an argument. If the expression is not valid, it is incremented to the next larger number.

#### `DateValue` Function

The `DateValue` function converts an expression into a `Date` subtype. Its usage is

>     result = DateValue(expr)

where result is a `Variant` of subtype `Date` and `expr` is a string expression representing a date, such as November 30, 1997 or 11/30/1997.

#### `Day` Function

The `Day` function extracts a day value from an expression representing a date. Its usage is

>     result = Day(expr)

where `result` is a whole number between 1 and 31, and `expr` is any expression that can represent a date. If `expr` is `Null`, `Null` is returned.

#### `Hour` Function

The `Hour` function extracts an hour value from an expression representing a time. Its usage is

>     result = Hour(expr)

where `result` is a whole number between 0 and 23, and `expr` is any expression that can represent a time. If `expr` is `Null`, `Null` is returned.

#### `Minute` Function

The `Minute` function extracts a minute value from an expression representing a time. Its usage is

>     result = Minute(expr)

where `result` is a whole number between 0 and 59, and `expr` is any expression that can represent a time. If `expr` is `Null`, `Null` is returned.

#### `Month` Function

The `Month` function extracts a month value from an expression representing a date. `Month` returns a whole number between 1 and 12, inclusive, representing the month of the year. Its usage is

>     result = Month(date)

where `result` is a whole number between 1 and 12, and `expr` is any expression that can represent a date. If `expr` contains `Null`, `Null` is returned.

#### `Now` Function

The `Now` function retrieves the current date and time according to the current setting of the computer's date and time. Its usage is

>     result = Now

where `result` is an expression containing the date and time.

#### `Second` Function

The `Second` function extracts the second value from an expression. Its usage is

>     result = Second(expr)

where `result` is a whole number between 0 and 59 and `expr` is any expression that can represent a time. If `expr` contains `Null`, `Null` is returned.

#### `Time` Function

The `Time` function retrieves the current system time. Its usage is

>     result = Time

where `result` is a `Variant` of subtype `Date`.

#### `TimeSerial` Function

The `TimeSerial` function sets a time value in a `Date` variable. `TimeSerial` returns a `Variant` of subtype `Date` containing the time for a specific hour, minute, and second. Its usage is

>     result = TimeSerial(hour, minute, second)

where `result` is a `Variant` of subtype `Date`, hour is a number between 0 and 23, minute is a number between 0 and 59, and second is a number between 0 and 59. A numeric expression in the correct range may be used as an argument. If the expression is not valid, it is incremented to the next larger number.

#### `TimeValue` Function

The `TimeValue` function retrieves a time from an expression indicating a time. Its usage is

>     result = TimeValue(expr)

where result is a `Variant` of subtype `Date` and `expr` is a string expression representing a time.

#### `Weekday` Function

The `Weekday` function determines the day of the week for a particular date. Its usage is

>     result = Weekday(expr, [firstdayofweek])

where `result` is a whole number representing the day of the week (see weekday values in the earlier table), `expr` is an expression representing a date. If `expr` contains `Null`, `Null` is returned. The optional `firstdayofweek` argument identifies the value assumed for the first day.

#### `Year` Function

The `Year` function extracts the year value from an expression. Its usage is

>     result = Year(expr)

where `result` is a whole number representing the year and `expr` is any expression that can represent a date. If expr is `Null`, `Null` is returned.

### Conditional Functions

The conditional functions facilitate the testing of certain variable conditions. Each of these functions returns a Boolean value (`True` or `False`) depending upon the implicit test being performed.

#### `IsArray` Function

The `IsArray` function determines whether a particular variable is an array subtype. Its usage is

>     bool = IsArray(varname)

where `bool` is `True` if the specified `varname` is an array; otherwise, the function returns `False`.

#### `IsDate` Function

The `IsDate` function determines if an expression can be converted to a date. Its usage is

>     bool = IsDate(expr)

where `bool` is `True` if the specified `expr` is recognizable as a date or time.

#### `IsEmpty` Function

The `IsEmpty` function determines whether a variable has been initialized. Its usage is

>     bool = IsEmpty(varname)

where `bool` is `True` if the specified `varname` has been initialized or set to a value.

#### `IsNull` Function

The `IsNull` function determines whether a variable contains valid data (not `Null`). Its usage is

>     bool = IsNull(varname)

where `bool` is `True` if the specified `varname` is `Null`, that is, contains no valid data. Because a variable containing `Null` will yield `Null` when used in a conditional expression, the use of `IsNull` is encouraged when the possibility exists for a variable to be `Null`.

#### `IsNumeric` Function

The `IsNumeric` function determines whether a variable has a numeric subtype or an expression can be evaluated as a numeric. Its usage is

>     bool = IsNumeric(expr)

where `bool` is `True` if `expr` can be evaluated as a number.

#### `IsObject` Function

The `IsObject` function determines whether a variable is an object subtype. Its usage is

>     bool = IsObject(varname)

where `bool` is `True` if the specified `varname` is a valid OLE Automation object.

#### `StrComp` Function

Unlike the other comparison operators the `StrComp` function compares two strings for equality or alphabetic sequence. Its usage is

>     result = StrComp(str1, str2[, bin])

where `result` is a signed numeric variable and `str1` and `str2` are string expressions. The optional `bin` argument specifies whether a binary (indicated with a `True` value), rather than an alphabetic, comparison is to be performed. If either `str1` or `str2` is `Null`, `result` will be `Null`. Otherwise the value of `result` will be set according to the following list:

Condition | `result` value
`str1 < str2` | `-1`
`str1 = str2` | `0`
`str1 > str2` | `+1`

### String Functions

String functions provides functionality when dealing with string variables.

#### `Asc` Function

The `Asc` function extracts the ANSI character code for the first letter in a string. Its usage is

>     result = Asc(string)

where `result` is the character code and `string` is any valid string expression. If `string` is `Empty`, a runtime error occurs.

#### `AscB` Function

The `AscB` function extracts the first byte in a string. Its usage is

>     result = AscB(string)

where `result` is a `Byte` subtype and `string` is any valid string expression. If `string` is `Empty`, a runtime error occurs.

#### `AscW` Function

The `AscW` function extracts the Unicode character code for the first letter in a string. Its usage is

>     result = AscW(string)

where `result` is the Unicode and `string` is any valid string expression. If `string` is `Empty`, a runtime error occurs.

#### `InStr` Function

The `InStr` function identifies the beginning character position of a token within a string. Its usage is

>     newstart = InStr([start, ]source, token[, compare])

where `newstart` is the character location where the token was found in the string (`0` if not located), `start` is the starting position for the search, `source` is the string to be searched, `token` is the string to be located, and `compare` is the type of comparison (`0` for a binary compare, `1` for a textual, case-insensitive compare).

#### `InStrB` Function

The `InStrB` function is the byte version of the `InStr` function and identifies the beginning byte position of a token within a string. Its usage is

>     newstart = InStr([start, ]source, token[, compare])

where `newstart` is the byte location where the token was found in the string (`0` if not located), `start` is the starting position for the search, `source` is the string to be searched, `token` is the string to be located, and `compare` is the type of comparison (`0` for a binary compare, `1` for a textual, case-insensitive compare).

#### `LCase` Function

The `LCase` function converts a string to lowercase. Its usage is

>     result = LCase(string)

where `result` is a lowercase string and `string` is any valid string expression.

#### `Left` Function

The `Left` function extracts a specified number of characters from the beginning of a string. Its usage is

>     result = Left(string, length)

where `result` is a string variable, `string` is a valid string expression, and `length` is a numeric expression indicating how many characters to return.

NOTE
Another function (`LeftB`) is provided for use with byte data contained in a string. Instead of specifying the number of characters to return, `length` specifies the number of bytes.

#### `LeftB` Function

The `LeftB` function, similar to the `Left` function, extracts a specified number of bytes from the beginning of a string. Its usage is

>     result = LeftB(string, length)

where `result` is a string variable, `string` is a valid string expression, and `length` is a numeric expression indicating the number of bytes to extract.

#### `Len` Function

The `Len` function determines the size of a string or determines how many characters are needed to store a variable. Its usage is

>     result = Len(string | varname)

where `result` is the number of characters in a string or the number of bytes required to store a variable, `string` is any valid string expression, and `varname` is a variable name.

#### `LenB` Function

The `LenB` function determines the size of a string or determines how many bytes are needed to store a variable. Its usage is

>     result = LenB(string | varname)

where `result` is the number of bytes in a string or the number of bytes required to store a variable, `string` is any valid string expression, and `varname` is a variable name.

#### `LTrim` Function

The `LTrim` function copies a string while stripping leading spaces. Its usage is

>     result = LTrim(string)

where `result` is the stripped string and `string` is a valid string expression from which the spaces are to be removed.

#### `Mid` Function

The `Mid` function copies a specified number of characters from a position within a string. Its usage is

>     result = Mid(string, start[, length])

where `result` is the resultant string, `string` is the expression from which characters are to be copied, `start` is the position in `string` where the part to be taken begins, and `length` is the number of characters to copy.

#### `MidB` Function

The `MidB` function is the byte version of the `Mid` function. It copies a specified number of bytes from a position within a string. Its usage is

>     result = MidB(string, start[, length])

where `result` is the resultant string, `string` is the expression from which bytes are to be copied, `start` is the position in `string` where the part to be taken begins, and `length` is the number of bytes to copy.

#### `Right` Function

The `Right` function copies a specified number of characters from the trailing portion of a string. Its usage is

>     result = Right(string, length)

where `result` is the resultant string, `string` is the expression from which the characters are to be copied, and `length` is a numeric expression indicating how many characters to copy.

#### `RightB` Function

The `RightB` function is the byte version of the `Right` function. It copies a specified number of bytes from the trailing portion of a string. Its usage is

>     result = RightB(string, length)

where `result` is the resultant string, `string` is the expression from which the bytes are to be copied, and `length` is a numeric expression indicating how many bytes to copy.

#### `RTrim` Function

The `RTrim` function copies a string while stripping trailing spaces. Its usage is

>     result = RTrim(string)

where `result` is the stripped string and `string` is a valid string expression from which the spaces are to be removed.

#### `String` Function

The `String` function builds a string containing multiple copies of the same character. Its usage is

>     result = String(number, character)

where `result` is a string variable, `number` is the length of the returned string, and `character` is the character code used to build the return string.

#### `Trim` Function

The `Trim` function copies a string while stripping leading and trailing spaces. Its usage is

>     result = Trim(string)

where `result` is the copied string and `string` is a valid string expression from which the spaces are to be removed.

#### `UCase` Function

The `UCase` function copies a string while converting all characters to uppercase. Its usage is

>     result = UCase(string)

where `result` is the resultant string and `string` is any valid string expression.

### Input Functions

Input functions are procedures that automate and simplify the display and preparation of input for a script. They make it easy to provide dialog boxes and other Windows controls.

#### `InputBox` Function

The `InputBox` function prompts the user for input. It displays dialog box containing a prompt or other controls and then waits for the user to reply. Its usage is

>     result = InputBox(prompt[, title][, default][, x][, y][, help, context])

where `result` is the string entered by the user, `prompt` is the message to be displayed, `title` is a string to be displayed in the title bar, `default` is the preloaded response for the user, `x` and `y` are the coordinates-in twips (1/20th of a point)-for placement of the dialog box, `help` identifies the Help file to use to provide context-sensitive Help for the dialog box, and `context` is the Help context number for the appropriate Help topic. When a Help file is specified, a Help button is automatically added to the dialog box.

Upon return from the procedure, `result` will contain the contents of the text box (if the user chooses OK) or a zero-length string (if the user selects Cancel).

#### `MsgBox` Function

The `MsgBox` function displays a message in a dialog box with buttons and returns a value indicating which button the user has chosen. Its usage is

>     result = MsgBox(prompt[, buttons][, title][, help, context])

where `result` is the value of the button selected by the user (see Table A.4), `prompt` is the string to be displayed in the dialog box, `buttons` is a number indicating the buttons and types to be displayed as depicted in Table A.5, `title` is the string to be displayed in the title bar of the dialog box, `help` identifies the Help file to use to provide context-sensitive Help for the dialog box, and `context` is the Help context number for the appropriate Help topic. When a Help file is specified, a Help button is automatically added to the dialog box.

Table A.4. `result` values.

Value | Description
`1` | OK
`2` | Cancel
`3` | Abort
`4` | Retry
`5` | Ignore
`6` | Yes
`7` | No

Table A.5. `buttons` settings.

Setting | Description
Button settings
`0` | OK button only
`1` | OK and Cancel buttons
`2` | Abort, Retry, and Ignore buttons
`3` | Yes, No, and Cancel buttons
`4` | Yes and No buttons
`5` | Retry and Cancel buttons
Icon settings
`16` | Critical Message icon
`32` | Warning Query icon
`48` | Warning Message icon
`64` | Information Message icon
Default settings
`0` | First button is default
`256` | Second button is default
`512` | Third button is default
`768` | Fourth button is default
Dialog type
`0` | Application modal
`4096` | System modal

### Mathematical Functions

The mathematical functions simplify the programming of tasks involving mathematical and geometric procedures. When using these functions, remember that some functions may be derived from other functions.

Some useful formulas are shown below:

>     radians = degrees * PI / 180

>     degrees = radians * 180 / PI

>     PI = 3.1415926535897932

>     natural log:  e = 2.718282

>     Sin(a) = a / c

>     Cos(a) = b / c

>     Tan(a) = a / b

>     Sec(a) = 1 / Cos(a)

>     Cosec(a) = 1 / Sin(a)

>     Cotan(a) = 1 / Tan(a)

>     Arcsin(X) = Atn(X / Sqr(-X * X + 1))

>     Arccos(X) = Atn(-X / Sqr(-X * X + 1)) + 2 * Atn(1)

>     Arcsec(X) = Atn(X / Sqr(X * X - 1)) + Sgn((X) -1) * (2 * Atn(1))

>     Arccosec(X) = Atn(X / Sqr(X * X - 1)) + (Sgn(X) - 1) * (2 * Atn(1))

>     Arccotan(X) = Atn(X) + 2 * Atn(1)

>     HSin(X) = (Exp(X) - Exp(-X)) / 2

>     HCos(X) = (Exp(X) + Exp(-X)) / 2

>     HTan(X) = (Exp(X) - Exp(-X)) / (Exp(X) + Exp(-X))

>     HSec(X) = 2 / (Exp(X) + Exp(-X))

>     HCosec(X) = 2 / (Exp(X) - Exp(-X))

>     HCotan(X) = (Exp(X) + Exp(-X)) / (Exp(X) - Exp(-X))

>     HArcsin(X) = Log(X + Sqr(X * X + 1))

>     HArccos(X) = Log(X + Sqr(X * X - 1))

>     HArctan(X) = Log((1 + X) / (1 - X)) / 2

>     HArcsec(X) = Log((Sqr(-X * X + 1) + 1) / X)

>     HArccosec(X) = Log((Sgn(X) * Sqr(X * X + 1) +1) / X)

>     HArccotan(X) = Log((X + 1) / (X - 1)) / 2

>     LogN(x) = Log(x) / Log(n)

#### `Abs` Function

The `Abs` function obtains the absolute value of a number. Its usage is

>     result = Abs(number)

where `result` is the absolute value of the `number` argument.

#### `Atn` Function

The `Atn` function obtains the arctangent of a number. Its usage is

>     result = Atn(number)

where `result` is the angle in radians that corresponds to the tangent `number` argument.

#### `Cos` Function

The `Cos` function obtains the cosine of an angle. Its usage is

>     result = Cos(number)

where `result` is the ratio of the length of the side adjacent to the angle divided by the length of the hypotenuse and `number` is an angle in radians.

#### `Exp` Function

The `Exp` function obtains the base of natural logarithms raised to a power. Its usage is

>     result = Exp(number)

where `result` is the antilog of the `number` argument.

#### `Fix` Function

The `Fix` function obtains the integer portion of a number. Its usage is

>     result = Fix(number)

where `result` is the integer portion of the number argument.

#### `Int` Function

The `Int` function obtains the integer portion of a number. Its usage is

>     result = Int(number)

where `result` is the integer portion of the `number` argument.

#### `Log` Function

The `Log` function obtains the natural logarithm of a number. Its usage is

>     result = Log(number)

where `result` is the logarithmic value of the `number` argument.

#### `Rnd` Function

The `Rnd` function obtains a random number. Its usage is

>     result = Rnd[(switch)]

where `result` is a random number and `switch` indicates how the random number is to be determined. A positive number for `switch` indicates that the next random number in the sequence should be returned.

Before calling this function, the random number generator should be initialized by using the `Randomize` statement.

#### `Sgn` Function

The `Sgn` function obtains the sign of a number. Its usage is

>     result = Sgn(number)

where `result` is `1` if the `number` argument is positive, `0` if `number` is `0`, and `-1` if `number` is negative.

#### `Sin` Function

The `Sin` function obtains the sine of an angle. Its usage is

>     result = Sin(number)

where `result` is the ratio of the length of the side opposite the angle divided by the length of the hypotenuse and `number` is an angle in radians.

#### `Sqr` Function

The `Sqr` function obtains the square root of a number. Its usage is

>     result = Sqr(number)

where `result` is the square root of the `number` argument.

#### `Tan` Function

The `Tan` function obtains the tangent of an angle. Its usage is

>     result = Tan(number)

where `result` is the ratio of the length of the side opposite the angle divided by the length of the side adjacent to the angle and `number` is an angle in radians.

| Use of this site is subject certain Terms & Conditions. Copyright (c) 1996-1999 EarthWeb, Inc.. All rights reserved. Reproduction in whole or in part in any form or medium without express written permission of EarthWeb is prohibited. Please read our privacy policy for details.