dblink_ora
==========
dblink_ora provides an OCI-based database link that allows you SELECT, INSERT, 
UPDATE or DELETE data stored on an Oracle system from within Postgres Plus 
Advanced Server.


Connecting to an Oracle Database
================================
To enable Oracle connectivity, download Oracle's freely available OCI
drivers from their website, presently at:

    http://www.oracle.com/technology/tech/oci/instantclient/index.html

Before creating a link to an Oracle server, you must tell Advanced Server where to 
find the OCI driver. You can either set the LD_LIBRARY_PATH environment variable (or 
PATH on Windows) to the lib directory of the Oracle client installation or set the value 
of the oracle_home configuration parameter in the postgresql.conf file. The value 
specified in the oracle_home configuration parameter will override the LD_LIBRARY_PATH 
(or PATH) environment variable.

If you use the LD_LIBRARY_PATH (or PATH) environment variable, you must ensure that the 
variable is properly set each time you start Advanced Server.

If the Oracle instant client that you've downloaded does not include the libclntsh.so 
library, you must create a symbolic link named libclntsh.so that points to the 
downloaded version.  Navigate to the Instant Client directory, and execute the 
following command:

        ln -s libclntsh.so<version_number> libclntsh.so

Where <version_number> is the version number of the libclntsh.so library.  For example:

	ln -s libclntsh.so.11.1 libclntsh.so

To set the oracle_home configuration parameter in the postgresql.conf file, 
edit the file, adding the following line: 

    oracle_home = '<lib_directory>' 

  Where: 

    <lib_directory> is the name of the directory that contains 
    libclntsh.so (on Linux) or oci.dll (on Windows). 

After setting the oracle_home configuration parameter, you must restart the server 
for the changes to take effect.  


Reference - dblink_ora Functions and Procedures
===============================================

dblink_ora_connect()
--------------------
The dblink_ora_connect() function establishes a connection to an Oracle database 
with user-specified connection information.

    dblink_ora_connect(text, -- Link Name
                       text, -- Hostname
                       text, -- Service Name
                       text, -- User Name
                       text, -- User Password
                       int,  -- Port
                       bool) -- isDBA

You can optionally use a second form of the dblink_ora_connect() function:

    dblink_ora_connect(text, -- Link Name
                       bool) -- isDBA

The second form of the dblink_ora_connect() function allows you to use the connection
properties of a pre-defined foreign server when establishing a connection to the server.
 
Before invoking the second form of the dblink_ora_connect() function, use the CREATE
SERVER command to store the connection properties for the link to a system table.  When 
you call the dblink_ora_connect() function, substitute the server name specified in the
CREATE SERVER command for the Link Name parameter.

Specify a value of TRUE for the isDBA parameter to request SYSDBA privileges on the 
Oracle server.  The isDBA parameter is optional in both forms of the command; if omitted, 
the default value is FALSE.

dblink_ora_status()
-----------------
The dblink_ora_status() function returns the database connection status.

    dblink_ora_status(text)  -- Link Name

If the specified connection is active, the dblink_ora_status() function returns 
a value of "OK".

dblink_ora_disconnect()
-----------------------
The dblink_ora_disconnect() function closes a database connection.

    dblink_ora_disconnect(text) -- Link Name

dblink_ora_record()
-------------------
The dblink_ora_record() function retrieves information from a database.

    dblink_ora_record(text,  -- Link Name
                      text)  -- SQL Query

dblink_ora_call()
-----------------
The dblink_ora_call() function executes a non-SELECT statement on an Oracle 
database and returns a result set.

    dblink_ora_call(text,    -- Link Name
                    text,    -- non-SELECT SQL statement
                    numeric) -- Number of Iterations

dblink_ora_exec()
-----------------
The dblink_ora_exec() procedure executes a DML or DDL statement in the remote 
database.

    dblink_ora_exec(text,    -- Link Name
                    text)    -- SQL INS/UPD/DEL statement

dblink_ora_copy()
---------------
The dblink_ora_copy() function copies an Oracle table to an EnterpriseDB 
table.  The dblink_ora_copy() function returns a BIGINT value that represents 
the number of rows copied.


    dblink_ora_copy(text,    -- Link Name
                    text,    -- SQL SELECT statement
                    text,    -- Destination Schema Name
                    text,    -- Destination Table Name
                    bool,    -- Truncate Table
                    int)     -- Feedback Count

The Truncate Table parameter is optional; if omitted, the value is FALSE.

The Feedback Count parameter is optional; if omitted, the value is '0'.  During 
the execution of the function, Advanced Server raises a notice of severity INFO 
with each iteration of the 'Feedback Count'.  For example, if FeedbackCount is 10, 
dblink_ora_copy() raises a notice every 10 records.

The following example uses the dblink_ora_copy() function over a connection named 
edb_conn to copy the empid and deptno columns from a table (on an Oracle server) 
named ora_acctg to a table located in the public schema on an instance of Advanced 
Server named as_acctg.  The TRUNCATE option is specified; a Feedback Count of 3 is 
also specified:

    edb=# SELECT dblink_ora_copy('edb_conn','select empid,deptno 
                 FROM ora_acctg', 'public', 'as_acctg', true, 3);
    INFO:  Row: 0
    INFO:  Row: 3
    INFO:  Row: 6
    INFO:  Row: 9
    INFO:  Row: 12
     dblink_ora_copy 
    -----------------
                12
    (1 row)


Calling dblink_ora Functions
================================
The following example demonstrates establishing a connection using the 
dblink_ora_connect() function:

      SELECT dblink_ora_connect
                     ( 'acctg', 'localhost', 'xe', 'hr', 'pwd', 1521 );

The above example connects to a service named 'xe' running on port 1521 (on host 
'localhost') with a user name of 'hr' and a password of 'pwd'.  You may refer to 
this connection in other dblink_ora functions using the connection name 'acctg'.

The following example uses the 'acctg' connection to retrieve information from the 
Oracle server:

      SELECT * FROM dblink_ora_record( 'acctg', 
                     'SELECT first_name from employees') AS t1(id VARCHAR);

The example retrieves a list that includes all of the entries in the 'first_name' 
column of the 'employees' table.

