|
Internal functions
Abs
Computes the absolute value of a numeric expression.
Syntax
Abs(numeric expression)
Abs returns the unsigned magnitude of any numeric expression. For example, Abs(-21) returns 21 and Abs(21) returns 21. The return value from the Abs function will be of the same type as that of the argument.
Example
Sub Main()
Print "Absolute value of .3456 is:",
Abs(.3456)
Print "Absolute value of -.3456 is:",
Abs(.3456)
End Sub
Asc
Returns the ANSI numeric value for the first character in a string expression.
Syntax
Asc(string expression)
The string expression argument can be any valid string; however, only the first character in the string expression will be evaluated. Any subsequent characters will be ignored.
Example
See the code Example for the Chr internal function.
Atn
Computes the arctangent of a number.
The return value of Atn is expressed in radians. The return type for Atn is Double.
Syntax
Atn(numeric expression)
Chr
Returns a string containing the character represented by the ANSI numeric code argument.
Syntax
Chr(numeric expression)
Example
Sub Main()
Dim i as Integer
Dim c as String
For i = 1 to 255
c = Chr(i)
Print "character:", c
End Sub
Cos
Computes the cosine of a number.
The return value of Cos is expressed in radians. The return type for Cos is Double.
Syntax
Cos(numeric expression)
DateSerial
Returns a date value given the year, month, and day as arguments.
If an invalid date has been specified, the system will display an error.
Syntax
DateSerial(year, month, day)
The arguments for this function accept any numeric expression which evaluates to the following integer values:
• year - 100 to 9999 inclusive
• month - 1 to 12 inclusive
• day - 1 to 31 inclusive.
Example
Sub Main ()
Dim myyear As Integer
Dim mymonth As Integer
Dim myday As Integer
Dim mybirthday As Date
myyear = 1971 : mymonth = 7 : myday = 9
mybirthday = DateSerial(myyear, mymonth, myday)
Print "My birthday is:", mybirthday
End Sub
DateValue
Returns a date value given a string argument.
Syntax
DateValue(string expression)
The argument for this function is any string expression that represents a valid date. If an invalid string has been specified, the system will display an error.
Example
Sub Main()
Dim mydatestr As String
Dim mybirthday As Date
mydatestr = "7/9/71"
mybirthday = DateValue (mydatestr)
Print "My birthday is:", mybirthday
End Sub
Day
Returns the day of the month (1-31) for any valid date expression.
Syntax
Day(date expression)
Example
Sub Main()
Dim d As Date
Dim daynum As Integer
d = Today
daynum = Day(d)
Select Case daynum
Case 1, 21, 31
Print "Today is the "; daynum; "st of the month"
Case 2, 22
Print "Today is the "; daynum; "nd of the month"
Case 3, 23
Print "Today is the "; daynum; "rd of the month"
Case Else
End Select
End Sub
Exp
Returns the natural logarithm base number e raised to the power of a numeric argument.
The return value is a floating-point number.
Syntax
Exp(numeric expression)
The argument for this function can be any valid numeric expression.
Fix
Removes the fractional part of a number and return the truncated value as an integer (or a long).
This is identical to the Int function.
Syntax
Fix(numeric expression)
The argument may be any valid numeric expression.
Example
Sub Main()
Dim mynum As Double
mynum = 3.1415
Print "The whole number part of 'mynum' is:"; Fix (mynum)
Print "...and the decimal part of the number is:"; mynum - Fix(mynum)
End Sub
Hex
Returns the string containing the hexadecimal value of a number.
Syntax
Hex(numeric expression)
The numeric expression argument is rounded to an integer value before being evaluated.
Example
Sub Main()
Dim i As Integer
Dim hexval As String
For i = 0 to 256
hexval = Hex(i)
Print "decimal:", i
Print "hex:", hexval
Next i
End Sub
Hour
Returns an integer (0-23) that represents the hour from any valid date expression.
Syntax
Hour(date expression)
Example
Sub Main()
...
Dim secnum As Integer, minnum As Integer,
hournum As Integer
...
secnum = Second(d)
Print "The current second is "; secnum
End Sub
IIf (immediate if)
Evaluates the expression and returns one of two possible values.
IIf can only be used to return either of two values rather than directing programmatic flow. The return type of IIf is the same as that of the value that is returned.
Syntax
IIf(conditional expression, trueval, falseval)
The trueval and falseval arguments can be of any type. These arguments do not need to be the same data type.
Example
Sub Main()
Dim i As Integer
For i = 1 to 10
Print "the value of i is";
IIf(i<=5, "less than or equals", "greater than"); "5"
Next i
End Sub
InStr
Returns the position of the first occurrence of one string (searchstring) within another (sourcestring).
Syntax
InStr([start,]) sourcestring, searchstring [case])
The optional start argument is a valid numeric expression used to offset the starting position of the search in sourcestring. If the start argument is omitted, the default starting offset is 1. The optional case argument is used to determine the case sensitivity of the comparison.
If case is 0, the comparison is case sensitive, for example, "a"<>"A". If case is 1, the comparison is case insensitive, for example, "a"="A". If the case argument is omitted, the default behavior is case sensitive comparisons. If the case argument is used, the start argument is required.
If searchstring is found within the sourcestring, this function returns an integer that indicates the character position of the first occurrence of the string. If searchstring was not found, InStr returns 0. If searchstring is a zero-length string, start is returned.
Example
Sub Main()
Dim s As String, Ioc As Integer
s = "the quick brown fox jumps over the lazy dog"
Ioc = InStr(s, "fox")
If Ioc<>0 Then
Print "The string 'fox' was first found at character position "; Ioc
Else
Print "The string 'fox' was not found in the search string"
End If
End Sub
Int
Removes the fractional part of a number and returns the truncated value as an integer (or a long).
Syntax
Int(numeric expression)
The argument can be any valid numeric expression.
Example
Sub Main()
Dim mynum As Double
mynum = 3.1415
Print "The whole number part of 'mynum' is:"; Int(mynum)
Print "...and the decimal part of the number is:"; mynum - Int(mynum)
End Sub
IsArray
Determines whether the supplied argument is an array. It returns TRUE or FALSE depending on whether the supplied argument is an array.
Syntax
IsArray(variablename)
Example
Sub Main()
Dim i As Integer
Dim arr(10) As Integer
If IsArray(arr) Then
For i = LBound(arr) To UBound(arr)
arr(i) = i
Next i
End If
End Sub
IsDate
Determines whether the supplied argument is a valid date. It returns TRUE or FALSE depending on whether the supplied argument is a valid date.
Syntax
IsDate (date expression)
The date expression argument may be a string, date, or any numeric data type.
Example
Sub Main()
Dim d As Date
Dim s As String
s = "1/2/97"
If IsDate(s) Then
d=s
Print "Valid date format"
Else
Print "Invalid date format"
End If
End Sub
IsNumeric
Determines whether the supplied argument is numeric. It returns TRUE or FALSE depending on whether the supplied argument is a valid numeric expression.
Syntax
IsNumeric(expression)
LaunchURL
Launches a URL (http, ftp, fcp, mailto...) on the FirstClass client.
Syntax
LaunchURL(URL string)
Supply the desired URL as a string to the command and it will be launched in the registered browser, mail client, or other applicable application.
Example
Sub Main()
LaunchURL ("http://www.firstclass.com")
End Sub
LBound
Returns an integer indicating the lower bound of an array.
If the variable is not an array, an error occurs.
Syntax
LBound(array variable)
Example
Sub Main()
Dim i As Integer
Dim arr(10) As Integer
If IsArray(arr) Then
For i = LBound(arr) To UBound(arr)
arr(i) = i
Next i
End If
End Sub
LCase
Returns a string argument converted to all lowercase letters.
Syntax
LCase(string expression)
Example
Sub Main()
Dim s As String
s = LCase ("hEllo wOrld")
Print s
'displays "hello world"
Print LCase("THIS IS NOW LOWERCASE")
'displays "this is now lowercase"
End Sub
Left
Returns a string containing the leftmost characters of a string argument.
Syntax
Left(string expression, numeric expression)
The numeric expression argument can be any valid integer value greater than or equal to 0. If numeric expression is greater than or equal to the length of string expression, the entire string is returned.
Example
Sub Main()
Dim s As String, Ioc As Integer
s = "the quick fox jumps over the dog"
Ioc = InStr(s, " ") 'find the first occurrence of a space character
If Ioc<>0 Then
Print "The first word in the sentence is:"; Left(s, Ioc - 1)
Print "The rest of the sentence is:"; Right(s, Len(s) - Ioc)
Else
print "Invalid sentence (no spaces)."
End If
End Sub
Len
Returns the length of a string argument (as an integer), or the number of bytes required to create a variable.
Syntax
Len (string expression|variable name)
The argument string expression can be any valid string expression.
Example
Sub Main()
Dim s As String, length As Integer
Dim x As Long, y As Double
s = "the quick brown fox jumps over the lazy dog"
length = Len(s)
...
Print "The size of Double is"; Len(y); "bytes"
End Sub
Log
Computes the natural logarithm of a number.
Syntax
Log(numeric expression)
LTrim
Returns a string with all leading space and tab characters removed.
Syntax
LTrim(string expression)
The argument string expression can be any valid string.
Example
Sub Main()
Dim s As String
s = " test string "
Print "(" & LTrim(s) & ")"
'prints (test string )
End Sub
Mid
Returns a substring from within a string expression.
Syntax
Mid(string expression, start offset [,length])
The string expression argument can be any valid string. The start offset argument specifies the character offset from which to retrieve the substring. The optional length argument indicates the number of characters to return. If the length argument is omitted, Mid returns all characters from the start offset to the end of the string. If length is longer than the remaining number of characters in the string, all characters from the start and offset to the end of the string are returned.
Example
Sub Main()
Dim s As String
Dim loc As Integer, loc2 As Integer
s = "the quick fox runs fast"
loc = InStr(1, s, " ")
loc2 = InStr(loc + 1, s, " ")
Print "token:"; Mid(s, loc + 1, loc2 - loc - 1);" ' "
End Sub
Minute
Returns an integer (0-59) that represents the minute from any valid date expression.
Syntax
Minute(date expression)
Example
See the code example for the Second internal function.
Month
Returns the month of the year for any valid date expression.
Syntax
Month(date expression)
Example
Sub Main()
Dim d As Date
Dim monthnum As Integer
d = Today
monthnum = Month(d)
Select Case monthnum
Case 1
Print "This is the "; monthnum; " month of the year"
...
Case Else
Print "This is the "; monthnum; " month of the year"
End Select
End Sub
MsgBoxResponse
Returns the value of the last user input to the MsgBox BASIC command.
MsgBoxResponse returns one of these constant values:
• fcOK - user clicked the OK button
• fcCancel - user clicked the Cancel button
• fcYes - user clicked the Yes button
• fcNo - user clicked the No button.
Syntax
MsgBoxResponse
Example
See the code example for the Sgn internal function.
Now
Returns a date value containing the current time and date from the server's system clock.
Syntax
Now
Example
Sub Main()
Dim d As date
d = Now
Print "The current time and date is: ", d
End Sub
Oct
Returns a string containing the octal value of a number.
Syntax
Oct(numeric expression)
The numeric expression argument is rounded to an integer value before being evaluated.
Example
See the code example for the Hex internal function.
Replace
Searches the source string for all occurrences of the search string. Each time the search string is found, it is replaced with the defined replacement string.
Syntax
Replace(sourcestring, searchstring, replacestring)
The sourcestring, searchstring, and replacestring arguments can be any valid string expressions.
Example
Sub Main()
Dim s As string
s = "one, two, three, four, five"
s = Replace(s, ",", ";")
' s is now assigned "one; two; three; four; five"
Print s
End Sub
Right
Returns a string containing the right-most characters of a string argument.
Syntax
Right(string expression, numeric expression)
numeric expression can be any valid integer value greater than or equal to 0. If numeric expression is greater than or equal to the length of the string expression, the entire string is returned.
Example
See the code example for the Left internal function.
Rnd
Returns a random fractional number from 0 to 1.
 NoteTo seed the Rnd function with new values, use the Randomize BASIC command.
Syntax
Rnd
Example
See the code example for the Randomize command.
Round
Removes the fractional part of a number and returns the rounded value as an integer (or a long). Numbers with fractional parts greater than or equal to 0.5 will be rounded up to the nearest integer value. Numbers with fractional parts less than 0.5 will be rounded down.
Syntax
Round(numeric expression)
The argument can be any valid numeric expression.
Example
Sub Main()
Dim mynum As Double
Dim i as integer
For I = 1 to 20
mynum = i/10
Print "The value of 'mynum' is: "; mynum
Print "The rounded value of 'mynum' is: ";
Round(mynum)
Next i
End Sub
RTrim
Returns a string with all trailing space and tab characters removed.
Syntax
RTrim(string expression)
The argument string expression can be any valid string.
Example
Sub Main()
Dim s As String
s = " test string
Print "(" & RTrim(s) & ")"
'prints ( test string)
End Sub
Second
Returns an integer value that represents the seconds from any valid date expression.
Syntax
Second(date expression)
Example
Sub Main()
Dim d As Date
Dim secnum As Integer, minnum As Integer, hournum As Integer
d = Time
hournum = Hour (d)
minnum = Minute (d)
secnum = Second (d)
Print "The current hour is "; hournum
Print "The current minute is "; minnum
Print "The current second is "; secnum
End Sub
Sgn
Returns an integer value indicating the sign of a number.
Syntax
Sgn(numeric expression)
The numeric expression argument can be any valid numeric expression. If the value of a numeric expression is less than 0, Sgn returns -1. If the value of a numeric expression is greater than 0, Sgn returns 1. If the value of a numeric expression is 0, Sgn returns 0.
Example
Sub Main()
Dim dbl As Double
Dim mysign As Integer
dbl = 3.1415
mysign = Sgn (dbl)
If mysign < 0 Then
Print "The value of 'dbl' is negative"
Else
If mysign > 0
Print "The value of 'dbl' is positive"
Else
Print "The value of 'dbl' is zero"
End If
End If
End Sub
Shell
Runs an executable program on the server.
Programs run on the server may have command line arguments passed to them, however, no additional input may be provided to the running program. Operating system shell commands may also be run from this function. Shell returns an integer value that is the command interpreter's error code. 0 indicates that the command interpreter was able to begin processing the request. Non-zero indicates an error.
Syntax
Shell(string expression)
The argument must be the full path and executable name of the program to be run on the server.
Example
Sub Main()
Dim rc As Integer
rc = Shell ("Copy C:\FCPO\LogFiles\*.* C:\Backup\LogFiles")
If rc = 0 Then
Print "Copy has started successfully."
Else
Print "Could not begin copy."
End If
End Sub
Sin
Computes the sine of a number.
The return value of Sin is expressed in radians. The return type for Sin is Double.
Syntax
Sin(numeric expression)
Space
Returns a string containing a number of space characters indicated by the argument.
Syntax
Space(numeric expression)
The argument can be any valid numeric expression.
Example
Sub Main()
Dim MyStringVariable As String
MyStringVariable = Space(15) ' returns a string with 15 spaces
'to the variable MyStringVariable
Print MyStringVariable
Spawn
Runs a process or application on the FirstClass server.
This function has several advantages over the Shell() function and, where possible, should be used in place of that function.
Syntax
Spawn(application name [fcWait | fcNoWait])
application name contains a text string which is the application name to be executed, including any command line arguments.
The second argument is a constant, which specifies whether the application should wait until the called process has completed (fcWait: synchronous; can block the FirstClass server) or whether the application should launch the process and continue executing (fcNoWait: asynchronous; never blocks the FirstClass server).
Example
Spawn ("C:\Acrobat3\Reader\AcroRd32.exe", fcNoWait) 'launches a program on the server and immediately resumes processing the application'
End Sub
Sqr
Returns the square root of any valid numeric expression (as a floating-point number).
Syntax
Sqr(numeric expression)
Example
Sub Main()
Print "The square root of 2 is:", Sqr(2)
End Sub
StartupString
Returns the startup string (command line argument) for an application.
This is used to differentiate different installations of an application or to seed a FirstClass RAD program with initial values.
Syntax
StartupString
Example
Sub Main()
Print "The command line argument for this application is";
StartupString
End Sub
Str
Returns a string representation of a number (for any valid numeric expression).
Syntax
Str(numeric expression)
Example
Sub Main()
Dim cost As String
Dim output As String
cost = Str(5000)
output = "the total cost is: " & cost
Print output
End Sub
StrComp
Compares two string expressions.
Syntax
StrComp(string1, string2,[, case])
The optional case argument is used to determine the case sensitivity of the comparison. If case is 0, the comparison is case sensitive ("a" <> "A"). If case is 1, the comparison is case insensitive ("a" = "A"). If the case argument is omitted, the default behavior is case-sensitive comparisons ("a" <> "A"). StrComp returns the following integer values based on the comparison evaluation:
• -1 string1 < string2
• 0 string1 = string2
• 1 string1 > string2
• undefined NULL string.
Example
Sub Main()
Dim s As String
s = "aaa"
Select Case StrComp(s, "bbb")
Case -1
Print "Source string is less than comparison string."
...
End Select
End Sub
StrFill
Creates a string of repeating characters of a specified length.
Syntax
StrFill(numeric expression, character expression)
The numeric expression argument specifies the number of characters in the result string. The character expression argument can be either a string representation or the ANSI code of a character. If the character is passed as a string representation, only the first character of the string is used.
Example
Sub Main()
Dim MyStringVariable As String
MyStringVariable = StrFill(5, "@") ' returns "@@@@@
Print MyStringVariable
...
End Sub
StrSplit
This command is exactly like StrToken except that it will not skip double delimiters.
StrToken
Parses a delimited string into its component substring tokens. This enhances FirstClass RAD's ability to quickly and easily parse delimited strings.
Syntax
StrToken(sourcestring, delimiters, tokennumber)
StrToken takes 3 arguments:
• sourcestring - contains a delimited list of substring tokens
• delimiters - a text string which specifies all of the delimiters to use when separating tokens
• tokennumber - the ordinal number of the substring to return (starting with 1 for the first string).
Example
This Example gets the last login time of the administrator and breaks the resulting batch administration reply up into its constituent substrings. This code uses both the space character and the double-quote character (Chr(34)) as delimiters for the delimiters argument. Batch administration replies without quotes will not need the Chr(34) as delimiters for the delimiter argument. Batch administration replies without quotes will not need the Chr(34) delimiter and can simply use the space or other delimiter as needed.
Sub Main()
BatchAdmin ("Get User Admin 123 +d")
Print "source string:"; fcBatchAdminReply
Print "substring 1:"; StrToken (fcBatchAdminReply, " " & Chr(34), 1)
Print "substring 2:" ; StrToken(fcBatchAdminReply, " " & Chr(34), 2)
Print "substring 2:" ; StrToken(fcBatchAdminReply, " " & Chr(34), 3)
Print "substring 2:" ; StrToken(fcBatchAdminReply, " " & Chr(34), 4)
End Sub
Running this code gives you the following output (dates and times will vary on your system):
source string: 1230 14 "2000/01/04 13:30:39"
substring 1: 1230
substring 2: 14
substring 3: 2000/01/04
substring 4: 13:30:39
Tab
Returns a string containing the Tab character.
Syntax
Tab
Example
Sub Main()
Dim s As String
s = "apple" & Tab & "orange" & Tab & "grape"
Print s 'creates a tab-delimited list of strings and displays them to output window
End Sub
Tan
Computes the tangent of a number.
The return value of Tan is expressed in radians. The return type for Tan is Double.
Syntax
Tan(numeric expression)
TCase
Returns a string argument converted to title case.
Syntax
TCase(string expression)
Example
Sub Main()
Dim s As String
s = TCase("jon q. public")
Print s 'displays "jon q. public"
End Sub
Time
Returns the current time from the server's system clock.
Syntax
Time
Example
See the code example for the Second internal function.
Timer
Returns the number of seconds that have elapsed since 12:00 AM. This is useful for benchmarking application operations.
Syntax
Timer
Example
Sub Main()
Dim timestart As Integer, timefinish As Integer
timestart = Timer
MsgBox("How fast can you click OK?")
timefinish = Timer
Print "It took you "; timefinish - timestart; "seconds to click OK"
End Sub
TimeSerial
Returns a date data type value given the hour, minute, and second as arguments.
If an invalid time has been specified, the system will display an error.
Syntax
TimeSerial(hour, minute, second)
The arguments for this function accept any numeric expression that evaluates to the following integer values:
• hour - 0 to 23 inclusive
• minute - 0 to 59 inclusive
• second - 0 to 59 inclusive.
Example
Sub Main()
Dim meethour As Integer
Dim meetmin As Integer
Dim meetsec As Integer
Dim mymeeting As Date
meethour = 14: meetmin = 15: meetsec = 0
mymeeting = TimeSerial(meethour, meetmin, meetsec)
Print "I have a meeting at:", mymeeting
End Sub
TimeValue
Returns a date data type, given a string argument.
Syntax
TimeValue(string expression)
The argument for this function is any string expression that represents a valid time. If an invalid time string has been specified, the system will display an error.
Example
Sub Main()
Dim mytimestr As String
Dim mymeeting As Date
mytimestr = "2:15:00 PM"
mymeeting = TimeValue(mytimestr)
Print "I have a meeting at: ",mymeeting
End Sub
Today
Returns the current date from the server's system clock.
Syntax
Today
Example
See the code example for the Day internal function.
Trim
Returns a string with all leading and trailing space and tab characters removed.
Syntax
Trim(string expression)
The argument string expression can be any valid string.
Example
Sub Main()
Dim s As String
s=" test string "
Print "(" & Trim(s) & ")"
'prints (test string)
End Sub
UBound
Returns an integer indicating the upper bound of an array.
If the variable is not an array, an error occurs.
Syntax
UBound(array variable)
Example
See the code example for the IsArray internal function.
UCase
Returns the string argument converted to all uppercase letters.
Syntax
UCase(string expression)
Example
Sub Main()
Dim s As String
s = UCase(hELlo wOrld")
Print s 'displays "HELLO WORLD"
Print UCase ("this is now uppercase")
'displays "THIS IS NOW UPPERCASE"
End Sub
Val
Returns the numeric value of a string argument.
Syntax
Val(string expression)
The string expression argument can be any string that represents a number. If string expression contains the decimal point character, Val returns a floating-point value, otherwise Val returns an integer value.
Example
Sub Main()
'this program converts string "50" into a number and then uses the number in a math calculation
Dim s As String
Dim num As Integer
s = "50"
num = Val(s)
Print "The numeric value of 's' times 5 is: ",num *5
End Sub
Weekday
Returns a number indicating the day of the week for any valid date expression.
Syntax
Weekday(date expression)
Example
Sub Main()
Dim d As Date
Dim daynum As Integer
Dim mydays(1 to 7) As String
mydays(1) = "Sunday": mydays(2) = "Monday":...
d = today
daynum = Weekday(d)
Print "Today, the day of the week is"; mydays(daynum)
End Sub
Year
Returns the year from any valid date expression.
Syntax
Year (date expression)
Example
Sub Main()
Dim d As Date
Dim yearnum As Integer
d = Today
yearnum = Year(d)
Print "This year is"; yearnum; "A.D."
End Sub
FirstClass internal functions
BatchAdmin
Runs administration-level batch administration commands.
The return string will contain either the requested data or information describing any errors that might have occurred. A return code is generated and may be retrieved with the FCBatchAdminCode internal function. A return string of text is generated and may be retrieved with the FCBatchAdminReply internal function.
Syntax
BatchAdmin (batchcommand)
BatchAdmin takes the batchcommand argument and passes it to batch administration with administrator-level permissions.
Example
BatchAdmin ("getadmin")
if FCBatchAdminCode <> 0 Then
Print "Error with batch script!!!"
Print "The error message is:"; FCBatchAdminReply
Else
Print "The Admin's account is:"; FCBatchAdminReply 'gets the admin user ID and prints it to the debug window
End If
FCAppBuildNumber
Returns the current .fcx build number (as an integer value) of an application.
Build numbers are built into .fcx-compiled applications when they are entered on the Project Attributes form. This form is accessed by clicking Options on the Project tab in FirstClass RAD project manager.
Syntax
FCAppBuildNumber[(applicationname)]
If the optional argument applicationname is supplied, this function returns the build number of the specified application provided that it is loaded on the server. If the optional argument is not supplied, FCAppBuildNumber returns the build number of the calling application.
FCAppDescription
Returns the application description information (as a string) of an application.
Application description information strings are built into .fcx-compiled applications when they are entered in the FirstClass RAD Project Attributes form.
Syntax
FCAppDescription[(applicationname)]
If the optional argument applicationname is supplied, this function returns the application description information of the specified application provided that it is loaded on the server. If the optional argument is not supplied, FCAppDescription returns the application description information of the calling application.
FCAppDeveloper
Returns the developer information (as a string) of an application.
Application developer information strings are built into .fcx-compiled applications when they are entered in the FirstClass RAD Project Attributes form.
Syntax
FCAppDeveloper[(applicationname)]
If the optional argument applicationname is supplied, this function returns the developer information string of the specified application provided that it is loaded on the server. If the optional argument is not supplied, FCAppDeveloper returns the developer information string of the calling application.
FCAppIcon
Returns an application's icon resource number as a numeric value that is compiled into the application by FirstClass RAD.
Syntax
FCApplcon[(applicationname)]
If the optional application argument applicationname is omitted, the value returned is from the called application.
FCAppLoadState
Returns the current load status of the application specified by the optional applicationname argument.
If no argument is specified, FCAppLoadState returns the load status of the calling application.
This function returns one of the following constants:
• FCAppLoaded - application is currently loaded by FirstClass RAD
• FCAppUnloaded - application is not loaded by FirstClass RAD
• FCAppUnloading - FirstClass RAD is unloading the application
• FCAppReloading - FirstClass RAD is reloading the application.
Syntax
FCApploadState[(applicationname)]
FCAppLaunchMethod
Returns the method by which the calling application was launched.
This function returns one of the following constants:
• FCServerLaunched - application is launched as server application
• FCSessionLaunched - application is launched at client login
• FCDebugLaunched - application is launched by FirstClass RAD in debug mode
• FCUserLaunched - application is launched from Desktop stationery
• FCAppLaunched - application is launched from another FirstClass RAD application.
Syntax
FCAppLaunchMethod
FCAppName
Returns the name (a string value) of the calling application.
Syntax
FCAppName
FCAppServerVersion
Returns the version number of FirstClass RAD currently running.
The version number is returned as a whole number integer representing the version number multiplied by 1000. For example, RAD version 1.210 will return the value 1210, version 2.0 will return 2000, and so on.
This internal function is useful for determining backward compatibility issues between applications and FirstClass RAD.
Syntax
FCAppServerVersion
Example
FCAppServerVersion = 1210
FCAppSessionUsage
Returns the number of application sessions currently in use on the FirstClass server.
Syntax
FCAppSessionUsage[(applicationname)]
If the optional argument applicationname is supplied, this function returns the number of application sessions currently in use by the specified application.
FCAppVersion
Returns the version number (as a string) of an application.
Application version strings are built into .fcx-compiled applications when they are entered in the FirstClass RAD Project Attributes form.
Syntax
FCAppVersion[(applicationname)]
If the optional argument applicationname is supplied, this function returns the version number string of the specified application provided that it is loaded on the FirstClass server. If the optional argument is not supplied, FCAppVersion returns the version string of the calling application.
FCBatchAdmin
Sends a batch administration command to the FirstClass server and returns a result code.
The function returns the success or failure of the call as a numeric value. A non-zero result indicates an error has occurred; zero indicates success. Any data returned from the batch administration request (including explicit error messages) may be accessed via the FCBatchAdminReply function.
Syntax
FCBatchAdmin(batchstring)
where batchstring is a single string argument that the FCBatchAdmin FirstClass internal function sends to FirstClass batch administration for processing.
FCBatchAdminCode
Returns the last batch administration command's return code.
If FCBatchAdminCode returns a non-zero value, there has been an error with the last batch administration command executed.
Syntax
FCBatchAdminCode
FCBatchAdminReply
Retrieves a string containing batch administration reply data supplied from the last FCBatchAdmin call.
Syntax
FCBatchAdminReply
Example
Sub Main()
If FCBatchAdmin ("GET ADMIN") = 0 Then
Print "The Default Admin account is: ";
FCBatchAdminReply
End If
End Sub
FCClientPlatform
Returns a constant value that is the platform on which the FirstClass client is currently being used.
FCClientPlatform returns one of the following values:
• fcCLUI - command line user interface
• fcDOS - DOS client
• fcFinger - Finger
• fcFTP - FTP
• fcGateway - gateway
• fcHTTP - HTTP
• fcIMAP - IMAP
• fcInternet - Internet Services
• fcJava - Java client
• fcLDAP - LDAP client
• fcMac OS - Mac OS client
• fcMAPI - MAPI
• fcNNTP - NNTP
• fcOfflineServer - offline server
• fcPersonalServer -FirstClass Personal server
• fcPOP - POP
• fcSMTP - SMTP
• fcUNIX - UNIX client
• fcUnknown - unknown client platform
• fcVoice - Voice
• fcWindows - Windows client.
Syntax
FCClientPlatform
FCClientVersion
Returns an integer value that is the FirstClass client's version number.
Syntax
FCClientVersion
FCEventShiftState
Returns the current state of the Shift and Ctrl keys when an event occurs.
FCEventShiftState returns the following integer values based on the shift state:
• no special state - 0
• Shift key held - 1
• Ctrl key held - 2
• Shift and Ctrl keys held - 3.
Syntax
FCEventShiftState
FCGetPrivGroups
Retrieves the FirstClass server's privilege group list into the FCPrivGroup array.
FCGetPrivGroups returns an integer indicating the total number of privilege groups in the current FirstClass server. After calling FCGetPrivGroups, an application may access the FCPrivGroup array to retrieve the names of the server's privilege groups.
Syntax
FCGetPrivGroups
Example
Sub Main()
Dim i As Integer
Dim NumGroups As Integer
NumGroups = FCGetPrivGroups
MsgBox(FCPrivGroup(1))
End Sub
FCPOFolder
Returns the path (as a string) to the FirstClass server's main post office folder, regardless of platform.
Syntax
FCPOFolder
Example
print FCPOFolder
FCPrivGroup
Returns a string value which is the name of a privilege group.
Syntax
FCPrivGroup(groupnum)
The groupnum argument specifies the ordinal number, starting at 0 or the current array base index, of the privilege group in the group list. The internal function FCGetPrivGroup must be called to initiate the privilege group list.
Example
Sub Main()
Dim i As Integer
Dim NumGroups As Integer
NumGroup = FCGetPrivGroup
For i = 0 to NumGroups -1
Print FCPrivGroup(i)
End If
End Sub
FCSpawnReturn
Obtains the return code from a process started by Spawn or Shell.
Syntax
FCSpawnReturn
FCSeverSerialNumber
Returns an integer value that is the FirstClass server's serial number.
This function is often used for application licensing purposes.
Syntax
FCServerSerialNumber
FCUserFirstName
Returns a string containing the first name of the user currently using the application.
Syntax
FCUserFirstName
Example
Sub Main()
Print "Your Account Information"
Print "...................................."
Print "First Name:"; FCUserFirstName
...
End Sub
FCUserID
Returns a string containing the user ID of the FirstClass user currently using the application.
Syntax
FCUserID
Example
Sub Main()
Print "UserID:"; FCUserID
...
End Sub
FCUserLastName
Returns a string containing the last name of the FirstClass user currently using the application.
Syntax
FCUserLastName
Example
Sub Main()
Print "Last Name:"; FCUserLastName
...
End Sub
FCUserMI
Returns a string containing the middle initial of the FirstClass user currently using the application.
Syntax
FCUserMI
Example
Sub Main()
Print "Middle Initial:"; FCUserMI
...
End Sub
FCUserName
Returns a string containing the full user name of the FirstClass user currently using the application.
Syntax
FCUserName
Example
Sub Main()
Print "Full Name:"; FCUserName
...
End Sub
FCUserPrivGroup
Determines whether the user is in the specified privilege group.
If the user is not in the privilege group, or the privilege group specified does not exist, the function returns FALSE. If the user is in the privilege group specified, the function returns TRUE.
Syntax
FCUserPrivGroup(privilege group)
Example
Sub Main()
If FCUserPrivGroup("Administrators") Then
Print "You are a member of the 'Administrators' privilege group."
Else
Print "You are not a member of the 'Administrators' privilege group."
Print "Access Denied"
End 'terminate the program
End If
End Sub
Statement attributes
AsyncEnable
Retrieves or assigns an integer value indicating the ODBC asynchronicity of a statement.
Syntax
statementname.AsyncEnable [ = constant]
These are the possible values for constant:
• SQL_ASYNC_ENABLE_OFF - off
• SQL_ASYNC_ENABLE_ON - on
• SQL_ASYNC_ENABLE_DEFAULT - off.
The default value for this attribute is SQL_ASYNC_ENABLE_OFF, which indicates that the statement will process synchronously.
BindType
Retrieves or assigns an integer value indicating the ODBC column binding of a statement.
Syntax
statementname.BindType [ = constant]
These are the possible values for constant:
• SQL_BIND_BY_COLUMN - column binding
• SQL_BIND_TYPE_DEFAULT - row-wise binding.
The default value for this attribute is SQL_BIND_TYPE_DEFAULT.
Column
Retrieves or assigns column attributes and methods.
Syntax
statementname.Column(colname | colnum)[.attribute] [ = value]
This attribute references a cursor's column either by name or by ordinal number.
Concurrency
Retrieves or assigns an integer value indicating the ODBC concurrency of a statement.
Syntax
statementname.Concurrency [ = constant]
These are the possible values for constant:
• SQL_CONCUR_READ_ONLY - updates will be attempted; cursor is read only
• SQL_CONCUR_LOCK - cursor uses the lowest level of locking sufficient to ensure that the row can be updated
• SQL_CONCUR_ROWVER - cursor uses optimistic concurrency control, comparing row versions
• SQL_CONCUR_VALUES - cursor uses optimistic concurrency control, comparing values.
The default value for SQL_CONCURRENCY is SQL_CONCUR_READ_ONLY.
CursorType
Retrieves or assigns an integer value indicating the ODBC cursor type of a statement.
Syntax
statementname.CursorType [ = constant]
These are the possible values for constant:
• SQL_CURSOR_KEYSET_DRIVEN
• SQL_CURSOR_FORWARD_ONLY
• SQL_CURSOR_DYNAMIC
• SQL_CURSOR_STATIC
• SQL_CURSOR_TYPE_DEFAULT
• SQL_CURSOR_FORWARD_ONLY - the cursor only scrolls forward
• SQL_CURSOR_STATIC - the data in the result set is static
• SQL_CURSOR_KEYSET_DRIVEN - the driver uses the keys for the number of rows specified in the SQL_KEYSET_SIZE statement option
• SQL_CURSOR_DYNAMIC - the driver only uses the keys for the rows in the rowset.
The default value is SQL_CURSOR_FORWARD_ONLY. This attribute cannot be set on an open cursor.
DisplayErrors
Specifies whether the default error handling system should be used or disabled in the event that an ODBC error occurs.
If the DisplayErrors attribute is set to TRUE (the default), ODBC errors will be delivered via modal message box to the offending application.
If the DisplayErrors attribute is set to FALSE, the error message will be suppressed and normal application processing will continue, ignoring the error. Specific error information may then be retrieved by the DBError and DBErrorCode attributes, allowing you to build custom database error handlers.
Syntax
statementname.DisplayErrors [= TRUE/FALSE]
Example
Sub Main ()
Dim stmt as dbStatement
stmt.OpenStatement(Parks, dbDynamic, dbRowver)
stmt.DisplayErrors = FALSE
stmt.ExecuteSQL("Select * from parkinfo")
...
End sub
DisplayWarnings
Indicates whether ODBC warning messages should be displayed when they occur on the statement.
Syntax
statementname.DisplayWarnings [ = TRUE|FALSE]
The default value is FALSE, indicating that warnings should be suppressed.
KeysetSize
Retrieves or assign an integer value indicating the number for rows in an ODBC keyset driven cursor.
Syntax
statementname.KeysetSize [= size]
The size variable can be set to the desired size or to the default SQL_KEYSET_SIZE_DEFAULT, which indicates that the keyset is completely keyset-driven.
MaxLength
Retrieves or assigns an integer value indicating the maximum amount of data that can be returned from a column.
Syntax
statementname.MaxLength [ = length]
The length variable can be set to the desired length or to the constant SQL_MAX_LENGTH_DEFAULT, which indicates that the column should return all data.
MaxRows
Retrieves or assigns an integer value indicating the ODBC maximum rows to return in a statement.
Syntax
statementname.MaxRows [ = numrows]
The numrows variable can be set to the desired number of rows or to the constant SQL_MAX_ROWS_DEFAULT, which returns all rows returned from the query.
NoScan
Retrieves or assigns an integer value indicating whether the ODBC driver should scan an SQL string for ODBC escape clauses.
Syntax
statementname.NoScan [ = constant]
These are the possible values for constant:
• SQL_NOSCAN_OFF - off
• SQL_NOSCAN_ON - on
• SQL_NOSCAN_DEFAULT - on.
The default value for this attribute is SQL_NOSCAN_ON, which indicates that SQL strings will not be scanned for escape clauses.
NumCols
Retrieves the number of columns returned in a statement.
This attribute is read only at runtime.
Syntax
statementname.NumCols
QueryTimeout
Retrieves or assigns an integer value indicating the ODBC query timeout in seconds.
Syntax
statementname.QueryTimeout [= timeout]
The timeout variable can be set to the desired number of seconds or to the constant SQL_QUERY_TIMEOUT_DEFAULT, which indicates that the query will continue to execute until it has completed.
RetrieveData
Retrieves or assigns an integer value indicating whether the ODBC driver should automatically retrieve the data for the current row.
Syntax
statementname.Retrieve [= constant]
These are the possible values for constant:
• SQL_RD_OFF - off
• SQL_RD_ON - on
• SQL_RD_DEFAULT - on.
The default value for this attribute is SQL_RD_ON, which indicates that data will be automatically retrieved for each row.
RowsetSize
Retrieves or assigns an integer value indicating the cursor rowset size.
Syntax
statementname.RowsetSize [ = size]
The size variable can be set to the desired number of rows in the rowset or SQL_ROWSET_SIZE_DEFAULT, which specifies a rowset size of 1 record.
SimulateCursor
Retrieves or assigns an integer value that specifies whether drivers that simulate positioned update and delete statements ensure that these statements affect only a single row.
Syntax
statementname.StatementCursor [ = constant]
These are the possible values for constant:
• SQL_SC_NON_UNIQUE - does not guarantee that simulated positioned update or delete statements will affect only a single row
The application must enforce this behavior.
• SQL_SC_TRY_UNIQUE - attempts to guarantee that simulated positioned update or delete statements affect only a single row
The driver always executes such statements, even if they might affect more than one row.
• SQL_SC_UNIQUE - the driver guarantees that simulated positioned update or delete statements affect only a single row.
UseBookmarks
Retrieves or assigns an integer value indicating whether the statement can use bookmarks.
NoteTo use bookmarks with a cursor, the application must specify this option before opening the cursor.
Syntax
statementname.UseBookmarks [ = constant]
These are the possible values for constant:
• SQL_UB_OFF - off
• SQL_UB_ON - on
• SQL_UB_DEFAULT - off.
The default value for this attribute is SQL_UB_OFF.
Statement methods
BOF
Returns the current value of the beginning of file (BOF) flag.
When the program attempts to move the record pointer off the beginning of the result set, the BOF flag is set to TRUE and the record pointer is positioned at the first record in the result set.
NoteIt is not possible to move completely off the front of the result set; the rowset buffers will always be associated with a row if there are rows in the result set.
BOF returns FALSE if the record pointer has been successfully moved to a new record in the result set. If the record set is empty, BOF and EOF always return TRUE.
Syntax
statementname.BOF
Compliance
Level 2
Example
The following example displays all contact names from a database from the last record to the first:
Sub DisplayContactNames(Contact as DBStatement)
Contact.MoveLast
Do While Not Contact.BOF
Print "Contact name:"; Contact.Column("name")
Contact.MovePrev
Loop
End Sub
CloseStatement
Closes a statement on a database connection.
Changes made to row buffers that have not been updated are discarded.
Syntax
statementname.CloseStatement
Compliance
Core level
DBError
Returns a string containing the last database statement error.
This method is useful for determining the type of error that has occurred in an error handling routine.
Syntax
statementname.DBError
Compliance
Core level
DBErrorCode
Stores a numeric value which is the ODBC error code of the last operation performed.
Constant values that are common return values from ODBC include:
• db_success - operation completed successfully
• db_success_with_info - operation completed successfully with more information available
• db_no_data_found - no data was returned from the operation when data was expected
• db_error - ODBC error occurred.
Syntax
statementname.DBErrorCode
Delete
Deletes the current record and moves the record pointer to the next record. The Delete method can be used on form fields.
There is no warning for deleting records with positioned deletes. Make sure your application deletes only the records you are interested in deleting. Delete confirmations are handled by the application.
 WarningAny records deleted with this method will be permanently lost.
Syntax
statementname.Delete
Compliance
Level 2
Example
The following example finds a specific record, prints out its information, and then deletes it from the database using a positioned delete.
Sub Main()
Dim cnct As DBConnection
Dim stmt As DBStatement
cnct.OpenConnection("MyDSN") 'Open the data source "MyDSN"
stmt.OpenStatement(cnct, dbKeyset, dbRowver)
stmt.ExecuteSQL("SELECT * FROM MyTable WHERE CustNum = 12345")
Print "Deleting Customer."
Print "Customer Name:"; stmt.Column("CustName")
Print "Customer Phone:"; stmt.Column("CustAddr")
Print "Customer Last Contacted:";
stmt.Column("CustLastContact")
stmt.Delete 'Delete the current record
stmt.CloseStatement
cnct.CloseConnection 'Close the connection
End Sub
Empty
Returns whether or not the current recordset has any records.
If there are records in the recordset, Empty returns FALSE; otherwise, Empty returns TRUE.
Syntax
statementname.Empty
Compliance
Core level
Example
See the code example for the ExecuteSQL statement method.
EOF
Returns the current value of the end of file (EOF) flag.
When the program attempts to move the record pointer off the end of the result set, the EOF flag is set to TRUE and the record pointer is positioned at the last record in the result set.
NoteIt is not possible to move completely off the end of the result set; the rowset buffers will always be associated with a row if there are rows in the result set.
EOF returns FALSE if the record pointer has been successfully moved to a new record in the result set. If the record set is empty, BOF and EOF always return TRUE.
Syntax
statementname.EOF
Compliance
Core level
Example
The following example displays all contact names from a database from the first record to the last.
Sub DisplayContactNames(Contact as DBStatement)
Contact.MoveFirst
Do While Not Contact.EOF
Print "Contact name:"; Contact.Column("name")
Contact.MoveNext
Loop
End Sub
ExecuteSQL
Executes an SQL statement and returns a cursor if applicable.
Syntax
statementname.ExecuteSQL(query)
Compliance
Core level
Example
The following example opens a connection on a data source, opens a statement on a connection, and runs a query to determine if a particular record exists. If the record exists, customer information is displayed. Otherwise, a warning is displayed.
Sub Main()
Dim cnct As DBConnection
Dim stmt As DBStatement
cnct.OpenConnection("MyDSN") 'Open the data source "MyDSN"
stmt.OpenStatement(cnct, dbKeyset, dbRowver)
stmt.ExecuteSQL("SELECT * FROM MyTable WHERE CustNum = 12345")
If (stmt.Empty) Then 'If no records were returned
Print "The customer does not exist in the database!"
Else
Print "Customer Information:"
Print "Customer Name:"; stmt.Column("CustName")
Print "Customer Phone:"; stmt.Column("CustAddr")
Print "Customer Last Contacted:";
stmt.Column("CustLastContact")
End If
stmt.CloseStatement
cnct.CloseConnection 'Close the connection
End Sub
Filter
Requeries a record set with an SQL WHERE clause.
The Filter method is a fast, effective way of narrowing the records contained in a record set. Filter can be used on any statement cursor generated with an SQL statement provided that it does not have an SQL WHERE clause.
Filter is the preferred method for searching records in bound table applications.
Syntax
statementname.Filter(WHEREclause)
The Filter command appends the WHERE clause specified by the WHEREclause argument to the original SQL statement and requeries the database. After filtering a query, the record pointer points to the first record in the recordset.
Calling the Filter method with a WHEREclause of "" removes the current Filter WHERE clause and returns the complete unfiltered recordset.
Compliance
Core level
Example
The following code example filters the Customers table in the data environment by customer name with a text string read off the form.
Sub Click()
Dim filterstr As String
filterstr = "MyCustName Like "' & txtSearchText.Text & "%"'
Customers.Filter(filterstr)
End Sub
FindFirst, FindLast, FindNext, FindPrev
Finds a record in a recordset.
Syntax
statementname.FindFirst(condition), statementname.FindLast(condition), statementname.FindNext(condition), statementname.FindPrev(condition)
This method moves the record pointer through the record set until condition evaluates to TRUE or the end of the record set is reached. Each time the record pointer is moved, condition is re-evaluated.
The starting location and direction of record pointer movement depends on which method is used:
• FindFirst - begins at the first record and moves forward through the record set
• FindLast - begins at the last record and moves backward through the record set
• FindNext - begins at the current record and moves forward through the record set
• FindPrev - begins at the first record and moves backward through the record set.
If the condition does not evaluate to TRUE and the end of the record set is reached, the NoMatch flag is set to TRUE.
The argument condition may be any valid conditional expression; however, it is best to include comparisons to columns in the cursor or it is not likely that condition will evaluate to TRUE.
NoteIn order to prevent deadlock in asynchronous systems, Find requires server re-entrance for each move and evaluation of condition. Re-entrance has a substantial amount of overhead and it is often faster and more effective to use the Filter method instead of a Find method.
Compliance
Level 2
Example
Sub Main()
Dim cnct As DBConnection
Dim stmt As DBStatement
cnct.OpenConnection("MyDSN") 'Open the data source "MyDSN"
stmt.OpenStatement(cnct, dbKeyset, dbRowver)
stmt.ExecuteSQL ("SELECT * FROM MyTable")
'Starting from the first record in the recordset, find the first record which
'makes the condition CustNum = 12345 evaluate to TRUE.
stmt.FindFirst(stmt.Column("CustNum") = 12345)
If (stmt.NoMatch) Then 'Record was not found
Print "The customer does not exist in the database!"
Else
Print "Customer Information:"
Print "Customer Name: ";stmt.Column("CustName")
Print "Customer Phone: ";stmt.Column("CustAddr")
Print "Customer Last Contacted: ";stmt.Column("CustLastContact")
End If
stmt.CloseStatement
cnct.CloseConnection 'Close the connection
End Sub
GetTables
Retrieves table information about the current data source and returns it as a result set.
Syntax
statementname.GetTables
Compliance
Level 1
Insert
Clears the current row buffers and prepares for positioned insert at the end of a record set. The record is not actually written to the database until the Update method is run.
Syntax
statementname.Insert
Compliance
Level 2
Example
The following example uses a positioned insert to insert a record into a record set. Once the statement is in insert mode, the row buffers are assigned values and then updated to write the new record to the database:
Sub Main()
Dim cnct As DBConnection
Dim stmt As DBStatement
cnct.OpenConnection("MyDSN") 'Open the data source "MyDSN"
stmt.OpenStatement(cnct, dbKeyset, dbRowver)
stmt.ExecuteSQL("SELECT * FROM My Table")
stmt.Insert 'Insert a new record
stmt.Column("CustName") = "Harold"
stmt.Column("CustAddr") = "99 Main Street"
stmt.Column("CustLastContact") = Today
stmt.Update 'Write new record to database
stmt.CloseStatement
cnct.CloseConnection 'Close the connection
End Sub
Lock
Locks the current record to prevent updates by other users.
The Lock method provides a way for applications to control concurrency on connections that do not support transactions. Generally, data sources that support concurrency levels and transactions will not support the Lock method.
To simulate a transaction, an application uses the Lock method to lock each of the rows in the transaction. It then uses the Update or Delete methods to update or delete each row. When all operations in the transaction have completed, the application uses the Unlock method to unlock each row.
A row locked with the Lock method remains locked until the application calls the Unlock method or until the statement is closed.
Syntax
statementname.Lock
Compliance
Some level 2 drivers
Example
The following example locks the current record, updates it and then unlocks it so that it is available for other users to modify.
Sub Main()
Dim cnct As DBConnection
Dim stmt As DBStatement
cnct.OpenConnection("MyDSN") 'Open the data source "MyDSN"
stmt.OpenStatement(cnct, dbKeyset, dbRowver)
stmt.ExecuteSQL("SELECT * FROM My Table WHERE CustNum = 12345")
stmt.Lock
stmt.Column("CustName") = "Harold"
stmt.Column("CustAddr") = "99 Main Street"
stmt.Column("CustLastContact") = Today
stmt.Update 'Write new data to database
stmt.Unlock
stmt.CloseStatement
cnct.CloseConnection 'Close the connection
End Sub
MakeList
Creates a list suitable for use as a static or editable List attribute from a column in a database.
The MakeList statement method generates a list of all the items contained in the statement by concatenating the results and separating the list with semicolons.
Syntax
MakeList(StringColumn, [NumericColumn])
The StringColumn is the text name of the column of data to be used to generate the list content. The NumericColumn is an optional argument used to add numeric values to the items in the list.
Example
...
Dim stmt As DBStatement
stmt.OpenStatement (MyConnection)
stmt.ExecuteSQL ("SELECT NAME ID FROM NAMES WHERE ID < 40")
1stNames.List=stmt.MakeList ("NAME", "ID")
stmt.CloseStatement
...
MoveFirst, MoveLast, MoveNext, MovePrev
Moves the position of the record pointer and updates bound columns.
The Move method automatically discards any changes on a modified or inserted record if the changes have not been written to the database with the Update method.
Syntax
statementname.MoveFirst, statementname.MoveLast,
statementname.MoveNext, statementname.MovePrev
The starting location and direction of record pointer movement depends on which method is used:
• MoveFirst - moves the record pointer to the first record in the record set
• MoveLast - moves the record pointer to the last record in the record set
• MoveNext - moves the record pointer to the next record in the record set
• MovePrev - moves the record pointer to the previous record in the record set.
Compliance
Level 2 (SQLExtendedFetch)
Example
The following example displays all contact names from a database from the first record to the last.
Sub DisplayContactNames(Contact as DBStatement)
Contact.MoveFirst
Do While Not Contact.EOF
Print "Contact name:"; Contact.Column("name")
Contact.MoveNext
Loop
End Sub
NoMatch
Returns TRUE or FALSE depending on whether the last Find method located a matching record.
Syntax
statementname.NoMatch
Compliance
Level 2
Example
See the code example for the Find statement method.
OpenStatement
Opens a statement on a database connection.
Syntax
statementname.OpenStatement(cnctname [,dbCursorType] [dbConcurrency])
The cnctname argument specifies the name of a valid DBConnection object that has already opened a connection on a valid data source.
The optional arguments dbCursorType and dbConcurrency may be used to set the statement's cursor type and concurrency respectively.
The dbCursorType argument may be set to one of the following constants:
• dbForwardOnly - forward-only cursor
• dbStatic - static cursor
• dbKeyset - keyset-driven cursor
• dbDynamic - dynamic cursor.
The dbConcurrency argument may be set to one of the following constants:
• dbReadOnly - cursor is read only
• dbLock - cursor uses row-level locking concurrency
• dbValues - cursor uses optimistic concurrency, comparing values
• dbRowver - cursor uses optimistic concurrency, comparing row versions.
The cursor type and concurrency may also be set explicitly with the Cursor Type and Concurrency attributes; however, the dbCursorType and dbConcurrency arguments provide an effective shortcut.
If a statement's cursor type and concurrency are not explicitly specified, a statement creates by default a forward-only read-only cursor.
Compliance
Core level
Example
The following example opens a connection on a data source, opens a statement on a connection, and runs a query to determine if a particular record exists. If the record exists, customer information is displayed. Otherwise, a warning is displayed.
Sub Main()
Dim cnct As DBConnection
Dim stmt As DBStatement
cnct.OpenConnection("MyDSN") 'Open the data source "MyDSN"
stmt.OpenStatement(cnct, dbKeyset, dbRowver)
stmt.ExecuteSQL("SELECT * FROM MyTable WHERE CustNum = 12345")
If (stmt.Empty) Then 'If no records were returned
Print "The customer does not exist in the database!"
Else
Print "Customer Information:"
Print "Customer Name:"; stmt.Column("CustName")
Print "Customer Phone:"; stmt.Column("CustAddr")
Print "Customer Last Contacted:";
stmt.Column("CustLastContact")
End If
stmt.CloseStatement
cnct.CloseConnection 'Close the connection
End Sub
Refresh
Refreshes the values in the current rowset buffers.
If changes have occurred to the current row in the underlying database, calling the Refresh method will update the local cursor and propagate any relevant changes to bound controls.
If you have modified the current values in the rowset buffers, calling Refresh will get a new copy of the original row from the database and overwrite any changes.
Syntax
statementname.Refresh
Compliance
Level 2
Example
Sub Click()
MsgBox("Update the current record?",FCYesNo, "Update")
If MsgBoxResponse = FCYes Then
MyStmt.Update 'Update the current record
Else
MyStmt.Refresh 'Discard changes and retrieve original values
End If
End Sub
Requery
Re-executes the current statement's query. This is similar to the Refresh method except that all rows in the cursor are refreshed. Upon calling the Requery method, the record pointer is positioned at the first record in the result set.
Syntax
statementname.Requery
Compliance
Core level
Unfilter
Requeries the record set without the WHERE clause specified by the Filter method.
Calling the Unfilter method is equivalent to calling the Filter method with a WHERE clause of "". Unfilter removes the current Filter WHERE clause and returns the complete unfiltered record set.
Syntax
statementname.Unfilter
Compliance
Core level
Unlock
Unlocks the current record to allow updates by other users.
Syntax
statementname.Unlock
Compliance
Some level 2 drivers
Example
See the code example for the Lock statement method.
Update
Updates the current row in the database. If possible, all changes to the row will be written to the database. The update method is also used to confirm the insertion of a new record.
Syntax
statementname.Update
Compliance
Level 2
Example
The following example runs SQL to retrieve a record, changes some column values, and writes the changes to the database using the positioned Update method.
Sub Main()
Dim cnct As DBConnection
Dim stmt As DBStatement
cnct.OpenConnection("MyDSN") 'Open the data source "MyDSN"
stmt.OpenStatement(cnct, dbKeyset, dbRowver)
stmt.ExecuteSQL("SELECT * FROM MyTable WHERE CustNum = 12345")
stmt.Column("CustName") = "Joe"
smt.Column("CustAddr") = "101010 Binary Ave."
stmt.Column("CustLastContact") = Today
stmt.Update 'Write changes to the database
stmt.CloseStatement
cnct.CloseConnection 'Close the connection
End Sub
|