Appendix A

VBScript Language Reference

• 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.

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.

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.

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.

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.

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.

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.

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.

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.

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:

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.

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:

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.

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:

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.

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.

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.