/*
 * dblink_oka (Version 0.01)
 *
 * Function returning data from an Oracle database
 *
 * Cybertec Geschwinde &. Schoenig
 * http://www.postgresql.at
 * Hans-Juergen Schoenig <hs@cybertec.at>
 *
 * Copyright (c) 2001, 2002 by PostgreSQL Global Development Group
 * ALL RIGHTS RESERVED;
 * 
 * Permission to use, copy, modify, and distribute this software and its
 * documentation for any purpose, without fee, and without a written agreement
 * is hereby granted, provided that the above copyright notice and this
 * paragraph and the following two paragraphs appear in all copies.
 * 
 * IN NO EVENT SHALL THE AUTHOR OR DISTRIBUTORS BE LIABLE TO ANY PARTY FOR
 * DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES, INCLUDING
 * LOST PROFITS, ARISING OUT OF THE USE OF THIS SOFTWARE AND ITS
 * DOCUMENTATION, EVEN IF THE AUTHOR OR DISTRIBUTORS HAVE BEEN ADVISED OF THE
 * POSSIBILITY OF SUCH DAMAGE.
 * 
 * THE AUTHOR AND DISTRIBUTORS SPECIFICALLY DISCLAIMS ANY WARRANTIES,
 * INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
 * AND FITNESS FOR A PARTICULAR PURPOSE.  THE SOFTWARE PROVIDED HEREUNDER IS
 * ON AN "AS IS" BASIS, AND THE AUTHOR AND DISTRIBUTORS HAS NO OBLIGATIONS TO
 * PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
 *
 */


What is it?
===========

This module is supposed to retrieve data from an Oracle database.
Internally it is based on PostgreSQL's table function code.


Motivation:
===========

After having a look at Joe Conway's dblink we wanted to have the same functionality 
for other databases such as Oracle. First we wanted to do it for SAP DB but after
they don't provide a public C/C++ interface so we decided to give Oracle a try.
Basically this code has been written for teaching myself a little more C. Some C
gurus might have seen that this might not be the best solution. However, it works
nicely for me and maybe for others as well.
If there are any problems with the code feel free to send me a patch ;).


How to get started?
===================

The first thing you have to do is to install libsqlora8 which can be downloaded 
freely from http://www.poitschke.de/libsqlora8/. For this version of dblink_ora
we have used libsqlora8-2.3.0pre5.tar.gz.
Please follow the instructions to install this module.
I have not used Oracle's OCI interface directly because it would have been far too
complicated to get the job done.
In the next step you have to modify the Makefile - all you have to do is to set the
paths correctly.
Now you can test the module by running:

psql somedb < func.sql

I hope this works.

[hs@sabrina oracle]$ time psql test < func.sql
DROP FUNCTION
CREATE FUNCTION
DROP FUNCTION
CREATE FUNCTION
DROP FUNCTION
CREATE FUNCTION
DROP FUNCTION
CREATE FUNCTION
DROP FUNCTION
CREATE FUNCTION
 dblink_oraconnect
-------------------
 OK
(1 row)

NOTICE:  SQL statement successful
NOTICE:  Found 2 columns
 ename  | sal
--------+------
 SMITH  | 798
 ALLEN  | 1598
 WARD   | 1248
 JONES  | 2973
 MARTIN | 1248
 BLAKE  | 2848
 CLARK  | 2448
 SCOTT  | 2998
 KING   | 4998
 TURNER | 1498
 ADAMS  | 1098
 JAMES  | 948
 FORD   | 2998
 MILLER | 1298
(14 rows)

NOTICE:  Affected: -1
ERROR:  Cannot execute SQL statement
NOTICE:  Affected: 14
           ?column?           | dblink_oraexec
------------------------------+----------------
 UPDATE emp SET sal = sal - 1 |             14
(1 row)

NOTICE:  Affected: 0
 ?column? | dblink_oraexec
----------+----------------
 ROLLBACK |              0
(1 row)

NOTICE:  SQL statement successful
NOTICE:  Found 2 columns
 ename  | sal
--------+------
 SMITH  | 798
 ALLEN  | 1598
 WARD   | 1248
 JONES  | 2973
 MARTIN | 1248
 BLAKE  | 2848
 CLARK  | 2448
 SCOTT  | 2998
 KING   | 4998
 TURNER | 1498
 ADAMS  | 1098
 JAMES  | 948
 FORD   | 2998
 MILLER | 1298
(14 rows)

NOTICE:  Affected: -1
ERROR:  Cannot execute SQL statement
NOTICE:  Affected: 14
           ?column?           | dblink_oraexec
------------------------------+----------------
 UPDATE emp SET sal = sal + 1 |             14
(1 row)

NOTICE:  SQL statement successful
NOTICE:  Found 2 columns
 ename  | sal
--------+------
 SMITH  | 799
 ALLEN  | 1599
 WARD   | 1249
 JONES  | 2974
 MARTIN | 1249
 BLAKE  | 2849
 CLARK  | 2449
 SCOTT  | 2999
 KING   | 4999
 TURNER | 1499
 ADAMS  | 1099
 JAMES  | 949
 FORD   | 2999
 MILLER | 1299
(14 rows)

NOTICE:  Affected: 14
           ?column?           | dblink_oraexec
------------------------------+----------------
 UPDATE emp SET sal = sal - 1 |             14
(1 row)

NOTICE:  Affected: 0
 ?column? | dblink_oraexec
----------+----------------
 COMMIT   |              0
(1 row)

 dblink_oradisconnect
----------------------
 OK
(1 row)


real    0m1.907s
user    0m0.008s
sys     0m0.006s


Future plans?
=============

- Teaching myself some more C.
- Proper matching of datatypes
- Maybe we had add support for 2 Phase-Commit (I don't know if 2PC is supported by OCI,
  if anybody has more information on this topic please contact me.
- Implement a Makefile which is compliant with those in the contrib section
- Enhanced stability ;).

	Hans-Juergen Schoenig
	(hs@cybertec.at)

