Schongar P.VBScript unleashed.1997

generates a runtime error.

Chr

The Chr function takes a character code as a parameter and returns the corresponding character. Keep in mind that the characters for codes 0 to 31 are nonprintable:

StrMyString = "This is my two line" + (Chr(13) + Chr(10)) + "text string example."

In this example line, the string has a carriage return and a line feed added to the middle of the text. This will cause a break in the string, displaying it on two lines.

InStr

The InStr function is a powerful text-searching tool that finds the position of text substrings within strings of text. This is a fairly complex function, so you should first be familiar with the function's syntax:

position = InStr(startpos, string1, string2, type)

The InStr function returns the position of the substring within the string. In this case, the return value is held by the variable position. Let's go through the other arguments individually.

Startpos

The startpos argument is a numeric value that tells the function where to start searching. This is an important argument because if you're thinking about adding search functions to your own string operations, you'll need to adjust the number as you find multiple occurrences of the search string in a large body of text.

String1

The string1 argument is the string in which you are searching for the string2 string.

String2

String2 is the text for which you're searching.

Type

The type argument specifies the string comparison that you're performing. This argument can have a value of 0 (default) or 1. A type 0 comparison is a binary comparison. The function will return a position only in the case of an exact match. An argument of 1 will do a non-case-sensitive, textual search.

We can see the difference between the two types of searches in the following code:

Dim strBigString, strSearchString, intReturn0, intReturn1

strBigString = "This is the BIG string"

strSearchString = "big"

intReturn0 = InStr( , strBigString, strSearchString, 0)

intReturn1 = InStr( , strBigString, strSearchString, 1)

In this sample, the intReturn0 variable is set to 0 because the function does not find the string "big" in strBigString. The variable inReturn1 is set to 13 because strSearchString is found in the non-case- sensitive search.

Table 3.4. Return values for the InStr function.

If the value of startpos is greater than the length of mainstring, the function returns a 0.

LCase

The LCase function takes a string and converts all the characters to lowercase. It takes a string as an argument and returns the converted string.

Left

The Left function returns a string containing the characters from the left side of the string, up to a specified number. The function takes two arguments, string and length:

Dim strMyString, strMain

strMain = "The rain in Spain..."

strMyString = Left(strMain, 15)

In this sample, the string variable strMyString would be set to The r, the first five characters of the string. If the number you specify in the length argument is greater than or equal to the length of the string, the function will return the entire string.

LTrim

The LTrim function returns a copy of the string argument with the leading spaces removed from the string:

Dim strMyString, strMain

strMain = " There are four leading spaces here."

strMyString = LTrim(strMain)

In this example, the functions returns the string, "There are four leading spaces here."

Mid

The Mid function returns a substring of a specified length from another string. This function takes three parameters: string, start, and length. The length argument is optional.

Dim strMyString, strMain

strMain = "Ask not what your country can do for you..."

strMyString = Mid(strMain, 8, 10)

In this example, we're looking for a string that starts at character 8 and is 10 characters in length. The string value contained in strMyString is equal to what your .

Right

The Right function works like the Left function, but it returns a specified number of characters starting from the last character in the string. This function takes the number of characters as an argument and returns a string:

Dim strMyString, strMain

strMain = "How now brown cow?"

strMyString = Right(strMain, 10)

In this example, strMyString is set to the last 10 characters of strMain, or brown cow?.

RTrim

The Rtrim function works like the Ltrim function. It removes trailing spaces from a string. It takes a single argument, string, and returns a string.

Str()

The Str()function takes a number as an argument and returns a string value representing the number. The first character in the resulting string is always a space that acts as a placeholder for the sign of the number. If you want to use a numeric value in a string or a function that takes a string as a parameter, you'll need to use this function or the CStr function to make the conversion first.

StrComp

The StrComp function takes two strings as arguments and compares them, based on the third argument, which defines the type of comparison:

Dim RetVal, strString1, strString2

strString1 = "This is a string."

strString2 = "This is a STRING."

RetVal = StrComp(strString1, strString2, 1)

The StrComp function returns a numeric value that indicates whether the items are the same. The comparison type has two possible values: 0 (default) is a binary comparison, and 1 is non-case-sensitive. Table 3.5 show the return values for the StrComp function.

Table 3.5. Return values for the StrComp function.

String

The String function takes a number and character code argument and returns the character, repeated a number of times:

Dim strRetString

strRetString = String(3, 97)

This example returns the string "aaa". If the character code argument is greater than 255, the code is automatically converted to a valid character using the formula charcode = (char Mod 256).

Trim

The Trim function returns the string argument, with leading and trailing spaced removed.

UCase

The UCase function converts all the characters in the string argument to uppercase.

Val

The Val function takes a string argument and returns numbers from the string. The function stops retrieving numbers as soon as it hits a non-numeric character:

Dim MyNumber, strMyString

MyString = "300 South Street"

MyNumber = Val(strMyString)

In this example, the function returns the number 300. The Val function recognizes decimal points and radix prefixes. A radix prefix is a prefix that defines an alternative numbering system. The &O prefix is used for octal values and &H for hexadecimal.

Conversion Functions

Conversion functions enable you to change the subtype of a variable. Although VBScript uses the variant type for all variables, in many cases an argument of a certain type is required. An example would be a function that takes a string argument. If you want to be able to use numeric data, you'll need to convert it to a string before calling the function.

CByte

The Cbyte function converts an expression to the subtype byte.

CDbl

The CDbl function converts an expression to the subtype double.

CInt

The CInt function converts an expression to the subtype integer.

CLng

The CLng function converts an expression to the subtype long.

CStr

The CStr function returns a string from a valid expression. Table 3.6 lists the return values for various expression types.

Table 3.6. Return values for the CStr function.

CVErr

The CVErr function returns the subtype error. It takes any valid error number as an argument.

Math Functions

Math functions enable you to perform operations on numbers in your VBS scripts. You'll find these functions fairly straightforward.

Abs

The Abs function takes a number as a parameter and returns its absolute value. The absolute value of a number is the numerical value of a number without considering its sign. An argument of -7 would return the value 7.

Array

The Array function returns a variant value containing an array. The array can be of any subtype. This function takes a list of values separated by commas as a parameter.

Atn

The Atn function returns the arctangent of a number, a trigonometric function that is used to determine angles in triangles. This function is the inverse of tangent (Tan), which calculates the ratio of sides in a right triangle. It takes a number as an argument.

Exp

The Exp function takes a numeric argument and returns e (the base of natural logarithms) raised to a power.

Hex

The Hex function returns a string value containing the value of an argument converted to hexadecimal form. If the argument is a fractional value, it is rounded to the nearest whole number before the function returns the string.

Keep in mind that this function returns a string. If you want to perform mathematical operations on the returned value, you must first convert the string back into a numerical value. Hexadecimal numbers are represented in VBScript using the &H prefix.

Int

The Int function returns the whole number portion of an argument. If the argument is negative, Int returns the first integer value that is less than or equal to the argument.

Fix

The Fix function works like the Int function, returning the whole number portion of an argument. The difference is that if the number argument is negative, Fix returns the first integer value that is greater than or equal to the argument.

Log

The Log function returns the natural logarithm of a numeric argument. The numeric argument that this function processes must be greater than zero.

Oct

The Oct function returns a string representing the octal value of a numeric argument. If the numeric argument is fractional, it is rounded up before the function returns a value. As with the Hex function, the returned string must be converted back to numeric form before you can perform mathematical operations on it. To use an octal value mathematically, you use the &O prefix.

Rnd

The Rnd function takes a numeric argument and returns a value between zero and one. The number generated depends on the numeric argument in relation to the values in Table 3.7.

Table 3.7. Number value determines generation technique.

If you want to generate a range of random numbers, use the following formula:

Int((upperbound - lowerbound + 1)*Rnd + lowerbound)

Let's use the Rnd function to create a program (see Listing 3.3) that generates random numbers. Random numbers are often used in computer games and simulations. We'll use this function to create a page that generates random Lotto numbers. Figure 3.4 shows the page in action.

Figure 3.4 : The Play 3 generator in action.

Listing 3.3. Lotto.htm.

<HTML>

<HEAD>

<TITLE>Play 3 Generator</TITLE>

</HEAD>

<BODY><CENTER>

<H1>Play 3 Generator</H1>

<HR COLOR="BLUE">

<INPUT TYPE="SUBMIT" NAME="Btn1" VALUE="Click for the lucky numbers!"><BR><BR>

<INPUT TYPE="SUBMIT" NAME="BtnBall1" VALUE="">

<INPUT TYPE="SUBMIT" NAME="BtnBall2" VALUE="">

<INPUT TYPE="SUBMIT" NAME="BtnBall3" VALUE="">

<SCRIPT LANGUAGE="VBScript">

<!--

Sub Btn1_OnClick()

BtnBall1.Value = RndBall()

BtnBall2.Value = RndBall()

BtnBall3.Value = RndBall()

End Sub

Function RndBall()

RndBall = (Int((9-0+1)*Rnd+0))

End Function

-->

</SCRIPT>

</CENTER>

</BODY>

</HTML>

You'll find that random number generation can really spice up your pages. You'll see more random number examples later in this book when we work with other controls that can be manipulated dynamically.

Sgn

The Sgn function returns a numeric value representing the sign of a number argument. It returns 1 if the number is greater than zero, 0 if equal to zero, and -1 if less than zero.

Sqr

The Sqr function returns the square root of a numeric argument. The argument value must be greater than or equal to zero.

Sin

The Sin function returns the sine of an angle.

Tan

The Tan function returns the tangent of an angle.

Time and Date Functions

You'll find time and date functions extremely useful in customizing your Web pages. You can add automatic time and date stamping to pages, and you can write programs that provide useful calendar functions.

Date

The Date function takes no arguments and returns the current system date. In Figure 3.5, the Date function returns the date value in the tester page.

Figure 3.5 : The Date function returns the date value in the tester page.

DateSerial

The DateSerial function takes year, month, and day arguments and returns a variant of subtype date. The year argument can be any year between 100 and 9999. The month and day arguments are numeric values.

DateValue

The DateValue function takes a string argument containing a valid date and returns a variant of subtype date. This is an extremely useful function, because it interprets a number of formatted date strings. For example, you could use "January 1, 1999," "1/1/99," or "Jan 1, 1999" as an argument. Once the date is a variant of subtype date, other date functions can be used on it.

Day

The Day function takes a date argument and returns the day as a numeric value between 1 and 31.

Hour

The Hour function takes a time argument and returns an hour value between 0 and 23.

Year

The Year function takes a date value and returns the year.

Weekday

The Weekday function takes a date and optionally a firstdayofweek argument and returns a numeric value representing the day of the week. If firstdayofweek isn't specified, the function defaults to Sunday. The settings for firstdayofweek are shown in Table 3.8.

*This value is used only in the firstdayofweek argument and is not a return value.

Listing 3.4 takes a string that you enter, converts the string to date format, and then runs the Day function against the date. The return value is then converted to a string that sends the day of the week to the message box. There is no error checking built into the script, so a nonvalid date entry will result in a runtime error. Figure 3.6 shows the results of Listing 3.4.

Figure 3.6 : What day did it happen?