 |
Help Document |
|
 |
|
Introducing FirstClass RAD
FirstClass Rapid Application Developer 2.0 (FirstClass RAD or RAD) lets you enhance FirstClass client functionality with intranet applications, including interfaces to databases.
To create FirstClass RAD applications, you create the required forms using FirstClass Designer, then (using BASIC) use FirstClass RAD to program the event procedures for the objects on the forms. Although FirstClass RAD must be installed on a Windows NT machine, you can use any FirstClass client (Windows or Mac OS) to run it.
To run FirstClass RAD applications, your users just need a FirstClass Windows or Mac OS client.
Naming conventions for FirstClass RAD
When you name FirstClass objects such as forms, fields, and code elements such as variables, constants, and subroutines, these names must:
• begin with a letter
• contain only letters, numbers, and the underscore character (_)
• be no longer than 255 characters
• differ from the names of BASIC operators and logical operators such as OR, AND, MOD, and NOT.
Examples
• Form
• frm
• FileOpen
• frmFileOpen
• Checkbox
• chk
• ReadOnly
• chkReadOnly
RAD Language reference contents
The Language reference describes the commands, methods, attributes, and so on, that you can include in your BASIC code for FirstClass RAD applications. For examples of these objects in use, see the Examples file on your FirstClass RAD CD.
Data types in code
Each variable n your code has a data type that determines what kind of data that variable can store. For example, String variables store text strings, and Integer variables store whole numbers.
Before you can use a variable in your code, you must declare it and its data type. This ensures that a variable only contains a value of the expected data type (for efficiency, FirstClass RAD does not support variables that can contain ambiguous data types).
Data types and databases
Both FirstClass RAD and databases require that all data contained in their data structures have explicit data types.
If your FirstClass RAD application will be connecting to a database, you must be sure to use data types that are compatible with the corresponding database data types. These are the FirstClass RAD counterparts for common ODBC database data types:
FirstClass RAD data types and ODBC database data types
Integer
integer, int, smallint, tinyint, boolean, bit, yes/no
Long
integer, int, smallint, tinyint, boolean, bit, yes/no
Single
float, double, single, double precision, decimal, numeric
Double
float, double, single, double precision, decimal, numeric
Currency
monetary, money, currency, smallmoney
String
char, character, varchar, variable character, text, memo
Date
date, time, date/time, datetime, smalldatetime
Using FirstClass RAD with databases
FirstClass RAD applications can connect to any ODBC-compliant database (ODBC is the industry standard for relational database access). A FirstClass RAD form can tie in to multiple database tables and multiple databases. The databases can be on different servers. For fields that will always contain data from the same source (the same column in a database table), you can create
bound columns database access.
For more flexibility, when you do not have fields that are bound to a particular column, you can create nonbound database access.
Creating ODBC data sources
Only applicable to applications that will connect to databases.
Before a FirstClass RAD application can connect to an ODBC-compliant database, you must use Windows NT to create an ODBC data source.
To do this:
1 Double-click ODBC in the Windows Control Panel.
2 Click Add on the ODBC Data Source Administrator's System DSN tab.
3 Select the ODBC driver for your database.
4 Click Finish.
5 Fill in the fields to set up the driver. For help, use Windows' online help or see the driver manufacturer's documentation.
6 Click OK.
Note
You need only connect to your ODBC database source once for all applications.
If you want to test the data source, you can connect to it with an ODBC client such as Microsoft Query, Microsoft Access, or Microsoft Excel.
Adding database connections
To add database connections:
1 Click New on the FirstClass RAD Project Manager's Connection tab.
2 Fill in the connection information.
3 Click OK.
Removing database connections
When you remove a database connection from a FirstClass RAD project, all tables associated with it that are listed on the Table tab are also removed. You cannot undo this operation.
To remove a database connection:
1 Select the connection on the FirstClass RAD Project Manager's Connection tab.
2 Click Remove.
Updating database connections
To update database connections:
1 Select the connection on the FirstClass RAD Project Manager's Connection tab.
2 Click Modify.
3 Change information as required.
4 Click OK.
Adding database table connections
Before you can add a connection to a table in a database, you must add a connection to the database as a whole.For details, see Adding database connections.
To add a connection to a table in a database:
1 Click New on the FirstClass RAD Project Manager's Table tab.
2 Fill in the table information.
3 Click OK.
Removing database table connections
When you remove a database table connection from a FirstClass RAD project, all associations to that table in the project's forms are also removed. You cannot undo this operation.
To remove a connection to a table in a database:
1 Select the table on the FirstClass RAD Project Manager's Table tab.
2 Click Remove.
Updating database table connections
To update database table connections:
1 Select the table on the FirstClass RAD Project Manager's Table tab.
2 Click Modify.
3 Change information as required.
4 Click OK.
Creating FirstClass RAD applications
With minor variations, you follow the same basic steps to create all FirstClass RAD applications. The Lanuguage reference section of our online help provides descriptions of the commands and statements you can use when programming your application.
1 If this is a database application, create an ODBC data source for the database. For details, see Creating ODBC data sources.
2 Create a settings file that contains all the resources (for example, custom icons) and forms that your application will require.
Use FirstClass Designer to create this settings file. You may want to call it application name.fc. FirstClass RAD requires that:
• all forms be Database Query forms, with IDs in the 8000-8899 range OR 8999 or Database HitList forms, with IDs in the 10000-10999 range
• form IDs be unique and unchanging (once you add a form to a project, you cannot change its ID)
• all field IDs on the forms be 1000 and higher.
For details on using FirstClass Designer, see FirstClass 6 Designer.
3 Use FirstClass RAD Project Manager to create a project for this application. For details, see Creating projects.
4 Set project attributes.
For details, see Setting project attributes.
5 If this is a database application, connect to the database. For details, see Adding database connections.
6 Add your forms to the project. For details, see Adding forms to projects.
7 Set the forms' attributes. For details, see Setting form attributes.
8 Set the fields' attributes for each form. For details, see Setting field attributes.
9 Program the project. For details, see Programming projects.
10 Test the project. For details, see Testing projects.
11 Build the application. For details, see Building applications.
12 Install the application in FirstClass. For details, see Installing applications.
FirstClass RAD projects
A FirstClass RAD application is created as a project which consists of:
• forms
• code modules
• database objects (if the application is connecting to a database).
To work with a FirstClass RAD project, you use the FirstClass RAD Project Manager. This application provides access to:
• information about the project as a whole
• information about the forms in the project
For applications that connect to databases:
• database connection information
• information about the database tables to use.
The FirstClass RAD Project Manager also lets you run your application for testing purposes, without having to rebuild and reinstall every time you want to test.
Creating projects
1 Connect, as an administrator, to the server where FirstClass RAD is installed.
Use the settings file that contains the resources needed for this project.
2 Start FirstClass RAD.
3 Click New on the FirstClass RAD Project Manager's Project tab.
4 Type the project name (maximum 23 characters, no spaces).
5 Click OK.
Setting project attributes
Project attributes apply to the project as a whole. To set these attributes:
1 Click Options on the FirstClass RAD Project Manager's Project tab.
2 Fill in the fields on the General, Client, and Server tabs.
3 Click OK.
Adding forms to projects
To add a form to a project:
1 Click New on the FirstClass RAD Project Manager's Form tab.
2 Choose the form.
3 Click OK.
The form opens.
Removing forms from projects
When you remove a form from a FirstClass RAD project, all of the configuration and code that was assigned to the form is also removed. You cannot undo this operation.
To remove a form from a project:
1 Select the form on the FirstClass RAD Project Manager's Form tab.
2 Click Remove.
Setting form attributes
Form attributes (the form's name, title, and tables for bound columns databases) apply to the form as a whole, rather than to individual fields on the form.
To set form attributes:
1 Select the form on the FirstClass RAD Project Manager's Form tab.
2 Click Modify.
Note
If you have just added the form, the form and its Attributes window open automatically.
3 Fill in the fields on the Attributes' Form tab.
4 To save your changes to a field, press Tab.
5 If fields will be bound to one or more database tables,
• Click Add.
• Choose a table at "Select a table", then click OK.
Removing tables from forms:
To remove a table from the form, select it, then click Remove.
Setting field attributes
Field attributes apply to the individual fields on a form.
To set the attributes (name and table/column for bound columns databases) for a field:
1 Select the form on the FirstClass RAD Project Manager's Form tab.
2 Click Modify.
Note
If you have just added the form, the form and its Attributes window open automatically.
3 Click the field.
4 Fill in the fields on the Attributes Field tab.
5 If this field will be bound to a database table,
choose the appropriate table at "Table".
6 Choose the appropriate column from this table at
"Column".
Programming projects
Programming a FirstClass RAD project involves:
• adding code that is used throughout the project
• adding code for forms
• adding code for fields
Opening projects
To open a project:
1 Click Open on the FirstClass RAD Project Manager's Project tab.
2 Select the project.
3 Click OK.
Adding code for projects
A FirstClass RAD project often contains code that is global (that is, it is called from multiple forms, multiple fields on a form, or anywhere in the project). This code can take the form of:
Subroutines
Code that performs particular steps. Instead of repeating the code for a step wherever it is needed, you can call the subroutine.
Declarations
A variable, constant, or user-defined type used when programming applications.
Variables
A placeholder in your code for particular values, such as values that users have entered. You must declare a variable before you can use it.
Constants
Similar to variables, except the value of a constant cannot be changed.
User-defined data types
Combinations of related variables into single data structures.
Global code is best stored in a code module. This lets you write the code once, instead of multiple times, and any changes to this code are automatically reflected everywhere the code is called.
By default, a project has one code module, called Module1. This module contains a Declarations section and a Main subroutine which is the entry point for your application. The application begins execution with the first line of code you add to the Main subroutine. You can add more code modules as needed for organizational purposes.
Adding code for fields
To add code that applies to a specific field on a form:
1 Select the form on the FirstClass RAD Project Manager's Form tab.
2 Click Modify to open the form and its attributes.
3 Click the field, then click Edit Code on the Attributes' Field tab.
Shortcut
Double-click the field.
4 Choose the event procedure that you want to program at "Event".
5 Update the code as required.
6 To save your changes, press Tab before closing the code window.
Note
You can choose additional event procedures to program for this field, and choose additional fields to program at "Object".
Adding code for forms
To add code that applies to a specific form:
1 Select the form on the FirstClass RAD Project Manager's Form tab.
2 Click Modify to open the form and its attributes.
3 Click the form body, then click Edit Code on the Attributes Form tab.
Shortcut:
Double-click the form body.
4 Choose the event procedure that you want to program at "Event".
5 Update the code as required.
6 To save your changes, press Tab before closing the code window.
Adding code modules
To add a code module:
1 Click New on the FirstClass RAD Project Manager's Module tab.
2 Type the module name (maximum 23 characters, no spaces).
3 Click OK.
The module window opens.
Removing code modules
When you remove a code module from a FirstClass RAD project, all of the subroutines and declarations within it are also removed. You cannot undo this operation.
To remove a code module from a project:
1 Select the module on the FirstClass RAD Project Manager's Module tab.
2 Click Remove.
Updating code modules
To add, edit, or delete code in a code module:
1 Select the module on the FirstClass RAD Project Manager's Module tab.
2 Click Modify.
3 Update the code as required.
4 To save your changes, press Tab before closing the code window.
Updating declarations
To add, update, or remove delcarations in a code module:
1 Open the window for this code module.
2 Choose Declarations at "Subroutine".
3 Update the code as required.
4 To save your changes, press Tab before closing the code window.
Adding subroutines
To add a subroutine to a code module:
1 Open the window for this code module.
2 Click New Subroutine (blank icon in upper right-hand corner)
3 Name your subroutine, then click OK.
Removing subroutines
When you remove a subroutine from a code module, all of the code within it is also removed. You cannot undo this operation.
To remove a subroutine from a code module:
1 Open the window for this code module.
2 Choose the subroutine at "Subroutine".
3 Click Delete Subroutine (icon with an "X" on it, in the
right-hand corner).
Updating subroutines
To add, edit, or delete code in a subroutine:
1 Open the window for the appropriate code module.
2 Choose the subroutine at "Subroutine".
3 Update the code as required.
4 To save your changes, press Tab before closing the code window.
Testing applications
You can run your application within FirstClass RAD before it is built, to check for errors. This avoids the need to continually rebuild and reinstall applications in order to test them. You can run the application at various stages of development (for example, after you have added all your forms), and it will respond based on the amount of code you have written for it at that time.
1 To test your project, click Run on the FirstClass RAD Project Manager's Project tab.
2 If an error message appears, click OK and check the code in your code module.
3 To stop testing, click Stop.
Building applications
After your project has been fully developed and tested, you can build the application from it. To do this:
1 Click Build on the FirstClass RAD Project Manager's Project tab.
2 The compiled application file (FCX) is added to the \FCPO\RAD folder. This file contains everything needed to run the application after it has been installed in FirstClass.
Note
If you built this application previously, the new FCX file will overwrite the old one.
3 Restart the server to load the FCX file.
Installing applications in FirstClass
After you have built your FirstClass RAD application, you need to install it in FirstClass so others can use it. Installation may involve two steps:
1 only required for applications that will be launched from an icon,
Creating stationery for the application
2 Distributing the resources (forms, icons, and so on) used by your application.
For details on how to distribute resources, see FirstClass Designer.
Creating application stationery
To create stationery so that users can launch your application from an icon:
1 Log in as an administrator, using your FirstClass RAD project's settings file.
2 Open the conference where you want the application icon.
3 Choose Admin > New Stationery > RAD Install Form.
4 Fill in the RAD Install Form fields, then click OK.
5 Choose File > Properties (Windows) or Get Info (Mac OS) with the stationery selected.
6 Uncheck the Protected check box.
7 Name the stationery and choose the icon you want.
8 Close the window and save your changes.
9 Open the Properties window again, and check the Protected check box.
10 Close the Info window and save your changes.
Note
You can install multiple instances of this application by opening other conferences and following the steps above.
The Language reference describes the commands, methods, attributes, and so on, that you can include in your BASIC code for FirstClass RAD applications. For examples of these objects in use, see the Examples file on your FirstClass RAD CD.
BASIC commands
Beep
Use the Beep BASIC command to play the FirstClass client's system beep sound.
Note
The FirstClass client cannot play the system beep unless the application has displayed a form.
Syntax
Beep
Examples
Sub Click() Dim i as integer
For i = 1 to 3 'Beep 3 times
Beep Next i
End Sub
Call
Use the Call BASIC command to call a subroutine.
Note
This is an optional command; subroutines can be called directly without using it. You can add arguments (arg1, and so on) to this command.
Syntax
Call subroutine
Call subroutine(arg1, arg2...)
subroutine
Examples
Sub Main()
Call MyStartupSub(StartupString)
Call MyMainProgramSub(1, "John", TRUE)
Call MyEndSub
End Sub
Console
Use the Console BASIC command to display output (printexpressions) on the server console.
Note
This command is identical to the Print command, except that output is directed to the server console instead of the FirstClass client's output window.
If you also want to write output to the server's log file, use the Report command.
Syntax
Console [printexpression,printexpression]
Console [printexpression,printexpression]
For an explanation of this syntax, see the Print command.
Examples
Console "Welcome to my application"
Console "Hello"; FCUserName
Console "the value of 'i' is";i
Const
Use the Const BASIC command to declare a user-defined constant.
Note
You can assign any type of expression to the constant. You can also specify a data type. If you do not specify a data type, the data type of the assigned expression is used.
Syntax
Const constname = expression
Const constname As datatype = expression
Example
Sub Main()
Const MYSTRING = "Hello world"
End Sub
CopyFile
Use the CopyFile BASIC command to copy a file on the FirstClass server from one location to another.
Note
The CopyFile command uses the host operating system to issue a copy from one location to another. The third parameter determines whether or not the copy will overwrite an existing file.
Syntax
CopyFile(FromPath, ToPath, TRUE/FALSE)
Example
CopyFile ("C:\FCSERVER\FCS.OLD","C:\FCSERVER\FCS2.OLD",FALSE)
Debug
Use the Debug BASIC command to print text to the console window only when the program is run from the development environment.
Note
The Debug command acts exactly like the Print keyword except that it will not be executed when the built application is run, but will only be activated when run from the development environment. This is useful to prevent debugging information from showing up to the user when you build and release the application.
Syntax
Debug StringToSend
Example
Sub Main()
Print "This string will always be printed"
Debug "This string only shows up when run from the development environment"
End Sub
Dim
Use the Dim BASIC command to declare a variable and allocate storage memory.
Note
The variable name (varname) can be any valid alphanumeric string, as long as it does not begin with a decimal number (0-9) or an underscore (_). Underscores and decimal numbers are allowed in any other location in the variable name.
You must specify the variable type (vartype). Valid types are Integer, Long, Single, Double, Date, Currency, String, and user-defined types.
You can create arrays (array...bound) of variables of up to 61 dimensions, with no more than 1,000,000 elements. You can also declare a string variable of a fixed length (length). The length argument can be any valid number that indicates the maximum length of the string.
Syntax
Dim varname As vartype
Dim varname(arrayupperbound) As vartype
Dim varname(arraylowerbound To arrayupperbound) As vartype
Dim varname As String * length
Dim varname1 As vartype, varname2 As vartype...
Examples
Dim i As Integer
Dim MyArray(10) As Integer 'declare an integer array of 10 elements (0-9)
Dim MyArray(0 To 9, 0 To 9) As Double 'declare a two-dimensional array
Dim str2 As String * 100 'declare a fixed-length string of 100 characters
Do...Loop
Use the Do...Loop BASIC command to execute a group of subcommands while a conditional expression is TRUE or until a conditional expression evaluates to TRUE.
Note
When a loop reaches its last subcommand, the conditions (condition) of the loop are re-evaluated. The loop then either iterates or processing continues at the first line after the loop. There are four types of Do...Loops (Do While...Loop, Do Until...Loop, Do...Loop While, Do...Loop Until). Each serves a different purpose. The main difference between the two While and Until loops is in the location of the condition. Do...Loop...condition commands always execute the subcommands at least once, even if the condition indicates that the loop should not iterate. Do While/Until condition...Loop commands only execute the subcommands if the condition indicates that the loop should iterate. Loops using While iterate while the condition is TRUE. Loops using Until iterate until the condition evaluates to TRUE.
Syntax
Do While condition commands...Loop
Do Until condition commands...Loop
Do commands...Loop While condition
Do commands...Loop Until condition
Examples
Do While Score < 10
Print Score
Loop
Do
Print Score
Loop Until Score > 10
DoEvents
Use the DoEvents BASIC command to interrupt a currently running subroutine to process pending user input.
Note
DoEvents allows applications to be developed which can respond to user input while the application loops and monitors data or updates values on the form.
Syntax
DoEvents (starttime, endtime)
Example
Sub Click ()
Dim StartTime as integer,
LastTime as integer
Dim IconNumber as integer
Randomize
StartTime = Timer
Do While (Timer < StartTime + 60)
'run loop for 60 seconds
If Timer > LastTime + 1 Then
'every second, run this code
IconNumber = Int ( (9 * Rnd) +1)
'Generate 1 of 9 random icons
DisplayIcon(IconNumber)
End If
Do Events '**Call DoEvents to process pending input**
Loop
End Sub
End
Use the End BASIC command to end a structure or procedure.
Note
This command is required to end Sub, Function, Select, and Type structures. It is also required to end If structures unless the If command is all on one line. An End command used by itself stops execution of the application.
Syntax
End
End Sub
End Function
End If
End Select
End Type
Example
If StartupString = "Box" Then
Print "Take the box to the curb"
End
End If
Erase
Use the Erase BASIC command to clear and reinitialize the values of an array.
Note
All elements of a numeric array are set to zero. All elements of a string array are set to empty strings (''''). Arrays of date values are set to day zero. If the array is of a user-defined type, each member of the type is treated as its own separate variable and is erased in accordance with its type.
Syntax
Erase array
Erase array1, array2...
Example
Sub Main()
Dim MyArray(1 to 10) As Integer
Dim I As Integer
Print "Assigning and Printing My Array"
For I = 1 to 10
MyArray(i)=i
Print MyArray(i)
Next i
Erase MyArray 'All values from array MyArray are now zero
Print "MyArray has been erased and now contains:"
For i = 1 to 10 'Prints all zeros
Print MyArray(i)
Next i
End Sub
Exit
Use the Exit BASIC command to end a procedure or loop structure.
Note
In the case of a procedure, processing moves to the line after the procedure call. In the case of a loop structure, processing moves to the line following the loop.
Syntax
Exit
Exit Sub
Exit Function
Exit Loop
Exit For
Examples
See code example for the For...Next BASIC command.
For...Next
Use the For...Next BASIC command to execute a group of commands for each increment of a counter.
Note
Each time a For...Next loop is iterated, the counter is incremented. You specify start and end values to indicate the initial and final values of the loop counter. The default increment is 1; however, you can specify a different increment by adding the Step keyword. The increment can be any valid number. If the increment is negative, the counter will count backwards from start to end. This is the only case where start is greater than end. You can also stop loop processing prematurely if a condition is met by using the Exit BASIC command.
Syntax
For counter = start To end
subcommands
Next
For counter = start To end
commands
Next counter
For counter = start To end Step increment
subcommands
Next
For counter = start To end
subcommands
condition
Exit For
subcommands
Next
Example
Dim I As Integer
For i = 1 to 10
If i > 5 Then
Exit For 'This will break the loop prematurely.'
End If
Print "Counting:", i
Next i
Next i
Function
Use the Function BASIC command to declare a procedure as a function capable of returning a value when it is called.
Note
The name of the function is treated as a variable from within the function and the value will be returned when the function returns. Functions can be of any type and can call other procedures and internal functions to process the result.
Syntax
Function FunctionName(ParameterToFunction As DataType) as Data Type
Example
Function MultiplyByTen(X as Integer)
as Integer
MultiplyByTen=MultiplyByTen*10
End Function
Sub Main
Print"Eight times ten is "& MultiplyByTen(8)
End Sub
GiveTime
Use the GiveTime BASIC command to suspend application processing and allow the server to re-enter.
Note
All applications are given about the same amount of processing time. If an application knows that it does not need all of its allotted time, it can use GiveTime to give up the remainder of its time to other server processes and applications. All database and field operations, and some commands, initiate their own server re-entrance. In these cases, there is no need to call the Givetime command.
This is a useful command for applications that are sometimes idle (for example, polling at set times).
Syntax
GiveTime
Example
starttime = Timer
Do While TRUE
If Timer < starttime + 5 Then
Give Time
Else
Print "5 seconds have elapsed..."
starttime = Timer
End If
Loop
Gosub...Return
Use the Gosub...Return BASIC command to jump to a procedure's labeled subroutine, then return to the line following Gosub.
Note
We do not recommend use of this command; it is only included for backward compatibility. Instead, use subroutines to handle frequently processed routines.
Processing jumps to the line that starts with the label. The label can be either a line number (consisting of the numbers 0-9) or an alphanumeric string (as long as it does not start with a number).
The label must be:
the first non-blank characters on the line followed by a colon (:).
Syntax
Gosub label
...
Return
Example
Dim I As Integer
For I = 1 to 10
Gosub MySubroutine
Goto MyEnd
Goto
Use the Goto BASIC command to jump to a label.
Note
Processing jumps to the line that starts with the label. The label can be either a line number (consisting of the numbers 0-9) or an alphanumeric string (as long as it does not start with a number). The label must be: the first non-blank characters on the line followed by a colon (:).
Syntax
Goto label
Example
Dim num As Integer
num = 5
Goto 20
Print "This will not get printed"
20 If num = 5 then
Goto numis5
If...Then
Use the If...Then BASIC command to branch processing based on a condition.
Note
This command requires a condition that must be TRUE or FALSE. Any numeric condition that is not TRUE is considered to be FALSE. When the condition is TRUE, the commands following this statement are executed, then processing continues on the line following End If.
You can include any number of ElseIf...Then clauses with a block If...Then structure to specify additional conditions.
Syntax
If condition Then command1 Else command2
If condition Then
commands
End If
If condition1 Then
commands
ElseIf condition2 Then
commands
Else
commands
End If
Example
If FCUserid = "guest" Then
Print "Welcome Guest User"
ElseIf FCUserid = "admin" Then
Print "Welcome Administrator"
Else
Print "Welcome"
'user is neither a guest nor administrator
End If
Let
Use the Let BASIC command to precede a variable assignment.
Note
The Let command assigns values to variables. It is optional in the BASIC language.
Syntax
Let VariableName = Value
Example
Let X=1
X=1
Load
Use the Load BASIC command to load a form's fields and data environment.
Note
This command makes a form's field and data resources available to the application, but does not make the form visible. To display a form, you must use the Show form method.
Syntax
Load formname
Example
Sub Main()
Load MyForm
If MyForm.MyTable.Column(1) = TRUE Then
MyForm.Title = "My Form's Title"
MyForm.Show
End If
End Sub
MsgBox
Use the MsgBox BASIC command to display a modal message box.
Note
Because this is a modal message box, processing for this application is suspended until the user responds by clicking a button in the message box. At that time, processing continues with the line following the MsgBox command. The MsgBox Response function tells the application which button the user clicked. MsgBox strings are now truncated at 509 characters.
You specify the string to appear in the message box (msgboxstring). You can also add a title to the message box (msgboxtitle), and can specify which buttons you want in the message box (msgboxbuttons). Valid values for msgboxbuttons are:
• OK button only, fcOKOnly
• OK and Cancel buttons, fcOKCancel
• Yes and No buttons, fcYesNo
• Yes, No, and Cancel buttons, fcYesNoCancel.
If you do not specify a title, none appears. If you do not specify message box buttons, just the OK button appears.
Syntax
MsgBox("msgboxstring")
MsgBox("msgboxstring", msgboxbuttons)
MsgBox("msgboxstring", msgboxbuttons, "msgboxtitle")
Example
MsgBox ("Would you like to save changes?", FCYesNoCancel, "Save")
On Error
Use the On Error BASIC command to enable or disable error handling.
Note
This command is used with the following commands:
Goto label
Processing jumps to the line that starts with the label if a critical error occurs. The label can be either a line number (consisting of the numbers 0-9) or an alphanumeric string (as long as it does not start with a number). The label must be:
the first non-blank characters on the line followed by a colon (:).
Resume
The application will try to re-execute the line that caused the error until it executes successfully. Be careful about using this command, because the application could loop on this line indefinitely.
Resume Next
Processing resumes with the line after the line that caused the error, including critical errors. Any lines that cause errors are skipped, and processing does not stop for critical errors.
Goto 0
Turns off error handling from this point on.
Syntax
On Error Goto label
On Error Resume
On Error Resume Next
On Error Goto 0
Example
Sub Main()
Dim i As Integer
On Error Goto ErrHandler
i=1/0 'division by zero error
Print "Error handling has resumed execution here"
Exit Sub
Option
Use the Option BASIC command to set BASIC interpreter options for this application.
Note
Currently, you can only set one option: Base. This option indicates the default index for the first element of arrays with default lower bounds declared with Dim. The index can be 0 (the default) or 1. Option Base must be called from the Declarations procedure of a code module, and can only be called once per application.
Syntax
Option Base index
Examples
Option Base 0
...
Dim MyArray(10) As Integer 'creates a 10-element array indexed from 0 to 9
Option Base 1
...
Dim MyArray(10) As Integer 'creates a 10-element array indexed from 1 to 10
PlaySound
Use the PlaySound BASIC command to play a FirstClass client sound resource.
Note
You must specify the resource ID of the FirstClass sound resource.
Syntax
PlaySound(ResourceID)
Print
Use the Print BASIC command to display output (printexpressions) to the FirstClass client's output window.
Note
One Print command can output any number of expressions. To specify a string as an expression, enclose it in double quotes ("string"). You can use the following characters with this command:
• , between expressions
Causes each expression to appear in the print zone following the previous expression. Print zones are located every 14 characters.
• ; between expressions
Causes each expression to appear immediately after the previous expression.
• , or; at end of line
Suppresses the carriage return that is normally output at the end of the output for each Print command line. Any subsequent Print command output will appear on the same line.
A print Command without a printexpression outputs a carriage return.
Syntax
Print
Print printexpression
Print printexpression, printexpression
Print printexpression; printexpression
Print,
Print;
Examples
Print "Welcome to my application"
Print 1, 2, 3, 4, 5 'prints each number in a separate print zone
Print "These two lines are ";
Print "output as one."
Randomize
Use the Randomize BASIC command to initialize the random number generator.
Note
If you do not use this command, the Rnd function will return the same list of random numbers every time it is run.
You can specify the numeric key from which to generate the random number list by using the seed argument. If you use the same value for seed each time a program is run, the same list of random numbers will be generated. If you do not include the seed argument, Randomize generates the random number list using the Timer function.
Syntax
Randomize [seed]
Examples
Dim i As Integer
Randomize
Print "Generating 5 random numbers"
For i = 1 to 25
ReDim
Use the ReDim BASIC command to change the number of elements in an array.
Note
Using this command on an existing array will replace the old array dimension with the new one.
To keep existing values in an array, include the Preserve keyword. If you do not include this keyword, the array is erased as if the Erase command had been used on it.
Syntax
ReDim varname As vartype
ReDim Preserve varname As vartype
ReDim varname (arrayupperbound) As vartype
ReDim varname (arraylowerbound To arrayupperbound) As vartype
ReDim varname1 As vartype, varname2 As vartype...
For an explanation of this syntax, see Dim.
Example
ReDim Preserve MyArray (MAXVAL+1) As Integer
Rem
Use the Rem BASIC command to comment out a line of text. The entire line is ignored.
Syntax
Rem comment
'comment
Examples
Rem This is a comment
' This is another comment
Report
Use the Report BASIC command to write output (printexpressions) to the server's log file.
Note
This command is identical to the Print command, except that output is directed to the log file and server console instead of the FirstClass client's output window.
If you just want to display output on the server console, use the Console command.
Syntax
Report
Report printexpression
Report printexpression, printexpression
Report printexpression; printexpression
Report,
Report;
For an explanation of this syntax, see the Print command.
Example
Report "Application began at:"; Now
RunApp
Use the RunApp BASIC command to run a built and loaded application in a new application environment space.
Note
You specify the application name (appname) with this command. You can also specify any valid string expression as a startup string (startupstring). This string is passed to the launched application as the StartupString value in the launched application.
Syntax
RunApp("appname")
RunApp("appname", "startupstring")
Examples
RunApp("Calc") 'Launches the Calc application
RunApp("Order", "buy12") 'Launches the Order application with the startup string "buy 12"'
Select Case
Use the Select Case BASIC command to build an expression- based conditional branching of programmatic flow.
Note
The Select Case selection structure provides a simplified method for comparing an expression or conditional command to a series of possible expressions or 'cases'.
If the Case is TRUE, the commands following the case are executed. Each case in the selection structure is executed accordingly. Each Select Case selection structure must end with the keywords End Select.
Is and To keywords provide a method for making comparisons within a Case command. Is allows you to use comparison operators while the To keyword allows you to compare and test a range of values for an expression.
Syntax
Select Case testexpression
[Case [Is | # To # ] expressionlist [commands]]
[Case Else] [commands]]
End Select
Sleep
Use the Sleep BASIC command to halt execution of the program until a specified time has elapsed.
Note
The parameter can either be Integer, in which case it specifies the number of seconds to sleep before continuing, or Date, in which case the program will not continue until the specified time and date are reached.
The program can still be unloaded from the server or stopped by closing the form in the case of a stationery-launched application. The Sleep command is of particular use in server applications, where you don't want to consume large amounts of server CPU calling the program, but want to execute some code on an occasional basis.
Syntax
Sleep(SecondOrDate)
Example
Print "This program will self-destruct in five seconds!"
Sleep (5)
End
Sort
Use the Sort BASIC command to sort a one dimensional array into ascending or descending order.
Note
Using the optional fcAscending and fcDescending parameters, the Sort command can sort arrays of type Integer, Long, Date, String, Single, Double, or Currency, in any order.
Syntax
Sort(Array)
Sub
Use the Sub BASIC command to declare the name and arguments for a sub procedure.
Note
The argument name may be any string that is a valid BASIC identifier and may not begin with underscore characters or decimal digits (0-9). A Sub may receive any number of arguments. The Sub argument arg can be any valid BASIC identifier and be of any type. If the keyword ByRef is used, the argument is passed by reference. If the keyword ByVal is used, the argument is passed by value. If no keyword is specified, the default behavior for arguments is passed by value.
Syntax
Sub name ([ByRef | ByVal] [arg1],[ByRef | ByVal] arg2]...)
Example
Sub DisplayMyUserInfo()
Print "My UserID is "; FCUserID
End sub
Type
Use the Type BASIC command to declare a user defined type.
Note
User-defined data types help organize data by making it possible to combine several related variables into a single data structure.
If a user-defined type is defined in the Declarations section of a code module, the type will be visible to the entire application and will remain for the lifetime of the application. If defined in a procedure, the type is only visible to the procedure and will remain only for the lifetime of the procedure.
Syntax
Type typename
varname As datatype
[varname As datatype...]
End Type
Example
Type CustType 'defined in Declarations
First as String
Last as String
SSNum as String *9
CustomerID as Integer
End Type
Unload
Use the Unload BASIC command to close a form and shut down its data environment.
Note
The Unload command closes the form indicated by the string expression formname. Upon closing, the form runs its Unload event procedure and shuts down the open tables in its data environment.
Syntax
Unload formname
Example
Sub Click()
Unload MyForm
End Sub
While...Wend
Use the While...Wend BASIC command to execute a group of commands while a conditional expression evaluates to TRUE.
Note
The While...Wend loop structure is similar to the Do...Loop structure, but has less flexibility. The While...Wend structure is included for backward compatibility reasons.
Syntax
While condition
commands
Wend
BASIC operators
&
Use the & BASIC operator to concatenate two strings (s1 and s2).
String concatenation adds the second string to the end of the first and returns this as a result string.
Syntax
s1 & s2
Example
Sub Main()
Dim s1 as String, s2 as String, result as String
s1 = "Hello" : s2 = "world"
result = s1 & s2
Print result 'result is assigned 'Hello world'
Print result 'prints Hello world
End Sub
*
Use the * BASIC operator to multiply two numbers (n1 and n2).
Note
n1 and n2 may be any valid numeric expression.
Syntax
n1 * n2
Example
Sub Main()
Print "10 times 4 is:", 10 * 4
End Sub
+
Use the + BASIC operator to add two numbers (n1 and n2) or concatenate two strings (although we recommend & for concatenation).
Note
n1 and n2 may be any valid numeric expressions.
Syntax
n1 + n2
Example
Sub Main()
Print "The sum of 10 and 4 is:", 10 + 4
End Sub
-
Use the - BASIC operator to subtract two numbers (n1 and n2) or to negate the value of a number (n).
Subtraction
Syntax
n1 - n2
Example
Sub Main()
Print "10 minus 4 is:", 10 - 4
End Sub
Negation
Syntax
-n
Examples
Sub Main()
Print "negated 99 is:", -99
Print "negated -99 is:", -(-99)
End Sub
/
Use the / BASIC operator to divide two numbers (n1 and n2), when you want the result expressed as a floating point value.
Note
n1 and n2 may be any valid numeric expression.
Syntax
n1 / n2
Example
Sub Main()
Print"10 divided by 4 is: ", 10/4 'prints 2.5
End Sub
<
Use the < (less than) BASIC operator to compare the values of two expressions (e1 and e2) of the same or similar types. If e1 is less than e2, TRUE is returned; otherwise, FALSE is returned.
Syntax
e1 < e2
Example
If num < 5 Then
Print "The value of 'num' is less than 5"
<=
Use the <= (less than or equal to) BASIC operator to compare the values of two expressions (e1 and e2) of the same or similar types. If e1 is less than or equal to e2, TRUE is returned; otherwise, FALSE is returned.
Syntax
e1 <= e2
Example
If num <= 5 Then
Print "The value of 'num' is less than or equal to 5"
<>
Use the <> (not equal) BASIC operator to compare the values of two expressions (e1 and e2) of the same or similar types. If the values are different, TRUE is returned; otherwise, FALSE is returned.
Syntax
e1 <> e2
Example
Sub Main()
Dim num as Integer
num = 5
If num <> 5 Then
Print "The value of 'num' is not equal to 5"
Else
Print "The value of 'num' is equal to 5"
End If
End Sub
=
Use the = (equal to) BASIC operator to compare the values of two expressions (e1 and e2) of the same or similar types. If the values are the same, TRUE is returned; otherwise, FALSE is returned.
Syntax
e1 = e2
Example
Sub Main()
Dim num as Integer
num = 5
If num = 5 Then
Print "The value of 'num' is equal to 5"
>
Use the > (greater than) BASIC operator to compare the values of two expressions (e1 and e2) of the same or similar types. If e1 is greater than e2, TRUE is returned; otherwise, FALSE is returned.
Syntax
e1 > e2
Example
Sub Main()
Dim num as Integer
num = 5
If num > 5 Then
Print "The value of 'num' is greater than 5"
Else
Print "The value of 'num' is less than or equal to 5"
End If
End Sub
>=
Use >= (greater than or equal to) BASIC operator to compare the values of two expressions (e1 and e2) of the same or similar types. If e1 is greater than or equal to e2, TRUE is returned; otherwise, FALSE is returned.
Syntax
e1>= e2
Example
If num >= 5 Then
Print "The value of 'num' is greater than or equal to 5"
AND
Use the AND BASIC operator to evaluate whether two expressions (e1 and e2) are TRUE. Both expressions must be TRUE for the AND result to be TRUE.
Syntax
e1 AND e2
Example
Sub Main()
Dim e1 as Integer, e2 as Integer e1 = TRUE: e2 = 5< 34
If e1 AND e2 Then
Print "Both expressions are TRUE"
Else
Print "Both expressions are not TRUE"
End If
End Sub
MOD
Use the MOD BASIC operator to return the remainder from the division of two numbers (n1 and n2), expressed as an integer.
Note
n1 and n2 may be any valid numeric expression.
Syntax
n1 MOD n2
Example
Sub Main()
Print "The remainder from 10 divided by 4 is:", 10 MOD 4
'prints 2
End Sub
NOT
Use the NOT BASIC operator to evaluate whether an expression (e) is FALSE.
Syntax
NOT e
Example
Sub Main()
Dim e1 as Integer
e1 = TRUE
If NOT e Then
Print "Expression 'e' was FALSE"
'NOT TRUE=FALSE
Else
Print "Expression 'e' was TRUE"
End If
End Sub
OR
Use the OR BASIC operator to evaluate whether one or both of two expressions (e1 and e2) are TRUE. Only one of the expressions needs to be TRUE for the OR result to be TRUE.
Syntax
e1 OR e2
Example
Sub Main()
Dim e1 as Integer, e2 as Integer
e1 = TRUE : e2 = 5 < 34
If e1 OR e2 Then
Print "Either one or both expressions are TRUE"
Else
Print "Both e1 and e2 do not evaluate to TRUE"
End If
End Sub
XOR
Use the XOR (exclusive OR) BASIC operator to evaluate whether only one of two expressions (e1 and e2) is TRUE. One expression must be TRUE and the other must be FALSE for the XOR result to be TRUE.
Syntax
e1 XOR e2
Example
Sub Main()
Dim e1 as Integr, e2 as Integer
e1 = TRUE: e2 = 5<34
If e1 XOR e2 Then
Print "Only one expression, e1 or e2, is TRUE"
Else
Print "Both e1 and e2 are TRUE or Both e1 and e2 are FALSE"
End If
End Sub
^
Use the ^ BASIC operator to raise a number (n1) to the power of a second number (n2). For example, raising a number to the power of 2 gives the square of the number.
Syntax
n1^n2
Example
Sub Main()
Print "10 squared is:", 10^2
Print "4 cubed is:", 4^3
Print "6.4 to the power of 1.5 is ", 6.4^1.5
End Sub
\
Use the \ BASIC operator to divide two numbers (n1 and n2) when you want the result expressed as an integer without the remainder.
Note
n1 and n2 may be any valid numeric expression. The dividend will be truncated and the result will be expressed as an integer value without remainder.
Syntax
n1\n2
Example
Sub Main()
Print "10 divided by 4 is:", 10\4 'prints 2
End Sub
BASIC variables
Currency
Use the Currency BASIC variable type for variables that contain monetary data.
Acceptable values
-922337203685477.5808 to 922337203685477.5807
Note
This data type uses a fixed decimal point and supports up to 15 digits to the left of the decimal and 4 digits to the right.
This is a superior data type for monetary calculations because the Single and Double data types are subject to small rounding errors.
Date
Use the Date BASIC variable type for variables that contain date data in a valid date format such as 1/1/2000 or January 1, 2000, as well as time data.
Acceptable values
January 1, 100 to December 31, 9999
Note
You can also use numeric data types for dates. If you do this, values to the left of the decimal represent the days from December 30, 1899. Values to the right of the decimal represent time as a fraction of a day (for example, 12:00pm is represented as .5).
DBConnection
Use the DBConnection BASIC variable type to create a database connection object.
Note
DBConnection has its own set of attributes and methods.
DBStatement
Use the DBStatement BASIC variable type to create a database statement object.
Note
DBStatement has its own set of attributes and methods.
Double
Use the Double BASIC variable type for variables that can contain any numeric value, including fractions and numbers of high decimal precision.
Acceptable values
-1.79769313486231E308 to 1.79769313486231E308
Note
This data type is less efficient than the Integer and Long data types, but more flexible.
The Single data type has the same constraints and size limits as Double. You can use these data types interchangeably. FirstClass RAD treats the traditionally smaller Single data type as a Double to support legacy BASIC code.
Email
Use the Email BASIC variable type to create an email object.
Note
Email has its own set of attributes and methods.
File
Use the File BASIC variable type to create a file object.
Note
File has its own set of attributes and methods.
Integer
Use the Integer BASIC variable for integer data types.
Note
See the Long data type for more information.
Range
-2,147,483,648 to 2,147,483,647
Long
Use the Long BASIC variable type for variables that never contain fractions.
Acceptable values
-2,147,483,648 to 2,147,483,647
Note
This data type is smaller and more efficient than numeric data types that can contain fractions.
The integer data type has the same constraints and size limits as Long. You can use these data types interchangeably. FirstClass RAD treats the traditionally smaller Integer data type as a Long to support legacy BASIC code.
String
Use the String BASIC variable type for variables that contain text strings.
Acceptable values
0 to approximately 65,500 characters
Note
By default, string lengths are variable; however, you can enforce a specific length by using a fixed length String variable. Shorter strings are allowed and are not padded. The length limit is only enforced when the string is longer than the limit.
Imposing a fixed length on a String variable:
To make a String variable a fixed length, append an asterisk (*) and a whole number, representing the maximum number of characters, to the String keyword. Strings that are longer than the maximum are truncated.
Example
Dim LastName As String * 7
Single
Use the Single BASIC variable for single data types.
Note
See the Double data type for more information
Range
1.7E +/- 308 (15 digits)
Column attributes
ColNum
Use the ColNum column attribute to retrieve the column's ordinal number in the table.
Note
This attribute is read-only at runtime.
Syntax
tablename.column(columnid).ColNum
Data
Use the Data column attribute to retrieve or assign a column's binary data.
Note
The data attribute is used to retrieve or assign the value of binary data columns. The data attribute contains binary data which, in most instances, may be manipulated as a string.
Syntax
tablename.column(columnid).Data
Datatype
Use the Datatype column attribute to retrieve the column's data type.
Note
Contains a constant integer value indicating the data type of the column.
The Datatype attribute will contain one of the following constants:
• fcString: Character or text data.
• fcInteger: Long integer numeric data.
• fcLong: Long Integer numeric data.
• fcSingle: Double floating point numeric data.
• fcDouble: Double floating point numeric data.
• fcCurrency: Currency data.
• fcDate: Date and Time data.
• fcBinary: Binary data.
This attribute is read-only at runtime.
Syntax
tablename.column(columnid).Datatype
Name
Use the Name column attribute to retrieve the column's database identifier.
Note
This attribute is read-only at runtime.
Syntax
tablename.column(columnid).Name
Nullable
Use the Nullable column attribute to retrieve the column's nullability.
Note
This attribute is read-only at runtime.
Syntax
tablename.column(columnid).Nullable
Precision
Use the Precision column attribute to retrieve the column's precision.
Note
This attribute is read-only at runtime.
Syntax
tablename.column(columnid).Precision
Scale
Use the Scale column attribute to retrieve the column's scale.
Note
This attribute is read-only at runtime.
Syntax
tablename.column(columnid).Scale
Text
Use the Text column attribute to retrieve or assign the column's text.
Note
Contains the text string of the column on the current row. Text may also contain date information. Text and Value are the default attributes for columns.
Syntax
tablename.column(columnid).Text
Value
Use the Value column attribute to retrieve or assign the column's value.
Note
Contains the numeric value of the column on the current row. Value may also contain date information. Text and Value are the default attributes for columns.
Syntax
tablename.column(columnid).Value
Connection attributes
AutoCommit
Use the AutoCommit connection attribute to retrieve or assign the AutoCommit attribute.
Note
Specifies whether to use auto-commit or manual-commit mode. The AutoCommit attribute can be one of the following constants:
• SQL_AUTOCOMMIT_OFF
The connection uses manual-commit mode. The application must explicitly commit or roll back a transaction with the Commit or Rollback methods.
• SQL_AUTOCOMMIT_ON
The driver uses auto-commit mode. Each command is committed immediately after it is executed.
• SQL_AUTOCOMMIT_DEFAULT
Autocommit On.
The default value for this attribute is SQL_AUTOCOMMIT_ON.
Changing from manual-commit mode to auto-commit mode commits any open transactions on the connection.
Syntax
connectionname.AutoCommit [= db Constant]
AccessMode
Use the AccessMode connection attribute to retrieve or assign the AccessMode attribute.
Note
Contains an integer value indicating the ODBC access mode of a connection.
The AccessMode attribute can be one of the following constants:
• SQL_MODE_READ_WRITE
Connections may process any read or write requests submitted.
• SQL_MODE_READ_ONLY
Connections will be instructed not to process requests which are not read-only; the behavior of the data source and ODBC driver which receive such requests is implementation defined.
• SQL_MODE_DEFAULT
Read-write access mode.
The default value for this attribute is SQL_MODE_READ_WRITE.
Syntax
connectionname.AccessMode [= dbConstant]
CurrentQualifier
Use the CurrentQualifier connection attribute to specify the concurrency attribute.
Note
A string containing the SQL command qualifier to be used by the data source. For some databases the qualifier string might indicate a database to access, or in the case of some file-based data sources, a directory where table files are stored. Either can be specified.
Syntax
connectionname.CurrentQualifier [= qualifier]
ODBCCursors
Use the ODBCCursors connection attribute to specify the ODBC cursor manager.
Note
Specifies how the connection uses the ODBC cursor library.
The ODBCCursors connection attribute can be one of the following constants:
• SQL_CUR_USE_IF_NEEDED
The connection uses the ODBC cursor library, only if it is needed. If statement's Move and Find methods are not supported by the ODBC data source, the ODBC driver manager will attempt to emulate them.
• SQL_CUR_USE_ODBC
The connection uses the ODBC cursor library.
• SQL_CUR_USE_DRIVER
The connection uses the cursors and scrolling capabilities of the driver. Statement's Move and Find methods are driven using the data source's cursor model.
• SQL_CUR_USE_DEFAULT
Use driver driven cursors. The default value for this attribute is SQL_CUR_USE_DRIVER.
Syntax
connectionname.ODBCCursors [= dbConstant]
LoginTimout
Use the LoginTimeout connection attribute to retrieve or assign the Login Timeout attribute.
Note
An integer value indicating the number of seconds to wait for a login request to complete. The default is data source driver dependent and is always non-zero.
If LoginTimeout is assigned 0, the timeout is disabled and a connection will wait indefinitely while attempting to login. The LoginTimeout connection attribute may be set to the constant SQL_LOGIN_TIMEOUT_DEFAULT, which specifies the default Login Timeout for the connection.
Syntax
connectionname.LoginTimeout [=logintimeout]
OptTraceFile
Use the OptTraceFile connection attribute to specify the trace file name.
Note
Indicates the name of the ODBC trace file. Filename may be any valid string expression that is a valid file system path.
Syntax
connectionname.OptTraceFile [ = filename]
OptTrace
Use the OptTrace connection attribute to specify the ODBC tracing option.
Note
Specifies an integer value indicating whether the ODBC Driver Manager performs tracing. The OptTrace attribute can be one of the following constants:
• SQL_OPT_TRACE_OFF
Tracing off.
• SQL_OPT_TRACE_ON
Tracing on.
• SQL_OPT_TRACE_DEFAULT
Tracing off.
An application specifies a trace file with the OptTraceFile attribute. If the file already exists, the ODBC Driver Manager appends to the file. If the trace file does not exist, the ODBC Driver Manager creates the file. If no tracing file has been specified, the ODBC Driver Manager writes to the file \SQL.LOG. The default value for this attribute is SQL_OPT_TRACE_OFF, which indicates that no ODBC tracing will occur.
Syntax
connectionname.OptTrace [= dbConstant]
PacketSize
Use the PacketSize connection attribute to specify the network packet size.
Note
An integer value specifying the network packet size in bytes. Many data sources do not support this attribute.
Syntax
connectionname.PacketSize [= size]
TranslateOption
Use the TranslateOption connection attribute to retrieve or assign the translation option for a translation DLL.
Note
Specifies a long integer value that is passed to the translation DLL.
Syntax
connectionname.TranslateOption [= option]
TranslateDLL
Use the TranslateDLL connection attribute to specify a translation DLL.
Note
Indicates the name of the DLL containing ODBC translation functions. DLLname may be any valid string expression that is a valid file system path to the translation DLL file. The translation DLL provides a facility for implementing additional translation functionality, including character set translation.
Syntax
connectionname.TranslateDLL [= DLLname]
QuoteChar
Use the QuoteChar connection attribute to retrieve the data source-specific quote character.
Note
This attribute is read-only at runtime.
Syntax
connectionname.QuoteChar
TxnIsolation
Use the Txnlsolation connection attribute to retrieve or assign the transaction isolation.
Note
Specifies an integer value indicating the ODBC transaction isolation level. The following definitions and behaviors are defined in ODBC.
Dirty Read
Transaction1 modifies a row and Transaction2 reads the modified row before Transaction1 commits the change. If Transaction1 rolls back the change, Transaction2 will have read a row that should have never existed.
Nonrepeatable Read
Transaction1 reads a row and Transaction2 updates or deletes that row and commits this change. If Transaction1 rereads the row, it will receive different values or discover that the row no longer exists.
Phantom
Transaction1 reads a set of rows that satisfy some search criteria. Transaction2 inserts a row that matches the search criteria. If Transaction1 reexecutes the query that reads the rows, it receives a different set of rows.
The Txnlsolation attribute must be one of the following constants:
• SQL_TXN_READ_UNCOMMITTED
Dirty reads, nonrepeatable reads, and phantoms are possible.
• SQL_TXN_READ_COMMITTED
Dirty reads are not possible. Nonrepeatable reads and phantoms are possible.
• SQL_TXN_REPEATABLE_READ
Dirty reads and nonrepeatable reads are not possible. Phantoms are possible.
• SQL_TXN_SERIALIZABLE
Transactions are serializable. Dirty reads, nonrepeatable reads, and phantoms are not possible.
• SQL_TXN_VERSIONING
Transactions are serializable, but higher concurrency is possible than with SQL_TXN_SERIALIZABLE. Dirty reads are not possible.
Syntax
connectionname.Txnlsolation [= dbConstant]
Connection methods
BrowseConnection
Use the BrowseConnection connection method to call against an ODBC driver or data source to determine which arguments are required to connect.
Note
Information is returned in the connections ConnectionString property, and is useful when connecting to an ODBC database for the first time. This same information states what data is required to establish a connection. Most ODBC data sources have a maximum of three arguments (DSN, userid, and password). Oracle and other enterprise databases may require a minimum of four (DSN, userid, password, and connection string).
The normal connection method used in FCRAD is OpenConnection, which takes the three arguments for normal data sources.
Syntax
connectionname.BrowseConnection(string)
Examples
Dim cnct as dbConnection
cnct.BrowseConnection ("DSN=ORACLE") 'Oracle data source
Print cnct.ConnectionString
UID:Login=?,PWD:Password=?;ConnectString: Connection String=?; 'string returned from the driver indicating which parameters are required
REM
'the format of the string returned from the driver indicating which parameters are required is (KEYWORD:DESCRIPTION=VALUE)
CloseConnection
Use the CloseConnection connection method to close a connection.
Syntax
connectionname.CloseConnection
Note
Close a connection on an ODBC data source. All open statements on the connection will automatically be closed.
Example
See the code example for the OpenConnection connection method.
Commit
Use the Commit connection method to commit a transaction.
Syntax
connectionname.Commit
Note
Commits a transaction on a data source. This method is only available to data sources that support transactions. Commit is not a valid operation for connections that have the AutoCommit attribute turned on.
Example
Sub Main()
Dim cnct as DBConnection
cnct.OpenConnection("MyDSN") 'Open the data source "MyDSN"
cnct.AutoCommit = SQL_AUTOCOMMIT_OFF
'Begin the transaction
' Create statements and execute SQL...
' ...
If (UserClickedCancel = TRUE)
cnct.Rollback 'Rollback changes
Else
cnct.Commit 'Commit changes
End if
cnct.CloseConnection 'Close the connection
End Sub
DriverConnection
Use the DriverConnection connection method to establish a data source with the raw ODBC connection information. This is the information returned by BrowseConnection
Note
The current limitation is that if you have built a "bound columns" application (using table and connection FCRAD objects instead of code) with a different database, and you would like to migrate to Oracle, you must do the following things:
• the connection must have its 'establish connections' selection list set to 'manual startup'
• in your Sub Main() you must run something similar to the DriverConnection code example (below) to connect to the database
• the table and column names in the Oracle database must match the names in your previous project or the migration will not work
Syntax
connectionname.DriverConnection(string)
Examples
'the following code can be used in a program to establish a live connection to the ORACLE data source, and allocate statements and run queries against it
Dim cnct As dbConnection
cnct.DriverConnection("DSN=ORACLE;UID=admin;PWD=frisky;ConnectString=MyOracleServerString")
OpenConnection
Use the OpenConnection connection method to open an ODBC data source connection.
Syntax
connectionname.OpenConnection(DSN[,login] [,password])
Note
Opens a connection on an ODBC data source. This method must be run on any DBConnection object prior to opening statements and executing database operations.
The DSN argument accepts any string expression that specifies a valid data source name as configured in the ODBC Data Source Administrator. The optional login and password arguments accept any string expressions that specify the data source login and password respectively.
Example
Sub Main()
Dim cnct As DBConnection
cnct.OpenConnection("MyDSN")
'Open the data source "MyDSN"
' Create statements and execute SQL...
' ...
cnct.CloseConnection
'Close the connection
End Sub
Rollback
Use the Rollback connection method to roll back a transaction.
Syntax
connectionname.Rollback
Note
Rolls back a transaction on a data source. This method is only available to data sources that support transactions. Rollback is not a valid operation for connections that have the AutoCommit attribute turned on.
Example
See code example for the Commit connection method.
Email attributes
Body
Use the Body email attribute to set the Body text for an email message.
Note
String expression may have any text value and is not limited to valid users on the system. String expression may have any text value. This attribute is optional; Body text is not required for an email message to be sent.
Syntax
emailvariable.Body [= string expression]
Examples
Sub Main()
Dim MyMessage As Email
...
MyMessage.Body = "FCRAD demo, you are using too much disk space."
MyMessage.Send
End Sub
From
Use the From email attribute to set the sender's identity for an email message.
Note
String expression may have any text value and is not limited to valid users on the system. This attribute must be set or the email message will not be delivered.
Syntax
emailvariable.From [= string expression]
Examples
Sub Main()
Dim MyMessage As Email
...
MyMessage.From = "Administrator"
MyMessage.Send
End Sub
Subject
Use the Subject email attribute to set the Subject text for an email message.
Note
String expression may have any text value. This attribute is optional; subject text is not required for an email message to be sent.
Syntax
emailvariable.Subject [= string expression]
Examples
Sub Main()
Dim MyMessage As Email
...
MyMessage.Subject = "Too many files..."
MyMessage.Send
End Sub
To
Use the To email attribute to set the recipient user name for an email message.
Note
User name may be any user name or conference as long as the user has 'send' privileges to the recipient. The To attribute supports mailing lists, but does not currently support the use of gateways. If the user name is invalid, the email message will fail. This attribute must be set or the email message will not be delivered.
Syntax
emailvariable.To [= user name]
Examples
Sub Main()
Dim MyMessage As Email
...
MyMessage.To = "FCRAD Demo"
MyMessage.Send
End Sub
Email Methods
Send
Use the Body email attribute to set the Body text for an email message.
Note
String expression may have any text value and is not limited to valid users on the system. String expression may have any text value. This attribute is optional; Body text is not required for an email message to be sent.
Syntax
emailvariable.Body [= string expression]
Examples
Sub Main()
Dim MyMessage As Email
...
MyMessage.Body = "FCRAD demo, you are using too much disk space."
MyMessage.Send
End Sub
Field attributes
Admin
Use the Admin field attribute to retrieve or assign the Admin attribute of a field.
Note
Allows the administrator to view and modify a field that is Hidden or Protected. This attribute has been depreciated. To emulate this functionality, get the user's 'userid' from the FCUserID function and set the Protected and Hidden attributes explicitly.
Syntax
[formname].fieldname.Admin [= TRUE/FALSE value]
Bold
Use the Bold field attribute to retrieve or assign the Bold style attribute of a field.
Note
Displays field text in bold text style.
Syntax
[formname].fieldname.Bold [= TRUE/FALSE value]
Border
Use the Border field attribute to retrieve or assign the Border attribute of a field.
Note
Displays a border around the field. When this attribute is set on a button field, it makes the button the default action for the form. Pressing the <ENTER> key will trigger a Click event for the field.
Syntax
[formname].fieldname.Border [= TRUE/FALSE value]
Bottom
Use the Bottom field attribute to retrieve or assign the Bottom attribute of a field.
Note
Displays field text aligned with the bottom boundary of the field.
Syntax
[formname].fieldname.Bottom [= TRUE/FALSE value]
Caption
Use the Caption field attribute to retrieve or assign the Caption attribute of a field.
Note
Contains the text caption for non-text fields. It is often used to set the text on button field.
Syntax
[formname].fieldname.Caption [=string expression]
Center
Use the Center field attribute to retrieve or assign the Center attribute of a field.
Note
Displays field text centered within the top and bottom boundaries of the field.
Syntax
[formname].fieldname.Center [= TRUE/FALSE value]
Color
Use the Color field attribute to retrieve or assign the Color attribute of a field.
Note
Displays the field text in the default color.
Syntax
[formname].fieldname.Color [= TRUE/FALSE value]
Condense
Use the Condense field attribute to retrieve or assign the Condense attribute of a field.
Note
Displays field text in condensed text style. The condensed text style is not available on the Windows client; it is only available on the Macintosh client.
Syntax
[formname].fieldname.Condense [= TRUE/FALSE value]
CreationDate
Use the CreationDate field attribute to retrieve the file CreationDate attribute of a File Viewer field.
Syntax
[formname].fieldname.CreationDate
Data
Use the Data field attribute to retrieve or assign a field's binary data.
Note
Used in fields such as a Picture or File Viewer. The Data field attribute contains binary data which, in most instances, may be manipulated as a string.
Syntax
[formname].fieldname.Data
DataSize
Use the DataSize field attribute to retrieve the data size attribute of a File Viewer field.
Syntax
[formname].fieldname.DataSize
DataType
Use the DataType field attribute to retrieve the field's data type.
Note
Contains a constant integer value indicating the data type of the field.
The DataType attribute will contain one of the following constants:
FCString
character or text data
FCInteger
long integer numeric data
FCLong
long integer numeric data
FCSingle
double floating point numeric data
FCDouble
double floating point numeric data
FCCurrency
currency data
FCDate
date and time data
This field attribute is read-only at runtime.
Syntax
[formname].fieldname.DataType
Editable
Use the Editable field attribute to retrieve or assign the Editable attribute of a field.
Note
Setting the Editable field attribute allows the user to edit and modify a field's value.
Syntax
[formname].fieldname.Editable [= TRUE/FALSE value]
Extend
Use the Extend field attribute to retrieve or assign the Extend attribute of a field.
Note
Displays field text in extended text style. The extended text style is not available on the Windows client; it is only available on the Macintosh client.
Syntax
[formname].fieldname.Extend [=TRUE/FALSE value]
FileCreator
Use the FileCreator field attribute to retrieve the Macintosh file creator attribute of a File Viewer field.
Syntax
[formname].fieldname.FileCreator
FileFlags
Use the FileFlags field attribute to retrieve the Macintosh file flags attribute of a File Viewer field.
Syntax
[formname].fieldname.FileFlags
Filename
Use the Filename field attribute to retrieve the filename attribute of a File Viewer field.
Syntax
[formname].fieldname.Filename
FileSize
Use the FileSize field attribute to retrieve the file size attribute of a File Viewer field.
Syntax
[formname].fieldname.FileSize
FileType
Use the FileType field attribute to retrieve the Macintosh file type attribute of a File Viewer field.
Syntax
[formname].fieldname.FileType
FullJust
Use the FullJust field attribute to retrieve or assign the FullJust attribute of a field.
Syntax
[formname].fieldname.FullJust [=TRUE | FALSE value]
Grey
Use the Gray field attribute to retrieve or assign the Grey attribute of a field.
Note
Displays field text in grey rather than the default color (black). Use this attribute in conunction with the Protected attribute to indicate editable fields that are currently protected.
Syntax
[formname].fieldname.Grey [=TRUE | FALSE value]
Hidden
Use the Hidden field attribute to retrieve or assign the Hidden attribute of a field.
Note
When this attribute is set, all users are prevented from viewing and manipulating the field. Since the field is unavailable to the user, modifying data, receiving events, and processing event procedures are not possible from the user interface. Field attributes, values, and events may still be accessed from within the code.
Syntax
[formname].fieldname.Hidden [= TRUE/FALSE value]
Icon
Use the Icon field attribute to retrieve or assign the resource ID of the currently displayed icon.
Note
The resource ID must match an icon resource ID that the users have in their settings file, the client itself, or the FirstClass resource registry. Otherwise, nothing will be displayed. Icon changes do not require transfer of data from client to server, so the changes are very quick.
Syntax
[formname].fieldname.Icon [= INTEGER value]
Index
Use the Index field attribute to retrieve or assign the Index attribute of an Expanding Database List or a Fixed List field.
Note
The Index attribute allows the retrieval or assignment of the ordinal number of the currently selected field in a Fixed List or Expanding Database List. The first element in a List is designated as Index 0. When the focus is set to an item in the list, the Index attribute of the list is set to the field's ordinal value.
The Index may also be set by direct assignment to a positive integer value.
Syntax
[formname].fieldname.Index [= numericvalue]
Italic
Use the Italic field attribute to retrieve or assign the Italic style attribute of a field.
Syntax
[formname].fieldname.Italic [= TRUE/FALSE value]
Key
Use the Key field attribute to retrieve or assign the Key attribute of an Expanding Database List or Fixed List field.
Note
The Key attribute allows the developer to store a non-displaying Key value in association with an element in a Fixed List or Expanding Database List.
The Key attribute may be assigned a value of any type, but once assigned at run-time, the data type of the Key attribute for the list cannot be changed.
Syntax
[formname].fieldname.Key [=anyvalue]
List
Use the List field attribute to retrieve or assign the List attribute of a List field.
Note
The List attribute is stored as a semicolon delimited list of strings. If the list is used in an enumerated list field, the values will be automatically assigned to each string in the list. Automatically generated numbers begin with 0 increment for each item in the list.
Numbers can also be assigned to the list items in an enumerated list.
Syntax
[formname].fieldname.List [=string expression]
Examples
Cat;Dog;Fish will be displayed in a list field as three separate strings (one string per list) Cat, Dog, and Fish
Automatically generated numbers:
Cat 'returns 0
Dog 'returns 1
Fish 'returns 2
Assigned numbers:
Cat=100;Dog=23;Fish=7
Cat 'returns 100
Dog 'returns 23
Fish 'returns 7
ListCount
Use the ListCount field attribute to return the current number of items in an expanding or fixed list field.
Syntax
[formname].fieldname.ListCount
For more information, see Fixed lists and expanding lists in the FirstClass Rapid Application Developer guide.
ModificationDate
Use the ModificationDate field attribute to retrieve the modification date attribute of a File Viewer field.
Syntax
[formname].fieldname.ModificationDate
Name
Use the Name field attribute to retrieve or assign the name of the field in question.
Note
Changing the name of a field with the program running can cause unpredictable behavior unless code is carefully written.
Syntax
[formname].fieldname.Name[= STRING value]
NoOpenSpace
Use the NoOpenSpace field attribute to retrieve or assign the NoOpenSpace attribute of a field.
Note
Setting this attribute prevents the form from expanding if the field expands.
Syntax
[formname].fieldname.NoOpenSpace [= TRUE/FALSE value]
Outline
Use the Outline field attribute to retrieve or assign the Outline attribute of a field.
Note
Setting this attribute displays the field text in outline text style. The outline text style is not available on the Windows client, only on the Macintosh client.
Syntax
[formname].fieldname.Outline [=TRUE/FALSE value]
Password
Use the Password field attribute to retrieve or assign the Password attribute of a field.
Note
Setting this attribute displays all text characters as asterisks. Text values will be exactly as they are input, but any input and output to this field will be displayed as asterisks.
Syntax
[formname].fieldname.Password [= TRUE/FALSE value]
Protected
Use the Protected field attribute to retrieve or assign the Protected attribute of a field.
Note
Setting this attribute prevents all users from manipulating the field. This includes modifying data, receiving events, and processing event procedures. Field attribute values and events may still be accessed from within the code.
Syntax
[formname].fieldname.Protected [=TRUE/FALSE value]
ResourceSize
Use the ResourceSize field attribute to retrieve the Macintosh resource fork size attribute of a File Viewer field.
Syntax
[formname].fieldname.ResourceSize
RJust
Use the RJust field attribute to retrieve or assign the RJust attribute of a field.
Note
The RJust field attribute displays field text with right justification.
Syntax
[formname].fieldname.RJust [= TRUE/FALSE value]
Selectable
Use the Selectable field attribute to retrieve or assign the Selectable attribute of a field.
Syntax
[formname].fieldname.Selectable [=TRUE/FALSE value]
Selected
Use the Selected field attribute to retrieve or assign the Selected attribute of a field.
Note
The Selected field attribute sets the focus to the field. This attribute has been deprecated; use the SetFocus field method.
Syntax
[formname].fieldname.Selected [=TRUE/FALSE value]
Shadow
Use the Shadow field attribute to retrieve or assign the Shadow style attribute of a field.
Note
The Shadow field attribute displays the field text in shadow text style. The shadow text style is not available on the Windows client; it is only available on the Macintosh client.
Syntax
[formname].fieldname.Shadow [=TRUE/FALSE value]
Text
Use the Text field attribute to retrieve or assign the text value of a field.
Note
The Text field attribute contains the string that is the text value for the field. It is only applicable to fields of string type. For example, text fields and editable lists. Text and Value are the default attributes for fields.
Syntax
[formname].fieldname.Text [=string expression]
Transparent
Use the Transparent field attribute to retrieve or assign the Transparent attribute of a field.
Note
The Transparent field attribute displays fields with transparent backgrounds. Background fields, such as graphics, icons, and so on, are visible through the field.
Syntax
[formname].fieldname.Transparent [=string expression]
Underline
Use the Underline field attribute to retrieve or assign the Underline attribute of a field.
Note
The Underline field attribute displays field text in Underline text style.
Syntax
[formname].fieldname.Underline [=TRUE/FALSE value]
Value
Use the Value field attribute to retrieve or assign the numeric Value of a field.
Note
Only applicable to fields with numeric values. For example, check boxes, enumerated lists, and so on. The Value field attribute also retrieves date information. Text and the Value field attribute are the default attributes for fields.
Syntax
[formname].fieldname.Value [=TRUE/FALSE value]
Wrap
Use the Wrap field attribute to retrieve or assign the Wrap attribute of a field.
Note
The Wrap field attribute displays field text with word wrap. It is essential for any multi-line text box. To enter and display carriage returns in a text field, this attribute must be set.
Syntax
[formname].fieldname.Wrap [TRUE/FALSE value]
Field events
Change
Use the Change field event to change an event.
Note
Event is triggered when the user changes the value of a field.
Click
Use the Click field event to click an event.
Note
Event is triggered when the user clicks on an unprotected field.
Example
Sub Click()
...
End Sub
DoubleClick
Use the DoubleClick field event to double click an event in a field.
Note
Event is triggered when the user double clicks on an unprotected field.
GotFocus
Use the GotFocus field event to make an event active.
Note
Event is triggered when the field receives the focus. A field can receive focus by being clicked, being selected with the <TAB> key, or programmatically with the SetFocus method.
LostFocus
Use the LostFocus field event to make an event inactive.
Note
Event is triggered when the field loses focus. A field loses focus when another field gains the focus.
Field methods
AddItem
Use the AddItem field method to add an item to an existing list field.
Note
AddItem simplifies the use of drop down lists by automating the addition of new items to the list. Add the supplied string parameter as an additional item in the List attribute. AddItem can only be used on editable and static selection lists.
Syntax
[formname].fieldname.AddItem([string value])
Change
Use the Change field method to call whenever the value of the field changes due to user or programmatic reassignment of the current value.
Note
Code can be associated with the Change method whenever you wish it to execute when a field is modified. The value of the field can be accessed from within the method to obtain the new value.
Example
Sub Change()
...
End Sub
DblClick
Use the DblClick field method to call an event whenever the user double clicks on the field in question.
Note
Code can be associated with the DblClick method whenever you wish it to be executed by a mouse action.
Example
Sub DblClick()
...
End Sub
RemoveItem
Use the RemoveItem field method to remove an item from an existing list field.
Note
RemoveItem simplifies the use of drop down lists by automating the deletion of items from the list. It will find the item specified in the string argument and remove it from the list, leaving all other entries the same. Can only be used on editable and static selection lists and affects the List attribute.
Syntax
[formname].fieldname.RemoveItem([string value])
Example
RemoveItem (An item in the list)
SelStart
Use the SelStart field method to set the starting location for a call to SelLength.
Note
Use the SelStart field method to specify the character at which to begin a SelLength text selection. Use SelStart(0) to set the selection at the beginning of the text field.
Syntax
[formname].fieldname.SelStart(numeric expression)
Example
Sub Click()
...
StringField1002.SelStart(5) 'set the starting position for text selection
StringField1002.SelStart(7) 'set the starting position for text selection
...
End Sub
SetFocus
Use the SetFocus field method to set the application focus of a field.
Note
If the form the field is on is shown, but not active, the form is activated and the focus is set. If the field receiving focus is hidden or protected, this method has no effect.
Syntax
[formname].fieldname.SetFocus
Example
Sub Click()
StringField1002.SetFocus 'set focus to StringField 1002
End Sub
SelLength
Use the SelLength field method to set the length of the selected text in a text field.
Note
If a starting point for the selection was not set with SelStart, the selected text begins at the first character. If numeric expression is larger than the number of characters in the text buffer, SelLength selects all of the text in the field. If numeric expression is set to 0, the cursor is placed at the location specified by SelStart (or character 0 if SelStart is not called first) and no text is selected.
Syntax
[formname].fieldname.SelLength(numeric expression)
Example
Sub Click()
...
StringField1002.SelLength(25) 'select the 1st 25 chars in StringField 1002
StringField1002.SelLength(0) '0 = no selection; place cursor at SelStart
StringField1002.SelLength(5) 'select characters 7 - 12
...
End Sub
Field types
Date
Date Selector fields have a Value attribute that contains the date entered or displayed in the field as a Date datatype.
Editable Text
An Editable Text field has a Text attribute that contains the text entered into the field.
Editable Selection List
Editable Selection List fields have a List Attribute that contains the items displayed in the list, exactly as they are assigned in Designer.
Items are semi-colon delineated. An Editable Selection List has a Text attribute which contains the string of the selected item from the list.
To get a numeric response instead of string, use the Static Selection List. Editable Selection Lists can be set to non-editable mode with the Editable attribute in FirstClass Designer or programmatically if you don't want the user to be able to enter text not in the list.
Expanding List
Expanding List fields have the special attributes of their subfield type as set in FirstClass Designer, so if the sub-field type is Text, you can use the Text attribute of any sub-field.
Expanding List attributes are accessed as if the Expanding List was an array, so lstExpanding(0)="Hello" would set the first attribute of the Expanding List to a literal string.
The Reset Method also allows you to clear all field content for the field and the Index Attribute tells you which element in the list has the focus.
File Viewer
File Viewer fields contain arbitrary data, including binary data.
They will display the data if there is an available viewer, but can also be used to store undisplayable binary data as well.
File Viewer fields can be used to display picture data from a database, for example, or provide a method for users to upload data to the program.
The special attributes FileName, FileSize, FileType, FileCreator, and FileFlags can be used to get information about the file currently held in the File Viewer field.
Fixed List
Fixed List fields have the special attributes of their sub-field type as set in Designer, so if the sub-field type is Text, you can use the Text attribute of any sub-field.
Fixed List attributes are accessed as if the Fixed List was an array, so lstFixed(0)="Hello" would set the first attribute of the Fixed List to a literal string.
The Reset Method also allows you to clear all field content for the field and the Index Attribute tells you which element in the list has the focus.
Fixed Lists stay whatever size you initially set them, unlike Expanding Lists, which grow larger as more elements are added.
Group Box
A Group Box field has no special attributes.
Guide Text
A Guide Text field has a Text attribute that contains the text displayed in the field.
Marquee
A Marquee field has a Text attribute that contains the text in the marquee.
Number
A number field has a Value attribute that contains the number entered into the field. This field type only allows numeric entry; no text is possible.
Progress Bar
Progress Bar fields have a Value attribute which can be set or retrieved and indicates the progress on the bar.
The range of this value is set in Designer and defaults to 0 to 100.
String with Icon
String with Icon fields have both a Text attribute that contains the text portion of the field, and an Icon attribute that contains the resource ID of the icon associated with the field.
Time Period
The Value attribute of a Time Period field contains a numeric representation of the period of time displayed in the field.
Field types - Buttons
CheckBox
Checkboxes have a default Value attribute equal to 0 (off), 1 (on) or 2 (greyed).
Configure your checkbox in Designer if you want more than two positions to be displayed.
Command Button
Command Buttons can be used as generic controls in RAD programs. You do not need to set a command in Designer to use the button in RAD, but rather will assign functionality to the Click Method of the button.
The Text attribute allows you to control the text displayed in the button programmatically.
Radio Button
Radio buttons do not have a Value attribute, but can be used with actions such as Click to provide additional programmatic direction when the button is pressed by the user, such as hiding other fields or changing the display of the form.
To find which radio button is selected, use the Value attribute of the Radio Group field which contains the Radio Button field.
Remember to set each Radio Button field in any Radio Group to a different value in Designer.
Radio Group
The radio group field has a Value attribute which is the default and contains the RadioButton value which is currently selected from the available buttons in the group.
The button values must be set in the designer and must be unique in order to function properly.
URL Button
URL Buttons are preset in Designer to open a single URL and cannot be modified programmatically in the RAD.
To get this sort of functionality, use a Command Button and the LaunchURL command in the Click Method of the button to achieve the same thing.
Field types - Graphics
Icon
Use the Icon field type to provide a Value attribute that contains the icon ID of the icon displayed in the field.
Line
Line fields have no special attributes.
Oval
Oval fields have no special attributes.
Picture
A picture field has a Value attribute equal to the resource ID of the picture contained therein.
The picture resource must exist in the settings document or the FirstClass Resource Registry in order to be properly displayed.
Rectangle
Rectangle fields have no special attributes.
Round Rectangle
Round Rectangle fields have no special attributes.
File attributes
Archive
Use the Archive file attribute to retrieve or assign a file's Windows archive bit.
Note
This attribute is ignored for Macintosh file downloads.
Syntax
filevariable.Archive
CreationDate
Use the CreationDate file attribute to retrieve or assign a file's creation date.
Note
Assignment of the creation date is only applicable to file downloads.
Syntax
filevariable.CreationDate
Data
Use the Data file attribute to retrieve or assign a file's data.
Note
The Data attribute contains binary data which, in most instances, may be manipulated as a string. The Data attribute is used directly in conjunction with the Download and Read methods.
Syntax
filevariable.Data
DataSize
Use the DataSize file attribute to retrieve the file's data fork size in bytes.
Syntax
filevariable.DataSize
FileCreator
Use the FileCreator file attribute to retrieve or assign a file's Macintosh file creator.
Note
This attribute may be assigned either a long integer or a four (4) character string representing the Macintosh file creator. For example:
MyFile.FileCreator = "ttxt"
The FileCreator attribute is ignored for Windows file operators.
Syntax
filevariable.FileCreator
FileFlags
Use the FileFlags file attribute to retrieve or assign the file's Macintosh file flags.
Note
The FileFlags attribute is ignored for Windows file operators.
Syntax
filevariable.FileFlags
Filename
Use the Filename file attribute to retrieve or assign a file's filename.
Note
n/a
Syntax
filevariable.Filename
FileSize
Use the FileSize file attribute to retrieve a file's size in bytes.
Note
The size of the resource fork, if any, is counted in returning the size of the file.
Syntax
filevariable.FileSize
FileType
Use the FileType file attribute to retrieve or assign the file's Macintosh file type.
Note
This attribute may be assigned either a long integer or a four (4) character string representing the Macintosh file type. For example:
MyFile.FileType = "TEXT"
This attribute is ignored for Windows file operations.
Syntax
filevariable.FileType
Hidden
Use the Hidden file attribute to retrieve or assign a file's Windows hidden bit.
Note
This attribute is ignored for Macintosh file downloads.
Syntax
filevariable.Hidden
ModificationDate
Use the ModificationDate file attribute to retrieve or assign a file's last modification date.
Note
Assignment of the modification date is only applicable to file downloads.
Syntax
filevariable.ModificationDate
Normal
Use the Normal file attribute to retrieve or assign the formal file bits for a Windows file.
Note
A file with this attribute does not have the read-only, system, hidden, or archive bits sets.
Syntax
filevariable.Normal
ReadOnly
Use the ReadOnly file attribute to retrieve or assign the file's Windows read-only bit.
Note
This attribute is ignored for Macintosh file downloads.
Syntax
filevariable.ReadOnly
ResourceSize
Use the ResourceSize file attribute to retrieve the file's resource fork size in bytes.
Syntax
filevariable.ResourceSize
SubDir
Use the SubDir file attribute to indicate whether the file entry is a subdirectory. The TRUE/FALSE flag indicates whether the item is a subdirectory. TRUE if it is, FALSE if it is a file or other filesystem object.
Note
The SubDir is used for accessing directory information returned from the FindFirst and FindNext methods. This attribute is read-only.
Syntax
filevariable.SubDir
System
Use the System file attribute to retrieve or assign the file's Windows system bit. TRUE/FALSE flag indicates whether the file contains the operating sytem "System" bit.
Note
This attribute is ignored for Macintosh file downloads.
Syntax
filevariable.System
File methods
CloseFile
Use the CloseFile file method to close a file that has been opened with the OpenFile method.
Note
If a file is not closed with the CloseFile method, it is automatically closed at the end of the lifetime of the filevariable object.
Syntax
filevariable.CloseFile
Example
See example for Open file method.
Download
Use the Download file method to initiate a client file download.
Note
The downloaded object may be either a file in a file system or it may be created from a string or data variable.
To download a file in a file system, open the desired file for reading with the OpenFile method and then call the Download method. To download a file from a string or data variable, assign the Data attribute of the file object that does not currently have a file open, and call the download method.
To specify the default filename (displayed in the file download dialogue) supply the file object's Filename attribute.
Syntax
filevariable.CloseFile
Example
MyFile.Data = "Test File Data"
MyFile.Filename = "Test.txt"
MyFile.Download
EOF
Use the EOF file method to return the current status of the end of file flag.
Note
The EOF flag indicates whether the file has read up to, or beyond, the end of the file.
Syntax
filevariable.EOF
Example
See example for Read file method
FindFirst,FindNext
Use the FindFirst, FindNext file methods to retrieve file information from the server's file system.
Note
The FindFirst method retrieves information from the first file found matching the filespec argument (any string representing a valid operating system file specification including wildcards). The FindNext method finds the next file (and subsequent files) matching the filespec argument specified in FindFirst.
When there are no more matching files, the filevariable's FileName attribute will be an empty string ('''').
Do not open the filevariable with the OpenFile method when using FindFirst, FindNext.
Syntax
Filevariable.FindFirst(filespec), filevariable.FindNext
Example
MyFile.FindFirst ("C:\Winnt\*.exe)
MyFile.FindNext
OpenFile
Use the OpenFile file method to open, create, or send a file for reading, writing, and/or downloading.
Note
The path specifies a path to a file on the server that is to be opened. The openconst argument specifies how the file should be opened and can consist of the following values:
fc.Read
opens a file for reading; otherwise displays an error
fc.Write
opens a file for writing; otherwise displays an error
fcAppend
opens a file for appending without removing the EOF marker before writing new data. Creates a new file if one does not exist.
fcUpdate
opens a file for both reading and writing; otherwise displays an error
fcReadWrite
opens an empty file for both reading and writing. If file exists, contents are deleted. Otherwise, file is created.
Syntax
filevariable.OpenFile(path,openconst)
Example
MyFile.OpenFile ("C:\TEST.TXT", fcWrite)
MyFile.OpenFile ("C:\TEST.TXT", fcRead)
Position
Use the Position file method to move the file cursor used for reading and writing.
Note
The Position method moves the position of the cursor in a file in the server's file system. The origin argument indicates the starting point, and the offset argument indicates number of bytes to move from that location (+ value indicates a move forward; - value indicates a move backwards). The origin argument must be one of the following:
fcBegin
file cursor origin at the beginning of file
fcEnd
file cursor origin at the end of file
fcCurr
file cursor origin is current position (unchanged)
Syntax
filevariable.Position(origin[,offset])
Example
MyFile.Position (fcBegin) 'position cursor at beginning of file'
MyFile.Position (fcEnd, -10) 'position cursor 10 characters back from end of file'
Read
Use the Read file method to attempt a binary read of bytes from a file on the server.
Note
The read data is stored in the Data attribute of the File object. If the end of file is reached before numbytes bytes are read, the Read method stores the maximum number of bytes.
Syntax
filevariable.Read(numbytes)
Example
MyFile.Read(100)
Print MyFile.Data
ReadLine
Use the ReadLine file method to read a text file until the end of the current line.
Syntax
ReadLine (MaximumBytesToBeRead)
Note
ReadLine will read from an open text file until the end of the current line and return the result as a string. This makes text parsing much easier and allows for faster reading of text based data into RAD variables.
Example
Dim MyFile as File
MyFile.OpenFile ("c:\autoexec.bat", fcRead)
print "The first line of your autoexec.bat file is:" &
MyFile.ReadLine(1024)
MyFile.CloseFile
Write
Use the Write file method to write binary or text data to a file on the server.
Note
If the file has not been opened for writing with the OpenFile method, Write will display an error.
Syntax
filevariable.Write(filedata)
Example
MyFile.Write 'This string is written into the file
FirstClass internal functions
BatchAdmin
Use the BatchAdmin internal function to run admin-level batch admin commands.
Note
BatchAdmin takes the batchcommand argument and passes it to the FirstClass Batch Admin with Admin level permission. 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.
The return string will contain either the requested data or information describing any errors that might have occurred.
Syntax
BatchAdmin (batchcommand)
Examples
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
Use the FCAppBuildNumber internal function to return the current .fcx build number (as an integer value) of an application.
Note
If the optional argument applicationname is supplied, this function returns the 'buildnumber' of the specified application provided that it is loaded on the server. If the optional argument is not supplied, FCAppBuildNumber returns the 'buildnumber' of the calling application.
'Buildnumbers' are built into .fcx compiled applications when they are entered in the FirstClass RAD Project Options dialog.
Syntax
FCAppBuildNumber[(applicationname)]
FCAppDescription
Use the FCAppDescription internal function to return the application description information (as a string) of an application.
Note
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.
Application description information strings are built into .fcx compiled applications when they are entered in the FirstClass RAD Project Options dialog.
Syntax
FCAppDescription[(applicationname)]
FCAppDeveloper
Use the FCAppDeveloper internal function to return the developer information (as a string) of an application.
Note
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. Application developer information strings are built into .fcx compiled applications when they are entered in the FirstClass RAD Project Options dialog.
Syntax
FCAppDeveloper[(applicationname)]
FCAppIcon
Use the FCApplcon internal function to return an application's icon resource number (as a numeric value), that is compiled into the application by FirstClass RAD.
Note
If the optional application argument [(applicationname)] is omitted, the value returned is from the calling application.
Syntax
FCApplcon[(applicationname)]
FCAppLoadState
Use the FCAppLoadState internal function to return the current load status of the application specified by the optional applicationname argument.
Note
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 RAD
FCAppUnloaded
Application is not loaded by RAD
FCAppUnloading
RAD is unloading the application
FCAppReloading
RAD is reloading the application
Syntax
FCApploadState[(applicationname)]
FCAppLaunchMethod
Use the FCAppLaunchMethod internal function to return the method by which the calling application was launched.
Note
This function returns one of the following constants:
FCServerLaunched
Application launched as server application
FCSessionLaunched
Application launched at client login
FCDebugLaunched
Application launched by FirstClass RAD in debug mode
FCUserLaunched
Application launched from Desktop stationery
FCAppLaunched
Application launched from another FirstClass RAD
Syntax
FCAppLaunchMethod
FCAppName
Use the FCAppName internal function to return the name (a string value) of the calling application.
Syntax
FCAppName
FCAppSessionUsage
Use the FCAppSessionUsage to return the number of application sessions currently in use on the FirstClass server.
Note
If the optional argument applicationname is supplied, this function returns the number of application sessions currently in use by the specified application.
Syntax
FCAppSessionUsage[(applicationname)]
FCAppServerVersion
Use the FCAppServerVersion internal function to return the version number of FirstClass RAD currently running.
Note
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 backwards compatibility issues between applications and RAD.
Syntax
FCAppServerVersion
Examples
FCAppServerVersion = 1210
FCAppVersion
Use the FCAppVersion internal function to return the version number (as a string) of an application.
Note
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.
Application version strings are built into .fcx compiled applications when they are entered in the FirstClass RAD Project Options dialog.
Syntax
FCAppVersion[(applicationname)]
FCBatchAdmin
Use FCBatchAdmin to send a batch admin command to the FirstClass server and returns a result code.
Note
FCBatchAdmin sends a single string argument, batchstring, to the FirstClass batch admin for processing. The function returns the success or failure of the call as a numeric value.
A non-zero result indicates an error has occured; zero indicates success. Any data returned from the batch admin request (including explicit error messages) may be accessed via the FCBatchAdminReply function.
Syntax
FCBatchAdmin(batchstring)
FCBatchAdminCode
Use the FCBatchAdminCode to return the last batch admin command's return code.
Note
If FCBatchAdminCode returns a non-zero value, there has been an error with the last batch admin command executed.
Syntax
FCBatchAdminCode
FCBatchAdminReply
Use the FCBatchAdminReply internal function to retrieve a string containing batch admin reply data supplied from the last FCBatchAdmin call.
Syntax
FCBatchAdminReply
Examples
Sub Main()
If FCBatchAdmin ("GET ADMIN") = 0 Then
Print "The Default Admin account is: ";
FCBatchAdminReply
End If
End Sub
FCClientPlatform
Use the FCClientPlatform internal function to return a constant value that is the current client's platform of the FirstClass user currently using the application.
Note
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
fcMacintosh
Macintosh client
fcMAPI
MAPI
fcNNTP
NNTP
fcOfflineServer
Offline server
fcPersonalServer
Personal server
fcPOP
POP
fcSMTP
SMTP
fcUNIX
UNIX client
fcUnknown
Unknown client platform
fcVoice = Voice
fcWindows
Windows client
Syntax
FCClientPlatform
FCClientVersion
Use the FCClientVersion internal function to return an integer value that is the FirstClass client's version number.
Syntax
FCClientVersion
FCEventShiftState
Use the FCEventShiftState internal function to return the current state of the shift and control keys when an event occurs.
Note
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
FCGetPrivGroup
Use the FCGetPrivGroup internal function to retrieve the FirstClass server's privilege group list into the FCGetPrivGroup array.
Note
FCGetPrivGroup returns an integer indicating the total number of privilege groups in the current FirstClass Server. Upon calling the FCGetPrivGroup, an application may call the FCPrivGroup function to retrieve the names of the server's privilege groups.
Syntax
FCGetPrivGroup
Examples
Sub Main()
Dim i As Integer
Dim NumGroups As Integer
NumGroup = FCGetPrivGroup
End If
End Sub
FCPOFolder
Use the FCPOFolder internal function to return the path (as a string) of the FirstClass server's FirstClass Post Office folder (\FCPO).
Syntax
FCPOFolder
FCPrivGroup
Use the FCPrivGroup internal function to retrieve a FirstClass server's privilege group name.
Note
FCPrivGroup returns a string value which is the name of a FirstClass server privilege group. 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.
Syntax
FCPrivGroup(groupnum)
Examples
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
Use the FCSpawnReturn internal function to obtain the return code from a process started by Spawn or Shell.
Syntax
FCSpawnReturn
FCSeverSerialNumber
Use the FCServerSerialNumber internal function to return an integer value that is the FirstClass server's serial number.
Note
This function is often used for application licensing purposes.
Syntax
FCServerSerialNumber
FCUserFirstName
Use the FCUserFirstName internal function to return a string containing the first name of the user currently using the application.
Syntax
FCUserFirstName
Examples
Sub Main()
Print "Your Account Information"
Print "...................................."
Print "First Name:"; FCUserFirstName
...
End Sub
FCUserCID
Use the FCUserCID internal function to return the unique FirstClass Client ID for the current user.
Note
The Client ID number is returned as an integer. The Client ID is the identifier that FirstClass uses internally to track a user. This number remains constant for a user regardless of changes to the user's name or userid and can be relied upon to be a consistent and distinctly unique reference to a FirstClass user.
Syntax
FCUserCID
Examples
FCUserCID = 55
FCUserID
Use the FCUserID internal function to return a string containing the user ID of the FirstClass user currently using the application.
Syntax
FCUserID
Examples
Sub Main()
Print "UserID:"; FCUserID
...
End Sub
FCUserLastName
Use the FCUserLastName internal function to return a string containing the last name of the FirstClass user currently using the application.
Syntax
FCUserLastName
Examples
Sub Main()
Print "Last Name:"; FCUserLastName
...
End Sub
FCUserMI
Use the FCUserMI internal function to return a string containing the middle initial of the FirstClass user currently using the application.
Syntax
FCUserMI
Examples
Sub Main()
Print "Middle Initial:"; FCUserMI
...
End Sub
FCUserName
Use the FCUserName internal function to return a string containing the full user name of the FirstClass user currently using the application.
Syntax
FCUserName
Examples
Sub Main()
Print "Full Name:"; FCUserName
...
End Sub
FCUserPrivGroup
Use the FCUserPrivGroup internal function to determine whether the user is in the specified privilege group.
Syntax
FCUserPrivGroup(string expression)
Note
Returns TRUE or FALSE depending on whether the user is in the privilege group supplied in the string expression argument. 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.
Examples
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
Form attributes
Hidden
Use the Hidden form attribute to retrieve or assign the Hidden attribute of the form.
Note
Shows or hides a form. This form attribute also can be used to determine the current state of a form; if the form is shown, the Hidden attribute is FALSE. Otherwise, the Hidden attribute is TRUE.
Syntax
[formname].Hidden [= TRUE/FALSE value]
Examples
Sub Click()
If MyForm.Hidden = TRUE Then
MyForm.Title = "Form Title"
MyForm.Show
End If
End Sub
MouseX,MouseY
Use the MouseX and MouseY form attribute to retrieve the last coordinates clicked on the form body (including any protected controls).
Note
Gives the X and Y coordinates on the form.
Syntax
formname.MouseX
formname.MouseY
Examples
Sub Main()
MyForm.MouseX
MyForm.MouseY
End Sub
Title
Use the Title form attribute to retrieve or assign the Title attribute of the form.
Note
Display the form's window title string. The title may be assigned any valid string expression.
Syntax
[formname].Title [=string expression]
Examples
Sub Click()
MyForm.Title = "My form Title"
MyForm.Show
End Sub
Form events
Activate
Use the Activate form event to activate an event on a form.
Note
The event is triggered when the form is activated. A form is activated when the form receives the active focus.
Click
Use the Click form event to click an event on a form.
Note
The event is triggered when the user clicks on the form body or on a protected field on the form.
Deactivate
Use the Deactivate form event to deactivate an event on a form.
Note
The event is triggered when the form is deactivated. A form is deactivated when the active focus is set to another form.
DoubleClick
Use the DoubleClick form event to double click an event on a form.
Note
The event is triggered when the user double clicks on the form body or on a protected field on the form.
Load
Use the Load form event to load an event.
Note
The event is triggered when the form is first loaded or shown. A form is loaded with the Load command or shown with the Show method.
Unload
Use the Unload form event to unload an event.
Note
The event is triggered when a form is closed, either by clicking the close box on the form or programmatically, using the Unload command.
Form methods
DisableFormEvents
Use the DisableFormEvents form method to disable form and field events.
Note
Disables all of the following form and field events:
Forms Fields
Click Click (except buttons)
DoubleClick DoubleClick
Activate GotFocus
Deactivate LostFocus
This form method is useful for applications running on high usage systems. If the events listed are not used in the application, disabling these form events can reduce client-server overhead.
Syntax
formname.DisableFormEvents
EnableFormEvents
Use the EnableFormEvents form method to enable form and field events.
Note
Enables form and field events disabled with the DisableFormEvents form method.
Syntax
formname.EnableFormEvents
Hide
Use the Hide form method to hide a form from view.
Note
A hidden form is not unloaded; the form continues to exist with current attributes and values intact. Showing a hidden form will redisplay the form with all attributes set as they were prior to running the Hide form method. If the application ends, a hidden form is automatically unloaded.
Syntax
formname.Hide
Show
Use the Show form method to display a form.
Note
Displays a modeless form. If the form has not been loaded, Show will load the form and data environment before displaying.
Syntax
formname.Show
Swap
Use the Swap form method to hide a form's content and display a second form within the form's original window.
Note
The swapform argument may be any string expression that is a valid form name. This method allows the programmer to dramatically change the interface in the window without hiding and unhiding fields.
Be sure to put the swapform argument as a string and not a direct reference to the form object. If the swapform argument is a direct reference to the form object, the form's default attribute, Title, will be used as the swap form name.
Examples
Form1.Swap("Form2) 'Correct!
Form1.Swap(Form2) 'Incorrect! Passes Form2's title as an argument.
Syntax
formname.Swap(swapform)
Internal functions
Abs
Use the Abs internal function to compute the absolute value of a numeric expression.
Note
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.
Syntax
Abs(numeric expression)
Examples
Sub Main()
Print "Absolute value of .3456 is:",
Abs(.3456)
Print "Absolute value of -.3456 is:",
Abs(.3456)
End Sub
Asc
Use the Asc internal function to return the ANSI numeric value for the first character in a string expression.
Note
The string expression argument may be any valid string; however, only the first character in the string expression will be evaluated. Any subsequent characters will be ignored.
Syntax
Asc(string expression)
Examples
See the code example for Chr internal function.
Atn
Use the Atn internal function to compute the arctangent of a number.
Note
The return value of Atn is expressed in radians. The return type for Atn is Double.
Syntax
Atn(numeric expression)
Chr
Use the Chr internal function to return a string containing the character represented by the ANSI numeric code argument.
Syntax
Chr(numeric expression)
Examples
Sub Main()
Dim i as Integer
Dim c as String
For i = 1 to 255
c = Chr(i)
Print "character:", c
End Sub
Cos
Use the Cos internal function to compute the cosine of a number.
Note
The return value of Cos is expressed in radians. The return type for Cos is Double.
Syntax
Cos(numeric expression)
DateSerial
Use the DateSerial internal function to return a date value given the year, month, and day as arguments.
Note
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
If an invalid date has been specified, the system will display an error.
Syntax
DateSerial(year, month, day)
Examples
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
Use the DateValue internal function to return a date value given a string argument.
Note
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.
Syntax
DateValue(string expression)
Examples
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
Use the Day internal function to return the day of the month (1-31) for any valid date expression.
Syntax
Day(date expression)
Examples
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
Use the Exp internal function to return the natural logarithm base number e raised to the power of a numeric argument.
Note
The return value is a floating-point number. The argument to this function may be any valid numeric expression.
Syntax
Exp(numeric expression)
Fix
Use the fix internal function to remove the fractional part of a number and return the truncated value as an integer (or a long).
Note
The argument may be any valid numeric expression. This is identical to the Int function.
Syntax
Fix(numeric expression)
Examples
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
Use the Hex internal function to return the string containing the hexadecimal value of a number.
Note
The numeric expression argument is rounded to an integer value before being evaluated.
Syntax
Hex(numeric expression)
Examples
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
Use the hour internal function to return the hour from a date expression.
Note
Returns an integer (0-23) that represents the hour from any valid date expression.
Syntax
Hour(date expression)
Examples
Sub Main()
...
Dim secnum As Integer, minnum As Integer,
hournum As Integer
...
secnum = Second(d)
Print "The current second is "; secnum
End Sub
LaunchURL
Use the LaunchURL internal function to launch a URL (http, ftp, fcp, mailto...) on the FirstClass client.
Note
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.
Syntax
LaunchURL(URL string)
Examples
Sub Main()
LaunchURL ("http://www.centrinity.com")
End Sub
llf
Use the IIF (immediate if) internal function to evaluate the expression and return one of two possible values.
Note
IIf may only be used to return either of two values rather than directing programmatic flow. The argument trueval and the argument falseval may be of any type. Also, trueval and falseval need not be of the same data type. The return type of IIf is the same as that of the value that is returned.
Syntax
IIf(conditional expression, trueval, falseval)
Examples
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
lnStr
Use the InStr internal function to return the position of the first occurrence of one string (searchstring) within another (sourcestring).
Note
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.
Syntax
InStr ([start,]) sourcestring, searchstring [case])
Examples
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
lnt
Use the Int internal function to remove the fractional part of a number and return the truncated value as an integer (or a long).
Note
The argument may be any valid numeric expression.
Syntax
Int(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
Use the IsArray internal function to determine whether the supplied argument is an array.
Note
Returns TRUE or FALSE depending on whether the supplied argument is an array.
Syntax
IsArray(variablename)
Examples
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
Use the IsDate internal function to determine whether the supplied argument is a valid date.
Note
Returns TRUE or FALSE depending on whether the supplied argument is a valid date. The date expression argument may be a string, date, or any numeric data type.
Syntax
IsDate (date expression)
Examples
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
Use the IsNumeric internal function to determine whether the supplied argument is numeric.
Note
Returns TRUE or FALSE depending on whether the supplied argument is a valid numeric expression.
Syntax
IsNumeric(expression)
LaunchURL
Use the LaunchURL internal function to launch a URL (http, ftp, fcp, mailto...) on the FirstClass client.
Note
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.
Syntax
LaunchURL(URL string)
Examples
Sub Main()
LaunchURL ("http://www.centrinity.com")
End Sub
LBound
Use the LBound internal function to return an integer indicating the lower bound of an array.
Note
If the variable is not an array, an error occurs.
Syntax
LBound(array variable)
Examples
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
Use the LCase internal function to return a string argument converted to all lowercase letters.
Syntax
LCase(string expression)
Examples
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
Use the Left internal function to return a string containing the leftmost characters of a string argument.
Note
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.
Syntax
Left(string expression, numeric expression)
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
Use the Len internal function to return the length of a string argument (as an integer), or the number of bytes required to create a variable.
Note
The argument string expression can be any valid string expression.
Syntax
Len (string expression | variable name)
Examples
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)
...
Pr int "The size of Double is"; Len(y); "bytes"
End Sub
Log
Use the Log internal function to compute the natural logarithm of a number.
Syntax
Log(numeric expression)
LTrim
Use the LTrim internal function to return a string with all leading space and tab characters removed.
Note
The argument string expression can be any valid string.
Syntax
LTrim(string expression)
Example
Sub Main()
Dim s As String
s = " test string "
Print "(" & LTrim(s) & ")"
'prints (test string )
End Sub
Mid
Use the Minute internal function to return the minute from a date expression.
Note
Returns an integer (0-59) that represents the minute from any valid date expression.
Syntax
Minute(date expression)
Examples
Sub Main()
...
Dim secnum As Integer, minnum As Integer,
hournum As Integer
...
secnum = Second(d)
Print "The current second is "; secnum
End Sub
Minute
Use the Mid internal function to return a sub-string from within a string expression.
Note
The start argument specifies the character offset from which to retrieve the sub-string. The optional length argument indicates the number of characters to return and, if 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, offset to the end of the string, are returned.
Syntax
Mid(string expression, start offset [,length])
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
Month
Use the Month internal function to return the month of the year for any valid date expression.
Syntax
Month(date expression)
Examples
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; "st month of the year"
...
Case Else
Print "This is the "; monthnum; "th month of the year"
End Select
End Sub
MsgBoxResponse
Use the MsgBoxResponse internal function to return the value of the last user input to the MsgBox BASIC command.
Syntax
MsgBoxResponse
Note
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)
Examples
See code example for Sgn.
Sin
Use the Sin internal function to compute the Sin of a number.
Note
The return value of Sin is expressed in radians. The return type for Sin is Double.
Syntax
Sin(numeric expression)
Space
Use the Space internal function to return a string containing a number of space characters indicated by the argument.
Note
The argument may be any valid numeric expression.
Syntax
Space(numeric expression)
Examples
Sub Main()
Dim MyStringVariable As String
MyStringVariable = Space(15) ' returns a string with 15 spaces
'to the variable MyStringVariable
Print MyStringVariable
End Sub
Sqr
Use the Sqr internal function to return the square root of any valid numeric expression (as a floating-point number).
Syntax
Sqr(numeric expression)
Examples
Sub Main()
Print "The square root of 2 is:", Sqr(2)
End Sub
StartupString
Use the StartupString internal function to return the startup string (command line argument) for an application.
Note
This internal function is used to differentiate different installations of an application or to seed a FirstClass RAD program with initial values.
Syntax
StartupString
Examples
Sub Main()
Print "The command line argument for this application is";
StartupString
End Sub
Str
Use the Str internal function to return 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
Use the StrComp internal function to compare two string expressions.
Note
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
Syntax
StrComp(string1, string2,[, case])
Examples
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
Use the StrFill internal function to create a string of repeating characters of a specified length.
Note
The numeric expression argument specifies the number of characters in the result string. The character expression 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.
Syntax
StrFill(numeric expression, character expression)
Example
Sub Main()
Dim MyStringVariable As String
MyStringVariable = StrFill(5, "@") ' returns "@@@@@
Print MyStringVariable
End Sub
Tab
Use the Tab internal function to return a string containing the Tab character.
Syntax
Tab
Examples
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
Use the Tan internal function to compute the tangent of a number.
Note
The return value of Tan is expressed in radians. The return type for Tan is Double.
Syntax
Tan(numeric expression)
TCase
Use the TCase internal function to return 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
Use the Time internal function to return the current time from the server's system clock.
Syntax
Time
Examples
See code example for Second internal function.
Timer
Use the Timer internal function to return the number of seconds that have elapsed since 12:00AM.
Note
This function is useful for benchmarking application operations.
Syntax
Timer
Examples
Sub Main()
Dime 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
Use the TimeSerial internal function to return a date data type value given the hour, minute, and second as arguments.
Note
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
If an invalid time has been specified, the system will display an error.
Syntax
TimeSerial(hour, minute, second)
Examples
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
Use the TimeValue internal function to return a date data type, given a string argument.
Note
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.
Syntax
TimeValue(string expression)
Examples
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
Use the Today internal function to return the current date from the server's system clock.
Syntax
Today
Examples
See code example for Day internal function.
Trim
Use the Trim internal function to return a string with all leading and trailing space and tab characters removed.
Note
The argument string expression can be any valid string.
Syntax
Trim(string expression)
Examples
Sub Main()
Dim s As String
s=" test string "
Print "(" & Trim(s) & ")"
'prints (test string)
End Sub
UBound
Use the UBound internal function to return an integer indicating the upper bound of an array.
Note
If the variable is not an array, an error occurs.
Syntax
UBound(array variable)
Examples
See code example for IsArray internal function.
UCase
Use the UCase internal function to return the string argument converted to all uppercase letters.
Syntax
UCase(string expression)
Examples
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
Use the Val internal function to return the numeric value of a string argument.
Note
The string expression argument is 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.
Syntax
Val(string expression)
Examples
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
Use the Weekday internal function to return 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
Use the Year internal function to return the year from any valid date expression.
Syntax
Year (date expression)
Examples
Sub Main()
Dim d As Date
Dim yearnum As Integer
d = Today
yearnum = Year(d)
Print "This year is"; yearnum; "A.D."
End Sub
Shell
Use the Shell internal function to run an executable program on the server.
Note
The argument must be the full path and executable name of the program to be run 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.
Syntax
Shell (string expression)
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
Spawn
Use the Spawn internal function to run a process or application on the FirstClass server.
Note
The application_name argument 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) or whether the application should launch the process and continue executing (fcNoWait: asynchronous).
Syntax
Spawn(application_name [fcWait | fcNoWait])
Examples
Spawn ("C:\Acrobat3\Reader\AcroRd32.exe", fcNoWait) 'launches a program on the server and immediately resumes processing the application'
StrToken
Use the StrToken internal function to parse a delimited string into its component sub-string tokens.
Note
The StrToken internal function enhances FCRAD's ability to quickly and easily parse delimited strings.
StrToken takes 3 arguments:
• sourcestring, which contains a delimited list of sub-string tokens
• delimiters, which is a text string which specifies all of the delimiters to use when separating tokens
• tokennumber which indicates the ordinal number of the sub-string to return (starting with 1 for the first string)
Examples
This example gets the last login time of the administrator and breaks the resulting batch admin reply up into its constitutent sub-strings.
Note
This code uses both the space character as well as the double-quote character (Chr(34) as delimiters for the delimiters argument, batch admin 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 1230 + d")
Print "source string:"; fcBatchAdminReply
Print "sub-string 1:"; Str Token(fcBatchAdminReply, " " & Chr(34), 1)
...
End Sub
ODBC objects
Column objects
Use the Column object ODBC to define the columns of data returned from queries that are stored in cursors (result sets).
Note
A Column object makes it possible to specify a single column or set of columns and the rows of data contained within them.
The attributes of a Column object are used to:
• specify a column or set of columns in a cursor
• store the attributes, such as Text, Value, Precision, Name, and DataType, of a column
• change database values
Connection objects
Use the Connection object ODBC as an active connection to an ODBC data source.
Note
Connection objects are the broadest objects in Object ODBC. They act as conduits through which all statements travel.
The attributes and methods of a Connection object are used to:
• establish the connection
This includes passing login and password information to the database driver.
• set connection options
This includes transaction isolation, cursor type, timeouts, and tracing report information about the database driver.
Object ODBC
Use the Object ODBC object with SQL queries to bound column databases.
Note
It organizes the database objects into a simple three-level hierarchy: Connection, Statement, and Column. Each object in this hierarchy has attributes and methods that are used to manipulate the object.
Statement objects
Use the Statement object ODBC to execute database operations on a connection. A statement specifies all aspects of database operations.
Note
The attributes and methods of a Statement object are used to:
• execute SQL queries
• store data that is returned as a result of a query (data is stored in a temporary set of columns and rows called a cursor or result set)
• manipulate data in the cursor (rows in the cursor can be browsed, changed, deleted, and added to)
• set and retrieve statement attributes, including information about cursor types, concurrency settings, and maximum number of rows.
Statement attributes
AsyncEnable
Use the AsyncEnable statement attribute to retrieve or assign the asynchronicity attribute.
Syntax
statementname.AsyncEnable [ = dbConstant]
Note
Contains an integer value indicating the ODBC asynchronicity of a statement.
The AsyncEnable attribute can be one of the following constants:
• 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
Use the BindType statement attribute to retrieve or assign the binding type.
Syntax
statementname.BindType [ = dbConstant]
Note
Contains an integer value indicating the ODBC column binding of a statement.
The BindType attribute can be one of the following constants:
• SQL_BIND_BY_COLUMN
Column binding
• SQL_BIND_TYPE_DEFAULT
Row-wise binding
The default value for this attribute is SQL_BIND_TYPE_DEFAULT, which indicates row-wise binding.
Column
Use the Column statement attribute to retrieve or assign column attributes and methods.
Syntax
statementname.Column(colname | colnum)[.attribute] [ = value]
Note
References a cursor's column either by name or by ordinal number.
Concurrency
Use the Concurrency statement attribute to retrieve or assign the concurrency attribute.
Syntax
statementname.Concurrency [ = dbConstant]
Note
Contains an integer value indicating the ODBC concurrency of a statement.
The Concurrency attribute can be one of the following constants:
• 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
Use the CursorType to retrieve or assign the cursor type attribute.
Syntax
statementname.CursorType [ = dbConstant]
Note
Contains an integer value indicating the ODBC cursor type of a statement.
The CursorType attribute can be one of the following constants:
• 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
Use the DisplayErrors attribute to specify whether the default error handling system should be used or disabled in the event that an unexpected ODBC error occurs.
Note
If the DisplayErrors attribute is set to TRUE (the default) then 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 the developer 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
Use the DisplayWarnings statement attributes to indicate whether to display ODBC warnings.
Note
Indicates whether ODBC warning messages should be displayed when they occur on the statement. The default value is FALSE, indicating that warnings should be suppressed.
Syntax
statementname.DisplayWarnings [ = TRUE|FALSE]
KeysetSize
Use the KeysetSize statement attribute to retrieve or assign the keyset size.
Syntax
statementname.KeysetSize [= size]
Note
Contains an integer value indicating the number for rows in an ODBC keyset driven cursor. The KeysetSize attribute can be set to the desired size or to the constant SQL_KEYSET_SIZE_DEFAULT.
The default value of this attribute is SQL_KEYSET_SIZE_DEFAULT, which indicates that the keyset is completely keyset-driven.
MaxLength
Use the MaxLength statement attribute to retrieve or assign the MaxLength attribute.
Syntax
statementname.MaxLength [ = length]
Note
Contains an integer value indicating the maximum amount of data that can be returned from a column. The MaxLength attribute can be set to the desired length or to the constant SQL_MAX_LENGTH_DEFAULT.
The default value for this attribute is SQL_MAX_LENGTH_DEFAULT, which indicates that the column should return all data.
MacRows
Use the MaxRows statement attribute to retrieve or assign the maximum number of rows to return.
Syntax
statementname.MaxRows [ = numrows]
Note
Contains an integer value indicating the ODBC maximum rows to return in a statement. The MaxRows attribute can be set to the desired length or to the constant SQL_MAX_ROWS_DEFAULT.
The default value for this attribute is SQL_MAX_ROWS_DEFAULT, which returns all rows returned from the query.
NoScan
Use the NoScan statement attribute to retrieve or assign the NoScan attribute.
Syntax
statementname.NoScan [ = dbConstant]
Note
Contains an integer value indicating whether the ODBC driver should scan an SQL string for ODBC escape clauses. The NoScan attribute can be one of the following constants:
• 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
Use the NumCols statement attribute to retrieve the number of columns returned.
Syntax
statementname.NumCols
Note
Retrieve the number of columns returned in a statement. This attribute is read-only at runtime.
QueryTimeout
Use the QueryTimeout statement attribute to retrieve or assign the query timeout.
Syntax
statementname.QueryTimeout [= timeout]
Note
Contains an integer value indicating the ODBC query timeout in seconds. The Query Timeout attribute can be set to the desired number of seconds or to the constant SQL_QUERY_TIMEOUT_DEFAULT.
The default value for this attribute is SQL_QUERY_TIMEOUT_DEFAULT, which indicates that the query will continue to execute until it has completed.
RetrieveData
Use the RetrieveData statement attribute to retrieve or assign the RetrieveData attribute.
Syntax
statementname.Retrieve [= dbConstant]
Note
Contains an integer value indicating whether the ODBC driver should automatically retrieve the data for the current row. The RetrieveData attribute can be one of the following constants:
• 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
Use the RowsetSize to retrieve or assign the rowset size.
Syntax
statementname.RowsetSize [ = size]
Note
Contains an integer value indicating the cursor rowset size. The RowsetSize attribute can be set to the desired number of rows in the rowset or SQL_ROWSET_SIZE_DEFAULT.
The default value for this attribute is SQL_ROWSET_SIZE_DEFAULT, which specifies a rowset size of 1 record.
SimulateCursor
Use the SimulateCursor statement attribute to retrieve or assign the SimulateCursor attribute.
Syntax
statementname.StatementCursor [ = dbConstant]
Note
Contains an integer value that specifies whether drivers that simulate positioned update and delete statements insure that these statements affect only a single row.
The SimulateCursor attribute can be one of the following constants:
• 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
Use the UseBookmarks to retrieve or assign the UseBookmarks attribute.
Syntax
statementname.UseBookmarks [ = db Constant]
Note
Contains an integer value indicating whether the statement can use bookmarks.
The UseBookmarks attribute can be one of the following constants:
• SQL_UB_OFF
Off
• SQL_UB_ON
On
• SQL_UB_DEFAULT
Off
To use bookmarks with a cursor, the application must specify this option before opening the cursor. The default value for this attribute is SQL_UB_OFF.
Statement methods
BOF
Use the BOF statement method to return the current value of the beginning of file (BOF) flag.
Syntax
statementname.BOF
Compliance
Level 2
Note
The BOF method returns the current value of the beginning of file flag. When the program attempts to move the record pointer off of 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.
It is not possible to move completely off of 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 recordset is empty, BOF and EOF always return TRUE.
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
Use the CloseStatement statement method to close a statement on a database connection.
Syntax
statementname.CloseStatement
Compliance
Core level
Note
Close a statement on a connection. Changes to row buffers that have not been updated are discarded.
DBError
Use the DBError statement method to return a string containing the last database statement error.
Note
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
Use the DBErrorCode method to store a numeric value, which is the ODBC error code of the last operation performed.
Syntax
statementname.DBErrorCode
Note
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.
Delete
Use the Delete statement method to perform a positioned delete in a record set.
Syntax
statementname.Delete
Compliance
Level 2
Note
Deletes the current record and moves the record pointer to the next record.
There is no warning for deleting records with positioned deletes. ANY RECORDS DELETED WITH THIS METHOD WILL BE PERMANENTLY LOST. Make sure your application deletes only the records you are interested in deleting. Delete confirmations are handled by the application.
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
Use the Empty statement method to return whether or not the current recordset has any records.
Syntax
statementname.Empty
Compliance
Core level
Note
Returns whether or not the current recordset has any records. If there are records in the recordset, Empty returns FALSE; otherwise, Empty returns TRUE.
Example
See the code example for the ExecuteSQL statement method.
EOF
Use the EOF statement method to return the current value of the end of file (EOF) flag.
Syntax
statementname.EOF
Compliance
Core level
Note
When the program attempts to move the record pointer off of 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.
It is not possible to move completely off of 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 recordset is empty, BOF and EOF always return TRUE.
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
Use the ExecuteSQL statement method to execute an SQL statement.
Syntax
statementname.ExecuteSQL(query)
Compliance
Core level
Note
Executes an SQL statement and returns a cursor if applicable.
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
Use the Filter statement method to requery a recordset with a SQL WHERE clause.
Syntax
statementname.Filter(whereclause)
Compliance
Core level
Note
Filter is a fast, effective way of narrowing the records contained in a recordset.
Filter may be used on any statement cursor generated with an SQL statement provided that it does not have an SQL WHERE clause. 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.
Filter is the preferred method for searching records in bound table applications.
Example
The following code example filters a table Customers in the data environment by customer name with a text string read off of the form.
Sub Click()
Dim filterstr As String
filterstr = "MyCustName Like "' & txtSearchText.Text & "%"'
Customers.Filter(filterstr)
End Sub
FindFirst, FindLast, FindNext, FindPrev
Use the FindFirst, FindLast, FindNext, FindPrev statement methods to find a record in a recordset.
Syntax
statementname.FindFirst(condition), statementname.FindLast(condition), statementname.FindNext(condition), statementname.FindPrev(condition)
Compliance
Level 2
Note
Moves the record pointer through the recordset until conditionevaluates to TRUE or the end of the recordset is reached. Each time the record pointer is moved condition is reevaluated.
The starting location and direction of record pointer movement depends on which method is used:
• FindFirst
Begin at first record and move forward through the recordset.
• FindLast
Begin at last record and move backward through the recordset.
• FindNext
Begin at current record and move forward through the recordset.
• FindPrev
Begin at first record and move backward through the recordset
If condition does not evaluate to TRUE and the end of the recordset 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.
In order to prevent deadlock in asynchronous systems, Find requires server reentrance for each move and evaluation of condition. Reentrance has a substantial amount of overhead and it is often faster and more effective to use the Filter method instead of a Find method.
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
Use the GetTables statement methods to retrieve table information about the current data source.
Syntax
statementname.GetTables
Compliance
Level 1
Note
Returns the list of table names stored in a specific data source. The GetTables method returns table information as a result set.
Insert
Use the Insert statement method to perform a positioned insert in a recordset.
Syntax
statementname.Insert
Compliance
Level 2
Note
Clears the current row buffers and prepares for positioned insert at the end of a recordset. The record is not actually written to the database until the Update method is run.
Example
The following example uses a positioned insert to insert a record into a recordset. 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
Use the Lock statement method to lock the current record to prevent updates by other users.
Syntax
statementname.Lock
Compliance
Some level 2 drivers
Note
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.
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
Use the MakeList statement method to create a list suitable for use as a static or editable List attribute from a column in a database.
Note
The MakeList statement method generates a list of all the items contained in the statement by concatenating the results and separating the list with semi-colons. 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.
Syntax
MakeList(StringColumn, NumericColumn)
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
Use the MoveFirst, MoveLast, MoveNext, MovePrev to move the position of the record pointer and update bound columns.
Syntax
statementname.MoveFirst, statementname.MoveLast,
statementname.MoveNext, statementname.MovePrev
Compliance
Level 2 (SQLExtendedFetch)
Note
Moves the position of the record pointer and updates bound columns.
The starting location and direction of record pointer movement depends on which method is used:
• MoveFirst
Move record pointer to the first record in the recordset.
• MoveLast
Move record pointer to the last record in the recordset.
• MoveNext
Move record pointer to the next record in the recordset.
• Moveprev
Move record pointer to the previous record in the recordset.
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.
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
Use the NoMatch statement method to return whether or not the last Find method located a matching record.
Syntax
statementname.NoMatch
Compliance
Level 2
Note
Returns TRUE or FALSE depending on whether the last Find method located a matching record.
Example
See the code example for the Find statement method.
OpenStatement
Use the OpenStatement statement method to open a statement on a database connection.
Syntax
statementname.OpenStatement(cnctname [,dbCursorType] [dbConcurrency])
Compliance
Core level
Note
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.
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
Use the Refresh statement method to refresh the values in the current rowset buffers.
Syntax
statementname.Refresh
Compliance
Level 2
Note
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.
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
Use the Requery statement method to requery the current statement.
Syntax
statementname.Requery
Compliance
Core level
Note
Re-executes the current statement's query. 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.
Unfilter
Use the Unfilter statement method to requery the recordset without the WHERE clause specified by the Filter method.
Syntax
statementname.Unfilter
Compliance
Core level
Note
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 recordset.
Unlock
Use the Unlock statement method to unlock the current record.
Syntax
statementname.Unlock
Compliance
Some level 2 drivers
Note
Unlocks the current record to allow updates by other users.
Example
Use the code example for the Lock statement method.
Update
Use the Update statement method to perform a positioned update in a recordset.
Syntax
statementname.Update
Compliance
Level 2
Note
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.
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