
                        -----------------------
                        Lotus DataLens for OS/2
                        -----------------------
-------
INSTALL
-------

This section explains how to install DataLens for OS/2. To use
DataLens with Lotus Notes for OS/2, you must have previously installed
Notes Release 3 for OS/2 and OS/2 version 1.3 or higher.  To use
DataLens with 1-2-3 for OS/2, you must have previously installed 1-2-3
for OS/2 Release 2.0 or higher and OS/2 version 2.1 or higher.

1.  Insert the DataLens for OS/2 "Disk" into your disk drive.

    TIP    Copy the contents of the DataLens disk onto your computer's
           hard disk, so you can easily install additional drivers and
           configure data sources later.

2.  From an OS/2 full (or window) screen session, type A:\SETUP and
    press Enter.  The "Welcome to Install" dialog box appears.

    NOTE   Replace "A" with the letter that represents the appropriate
           disk drive. If you copied the DataLens files to your hard
           disk, use that letter instead; for example:
           C:\DLENSKIT\SETUP.   

3.      Select "Continue". The "Will you be using DataLens with Lotus Notes?"
        dialog box appears.  If you are using with 1-2-3 for OS/2 2.1 only,
        select "No".

4.      The "Type of Installation" dialog box appears.

5.      Select an  installation method:

        *  "Standard" -- Installs the complete DataLens software on
           your computer.

        *  "Public" -- installs a public copy of the DataLens drivers
           on a file server. If you choose this method, be sure to
           tell users to select "Node" when installing DataLens, in
           order to use the public DataLens drivers.

        *  "Node" -- Select this method if you want to use publicly
           installed DataLens drivers.

           Before you use the Node installation, your Notes
           administrator must install a Public copy of DataLens for
           Lotus Notes on a file server that you can access.  You will
           need to know the path to the DataLens files on that server.

        *  "Configure Additional Data Sources" -- Select this method
           if you want to configure additional data sources. Data
           sources provide connection information to the DataLens
           drivers.

    NOTE   Configuration of Data Sources only applies to Lotus Notes
           installation.

    NOTE   It is highly recommended that the type of DataLens 
           installation match the type of Lotus Notes installation.
           For example, if you are using a Node installation of Lotus
           Notes, you should perform a Node installation of DataLens
           Drivers.

    If you selected "Configure Additional Data Sources", the "Select
    DataLens Drivers to Configure" dialog box appears; select a data
    source to configure and then skip to step 8. 
   
    If you selected "Standard", the "Enter Drive Letter for Installation" 
    dialog box appears; enter drive letter and skip to step 8.
   
    If you selected "Public" or "Node", the "Location of DataLens files
    on server" dialog box appears; continue with step 6.
   
6.  Enter the path where the shared DataLens application files will be
    (or already are) stored on the Notes server.

    If you're performing a "Node" installation, you can get this
    information from your Notes administrator. If you're performing a
    "Public" installation, you must assign a path now. The path for a
    "Public" install must exist already, Install will not create this
    directory.

7.  Install will copy all "DataLens Drivers during a "Public" Install.

8.  Select one or more drivers to install.

    For 1-2-3 for OS/2 2.0 users the installation procedures automatically 
    updates the lotus.bcf file.  The Install program will copy any existing
    LOTUS.BCF files found in the 1-2-3 program directory to BCF.BAK.  The 
    new LOTUS.BCF is written to the \LOTUSAPP.OS2\DATALENS directory.

    1-2-3 for OS/2 Release 2.1 will know the location of LOTUS.BCF from
    Install's change to OS/2 CONFIG.SYS ("x" represents correct drive):

         SET LOTUSBCF=x:\LOTUSAPP.OS2\DATALENS\LOTUS.BCF

    For a Standard or Public installation, Install will check the total
    space available on the specified disk to make sure you'll have room
    for all of the files on your hard drive. Since several drivers
    share resources, the total size of the selected drivers may in
    fact be smaller than you might expect.

    For a Public installation, all drivers are selected by default.

10. For a Standard install and Node install, the selected drivers will
    be configured.

11. Enter the data source information required for the current driver.
  
    Use this chart when filling in the dialog box:

    Dialog box option      Enter this information
    -----------------      ----------------------
    Source name            The data source name. This name represents
                           the location where the database tables are
                           stored; you will reference this name in the
                           Notes formula that activates the DataLens
                           driver.

                           The data source name can be up to 30 alpha-
                           numeric characters; it is case insensitive.
                           In the DATALENS.INI registration file, the
                           data source name appears enclosed in square
                           brackets; for example: [PUBLISHERS].

                           CAUTION!
                           -  You cannot use the same data source name
                              twice, even with different drivers.

                           -  The names "DataLens Drivers" and
                              "DataLens Data Sources" are already in
                              use by the DataLens software, so don't
                              use them as data source names.

    Path to files          For dBASE IV and Paradox, the database
                           tables are stored in a directory on the
                           computer's hard drive.  Enter the path to
                           that directory.

                           For example, if your personnel tables are
                           stored in a directory called EMPS, and this
                           directory is stored below your dBASE IV
                           directory on drive C, the path is:
                           C:\DBASE\EMPS

    Server name            For SQL Server, enter the name of the SQL
                           server by which the database will be
                           accessed. Follow the SQL Server naming
                           conventions.
 
    Database name          For IBM Database Manager, DB2/2, ORACLE, and
                           SQL Server, enter the name of the database
                           containing the tables you want to access.
     
                           Follow the naming conventions for the DBMS
                           you are using.

    Stored on network?     This option appears only when you are
                           configuring a data source for the Paradox
                           driver. If the database tables will be
                           accessed across a network, select "Yes";
                           Install then copies the "Path to files"
                           information into the "level2" registration
                           entry for the database, to ensure that you
                           can access the tables across the network.

    To add more data sources, return to step 10. Otherwise, continue to 
    step 12.

12. Select "OK" to complete the installation.

13. The "Do you wish to view the README file?" dialog box is displayed. If
    you select "Yes", the OS/2 editor "E.EXE" will be invoked and the 
    DataLens for OS/2 README file will be available for viewing.  If you
    select "No", install will exit.

-------------
DOCUMENTATION
-------------
1-2-3 for OS/2 2.X

In addition to your DataLens Drivers for OS/2 book, which is bound with the
1-2-3 for OS/2 User's Guide, there is some updated installation information
and updates since the book was issued.

Lotus Notes

In addition to installing the DataLens files, Install also copies the
"DataLens for Lotus Notes" database to the \DOC directory in your
Notes directory. "DataLens for Lotus Notes" is an online book;
it explains:
   *  How to install DataLens for Lotus Notes (for future reference)

   *  How to install additional DataLens drivers

   *  How to add, reconfigure, and delete data sources

   *  How to use the Notes @DbColumn, @DbLookup, and @DbCommand
      functions with DataLens

   *  How to modify the DATALENS.INI registration file for each
      driver
You can read "DataLens for Lotus Notes" in Notes (just add it to your
workspace and browse it like any other database. You can also print
the book; following the printing instructions in the database's "Using
DataLens for Lotus Notes" document.

-------------------------------------------
CONFIGURATION MODIFICATIONS AND DIRECTORIES
-------------------------------------------

DataLens Drivers for OS/2 Install has changed the following (these 
changes were noted as you went through the Install menus):

1.      CONFIG.SYS, 4 changes ("x" represents correct drive letter):

        LIBPATH and SET PATH are modified:
                  LIBPATH .. x:\LOTUSAPP.OS2\DATALENS;  ...is added
                  SET PATH .. x:\LOTUSAPP.OS2\DATALENS;  ...is added
        Appended to the end of CONFIG.SYS:
                  Set_Lotus_ini=x:\OS2
                  SET LOTUSBCF=x:\LOTUSAPP.OS2\DATALENS\LOTUS.BCF

2.      LOTUS.BCF is backed up as BCF.BAK in the 1-2-3 for OS/2 program
        directory (users performing a Standard DataLens Install may wish
        to delete or rename LOTUS.BCF).  The new, modified LOTUS.BCF is 
        copied to \LOTUSAPP.OS2\DATALENS.  As further backup, Install also 
        makes another backup of LOTUS.BCF called LOTUS.BAK, and this backup
        is found in \LOTUSAPP.OS2\DATALENS.

        Subsequent installs from the DataLens Drivers for OS/2 will
        copy LOTUS.BCF to LOTUS.BAK within the \LOTUSAPP.OS2\DATALENS
        directory before modifying LOTUS.BCF.



3.      LOTUS.INI, a text file, is written to x:\OS2 and identifies
        directories for "Lotus Applications" and "DataLens"

4.      DATALENS.INI is used by Lotus Notes. It is written to 
        \LOTUSAPP.OS2\DATALENS and records entries for driver database 
        parameters specified by the user.  DATALENS.INI is a text file, 
        and its parameters may be changed according to need.

-----------------------------------------
ORACLE 7 DATALENS DRIVER Upgrade
-----------------------------------------

Prerequisites for the ORACLE driver:
The ORACLE driver is compatible with ORACLE Version 6.x and 7.x databases.
The ORACLE driver requires a SQL*Net product with support for a remote ORACLE 
Version 6.x or Version 7.x database. (See the SQL*Net documentation and Oracle
database documentation for more information.)

Installing the ORACLE driver:
For 1-2-3, the DataLens Install program transfers the necessary ORACLE driver 
files to the \lotusapp.os2\datalens directory, and adds the following ORACLE 
driver record to the registration file, LOTUS.BCF:
DN="ORACLE"
DL="ORADLNO"
DD="DataLens Driver for ORACLE";
The ORACLE driver does not use the driver configuration (DC) parameter to set 
configuration options.  You can also add a database record to LOTUS.BCF by 
specifying the DB and DN parameters and, optionally, the DD parameter.
Before using the ORACLE driver, you or the database administrator must set up 
the ORACLE DataLens view, as described in the following section.

Setting up environment variables:
Check that two environment variables have been set by your SQL*Net product 
installation.  
These entries should be in the OS/2 CONFIG.SYS file after a set command.
TWO_TASK should be set to a database connection string.
ex. TWO_TASK=network_prefix:hostname:systemID
CONFIG should be set to the location of the file CONFIG.ORA.
ex. CONFIG=c:\oracle6\config.ora

The Oracle driver also requires that the SQLNET keyword be added to the file 
CONFIG.ORA for databases that will be accessed. The SQLNET keyword is 
documented in the SQL*NET product.  In the file CONFIG.ORA check for an entry
     SQLNET DBNAME actualname=network_prefix:hostname:systemID

Setting up the ORACLE DataLens view
ORACLE maintains and monitors its operations through the Data Dictionary. The 
Data Dictionary contains specific ORACLE catalogs of system and private tables.
After installing the ORACLE driver, you or your database administrator must 
next create a DataLens view in the Data Dictionary.  Because the Data 
Dictionary has catalogs of tables that only the database administrator has 
access to, this procedure is typically run by the database administrator.

1. Use SQL*DBA (from either the ORACLE server or a workstation if you have 
system authorization) to start up the database; for example
[c:\] sqldba
 set auth password
 startup
Password is the database authorization password.

2. Oracle Version 6.x users can skip to the next step.
   Oracle Version 7.x users must first connect as the SYS user and run the 
   server based sql script   $ORACLE_HOME/rdbms/admin/catalog6.sql. 
   This script will create system tables that will be referenced by the 
   DATALENS_OBJECTS view. Once the script has run, the SYS user needs
   to grant select on the created tables to the SYSTEM user. The tables are 
   obj$, user$, com$, tab$, view$, syn$, and tabauth$. This information can
   also be found, commented out, in the file DLNCAT.SQL.

3. Connect to the SYSTEM account on the database. (The default password for the SYSTEM account is MANAGER.)
For example, to connect to a local database, type the following at the sqldba> prompt:
connect system/password
Or, to connect to a remote database, type
connect system/password@network_prefix:hostname:systemID 

4.Create the DATALENS_OBJECTS view by running the DLNCAT.SQL file found in the \LOTUSAPP.OS2\DATALENS directory.
For example, if you're using the ORACLE driver with 1-2-3 and the 1-2-3 
directory is C:\LOTUSAPP.OS2\DATALENS, you type 
@c:\LOTUSAPP.OS2\DATALENS\dlncat.sql

5. Check to make sure the view was created. 
To do this in the SYSTEM account, type
select * from datalens_objects;
To check from a client workstation, connect to a user account and query the 
view. (Once the view is created on the remote database, all clients have 
access to the view; you do not need to create the view for each client.) 
For example, to check the view from the user account SCOTT/TIGER, type 
connect scott/tiger@x:corporate;
select * from datalens_objects;
A long list of unformatted records is displayed. If you do not see these 
records or if you receive an error message, repeat step 3.


Updates and Corrections to the DataLens driver for 1-2-3 booklet

When you send data between 1-2-3 and ORACLE tables, the ORACLE driver converts ORACLE data types to 1-2-3 data types, and vice versa, so that both programs 
can use and understand the same data. The following table shows
ORACLE data types and the data types the driver converts them to in 1-2-3.

ORACLE data type   Data type in 1-2-3  Field width  Precision Scale 
Char                      Label             1
Char (w)                  Label             w
Date                      Date              7                   
Decimal                   Float                         22          
Decimal(*)                Float                         22          
Decimal(*,s)              Number                        22      s 
Decimal(p)                Number                        22   
Decimal(p,s)              Number                        p       s 
Double precision          Number                        p       s 
Float                     Float                         22      
Float(*)                  Float                         22      
Float(b)                  Number                        b       
Integer                   Float                         22      
Number                    Float                         22      
Number(*)                 Float                         22      
Number(*,s)               Number                        22      s 
Number(p)                 Smallint                      L5      
Number(p)                 Integer                       L8      
Number(p,s)               Number                        p       s 
Raw(w)[not displayed in 1-2-3]              w
Smallint                  Float                         22
Varchar(w)                Label             w
The abbreviations are binary precision (b), decimal precision (p), scale (s), 
width (w) and length (L).

Notes on the ORACLE data types
If a number(*), float, or float(*) data has the null flag turned on, 1-2-3 
displays a random number as the scale. (This is a known anomaly.  1-2-3 
ignores the null flag setting).
1-2-3 does not support a negative scale, and instead displays a large positive 
number as the scale (This is also a known anomaly. 1-2-3 interprets the sign 
bit as part of the number, resulting in a large positive number).
To enter a date from 1-2-3 into ORACLE, format the date using Style Number Format. Otherwise, the driver treats the date as a value and an error occurs when 
passing the value to ORACLE.
The ORACLE driver does not display data in raw data type fields. 

To change a parameter setting
You set the ORACLE configuration parameters in CONFIG.ORA or from within 1-2-3. 
Set the configuration parameters in CONFIG.ORA to ensures that the parameters 
are automatically applied each time you start Notes or 1-2-3. 

Configuration parameter syntax
You cannot have spaces in the CONFIG.ORA.
If you installed DataLens for Notes before your Oracle SQL*Net product is 
installed you may have to move your message file, dlnus.msb, into your 
DBS subdirectory in your Oracle Home directory.

ORACLE driver Error Message updates:
DLN-30010  Connection error. ORACLE SQL*Net product must be available. 
Explanation:    The DataLens driver for ORACLE works with SQL*Net products. 
                SQL*Net must be correctly installed before the driver can be
                used. SQL*Net is an ORACLE Corp. product.
Solution:       Install SQL*Net or check that all environment variables have 
                been set.
DLN-30020  Output range too large or too few coloumns selected
Explanation:    The output range contains more columns than you specified in
                the SELECT statement.
Solution:       Make sure that the output range contains the same number of 
                columns as the SELECT statement, and that the column names 
                in the output range are unique.
DLN-30021  Output range too small or too many columns selected
Explanation:    The output range contains fewer columns than you specified in
                the SELECT statement.
Solution:       Make sure that the output range contains the same number of 
                columns as the SELECT statement, and that the column names 
                in the output range are unique.
Note: DLN-30033 is no longer a valid error message.

Any specific page or chapter references should not be used.


-----------------------------------------
NEW DATALENS DRIVERS REPLACED OLD DRIVERS
-----------------------------------------
DataLens Drivers for OS/2 Install will delete older versions of the
drivers which you select to install.  For example, if you selected
the DataLens for ORACLE Driver, the older ORACLE driver, as found
in your \123G (or default) directory, will be deleted, and the new
ORACLE driver will be written to the \LOTUSAPP.OS2\DATALENS directory.


------------------------------------------------------
3RD-PARTY AND OTHER DATALENS DRIVERS RESIDING IN \123G
------------------------------------------------------
You may have installed DataLens drivers from the earlier 1-2-3 for 
OS/2 or 1-2-3/G.  When you upgraded to the new 1-2-3 for OS/2 
Release 2.1, your \123G (default name) directory would have retained
any third-party DataLens drivers you may have purchased and
installed.

DataLens Drivers for OS/2 Install program leaves 3rd-party drivers in
the 1-2-3 for OS/2 program directory, e.g., \123G.  


--------------------------------------
DUAL 1-2-3 VERSIONS AND DATALENS FILES
--------------------------------------

DataLens Drivers for OS/2 Install does NOT affect DataLens Drivers
for Windows or DOS.

If you are running 1-2-3 for OS/2  AND  1-2-3 for Windows  AND/OR 
1-2-3 for DOS on the same node, note the following:

1-2-3 for OS/2 Release 2.1
--------------------------
  OS/2 DataLens drivers are found in \LOTUSAPP.OS2\DATALENS
  LOTUSBCF will point to location of LOTUS.BCF in OS2 CONFIG.SYS 
   "SET LOTUSBCF=x:\LOTUSAPP.OS2\DATALENS\LOTUS.BCF"
  There is a LOTUS.INI file in \OS2, and this file has:

  [DATALENS] 
  Program Path=x:\LOTUSAPP.OS2\DATALENS.

1-2-3 for Windows Release 4.x Under WINOS2
------------------------------------------
   Windows DataLens drivers are found in \LOTUSAPP\DATALENS
   There is a LOTUS.INI file for Release 4 in \OS2\MDOS\WINOS2, and 
   this file has: 

   [DATALENS] 
   Program Path=x:\LOTUSAPP\DATALENS.

1-2-3 for DOS Release 3.x DOS Session
-------------------------------------
   Windows DataLens drivers are found in \123R3 or 1-2-3 program
   directory.  

CAUTION:

You should  NOT  combine DataLens drivers from \LOTUSAPP.OS2\DATALENS 
and \LOTUSAPP\DATALENS.  


--------------------------------
1-2-3 FOR OS/2 SAMPLE .DBF FILES
--------------------------------

Three dBASE files, ADDFILE.DBF, DEPFILE.DBF, and EMPFILE.DBF, were
automatically installed when you installed 1-2-3 for OS/2 Release 2.1.
These are found in the 1-2-3 program directory.  To access these files
using /Data External Use, you need to install the DataLens dBASE IV
driver from the DataLens for OS/2 Install diskette.

NOTE:   Lotus DataLens for OS/2 Install will automatically install 
        the SAMPLE driver, which is a dBASE III driver, but you 
        will want to use the more capable dBASE IV driver (which is 
        dBASE III compatible).


---------
COPYRIGHT
---------

Under the copyright laws, neither the documentation nor the software
may be copied, photocopied, reproduced, translated, or reduced to any
electronic medium or machine-readable form, in whole or in part,
except in the manner described in the documentation.

Copyright 1994  Lotus Development Corporation
                55 Cambridge Parkway
                Cambridge, MA  02142

All rights reserved. Printed in the United States.

DataLens, Lotus, Lotus Notes, and 1-2-3 are registered trademarks of
Lotus Development Corporation.
IBM, DB2/2, and OS/2 are registered trademarks of International
Business Machines Corporation.
dBASE IV and Paradox are registered trademarks of Borland
International, Inc.
ORACLE is a registered trademark of Oracle Corporation.
Microsoft is a registered trademark of Microsoft Corporation.
