3. When prompted for the installation directory, use the default directory (the directory specified by the ODBC_PATH environment variable). 4. When the Install Drivers dialog box appears, select the NotesSQL driver and click OK. You do not need to modify any information in the Advanced dialog box. 5. At the end of the installation process, the ODBC Data Source Administrator dialog box appears so you can add Lotus Notes Data Sources. If you are upgrading from a previous 2.x version of NotesSQL, note that you do not have to make any changes to your Data Sources. All your previously added Data Sources will work with this release. 6. For ease of access, move this documentation database to your Notes data directory. 7. Reboot the system. Adding a Lotus Notes Data Source Before you can connect to a Domino database with NotesSQL, you must add a data source for it. You can change or delete a data source at any time. You can use as many data sources as you like with a particular driver, provided no two data sources have the same name. To add a Lotus Notes data source: 1. Start the ODBC Administrator. 2. Choose Add. 3. In the Add Data Source dialog box, select Lotus Notes from the Installed ODBC Drivers list box. 480 Lotus Domino Release 5.0: A Developer’s Handbook 4. Choose OK. This brings up the NotesSQL Configuration dialog box. Configuring a Lotus Notes Data Source This section lists the parameters of a Lotus Notes Data Source with a description of each. There are many parameters, but most have reasonable defaults. We suggest you try using the defaults first. The three dialog box fields that must be filled in are marked with an asterisk. Fields that ask for numeric values check your input. If you specify a value above the allowed maximum, the maximum value is substituted. If you specify a value below the allowed minimum, the minimum value is substituted. If you specify an invalid value, such as a letter, the default value is substituted. Data Source Name Enter a name that identifies the data source in the Data Source Name text box. For example, add the name “Employee” to identify the ODBC connection to an employee database. Description Enter a description of the data source in the Description text box. For example, add the description “Hire date, salary history, and current review of all employees” to describe the contents of the employee database. Chapter 14: Using Other Database Connectivity Tools 481 Server Enter the name of the Notes server that contains the Domino database you want to open in the Server text box. Leave the text box blank if the Domino database is on a local disk. Database Enter the path and name of the .NSF file you want to open in the Database text box. For example: • C:\PERSONNEL\EMPLOYEE.NSF for a file on a local disk, or • PERSONNEL\EMPLOYEE.NSF for a database on a Lotus Notes server. Whether the data is local or on a server, the path is relative to the Notes data directory on that machine. If the Notes data directory is D:\NOTES\DATA\, PERSONNEL\EMPLOYEE.NSF points to D:\NOTES\DATA\PERSONNEL\EMPLOYEE.NSF. Max Length of Text Fields This parameter specifies the maximum number of bytes NotesSQL allows in a string. This limits the number of characters returned from a Notes text field and the length of a string to be inserted into a Notes text field. • The maximum value allowed is 15,360. The minimum value allowed is 2. • The default value is 254. If the database will be used exclusively or primarily with Lotus 1-2-3, we recommend a value of 511. This is the maximum length of a string in a cell in Lotus 1-2-3. Max Number of Tables This parameter specifies the maximum number of tables in a single query. • The maximum value allowed is 100. The minimum value allowed is 1. • The default value is 20. Max Number of Subqueries This parameter specifies the maximum number of nested subqueries in a SQL statement. • The maximum value allowed is 100. The minimum value allowed is 1. • The default value is 20. Keep Temporary Indexes until SQLDisconnect This option controls the saving of temporary indexes. Select the option to save temporary indexes until SQLDisconnect. Leave the option unselected to delete indexes at the end of each SELECT result. • The option is unselected by default. 482 Lotus Domino Release 5.0: A Developer’s Handbook Return Notes Implicit Fields This option controls whether certain Notes fields are provided through SQLStatistics and SQLSpecialColumns. Turn it off for maximum interoperability. Turn it on for backward compatibility with NotesSQL 2.0 or earlier. • The option is unselected by default. Map Special Characters This option controls whether certain characters are mapped to the underscore character ( _ ). For details, see the section “Mapping Notes Names to SQL Names” later in this chapter. • The option is selected by default. Max Length of Rich Text Fields This parameter is the same as Max Length of Text Fields, but for rich text fields. • The maximum value allowed is 15,360. The minimum value allowed is 2. • The default value is 512. If the database will be used exclusively or primarily with Lotus 1-2-3, we recommend a value of 511. This is the maximum length of a string in a cell in Lotus 1-2-3. Note Notes databases have long text fields called rich text fields. The Body field of a Notes document is often a rich text field. If you want to retrieve all the data in such a field, be sure that the maximum string length you specify is large enough. SQL Statement Length This parameter specifies the maximum length of an SQL statement passed to SQLPrepare or SQLExecDirect. • The maximum value allowed is 32,767 (32K). The minimum value allowed is 2. • The default value is 4,096 (4K). Thread Timeout (available on 32-bit Windows platforms only). • All calls are serialized so that they proceed one after the other. This parameter specifies the number of seconds one thread should wait for another thread to finish. • The maximum value allowed is 99,999. The minimum value allowed is 0. A value of 0 means wait forever. • The default value is 60. Chapter 14: Using Other Database Connectivity Tools 483 Connecting to a Data Source You can use NotesSQL with any application that supports ODBC drivers for external data access. To connect to the Domino database, you select the data source you defined using the Setup dialog box. If your Notes user ID is password protected, Notes prompts for a password when you first connect to a remote database using NotesSQL. This information is not database specific and is retained for the length of the session, so you will not need to enter it more than once if you connect to more than one database. Notes never prompts for a user ID. Your user ID is part of your workstation installation. Connection Strings The following keywords are supported for the SQLDriverConnect call: The name of the Notes server where the database is located. If the database is on the local workstation, leave the field blank. Server The name of the Domino database, with a path if necessary.Database The name of the data source.DSN DescriptionKeyword For example, to connect to the Personnel data source in the directory PERSONNEL on server HR_1, use the following connection string: DSN=Personnel; Database=Personnel\employee.nsf; Server=HR_1 The following table describes how SQL components map to Notes components: A SQL View maps to a Notes view that selects documents from one form, in which all columns are calculable from the form. ViewView A SQL Index maps to a Notes view in which all sorted columns refer directly to fields in a single form, and which selects documents from only that form. ViewIndex When creating a NotesSQL Table or View, it is best to avoid the use of column names that are ODBC or SQL reserved words or that contain characters other than letters, numbers, or underscores. Form Field or View Column Column SQL Tables map to either Notes forms or Notes views. However, a Domino database contains only one real table, referred to as the Universal Relation. This table has the same name as the database. Form or View or Universal Relation Table CommentsNotes Components SQL Components 484 Lotus Domino Release 5.0: A Developer’s Handbook Note When a Domino database has both a form and a view with the same name, NotesSQL cannot distinguish between them in SQL statements and the view cannot be accessed. Mapping Notes Names to SQL Names Notes is more flexible about names than SQL. When naming a form or view, Notes allows many special characters and sequences of characters that are not part of the standard SQL syntax. It is not uncommon to number views so that they will appear in a certain order in the Create menu, for example: 1. Products 2. Suppliers If developers want hierarchical view names, they use the backslash: Products\By Name Products\By Age These common Notes naming conventions are not allowed by standard SQL syntax, which does not allow the use of periods, spaces and forward slashes in unquoted identifier names. Mapping Because of this difference in syntax support, NotesSQL optionally maps certain characters to the underscore character ( _ ). This mapping is configurable for each data source. The default is to map the names. We recommend using the default unless it causes a form or view to be inaccessible. This can happen when two similar names (for example, “Employees$” and “Employees_”) are mapped to the same name. If you choose to map names, NotesSQL maps forms, views and their aliases, form fields, and view columns. The characters mapped are: ~ ` ! @ # $ % ^ & * ( ) - + = { } [ ] \ : ; " ' < > , . / ? and the space character. The Universal Relation NotesSQL recognizes Notes forms and views as tables. In addition to forms and views, every Domino database contains a table that has the same name as the database. This table is called the Universal Relation. The Universal Relation contains all fields defined in all forms in the Domino database. The Universal Relation is the only true table in a Domino database. As a result, SQL tables created by NotesSQL behave more like SQL views than traditional relational database tables. Chapter 14: Using Other Database Connectivity Tools 485 For example, with NotesSQL, you can create a Notes form with the CREATE TABLE statement. However, the DROP TABLE statement deletes the Notes form but does not delete any data from the database. Using DROP TABLE with NotesSQL is like deleting a SQL view, in that the data remains in the database. You can view the data through other views that use the same field names, or by referencing the Universal Relation table. Continuing this example, if you create a new table with the same name as a previously deleted table, and use some of the field names from the deleted table, you could find data in the table before you insert any data. This is because the table is actually a view of existing data in the Universal Relation table. Documents (records) in the Domino database contain the name of the form used to create them. NotesSQL uses the form name stored in the document to identify the document when selecting from a form. Using the Universal Relation • You must have read/write access to a database to use its Universal Relation. Without read/write access, you cannot perform any operation (including SELECTs) on the Universal Relation. • The same field name can be used in more than one form with different data types in a Domino database. Therefore, you must use explicit field names in a SELECT clause that references the Universal Relation. In particular, you cannot use SELECT *. You can only perform text operations on fields in the Universal Relation because the data type for all fields is character. • The Universal Relation can participate in a self-join but cannot participate in any other kind of join. • NotesSQL supports the SELECT statement on the Universal Relation. NotesSQL does not support this on a read-only .NSF file. • NotesSQL supports the CREATE VIEW statement on the Universal Relation. • NotesSQL does not support INSERT, DELETE, UPDATE, DROP TABLE, or DROP VIEW statements on the Universal Relation. • NotesSQL uses the type “UNIVERSAL” to differentiate the Universal Relation in the result set of SQLTables. Using SQL Tables from Derived Forms and Views NotesSQL recognizes Notes forms and views as tables. In addition, the driver recognizes the Universal Relation as a table. However, Notes forms and views have very different properties that affect the performance of data access and display with NotesSQL. 486 Lotus Domino Release 5.0: A Developer’s Handbook Views in Notes databases list documents in a specific order. Avoid selecting from a table based on a Notes view and then specifying a different sort order. When you specify a different sort order on an existing view, Notes creates a temporary table on your workstation and re-sorts the documents. Creating a large temporary table and sorting the documents in that table will take a long time. Note Temporary table creation requires you to have read/write access to the database. If you have read-only access, you cannot perform an operation such as SELECT with ORDER BY or GROUP BY unless there is an existing view you can use to support the operation. To display information from a view in a different sort order, use a table based on a Notes form and create an index on the form using the order you want, or create a new view either in Notes or through ODBC. Tables derived from Notes forms are not necessarily indexed for fast access. When selecting data from a table based on a Notes form, NotesSQL looks for a view that acts as an index on that table. If such a view is present, access to the table will be fast. If no such view is present, access to the table may be very slow. In particular, if the table is small in relation to the database, it will take a long time for the driver to locate all the records in the table. This is because Notes must search the entire database and check every record to see if it belongs to the table. Example: Using SQL Tables Derived From Notes Forms and Views The Notes Personal Address Book (NAMES.NSF) is a good database to use as an example to compare the use of forms or views in a database. The Personal Address Book database includes: • A form called Person • A view called People with a sort key on LastName The following statement is the most efficient way to find people in the Personal Address Book sorted by LastName: SELECT LastName FROM People ORDER BY LastName People is a Notes view. This query is efficient because NotesSQL can use the index already associated with the People view that lists LastName in the right order. Now assume you want to list people sorted by their mailing addresses. You could use the following statement: SELECT LastName, Mail_Address FROM People ORDER BY Mail_Address Chapter 14: Using Other Database Connectivity Tools 487 Since the People view is not sorted on Mail_Address, NotesSQL uses the People index, generates a temporary table, and creates a temporary index on Mail_Address. This results in slower performance. A more efficient way to achieve the same result is to issue the following statement: SELECT LastName, Mail_Address FROM Person ORDER BY Mail_Address Person is a Notes form. If there is no index on Mail_Address, NotesSQL generates a temporary index on Mail_Address but does not need to generate a temporary table. This statement is faster than the previous statement, which used ORDER BY on a view-based table. This statement can be executed even faster if the user creates an index in Notes or by using the CREATE INDEX statement in NotesSQL. Column, Index, Table, and View Names Naming Rules A column, index, or view name can be up to 32 characters long. A table name can be up to 64 characters long. Index, view, and table names can consist of letters, digits, underscores (_), dollar signs ($), and spaces. If an index, view, or table name contains a space or is the same as a SQL reserved word, it must be enclosed in double quotes. Column names can consist of letters, digits, underscores (_), and dollar signs ($). Column names cannot contain spaces or conflict with a SQL reserved word. Creating Columns, Indexes, Tables, and Views When creating an index or view, remember that index names and view names must be unique within a database. Don’t use the name of an existing index or view. When creating a table, remember that table names must be unique within a database. Don’t use the name of an existing table or view. When creating or altering a table, remember that column names must be unique within a table. Don’t use the name of another column in the table. Name Visibility If a Domino database contains both a view and a form with the same name, NotesSQL will see the form but not the view. 488 Lotus Domino Release 5.0: A Developer’s Handbook Using Notes Views as Indexes NotesSQL will use an existing Notes view as an index if it meets the following criteria: • The view selection formula in the Notes view design is either SELECT Form = “name” or SELECT @All. • SELECT Form = “name” is faster than SELECT @All, unless all documents in the database were created using the same form. Note that views created with SELECT @All are not described as indexes through SQLStatistics. They are used by NotesSQL to improve performance. • Each sorted column in the view is defined as a simple reference to a field in that form (no formulas). • At least one column in the view is sorted. An easy way to see this information at a glance in Notes is to select File - Database - Design Synopsis. In the dialog box, choose Views, then click OK. Notes generates a detailed synopsis document that includes all the above information and more. Unique Indexes In Notes there is a view property labeled “Unique keys in index (for ODBC access).” When this setting is checked, NotesSQL describes the sorted columns of the view as the keys of a unique index. This happens through the ODBC call SQLStatistics. Having these indexes allows several third-party applications to issue updates against NotesSQL. Use some care with this feature. Checking the box doesn’t make the view a unique index in the relational database sense. Specifically, it doesn’t prevent duplicate records. It only puts the first document with a particular sorted value into the view. Therefore, if you are using this feature, updates may affect more than one record and ORDER BYs may generate small result sets. Here are some guidelines to follow to avoid these problems: • Only use the check box for one view that selects from each form that will be updated. • Choose a view with sorted columns that are each one field (not a formula or expression). • Choose a view with sorted columns that together uniquely identify a record. Chapter 14: Using Other Database Connectivity Tools 489 [...]... multi-valued fields composed of text as a single string Data items are separated by the display separator character (the character defined in Notes as the one to use to separate multiple values when displaying them) For example: 'a; b;c' Note An extra semicolon can appear in the result if the data was entered in Notes, any character other than a semicolon was used as the display separator character, and... Using Other Database Connectivity Tools 505 Domino Driver for JDBC The Lotus Domino Driver for JDBC is a Type 2 JDBC driver that allows you to access Domino databases from Java What is JDBC? JDBC is an object interface that allows Java applications and applets to retrieve and manipulate data in database management systems using SQL The interface allows a single application to connect to many different... NUMERIC java.math.BigDecimal DECIMAL java.math.BigDecimal SMALLINT Integer INTEGER Integer REAL Float FLOAT Float FLOAT Double DATE java.sql.Date TIME java.sql.Time TIMESTAMP java.sql.Timestamp Java Object Types Mapped to Domino Driver for JDBC Types The Java Object Types Boolean, Long, and byte[ ] are not supported by Domino Driver for JDBC String will always map to VARCHAR Java Object Type Lotus Domino. .. of ways of accessing Lotus Notes using the ODBC feature: • Remote Data Control (RDC) This is a visual control to deal with remote data access Basically, no programming is needed to access Notes This feature can provide read and write access to a database, but it is often used only to retrieve database data • Remote Data Object Some methods and properties are available in the Remote Data Object to access... Use a percent symbol ( % ) to represent any number of characters Use a backslash ( \ ) as the escape character continued 494 Lotus Domino Release 5.0: A Developer’s Handbook Operator Meaning NOT Use the NOT operator with another operator to specify a search condition that is false For example: NOT IN, NOT LIKE, or NOT BETWEEN ANY Use to compare a value to each value returned by a subquery Can be prefaced... our example is loaded, a data source list is created by the ListDataSources subroutine and listed in a listbox as follows: '** Form_Load is executed, when a Form is loaded Private Sub Form_Load() '** To create a data source list using ODBC API Call ListDataSources End Sub '** ListDataSources can make a data source list '** and display it in a listbox Sub ListDataSources() Dim ret As Integer Dim dataSource... JDBC classes and interfaces are part of the java.sql package The major components of JDBC are the JDBC driver manager and the underlying drivers JDBC uses the driver manager to handle finding and loading a driver A JDBC data source consists of the data the user application wants to access and its associated parameters Each JDBC driver processes JDBC method invocations, sends SQL statements to a specific... types of databases through a standard protocol JDBC handles details for such tasks as connecting to a database, fetching query results, committing or rolling back transactions, and converting SQL types to and from Java program variables JDBC is implemented as a driver manager with multiple drivers Each driver links the application to a specific type of database JDBC was first introduced in the Java Development... Object to access an ODBC database • ODBC API Call Environment handles, Connection handles and statement handles are retrieved in both the Remote Data Control and the Remote Data Object They can be combined with each other Program Structure The following sections provide some detailed information on how our sample application accesses a Domino database from Visual Basic Creating a Data Source List When... Data Types ODBC SQL to Notes data type mapping: ODBC SQL Data Type Lotus Notes Data Type SQL_CHAR Text SQL_VARCHAR Text SQL_LONGVARCHAR Text SQL_DECIMAL Number, Fixed format SQL_NUMERIC Number, Fixed format continued 490 Lotus Domino Release 5.0: A Developer’s Handbook ODBC SQL Data Type Lotus Notes Data Type SQL_SMALLINT Number, Fixed format SQL_INTEGER Number, General format SQL_REAL Number, General . the database is located. If the database is on the local workstation, leave the field blank. Server The name of the Domino database, with a path if necessary.Database The name of the data source.DSN. Universal Relation Table CommentsNotes Components SQL Components 484 Lotus Domino Release 5. 0: A Developer’s Handbook Note When a Domino database has both a form and a view with the same name, NotesSQL cannot distinguish between them in SQL statements and the. views as tables. In addition to forms and views, every Domino database contains a table that has the same name as the database. This table is called the Universal Relation. The Universal Relation