Merge pull request #6253 from EnterpriseDB/DOCS-953-OCL

DOCS-953 OCL 17.2.0.1 docs

product_docs/docs/ocl_connector/17/02_supported_platforms.mdx

@@ -0,0 +1,9 @@
+---
+title: "Supported platforms"
+
+---
+
+<div id="supported_platforms" class="registered_link"></div>
+
+The EDB OCL Connector is supported on the same platforms as EDB Postgres Advanced Server. To determine the platform support for the EDB OCL Connector, you can refer either to the platform support for EDB Postgres Advanced Server on the [Platform Compatibility page](https://www.enterprisedb.com/platform-compatibility#epas) on the EDB website or to [Installing EDB OCL Connector](./installing). 
+

product_docs/docs/ocl_connector/17/03_libpq_compatibility.mdx

@@ -0,0 +1,37 @@
+---
+title: "libpq cross-version compatibility"
+
+---
+
+<div id="libpq_compatibility" class="registered_link"></div>
+
+EDB OCL installation always uses the latest libpq. When upgrading to a new major release of EDB Postgres Advanced Server, the different scenarios supported under libpq cross-version compatibility are as follows:
+
+-   If the latest libpq is installed on the machine, OCL uses it.
+-   If the latest libpq isn't already installed, OCL installs it. It doesn't use the existing libpq of older versions even if it's installed.
+-   If you upgrade the OCL version, then libpq is also upgraded to its latest version.
+
+If you're upgrading to a minor release, you need to manually upgrade libpq.
+
+## Upgrading libpq for minor releases of EDB Postgres Advanced Server
+
+For minor releases of EDB Postgres Advanced Server, you might need to upgrade libpq to a required version on the client machine where you installed EDB OCL Connector. (Any new libpq version dependencies are listed in the release notes.) If you need to upgrade libpq, run the appropriate command for your operating system.
+
+### For Ubuntu/Debian
+
+```
+sudo apt-get install edb-as15-libpq5
+```
+
+### For RHEL and SLES 
+
+```
+sudo <package-manager> install edb-as15-server-libs
+```
+
+Where `<package-manager>` is the package manager used with your operating system:
+
+| Package manager |         Operating system         |
+| --------------- | -------------------------------- |
+| dnf             | RHEL 8/9 and derivatives         |
+| zypper          | SLES                             |

product_docs/docs/ocl_connector/17/04_open_client_library/02_forming_a_connection_string.mdx

@@ -0,0 +1,48 @@
+---
+title: "Forming a connection string"
+
+---
+
+<div id="forming_a_connection_string" class="registered_link"></div>
+
+The EDB OCL Connector accepts both Oracle-style and Postgres-style connection URIs. A connection string can take the following Oracle-style form:
+
+ `[//][host][:port][/dbname]`
+
+Or it can take the following Postgres-style forms:
+
+```text
+postgres://[user[:password]@][host][:port][/dbname]
+[?param1=value1&...]
+```
+
+```text
+postgresql://[user[:password]@][host][:port][/dbname]
+[?param1=value1&...]
+```
+
+You can also use a Postgres-style URI to specify multiple host components, each with an optional port component, in a single URI. A multi-host connection string takes the form:
+
+ `postgresql://<user>:<password>@host1:port1,host2:port2,host3:port3/`
+
+Where:
+
+ `user` is the name of the connecting user.
+
+ `password` is the password associated with the connecting user.
+
+ `host` is the host name or IP address to which you're connecting. To specify an IPV6 address, enclose the address in square brackets.
+
+ `port` is the port number to which you're connecting.
+
+ `dbname` is the name of the database with which you're connecting.
+
+ `paramx=valuex` pairs specify extra, application-specific connection properties.
+
+For example, each of the following connection strings establishes a connection to the `edb` database on port `5444` of a system with an IP address of `10.0.0.4`:
+
+ `//10.0.0.4:5444/edb`  
+ `postgres://<user>:<password>@10.0.0.4:5444/edb`  
+ `postgresql://<user>:<password>@10.0.0.4:5444/edb`
+
+For more information about using Postgres-style connection strings, see the [PostgreSQL core documentation](https://www.postgresql.org/docs/).

product_docs/docs/ocl_connector/17/04_open_client_library/03_compiling_and_linking_a_program.mdx

@@ -0,0 +1,41 @@
+---
+title: "Compiling and linking a program"
+
+---
+
+<div id="compiling_and_linking_a_program" class="registered_link"></div>
+
+The EDB Open Client Library allows applications written using the Oracle Call Interface API to connect to and access an EDB database with minimal changes to the C source code. The EDB Open Client Library files are named:
+
+- On Linux: `libedboci.so`
+
+- On Windows: `edboci.dll`
+
+The files are installed in the `oci/lib` subdirectory.
+
+## Compiling and linking a sample program
+
+This example compiles and links the sample program `edb_demo.c` in a Linux environment. The `edb_demo.c` file is located in the `oci/samples` subdirectory.
+
+1.  Set `ORACLE_HOME` to the complete pathname of the Oracle home directory, for example:
+
+    `export ORACLE_HOME=/usr/lib/oracle/xe/app/oracle/product/10.2.0/server`
+
+1.  Set `EDB_HOME` to the complete pathname of the home directory, for example:
+
+    `export EDB_HOME=/usr/edb`
+
+1.  Set `LD_LIBRARY_PATH` to the complete path of `libpthread.so`. By default, `libpthread.so` is located in `/lib64`.
+
+    `export LD_LIBRARY_PATH=/lib64/lib:$LD_LIBRARY_PATH`
+
+1.  Set `LD_LIBRARY_PATH` to include the EDB Postgres Advanced Server Open Client library. By default, `libedboci.so` is located in `$EDB_HOME/oci/lib`.
+
+    `export LD_LIBRARY_PATH=$EDB_HOME/oci:$EDB_HOME/oci/lib:$LD_LIBRARY_PATH`
+
+1.  Compile and link the OCL API program:
+
+    ```text
+    cd $EDB_HOME/oci/samples
+    make
+    ```

product_docs/docs/ocl_connector/17/04_open_client_library/04_ref_cursor_support.mdx

@@ -0,0 +1,120 @@
+---
+title: "Ref cursor support"
+
+---
+
+<div id="ref_cursor_support" class="registered_link"></div>
+
+The EDB Postgres Advanced Server Open Client Library supports the use of `REF CURSOR` as `OUT` parameters in PL/SQL procedures that are compatible with Oracle. Support is provided through the following APIs:
+
+-   `OCIBindByName`
+-   `OCIBindByPos`
+-   `OCIBindDynamic`
+-   `OCIStmtPrepare`
+-   `OCIStmtExecute`
+-   `OCIStmtFetch`
+-   `OCIAttrGet`
+
+The EDB OCL Connector also supports the `SQLT_RSET` data type.
+
+This example invokes a stored procedure that opens a cursor and returns a `REF CURSOR` as an output parameter. The code sample assumes that a PL/SQL procedure named `openCursor`, with an `OUT` parameter of type `REF CURSOR`, was created on the database server and that the required handles were allocated:
+
+```c
+char* openCursor = "begin \
+     openCursor(:cmdRefCursor); \
+   end;";
+OCIStmt* stmtOpenRefCursor;
+OCIStmt* stmtUseRefCursor;
+```
+
+Allocate handles for executing a stored procedure to open and use the `REF CURSOR`:
+
+```c
+/* Handle for the stored procedure to open the ref cursor */
+OCIHandleAlloc((dvoid *) envhp,
+               (dvoid **) &stmtOpenRefCursor,
+               OCI_HTYPE_STMT,
+               0,
+               (dvoid **) NULL));
+```
+
+```c
+/* Handle for using the Ref Cursor */
+OCIHandleAlloc((dvoid *) envhp,
+               (dvoid **) &stmtUseRefCursor,
+               OCI_HTYPE_STMT,
+               0,
+               (dvoid **) NULL));
+```
+
+Then, prepare the PL/SQL block that's used to open the `REF CURSOR`:
+
+```c
+OCIStmtPrepare(stmtOpenRefCursor,
+                 errhp,
+                 (text *) openCursor,
+                 (ub4) strlen(openCursor),
+                 OCI_NTV_SYNTAX,
+                 OCI_DEFAULT));
+```
+
+Bind the PL/SQL `openCursor OUT` parameter:
+
+```c
+OCIBindByPos(stmtOpenRefCursor,
+                 &bndplrc1,
+                 errhp,
+                 1,
+                 (dvoid*) &stmtUseRefCursor,
+                         /* the returned ref cursor */
+                 0,
+                 SQLT_RSET,
+                      /* SQLT_RSET type representing cursor */
+                 (dvoid *) 0,
+                 (ub2 *) 0,
+                 (ub2) 0,
+                 (ub4) 0,
+                 (ub4 *) 0,
+                 OCI_DEFAULT));
+```
+
+Use the `stmtOpenRefCursor` statement handle to call the `openCursor` procedure:
+
+```c
+OCIStmtExecute(svchp,
+                 stmtOpenRefCursor,
+                 errhp,
+                 1,
+                 0,
+                 0,
+                 0,
+                 OCI_DEFAULT);
+```
+
+At this point, the `stmtUseRefCursor` statement handle contains the reference to the cursor. To obtain the information, define output variables for the ref cursor:
+
+```c
+/* Define the output variables for the ref cursor */
+  OCIDefineByPos(stmtUseRefCursor,
+                   &defnEmpNo,
+                   errhp,
+                  (ub4) 1,
+                  (dvoid *) &empNo,
+                  (sb4) sizeof(empNo),
+                  SQLT_INT,
+                  (dvoid *) 0,
+                  (ub2 *)0,
+                  (ub2 *)0,
+                  (ub4) OCI_DEFAULT));
+```
+
+Then, fetch the first row of the result set into the target variables:
+
+```c
+/* Fetch the cursor data */
+  OCIStmtFetch(stmtUseRefCursor,
+                  errhp,
+                  (ub4) 1,
+                  (ub4) OCI_FETCH_NEXT,
+                  (ub4) OCI_DEFAULT))
+```