├── .gitattributes ├── .github ├── ISSUE_TEMPLATE │ ├── announcements.md │ ├── bug_report.md │ ├── config.yml │ ├── documentation-and-example-improvements.md │ ├── enhancement-requests.md │ ├── general-questions-and-runtime-problems.md │ └── installation-questions.md ├── pull_request_template.md └── stale.yml ├── .gitignore ├── .readthedocs.yaml ├── CONTRIBUTING.md ├── LICENSE.txt ├── Makefile ├── Makefile.win32 ├── NOTICE.txt ├── README.md ├── SECURITY.md ├── doc ├── Makefile ├── README.md ├── requirements.txt └── src │ ├── .static │ └── custom.css │ ├── _ext │ ├── parameters_table.py │ └── table_with_summary.py │ ├── conf.py │ ├── enums │ ├── dpiAuthMode.rst │ ├── dpiConnCloseMode.rst │ ├── dpiCreateMode.rst │ ├── dpiDeqMode.rst │ ├── dpiDeqNavigation.rst │ ├── dpiEventType.rst │ ├── dpiExecMode.rst │ ├── dpiFetchMode.rst │ ├── dpiJsonOptions.rst │ ├── dpiMessageDeliveryMode.rst │ ├── dpiMessageState.rst │ ├── dpiNativeTypeNum.rst │ ├── dpiOpCode.rst │ ├── dpiOracleTypeNum.rst │ ├── dpiPoolCloseMode.rst │ ├── dpiPoolGetMode.rst │ ├── dpiPurity.rst │ ├── dpiServerType.rst │ ├── dpiShutdownMode.rst │ ├── dpiSodaFlags.rst │ ├── dpiStartupMode.rst │ ├── dpiStatementType.rst │ ├── dpiSubscrGroupingClass.rst │ ├── dpiSubscrGroupingType.rst │ ├── dpiSubscrNamespace.rst │ ├── dpiSubscrProtocol.rst │ ├── dpiSubscrQOS.rst │ ├── dpiTpcBeginFlags.rst │ ├── dpiTpcEndFlags.rst │ ├── dpiVectorFlags.rst │ ├── dpiVectorFormat.rst │ ├── dpiVisibility.rst │ └── index.rst │ ├── functions │ ├── dpiConn.rst │ ├── dpiContext.rst │ ├── dpiData.rst │ ├── dpiDeqOptions.rst │ ├── dpiEnqOptions.rst │ ├── dpiJson.rst │ ├── dpiLob.rst │ ├── dpiMsgProps.rst │ ├── dpiObject.rst │ ├── dpiObjectAttr.rst │ ├── dpiObjectType.rst │ ├── dpiPool.rst │ ├── dpiQueue.rst │ ├── dpiRowid.rst │ ├── dpiSodaColl.rst │ ├── dpiSodaCollCursor.rst │ ├── dpiSodaDb.rst │ ├── dpiSodaDoc.rst │ ├── dpiSodaDocCursor.rst │ ├── dpiStmt.rst │ ├── dpiSubscr.rst │ ├── dpiVar.rst │ ├── dpiVector.rst │ └── index.rst │ ├── index.rst │ ├── license.rst │ ├── releasenotes.rst │ ├── structs │ ├── dpiAccessToken.rst │ ├── dpiAnnotation.rst │ ├── dpiAppContext.rst │ ├── dpiBytes.rst │ ├── dpiCommonCreateParams.rst │ ├── dpiConnCreateParams.rst │ ├── dpiConnInfo.rst │ ├── dpiContextCreateParams.rst │ ├── dpiData.rst │ ├── dpiDataTypeInfo.rst │ ├── dpiEncodingInfo.rst │ ├── dpiErrorInfo.rst │ ├── dpiIntervalDS.rst │ ├── dpiIntervalYM.rst │ ├── dpiJsonArray.rst │ ├── dpiJsonNode.rst │ ├── dpiJsonObject.rst │ ├── dpiMsgRecipient.rst │ ├── dpiObjectAttrInfo.rst │ ├── dpiObjectTypeInfo.rst │ ├── dpiPoolCreateParams.rst │ ├── dpiQueryInfo.rst │ ├── dpiShardingKeyColumn.rst │ ├── dpiSodaOperOptions.rst │ ├── dpiStmtInfo.rst │ ├── dpiStringList.rst │ ├── dpiSubscrCreateParams.rst │ ├── dpiSubscrMessage.rst │ ├── dpiSubscrMessageQuery.rst │ ├── dpiSubscrMessageRow.rst │ ├── dpiSubscrMessageTable.rst │ ├── dpiTimestamp.rst │ ├── dpiVectorInfo.rst │ ├── dpiVersionInfo.rst │ ├── dpiXid.rst │ └── index.rst │ ├── unions │ ├── dpiDataBuffer.rst │ ├── dpiVectorDimensionBuffer.rst │ └── index.rst │ └── user_guide │ ├── data_types.rst │ ├── debugging.rst │ ├── installation.rst │ ├── introduction.rst │ └── round_trips.rst ├── embed ├── README.md └── dpi.c ├── include └── dpi.h ├── samples ├── DemoAppContext.c ├── DemoBFILE.c ├── DemoBLOB.c ├── DemoBLOBsAsBytes.c ├── DemoBindArrays.c ├── DemoBindJSON.c ├── DemoBindObjects.c ├── DemoBulkAQ.c ├── DemoCLOB.c ├── DemoCLOBsAsStrings.c ├── DemoCQN.c ├── DemoCallProc.c ├── DemoConvertNumbers.c ├── DemoCreateSodaColl.c ├── DemoDMLReturning.c ├── DemoDistribTrans.c ├── DemoDropSodaColl.c ├── DemoFetch.c ├── DemoFetchDates.c ├── DemoFetchJSON.c ├── DemoFetchObjects.c ├── DemoGetAllSodaDocs.c ├── DemoGetSodaCollNames.c ├── DemoGetSodaDoc.c ├── DemoImplicitResults.c ├── DemoInOutTempLobs.c ├── DemoInsert.c ├── DemoInsertAsArray.c ├── DemoInsertManySodaColl.c ├── DemoInsertSodaColl.c ├── DemoIterSodaColls.c ├── DemoLongRaws.c ├── DemoLongs.c ├── DemoObjectAQ.c ├── DemoRawAQ.c ├── DemoRefCursors.c ├── DemoRemoveSodaDoc.c ├── DemoReplaceSodaDoc.c ├── DemoShardingNumberKey.c ├── DemoTokenPoolWithCallback.c ├── DemoTokenStandalone.c ├── Makefile ├── Makefile.win32 ├── README.md ├── SampleLib.c ├── SampleLib.h └── sql │ ├── DropSamples.sql │ ├── SampleEnv.sql │ └── SetupSamples.sql ├── src ├── dpiConn.c ├── dpiContext.c ├── dpiData.c ├── dpiDebug.c ├── dpiDeqOptions.c ├── dpiEnqOptions.c ├── dpiEnv.c ├── dpiError.c ├── dpiErrorMessages.h ├── dpiGen.c ├── dpiGlobal.c ├── dpiHandleList.c ├── dpiHandlePool.c ├── dpiImpl.h ├── dpiJson.c ├── dpiLob.c ├── dpiMsgProps.c ├── dpiObject.c ├── dpiObjectAttr.c ├── dpiObjectType.c ├── dpiOci.c ├── dpiOracleType.c ├── dpiPool.c ├── dpiQueue.c ├── dpiRowid.c ├── dpiSodaColl.c ├── dpiSodaCollCursor.c ├── dpiSodaDb.c ├── dpiSodaDoc.c ├── dpiSodaDocCursor.c ├── dpiStmt.c ├── dpiStringList.c ├── dpiSubscr.c ├── dpiUtils.c ├── dpiVar.c └── dpiVector.c ├── test ├── Makefile ├── Makefile.win32 ├── README.md ├── TestLib.c ├── TestLib.h ├── TestSuiteRunner.c ├── sql │ ├── DropTest.sql │ ├── SetupTest.sql │ └── TestEnv.sql ├── test_1000_context.c ├── test_1100_numbers.c ├── test_1200_conn.c ├── test_1300_conn_properties.c ├── test_1400_pool.c ├── test_1500_pool_properties.c ├── test_1600_queries.c ├── test_1700_transactions.c ├── test_1800_misc.c ├── test_1900_variables.c ├── test_2000_statements.c ├── test_2100_data_types.c ├── test_2200_object_types.c ├── test_2300_objects.c ├── test_2400_enq_options.c ├── test_2500_deq_options.c ├── test_2600_msg_props.c ├── test_2700_aq.c ├── test_2800_lobs.c ├── test_2900_implicit_results.c ├── test_3000_scroll_cursors.c ├── test_3100_subscriptions.c ├── test_3200_batch_errors.c ├── test_3300_dml_returning.c ├── test_3400_soda_db.c ├── test_3500_soda_coll.c ├── test_3600_soda_coll_cursor.c ├── test_3700_soda_doc.c ├── test_3800_soda_doc_cursor.c ├── test_3900_sess_tags.c ├── test_4000_queue.c ├── test_4100_binds.c ├── test_4200_rowids.c ├── test_4300_json.c ├── test_4400_vector.c └── valgrind │ ├── run.sh │ └── suppressions.txt └── util └── tracing └── mem_leak.py /.gitattributes: -------------------------------------------------------------------------------- 1 | * text=auto 2 | 3 | *.c text 4 | *.h text 5 | *.md text 6 | *.py text 7 | *.rst text 8 | *.txt text 9 | -------------------------------------------------------------------------------- /.github/ISSUE_TEMPLATE/announcements.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: Announcements 3 | about: Use this if you are sharing something interesting 4 | title: '' 5 | labels: announcement 6 | assignees: '' 7 | 8 | --- 9 | 10 | 11 | -------------------------------------------------------------------------------- /.github/ISSUE_TEMPLATE/bug_report.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: Bug report 3 | about: Create a report to help us improve 4 | title: '' 5 | labels: bug 6 | assignees: '' 7 | 8 | --- 9 | 10 | 21 | 22 | 1. What version of ODPI-C are you using (see dpi.h)? 23 | 24 | 2. What OS (and version) is your application on? 25 | 26 | 3. What compiler (and version) did you use? 27 | 28 | 4. What is your version of the Oracle Client (e.g. Instant Client)? How was it installed? Where it is installed? 29 | 30 | 5. What is your Oracle Database version? 31 | 32 | 6. What is the `PATH` environment variable (on Windows) or `LD_LIBRARY_PATH` (on Linux) set to? 33 | 34 | 7. What environment variables did you set? How *exactly* did you set them? 35 | 36 | 8. What problem or error(s) you are seeing? 37 | 38 | 9. Do you have a runnable code snippet to describe the problem? 39 | 40 | 50 | -------------------------------------------------------------------------------- /.github/ISSUE_TEMPLATE/config.yml: -------------------------------------------------------------------------------- 1 | blank_issues_enabled: false 2 | -------------------------------------------------------------------------------- /.github/ISSUE_TEMPLATE/documentation-and-example-improvements.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: Documentation and Example Improvements 3 | about: Use this to suggest changes to documentation and examples 4 | title: '' 5 | labels: enhancement 6 | assignees: '' 7 | 8 | --- 9 | 10 | 19 | 20 | 1. What is the link to the documentation section that needs improving? 21 | 22 | 2. Describe the confusion 23 | 24 | 3. Suggest changes that would help 25 | -------------------------------------------------------------------------------- /.github/ISSUE_TEMPLATE/enhancement-requests.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: Enhancement Requests 3 | about: Use this for enhancement requests 4 | title: '' 5 | labels: enhancement 6 | assignees: '' 7 | 8 | --- 9 | 10 | 21 | 22 | 1. Describe your new request in detail 23 | 24 | 2. Give supporting information about tools and operating systems. Give relevant product version numbers 25 | -------------------------------------------------------------------------------- /.github/ISSUE_TEMPLATE/general-questions-and-runtime-problems.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: Questions and Runtime Problems 3 | about: For general ODPI-C questions 4 | title: '' 5 | labels: question 6 | assignees: '' 7 | 8 | --- 9 | 10 | 23 | 24 | 1. What version of ODPI-C are you using (see dpi.h)? 25 | 26 | 2. What OS (and version) is your application on? 27 | 28 | 3. What compiler (and version) did you use? 29 | 30 | 4. What is your version of the Oracle Client (e.g. Instant Client)? How was it installed? Where it is installed? 31 | 32 | 5. What is your Oracle Database version? 33 | 34 | 6. What is the `PATH` environment variable (on Windows) or `LD_LIBRARY_PATH` (on Linux) set to? 35 | 36 | 7. What environment variables did you set? How *exactly* did you set them? 37 | 38 | 8. What problem or error(s) you are seeing? 39 | 40 | 9. Do you have a runnable code snippet to describe the problem? 41 | 42 | 52 | -------------------------------------------------------------------------------- /.github/ISSUE_TEMPLATE/installation-questions.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: Installation Problems 3 | about: Use this for installation questions 4 | title: '' 5 | labels: install & configuration 6 | assignees: '' 7 | 8 | --- 9 | 10 | 29 | 30 | 1. What version of ODPI-C are you using (see dpi.h)? 31 | 32 | 2. What OS (and version) is your application on? 33 | 34 | 3. What compiler (and version) did you use? 35 | 36 | 4. What is your version of the Oracle Client (e.g. Instant Client)? How was it installed? Where it is installed? 37 | 38 | 5. What is your Oracle Database version? 39 | 40 | 6. What is the `PATH` environment variable (on Windows) or `LD_LIBRARY_PATH` (on Linux) set to? 41 | 42 | 7. What environment variables did you set? How *exactly* did you set them? 43 | 44 | 8. What problem or error(s) you are seeing? 45 | -------------------------------------------------------------------------------- /.github/pull_request_template.md: -------------------------------------------------------------------------------- 1 | Sorry, Pull Requests for ODPI-C cannot be accepted. Please report bugs and ask questions using GitHub issues https://github.com/oracle/odpi/issues 2 | -------------------------------------------------------------------------------- /.github/stale.yml: -------------------------------------------------------------------------------- 1 | # https://probot.github.io/apps/stale/ 2 | 3 | # Number of days of inactivity before an issue becomes stale 4 | daysUntilStale: 30 5 | # Number of days of inactivity before a stale issue is closed 6 | daysUntilClose: 7 7 | # Issues with these labels will never be considered stale 8 | exemptLabels: 9 | - pinned 10 | - enhancement 11 | - bug 12 | - announcement 13 | - OCA accepted 14 | # Label to use when marking an issue as stale 15 | staleLabel: inactive 16 | # Comment to post when marking an issue as stale. Set to `false` to disable 17 | markComment: > 18 | This issue has been automatically marked as inactive because it has not been 19 | updated recently. It will be closed if no further activity occurs. Thank you 20 | for your contributions. 21 | # Comment to post when closing a stale issue. Set to `false` to disable 22 | closeComment: > 23 | This issue has been automatically closed because it has not been updated for a month. 24 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | build 2 | lib 3 | doc/build 4 | test/build 5 | __pycache__/ 6 | -------------------------------------------------------------------------------- /.readthedocs.yaml: -------------------------------------------------------------------------------- 1 | # required 2 | version: 2 3 | 4 | build: 5 | os: ubuntu-20.04 6 | tools: 7 | python: "3.9" 8 | 9 | # Build documentation in the doc/src directory with Sphinx 10 | sphinx: 11 | configuration: doc/src/conf.py 12 | 13 | # declare Python requirements required to build docs 14 | python: 15 | install: 16 | - requirements: doc/requirements.txt 17 | -------------------------------------------------------------------------------- /CONTRIBUTING.md: -------------------------------------------------------------------------------- 1 | Sorry, Pull Requests for ODPI-C cannot be accepted. Please report bugs and ask questions using [GitHub issues](https://github.com/oracle/odpi/issues) 2 | -------------------------------------------------------------------------------- /Makefile.win32: -------------------------------------------------------------------------------- 1 | #------------------------------------------------------------------------------ 2 | # Copyright (c) 2017, 2024, Oracle and/or its affiliates. 3 | # 4 | # This software is dual-licensed to you under the Universal Permissive License 5 | # (UPL) 1.0 as shown at https://oss.oracle.com/licenses/upl and Apache License 6 | # 2.0 as shown at http://www.apache.org/licenses/LICENSE-2.0. You may choose 7 | # either license. 8 | # 9 | # If you elect to accept the software under the Apache License, Version 2.0, 10 | # the following applies: 11 | # 12 | # Licensed under the Apache License, Version 2.0 (the "License"); 13 | # you may not use this file except in compliance with the License. 14 | # You may obtain a copy of the License at 15 | # 16 | # https://www.apache.org/licenses/LICENSE-2.0 17 | # 18 | # Unless required by applicable law or agreed to in writing, software 19 | # distributed under the License is distributed on an "AS IS" BASIS, 20 | # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 21 | # See the License for the specific language governing permissions and 22 | # limitations under the License. 23 | #------------------------------------------------------------------------------ 24 | 25 | #------------------------------------------------------------------------------ 26 | # 27 | # Sample nmake Makefile showing how ODPI-C can be built as a Windows DLL and 28 | # import library. 29 | # 30 | # This file is expected to be processed by nmake as in the following: 31 | # nmake /f Makefile.win32 32 | # 33 | # Installation instructions: 34 | # https://oracle.github.io/odpi/doc/installation.html 35 | # 36 | #------------------------------------------------------------------------------ 37 | 38 | SRC_DIR = src 39 | INCLUDE_DIR = include 40 | BUILD_DIR = build 41 | LIB_DIR = lib 42 | 43 | DLL_NAME = $(LIB_DIR)\odpic.dll 44 | LIB_NAME = $(LIB_DIR)\odpic.lib 45 | 46 | OBJS = $(BUILD_DIR)\dpiConn.obj $(BUILD_DIR)\dpiContext.obj \ 47 | $(BUILD_DIR)\dpiData.obj $(BUILD_DIR)\dpiEnv.obj \ 48 | $(BUILD_DIR)\dpiError.obj $(BUILD_DIR)\dpiGen.obj \ 49 | $(BUILD_DIR)\dpiGlobal.obj $(BUILD_DIR)\dpiLob.obj \ 50 | $(BUILD_DIR)\dpiObject.obj $(BUILD_DIR)\dpiObjectAttr.obj \ 51 | $(BUILD_DIR)\dpiObjectType.obj $(BUILD_DIR)\dpiPool.obj \ 52 | $(BUILD_DIR)\dpiStmt.obj $(BUILD_DIR)\dpiUtils.obj \ 53 | $(BUILD_DIR)\dpiVar.obj $(BUILD_DIR)\dpiOracleType.obj \ 54 | $(BUILD_DIR)\dpiSubscr.obj $(BUILD_DIR)\dpiDeqOptions.obj \ 55 | $(BUILD_DIR)\dpiEnqOptions.obj $(BUILD_DIR)\dpiMsgProps.obj \ 56 | $(BUILD_DIR)\dpiRowid.obj $(BUILD_DIR)\dpiOci.obj \ 57 | $(BUILD_DIR)\dpiDebug.obj $(BUILD_DIR)\dpiHandlePool.obj \ 58 | $(BUILD_DIR)\dpiHandleList.obj $(BUILD_DIR)\dpiSodaColl.obj \ 59 | $(BUILD_DIR)\dpiSodaCollCursor.obj $(BUILD_DIR)\dpiSodaDb.obj \ 60 | $(BUILD_DIR)\dpiSodaDoc.obj $(BUILD_DIR)\dpiSodaDocCursor.obj \ 61 | $(BUILD_DIR)\dpiQueue.obj $(BUILD_DIR)\dpiJson.obj \ 62 | $(BUILD_DIR)\dpiStringList.obj $(BUILD_DIR)\dpiVector.obj 63 | 64 | all: $(BUILD_DIR) $(LIB_DIR) $(DLL_NAME) $(LIB_NAME) 65 | 66 | clean: 67 | @if exist $(BUILD_DIR) rmdir /S /Q $(BUILD_DIR) 68 | @if exist $(LIB_DIR) rmdir /S /Q $(LIB_DIR) 69 | 70 | $(BUILD_DIR) $(LIB_DIR): 71 | @if not exist $(BUILD_DIR) mkdir $(BUILD_DIR) 72 | @if not exist $(LIB_DIR) mkdir $(LIB_DIR) 73 | 74 | {$(SRC_DIR)}.c{$(BUILD_DIR)}.obj: 75 | cl /nologo /c /Fo$(BUILD_DIR)\ /I$(INCLUDE_DIR) /DDPI_EXPORTS $< 76 | 77 | $(DLL_NAME) $(LIB_NAME): $(OBJS) 78 | link /nologo /dll /OUT:$(DLL_NAME) $(OBJS) 79 | -------------------------------------------------------------------------------- /NOTICE.txt: -------------------------------------------------------------------------------- 1 | Copyright (c) 2016, 2023, Oracle and/or its affiliates. 2 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # ODPI-C 2 | 3 | Oracle Database Programming Interface for C (ODPI-C) is an open source library 4 | of C code that simplifies access to Oracle Database for applications written in 5 | C or C++. It is a wrapper over [Oracle Call Interface 6 | (OCI)](http://www.oracle.com/technetwork/database/features/oci/index.html) that 7 | makes applications and language interfaces easier to develop. 8 | 9 | ODPI-C supports basic and advanced features of Oracle Database and 10 | Oracle Client. See the [homepage](https://oracle.github.io/odpi/) for 11 | a list. 12 | 13 | ## Installation 14 | 15 | See [ODPI-C Installation](https://oracle.github.io/odpi/doc/installation.html). 16 | 17 | ## Documentation 18 | 19 | See the [ODPI-C Documentation](https://oracle.github.io/odpi/doc/index.html) and 20 | [Release Notes](https://oracle.github.io/odpi/doc/releasenotes.html). 21 | 22 | ## Samples 23 | 24 | See [/samples](https://github.com/oracle/odpi/tree/main/samples). 25 | 26 | ## Help 27 | 28 | Please report bugs and ask questions using [GitHub issues](https://github.com/oracle/odpi/issues). 29 | 30 | ## Tests 31 | 32 | See [/test](https://github.com/oracle/odpi/tree/main/test). 33 | 34 | ## Contributing 35 | 36 | See [CONTRIBUTING](https://github.com/oracle/odpi/blob/main/CONTRIBUTING.md). 37 | 38 | ## Drivers Using ODPI-C 39 | 40 | Oracle Drivers: 41 | * [python-oracledb](https://oracle.github.io/python-oracledb) Python interface (previously known as cx_Oracle). 42 | * [node-oracledb](https://oracle.github.io/node-oracledb) Node.js module. 43 | 44 | Third-party Drivers: 45 | * [godror](https://github.com/godror/godror) Go Driver. 46 | * [odpic-raw](https://github.com/leptonyu/odpic-raw) Haskell Raw Bindings. 47 | * [oracle-simple](https://github.com/haskell-oracle/oracle-simple) Haskell driver. 48 | * [ruby-ODPI ](https://github.com/kubo/ruby-odpi) Ruby Interface. 49 | * [rust-oracle ](https://github.com/kubo/rust-oracle) Driver for Rust. 50 | * [Oracle.jl](https://github.com/felipenoris/Oracle.jl) Driver for Julia. 51 | * [oranif](https://github.com/KonnexionsGmbH/oranif) Driver for Erlang. 52 | * [nimodpi](https://github.com/mikra01/nimodpi) Driver for Nim. 53 | 54 | ## Security 55 | 56 | Please consult the [security guide](./SECURITY.md) for our responsible security 57 | vulnerability disclosure process. 58 | 59 | ## License 60 | 61 | Copyright (c) 2016, 2025, Oracle and/or its affiliates. 62 | 63 | This software is dual-licensed to you under the Universal Permissive License 64 | (UPL) 1.0 as shown at https://oss.oracle.com/licenses/upl and Apache License 65 | 2.0 as shown at http://www.apache.org/licenses/LICENSE-2.0. You may choose 66 | either license. 67 | 68 | If you elect to accept the software under the Apache License, Version 2.0, 69 | the following applies: 70 | 71 | Licensed under the Apache License, Version 2.0 (the "License"); 72 | you may not use this file except in compliance with the License. 73 | You may obtain a copy of the License at 74 | 75 | https://www.apache.org/licenses/LICENSE-2.0 76 | 77 | Unless required by applicable law or agreed to in writing, software 78 | distributed under the License is distributed on an "AS IS" BASIS, 79 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 80 | See the License for the specific language governing permissions and 81 | limitations under the License. 82 | -------------------------------------------------------------------------------- /SECURITY.md: -------------------------------------------------------------------------------- 1 | # Reporting security vulnerabilities 2 | 3 | Oracle values the independent security research community and believes that 4 | responsible disclosure of security vulnerabilities helps us ensure the security 5 | and privacy of all our users. 6 | 7 | Please do NOT raise a GitHub Issue to report a security vulnerability. If you 8 | believe you have found a security vulnerability, please submit a report to 9 | [secalert_us@oracle.com][1] preferably with a proof of concept. Please review 10 | some additional information on [how to report security vulnerabilities to 11 | Oracle][2]. We encourage people who contact Oracle Security to use email 12 | encryption using [our encryption key][3]. 13 | 14 | We ask that you do not use other channels or contact the project maintainers 15 | directly. 16 | 17 | Non-vulnerability related security issues such as great new ideas for security 18 | features are welcome on GitHub Issues. 19 | 20 | ## Security updates, alerts and bulletins 21 | 22 | Our project will typically release security fixes in conjunction with each 23 | patch release. 24 | 25 | Oracle security information, including past advisories, is available on the 26 | [security alerts][4] page. 27 | 28 | ## Security-related information 29 | 30 | We will provide security related information such as a threat model, 31 | considerations for secure use, or any known security issues in our 32 | documentation. Please note that labs and sample code are intended to 33 | demonstrate a concept and may not be sufficiently hardened for production use. 34 | 35 | [1]: mailto:secalert_us@oracle.com 36 | [2]: https://www.oracle.com/corporate/security-practices/assurance/vulnerability/reporting.html 37 | [3]: https://www.oracle.com/security-alerts/encryptionkey.html 38 | [4]: https://www.oracle.com/security-alerts/ 39 | -------------------------------------------------------------------------------- /doc/Makefile: -------------------------------------------------------------------------------- 1 | #------------------------------------------------------------------------------ 2 | # Copyright (c) 2016, 2022, Oracle and/or its affiliates. 3 | # 4 | # This software is dual-licensed to you under the Universal Permissive License 5 | # (UPL) 1.0 as shown at https://oss.oracle.com/licenses/upl and Apache License 6 | # 2.0 as shown at http://www.apache.org/licenses/LICENSE-2.0. You may choose 7 | # either license. 8 | # 9 | # If you elect to accept the software under the Apache License, Version 2.0, 10 | # the following applies: 11 | # 12 | # Licensed under the Apache License, Version 2.0 (the "License"); 13 | # you may not use this file except in compliance with the License. 14 | # You may obtain a copy of the License at 15 | # 16 | # https://www.apache.org/licenses/LICENSE-2.0 17 | # 18 | # Unless required by applicable law or agreed to in writing, software 19 | # distributed under the License is distributed on an "AS IS" BASIS, 20 | # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 21 | # See the License for the specific language governing permissions and 22 | # limitations under the License. 23 | #------------------------------------------------------------------------------ 24 | 25 | # Makefile to generate ODPI-C documentation using Sphinx 26 | 27 | SPHINXOPTS = 28 | SPHINXBUILD = sphinx-build 29 | SOURCEDIR = src 30 | BUILDDIR = build 31 | 32 | .PHONY: html 33 | html: 34 | @$(SPHINXBUILD) -M html $(SOURCEDIR) $(BUILDDIR) $(SPHINXOPTS) 35 | 36 | .PHONY: epub 37 | epub: 38 | @$(SPHINXBUILD) -M epub $(SOURCEDIR) $(BUILDDIR) $(SPHINXOPTS) 39 | 40 | .PHONY: pdf 41 | pdf: 42 | @$(SPHINXBUILD) -M latexpdf $(SOURCEDIR) $(BUILDDIR) $(SPHINXOPTS) 43 | 44 | .PHONY: clean 45 | clean: 46 | rm -rf $(BUILDDIR)/* 47 | -------------------------------------------------------------------------------- /doc/README.md: -------------------------------------------------------------------------------- 1 | The generated ODPI-C documentation is at 2 | https://oracle.github.io/odpi/doc/index.html 3 | 4 | This directory contains the documentation source. It is written using reST 5 | (re-Structured Text) format source files which are processed using Sphinx and 6 | turned into HTML, PDF or ePub documents. If you wish to build these yourself, 7 | you need to install Sphinx. Sphinx is available on many Linux distributions as 8 | a pre-built package. You can also install Sphinx on all platforms using the 9 | Python package manager "pip". For more information on Sphinx, please visit this 10 | page: 11 | 12 | http://www.sphinx-doc.org 13 | 14 | Once Sphinx is installed, the supplied Makefile can be used to build the 15 | different targets. The generated ODPI-C documentation found on GitHub can be 16 | built using the command "make html". 17 | -------------------------------------------------------------------------------- /doc/requirements.txt: -------------------------------------------------------------------------------- 1 | sphinx>=4.2.0 2 | sphinx-rtd-theme>=0.5.2 3 | -------------------------------------------------------------------------------- /doc/src/.static/custom.css: -------------------------------------------------------------------------------- 1 | /* Added code to display tables without horizontal scrollbars */ 2 | .wy-table-responsive table td, .wy-table-responsive table th { 3 | white-space: normal; 4 | } 5 | 6 | /* Added code to override the default content width in ReadtheDocs */ 7 | .wy-nav-content { 8 | max-width: none; 9 | } 10 | -------------------------------------------------------------------------------- /doc/src/_ext/parameters_table.py: -------------------------------------------------------------------------------- 1 | #------------------------------------------------------------------------------ 2 | # Copyright (c) 2023, Oracle and/or its affiliates. 3 | # 4 | # This software is dual-licensed to you under the Universal Permissive License 5 | # (UPL) 1.0 as shown at https://oss.oracle.com/licenses/upl and Apache License 6 | # 2.0 as shown at http://www.apache.org/licenses/LICENSE-2.0. You may choose 7 | # either license. 8 | # 9 | # If you elect to accept the software under the Apache License, Version 2.0, 10 | # the following applies: 11 | # 12 | # Licensed under the Apache License, Version 2.0 (the "License"); 13 | # you may not use this file except in compliance with the License. 14 | # You may obtain a copy of the License at 15 | # 16 | # https://www.apache.org/licenses/LICENSE-2.0 17 | # 18 | # Unless required by applicable law or agreed to in writing, software 19 | # distributed under the License is distributed on an "AS IS" BASIS, 20 | # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 21 | # See the License for the specific language governing permissions and 22 | # limitations under the License. 23 | #------------------------------------------------------------------------------ 24 | 25 | #------------------------------------------------------------------------------ 26 | # parameters_table.py 27 | # 28 | # Defines a directive (parameters-table) that creates a table with a specific 29 | # configuration on top of the extended "list-table-with-summary" directive. 30 | #------------------------------------------------------------------------------ 31 | 32 | from docutils.statemachine import ViewList 33 | 34 | import table_with_summary 35 | 36 | class ParametersTable(table_with_summary.ListTableWithSummary): 37 | 38 | def run(self): 39 | self.options["summary"] = \ 40 | "The first column displays the name of the parameter. The " \ 41 | "second column displays the parameter's mode. The third column " \ 42 | "displays the description of the parameter." 43 | self.options["header-rows"] = 1 44 | self.options["class"] = ["wy-table-responsive"] 45 | self.options["widths"] = [10, 5, 35] 46 | headings = ViewList(['* - Parameter', ' - Mode', ' - Description']) 47 | self.content = headings + self.content 48 | return super().run() 49 | 50 | def setup(app): 51 | app.add_directive('parameters-table', ParametersTable) 52 | -------------------------------------------------------------------------------- /doc/src/_ext/table_with_summary.py: -------------------------------------------------------------------------------- 1 | #------------------------------------------------------------------------------ 2 | # Copyright (c) 2022, Oracle and/or its affiliates. 3 | # 4 | # This software is dual-licensed to you under the Universal Permissive License 5 | # (UPL) 1.0 as shown at https://oss.oracle.com/licenses/upl and Apache License 6 | # 2.0 as shown at http://www.apache.org/licenses/LICENSE-2.0. You may choose 7 | # either license. 8 | # 9 | # If you elect to accept the software under the Apache License, Version 2.0, 10 | # the following applies: 11 | # 12 | # Licensed under the Apache License, Version 2.0 (the "License"); 13 | # you may not use this file except in compliance with the License. 14 | # You may obtain a copy of the License at 15 | # 16 | # https://www.apache.org/licenses/LICENSE-2.0 17 | # 18 | # Unless required by applicable law or agreed to in writing, software 19 | # distributed under the License is distributed on an "AS IS" BASIS, 20 | # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 21 | # See the License for the specific language governing permissions and 22 | # limitations under the License. 23 | #------------------------------------------------------------------------------ 24 | 25 | #------------------------------------------------------------------------------ 26 | # table_with_summary.py 27 | # 28 | # Defines a directive (list-table-with-summary) that adds support for a summary 29 | # option on top of the regular "list-table" directive. 30 | #------------------------------------------------------------------------------ 31 | 32 | import sphinx 33 | from docutils.parsers.rst import directives 34 | from docutils.parsers.rst.directives import tables 35 | 36 | from packaging import version 37 | 38 | class ListTableWithSummary(tables.ListTable): 39 | 40 | option_spec = {'summary': directives.unchanged} 41 | option_spec.update(tables.ListTable.option_spec) 42 | 43 | def run(self): 44 | result = super().run() 45 | summary = self.options.get('summary') 46 | if summary: 47 | table_node = result[0] 48 | table_node["summary"] = summary 49 | return result 50 | 51 | 52 | class HTMLTranslator(sphinx.writers.html5.HTML5Translator): 53 | 54 | def visit_paragraph(self, node): 55 | children = node.children 56 | if len(children) == 1 and children[0].astext() == "No relevant notes": 57 | atts = {"style": "clip: rect(1px, 1px, 1px, 1px);" 58 | "clip-path: inset(50%);" 59 | "height: 1px;" 60 | "overflow: hidden;" 61 | "position: absolute;" 62 | "white-space: nowrap;" 63 | "width: 1px;" 64 | } 65 | self.body.append(self.starttag(node, 'p', '', **atts)) 66 | else: 67 | super().visit_paragraph(node) 68 | 69 | def visit_table(self, node): 70 | if version.parse(sphinx.__version__) > version.parse('4.2.0'): 71 | self._table_row_indices = [0] 72 | else: 73 | self._table_row_index = 0 74 | 75 | atts = {} 76 | classes = [cls.strip(' \t\n') \ 77 | for cls in self.settings.table_style.split(',')] 78 | classes.insert(0, "docutils") # compat 79 | 80 | # set align-default if align not specified to give a default style 81 | classes.append('align-%s' % node.get('align', 'default')) 82 | 83 | if 'width' in node: 84 | atts['style'] = 'width: %s' % node['width'] 85 | if 'summary' in node: 86 | atts['summary'] = node['summary'] 87 | tag = self.starttag(node, 'table', CLASS=' '.join(classes), **atts) 88 | self.body.append(tag) 89 | 90 | 91 | def setup(app): 92 | app.add_directive('list-table-with-summary', ListTableWithSummary) 93 | app.set_translator("html", HTMLTranslator, override=True) 94 | -------------------------------------------------------------------------------- /doc/src/conf.py: -------------------------------------------------------------------------------- 1 | #!/usr/bin/env python3 2 | # -*- coding: utf-8 -*- 3 | 4 | #------------------------------------------------------------------------------ 5 | # Copyright (c) 2016, 2025, Oracle and/or its affiliates. 6 | # 7 | # This software is dual-licensed to you under the Universal Permissive License 8 | # (UPL) 1.0 as shown at https://oss.oracle.com/licenses/upl and Apache License 9 | # 2.0 as shown at http://www.apache.org/licenses/LICENSE-2.0. You may choose 10 | # either license. 11 | # 12 | # If you elect to accept the software under the Apache License, Version 2.0, 13 | # the following applies: 14 | # 15 | # Licensed under the Apache License, Version 2.0 (the "License"); 16 | # you may not use this file except in compliance with the License. 17 | # You may obtain a copy of the License at 18 | # 19 | # https://www.apache.org/licenses/LICENSE-2.0 20 | # 21 | # Unless required by applicable law or agreed to in writing, software 22 | # distributed under the License is distributed on an "AS IS" BASIS, 23 | # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 24 | # See the License for the specific language governing permissions and 25 | # limitations under the License. 26 | #------------------------------------------------------------------------------ 27 | 28 | import os 29 | import sys 30 | 31 | # If your extensions are in another directory, add it here. 32 | sys.path.append(os.path.abspath("_ext")) 33 | 34 | # Add any Sphinx extension module names here, as strings. They can be extensions 35 | # coming with Sphinx (named 'sphinx.ext.*') or your custom ones. 36 | extensions = ["table_with_summary", "parameters_table", 'sphinx_rtd_theme'] 37 | 38 | # the location of templates that are being used, relative to this directory 39 | templates_path = ['.templates'] 40 | 41 | # the suffix used for all source files 42 | source_suffix = '.rst' 43 | 44 | # the name of the root document 45 | root_doc = master_doc = 'index' 46 | 47 | # general information about the project 48 | project = 'ODPI-C' 49 | copyright = '2016, 2025, Oracle and/or its affiliates. All rights reserved.' 50 | author = 'Oracle' 51 | 52 | # the version info for the project, acts as replacement for |version| and 53 | # |release|, also used in various other places throughout the built documents 54 | # 55 | # the short X.Y version 56 | version = '5.6' 57 | 58 | # the full version, including alpha/beta/rc tags 59 | release = '5.6.0b1' 60 | 61 | # The name of the Pygments (syntax highlighting) style to use. 62 | pygments_style = 'sphinx' 63 | 64 | # Options for HTML output 65 | # ----------------------- 66 | 67 | # The style sheet to use for HTML and HTML Help pages. A file of that name 68 | # must exist either in Sphinx' static/ path, or in one of the custom paths 69 | # given in html_static_path. 70 | # html_style = 'default.css' 71 | 72 | # The theme to use for readthedocs. 73 | html_theme = 'sphinx_rtd_theme' 74 | 75 | # the name for this set of documents. 76 | html_title = 'ODPI-C v' + release 77 | 78 | # the location for static files (such as style sheets) relative to this 79 | # directory; these are copied after the builtin static files and will overwrite 80 | # them 81 | html_static_path = ['.static'] 82 | 83 | # the location of the favicon to use for all pages 84 | # html_favicon = "_themes/oracle/static/favicon.ico" 85 | 86 | # If not '', a 'Last updated on:' timestamp is inserted at every page bottom, 87 | # using the given strftime format. 88 | html_last_updated_fmt = '%b %d, %Y' 89 | 90 | # If true, the reST sources are included in the HTML build as _sources/. 91 | html_copy_source = False 92 | 93 | # Output file base name for HTML help builder. 94 | htmlhelp_basename = 'oracledbdoc' 95 | 96 | numfig = True 97 | 98 | # default domain is C 99 | primary_domain = "c" 100 | 101 | # Display tables with no horizontal scrollbar 102 | def setup(app): 103 | app.add_css_file('custom.css') 104 | -------------------------------------------------------------------------------- /doc/src/enums/dpiAuthMode.rst: -------------------------------------------------------------------------------- 1 | .. _dpiAuthMode: 2 | 3 | ODPI-C Enumeration dpiAuthMode 4 | ------------------------------ 5 | 6 | This enumeration identifies the mode to use when authorizing connections to the 7 | database. 8 | 9 | .. list-table-with-summary:: 10 | :header-rows: 1 11 | :class: wy-table-responsive 12 | :widths: 15 35 13 | :summary: The first column displays the value of the dpiAuthMode 14 | enumeration. The second column displays the description of the 15 | dpiAuthMode enumeration value. 16 | 17 | * - Value 18 | - Description 19 | * - DPI_MODE_AUTH_DEFAULT 20 | - Default value used when creating connections. 21 | * - DPI_MODE_AUTH_PRELIM 22 | - Used together with DPI_MODE_AUTH_SYSDBA or DPI_MODE_AUTH_SYSOPER to 23 | authenticate for certain administrative tasks (such as starting up or 24 | shutting down the database). 25 | * - DPI_MODE_AUTH_SYSASM 26 | - Authenticates with SYSASM access. The use of this value requires Oracle 27 | Client 12.1 or higher. 28 | * - DPI_MODE_AUTH_SYSBKP 29 | - Authenticates with SYSBACKUP access. The use of this value requires 30 | Oracle Client 12.1 or higher. 31 | * - DPI_MODE_AUTH_SYSDBA 32 | - Authenticates with SYSDBA access. 33 | * - DPI_MODE_AUTH_SYSDGD 34 | - Authenticates with SYSDG access. The use of this value requires Oracle 35 | Client 12.1 or higher. 36 | * - DPI_MODE_AUTH_SYSKMT 37 | - Authenticates with SYSKM access. The use of this value requires Oracle 38 | Client 12.1 or higher. 39 | * - DPI_MODE_AUTH_SYSOPER 40 | - Authenticates with SYSOPER access. 41 | * - DPI_MODE_AUTH_SYSRAC 42 | - Authenticates with SYSRAC access. The use of this value requires Oracle 43 | Client 12.2 or higher. 44 | -------------------------------------------------------------------------------- /doc/src/enums/dpiConnCloseMode.rst: -------------------------------------------------------------------------------- 1 | .. _dpiConnCloseMode: 2 | 3 | ODPI-C Enumeration dpiConnCloseMode 4 | ----------------------------------- 5 | 6 | This enumeration identifies the mode to use when closing connections to the 7 | database. 8 | 9 | .. list-table-with-summary:: 10 | :header-rows: 1 11 | :class: wy-table-responsive 12 | :widths: 15 35 13 | :summary: The first column displays the value of the dpiConnCloseMode 14 | enumeration. The second column displays the description of the 15 | dpiConnCloseMode enumeration value. 16 | 17 | * - Value 18 | - Description 19 | * - DPI_MODE_CONN_CLOSE_DEFAULT 20 | - Default value used when closing connections. 21 | * - DPI_MODE_CONN_CLOSE_DROP 22 | - Causes the session to be dropped from the session pool instead of 23 | simply returned to the pool for future use. 24 | * - DPI_MODE_CONN_CLOSE_RETAG 25 | - Causes the session to be tagged with the tag information given when the 26 | connection is closed. A value of NULL for the tag will cause the tag to 27 | be cleared. 28 | -------------------------------------------------------------------------------- /doc/src/enums/dpiCreateMode.rst: -------------------------------------------------------------------------------- 1 | .. _dpiCreateMode: 2 | 3 | ODPI-C Enumeration dpiCreateMode 4 | -------------------------------- 5 | 6 | This enumeration identifies the mode to use when creating connections to the 7 | database. Note that the OCI objects mode is always enabled. 8 | 9 | .. list-table-with-summary:: 10 | :header-rows: 1 11 | :class: wy-table-responsive 12 | :widths: 15 35 13 | :summary: The first column displays the value of the dpiCreateMode 14 | enumeration. The second column displays the description of the 15 | dpiCreateMode enumeration value. 16 | 17 | * - Value 18 | - Description 19 | * - DPI_MODE_CREATE_DEFAULT 20 | - Default value used when creating connections. 21 | * - DPI_MODE_CREATE_EVENTS 22 | - Enables events mode which is required for the use of advanced queuing 23 | (AQ) and continuous query notification (CQN). 24 | * - DPI_MODE_CREATE_THREADED 25 | - Enables threaded mode. Internal OCI structures not exposed to the user 26 | are protected from concurrent access by multiple threads. Error 27 | information is also managed in thread local storage. 28 | -------------------------------------------------------------------------------- /doc/src/enums/dpiDeqMode.rst: -------------------------------------------------------------------------------- 1 | .. _dpiDeqMode: 2 | 3 | ODPI-C Enumeration dpiDeqMode 4 | ----------------------------- 5 | 6 | This enumeration identifies the modes that are possible when dequeuing messages 7 | from a queue. 8 | 9 | .. list-table-with-summary:: 10 | :header-rows: 1 11 | :class: wy-table-responsive 12 | :widths: 15 35 13 | :summary: The first column displays the value of the dpiDeqMode 14 | enumeration. The second column displays the description of the 15 | dpiDeqMode enumeration value. 16 | 17 | * - Value 18 | - Description 19 | * - DPI_MODE_DEQ_BROWSE 20 | - Read the message without acquiring a lock on the message (equivalent 21 | to a SELECT statement). 22 | * - DPI_MODE_DEQ_LOCKED 23 | - Read the message and obtain a write lock on the message (equivalent 24 | to a SELECT FOR UPDATE statement). 25 | * - DPI_MODE_DEQ_REMOVE 26 | - Read the message and update or delete it. This is the default mode. 27 | Note that the message may be retained in the queue table based on 28 | retention properties. 29 | * - DPI_MODE_DEQ_REMOVE_NO_DATA 30 | - Confirms receipt of the message but does not deliver the actual message 31 | content. 32 | -------------------------------------------------------------------------------- /doc/src/enums/dpiDeqNavigation.rst: -------------------------------------------------------------------------------- 1 | .. _dpiDeqNavigation: 2 | 3 | ODPI-C Enumeration dpiDeqNavigation 4 | ----------------------------------- 5 | 6 | This enumeration identifies the method used for determining which message is to 7 | be dequeued from a queue. 8 | 9 | .. list-table-with-summary:: 10 | :header-rows: 1 11 | :class: wy-table-responsive 12 | :widths: 15 35 13 | :summary: The first column displays the value of the dpiDeqNavigation 14 | enumeration. The second column displays the description of the 15 | dpiDeqNavigation enumeration value. 16 | 17 | * - Value 18 | - Description 19 | * - DPI_DEQ_NAV_FIRST_MSG 20 | - Retrieves the first available message that matches the search criteria. 21 | This resets the position to the beginning of the queue. 22 | * - DPI_DEQ_NAV_NEXT_MSG 23 | - Retrieves the next available message that matches the search criteria. 24 | This is the default method. 25 | * - DPI_DEQ_NAV_NEXT_TRANSACTION 26 | - Skips the remainder of the current transaction group (if any) and 27 | retrieves the first message of the next transaction group. This option 28 | can only be used if message grouping is enabled for the queue. 29 | -------------------------------------------------------------------------------- /doc/src/enums/dpiEventType.rst: -------------------------------------------------------------------------------- 1 | .. _dpiEventType: 2 | 3 | ODPI-C Enumeration dpiEventType 4 | ------------------------------- 5 | 6 | This enumeration identifies the types of events that can take place. The event 7 | type is part of the messages that are sent to subscriptions. 8 | 9 | .. list-table-with-summary:: 10 | :header-rows: 1 11 | :class: wy-table-responsive 12 | :widths: 15 35 13 | :summary: The first column displays the value of the dpiEventType 14 | enumeration. The second column displays the description of the 15 | dpiEventType enumeration value. 16 | 17 | * - Value 18 | - Description 19 | * - DPI_EVENT_AQ 20 | - Indicates that a queue has messages available to dequeue. 21 | * - DPI_EVENT_DEREG 22 | - Indicates that a subscription is no longer registered with the database 23 | and will no longer generate events. 24 | * - DPI_EVENT_NONE 25 | - Indicates that no event has taken place. 26 | * - DPI_EVENT_OBJCHANGE 27 | - Indicates that an object change has taken place. 28 | * - DPI_EVENT_QUERYCHANGE 29 | - Indicates that a query change has taken place. 30 | * - DPI_EVENT_SHUTDOWN 31 | - Indicates that a database is being shut down. 32 | * - DPI_EVENT_SHUTDOWN_ANY 33 | - Indicates that an instance of Oracle Real Application Clusters (RAC) is 34 | being shut down. 35 | * - DPI_EVENT_STARTUP 36 | - Indicates that a database is being started up. 37 | -------------------------------------------------------------------------------- /doc/src/enums/dpiExecMode.rst: -------------------------------------------------------------------------------- 1 | .. _dpiExecMode: 2 | 3 | ODPI-C Enumeration dpiExecMode 4 | ------------------------------ 5 | 6 | This enumeration identifies the available modes for executing statements 7 | using :func:`dpiStmt_execute()` and :func:`dpiStmt_executeMany()`. 8 | 9 | .. list-table-with-summary:: 10 | :header-rows: 1 11 | :class: wy-table-responsive 12 | :widths: 15 35 13 | :summary: The first column displays the value of the dpiExecMode 14 | enumeration. The second column displays the description of the 15 | dpiExecMode enumeration value. 16 | 17 | * - Value 18 | - Description 19 | * - DPI_MODE_EXEC_ARRAY_DML_ROWCOUNTS 20 | - Enable getting row counts for each DML operation when performing an 21 | array DML execution. The actual row counts can be retrieved using the 22 | function :func:`dpiStmt_getRowCounts()`. 23 | * - DPI_MODE_EXEC_BATCH_ERRORS 24 | - Enable batch error mode. This permits an an array DML operation to 25 | succeed even if some of the individual operations fail. The errors can 26 | be retrieved using the function :func:`dpiStmt_getBatchErrors()`. 27 | * - DPI_MODE_EXEC_COMMIT_ON_SUCCESS 28 | - If execution completes successfully, the current active transaction is 29 | committed. 30 | * - DPI_MODE_EXEC_DEFAULT 31 | - Default mode for execution. Metadata is made available after queries 32 | are executed. 33 | * - DPI_MODE_EXEC_DESCRIBE_ONLY 34 | - Do not execute the statement but simply acquire the metadata for the 35 | query. 36 | * - DPI_MODE_EXEC_PARSE_ONLY 37 | - Do not execute the statement but only parse it and return any parse 38 | errors. Note that using this mode with a DDL statement will result in 39 | the statement being executed. 40 | -------------------------------------------------------------------------------- /doc/src/enums/dpiFetchMode.rst: -------------------------------------------------------------------------------- 1 | .. _dpiFetchMode: 2 | 3 | ODPI-C Enumeration dpiFetchMode 4 | ------------------------------- 5 | 6 | This enumeration identifies the mode to use when scrolling the cursor to a new 7 | location using the function :func:`dpiStmt_scroll()`. 8 | 9 | .. list-table-with-summary:: 10 | :header-rows: 1 11 | :class: wy-table-responsive 12 | :widths: 15 35 13 | :summary: The first column displays the value of the dpiFetchMode 14 | enumeration. The second column displays the description of the 15 | dpiFetchMode enumeration value. 16 | 17 | * - Value 18 | - Description 19 | * - DPI_MODE_FETCH_ABSOLUTE 20 | - Scroll the cursor to the row identified by the offset parameter using 21 | absolute positioning. 22 | * - DPI_MODE_FETCH_FIRST 23 | - Scroll the cursor to the first row in the result set. The offset is 24 | ignored when using this mode. 25 | * - DPI_MODE_FETCH_LAST 26 | - Scroll the cursor to the last row in the result set. The offset is 27 | ignored when using this mode. 28 | * - DPI_MODE_FETCH_NEXT 29 | - Scroll the cursor to the next row in the result set. The offset is 30 | ignored when using this mode. 31 | * - DPI_MODE_FETCH_PRIOR 32 | - Scroll the cursor to the previous row in the result set. The offset is 33 | ignored when using this mode. 34 | * - DPI_MODE_FETCH_RELATIVE 35 | - Scroll the cursor to the row identified by the offset parameter using 36 | relative positioning. A positive number will move forward in the result 37 | set while a negative number will move backwards in the result set. 38 | -------------------------------------------------------------------------------- /doc/src/enums/dpiJsonOptions.rst: -------------------------------------------------------------------------------- 1 | .. _dpiJsonOptions: 2 | 3 | ODPI-C Enumeration dpiJsonOptions 4 | --------------------------------- 5 | 6 | This enumeration identifies the options that can be used when calling 7 | :func:`dpiJson_getValue()`. 8 | 9 | .. list-table-with-summary:: 10 | :header-rows: 1 11 | :class: wy-table-responsive 12 | :widths: 15 35 13 | :summary: The first column displays the value of the dpiJsonOptions 14 | enumeration. The second column displays the description of the 15 | dpiJsonOptions enumeration value. 16 | 17 | * - Value 18 | - Description 19 | * - DPI_JSON_OPT_DATE_AS_DOUBLE 20 | - Convert values that are stored as Oracle dates and timestamps in the 21 | JSON value into double values (number of milliseconds since 22 | January 1, 1970). 23 | * - DPI_JSON_OPT_DEFAULT 24 | - Default value. 25 | * - DPI_JSON_OPT_NUMBER_AS_STRING 26 | - Convert values that are stored as Oracle numbers in the JSON value into 27 | strings in order to retain precision. 28 | -------------------------------------------------------------------------------- /doc/src/enums/dpiMessageDeliveryMode.rst: -------------------------------------------------------------------------------- 1 | .. _dpiMessageDeliveryMode: 2 | 3 | ODPI-C Enumeration dpiMessageDeliveryMode 4 | ----------------------------------------- 5 | 6 | This enumeration identifies the delivery mode used for filtering messages 7 | when dequeuing messages from a queue. 8 | 9 | .. list-table-with-summary:: 10 | :header-rows: 1 11 | :class: wy-table-responsive 12 | :widths: 15 35 13 | :summary: The first column displays the value of the dpiMessageDeliveryMode 14 | enumeration. The second column displays the description of the 15 | dpiMessageDeliveryMode enumeration value. 16 | 17 | * - Value 18 | - Description 19 | * - DPI_MODE_MSG_BUFFERED 20 | - Dequeue only buffered messages from the queue. 21 | * - DPI_MODE_MSG_PERSISTENT 22 | - Dequeue only persistent messages from the queue. This is the default 23 | mode. 24 | * - DPI_MODE_MSG_PERSISTENT_OR_BUFFERED 25 | - Dequeue both persistent and buffered messages from the queue. 26 | -------------------------------------------------------------------------------- /doc/src/enums/dpiMessageState.rst: -------------------------------------------------------------------------------- 1 | .. _dpiMessageState: 2 | 3 | ODPI-C Enumeration dpiMessageState 4 | ---------------------------------- 5 | 6 | This enumeration identifies the possible states for messages in a queue. 7 | 8 | .. list-table-with-summary:: 9 | :header-rows: 1 10 | :class: wy-table-responsive 11 | :widths: 15 35 12 | :width: 100% 13 | :summary: The first column displays the value of the dpiMessageState 14 | enumeration. The second column displays the description of the 15 | dpiMessageState enumeration value. 16 | 17 | * - Value 18 | - Description 19 | * - DPI_MSG_STATE_EXPIRED 20 | - The message has been moved to the exception queue. 21 | * - DPI_MSG_STATE_PROCESSED 22 | - The message has already been processed and is retained. 23 | * - DPI_MSG_STATE_READY 24 | - The message is ready to be processed. 25 | * - DPI_MSG_STATE_WAITING 26 | - The message is waiting for the delay time to expire. 27 | -------------------------------------------------------------------------------- /doc/src/enums/dpiNativeTypeNum.rst: -------------------------------------------------------------------------------- 1 | .. _dpiNativeTypeNum: 2 | 3 | ODPI-C Enumeration dpiNativeTypeNum 4 | ----------------------------------- 5 | 6 | This enumeration identifies the type of data that is being transferred to and 7 | from the database. It is used in the structures 8 | :ref:`dpiDataTypeInfo`, 9 | :ref:`dpiShardingKeyColumn` and 10 | :ref:`dpiJsonNode`. 11 | 12 | .. list-table-with-summary:: 13 | :header-rows: 1 14 | :class: wy-table-responsive 15 | :widths: 15 35 16 | :summary: The first column displays the value of the dpiNativeTypeNum 17 | enumeration. The second column displays the description of the 18 | dpiNativeTypeNum enumeration value. 19 | 20 | * - Value 21 | - Description 22 | * - DPI_NATIVE_TYPE_BOOLEAN 23 | - Data is passed as a boolean value in :member:`dpiDataBuffer.asBoolean`. 24 | * - DPI_NATIVE_TYPE_BYTES 25 | - Data is passed as a byte string in :member:`dpiDataBuffer.asBytes`. 26 | * - DPI_NATIVE_TYPE_DOUBLE 27 | - Data is passed as a double precision floating point number in 28 | :member:`dpiDataBuffer.asDouble`. 29 | * - DPI_NATIVE_TYPE_FLOAT 30 | - Data is passed as a single precision floating point number in 31 | :member:`dpiDataBuffer.asFloat`. 32 | * - DPI_NATIVE_TYPE_INT64 33 | - Data is passed as a 64-bit integer in :member:`dpiDataBuffer.asInt64`. 34 | * - DPI_NATIVE_TYPE_INTERVAL_DS 35 | - Data is passed as an interval (days to seconds) in 36 | :member:`dpiDataBuffer.asIntervalDS`. 37 | * - DPI_NATIVE_TYPE_INTERVAL_YM 38 | - Data is passed as an interval (years to months) in 39 | :member:`dpiDataBuffer.asIntervalYM`. 40 | * - DPI_NATIVE_TYPE_JSON 41 | - Data is passed as a JSON node in :member:`dpiDataBuffer.asJsonNode`. 42 | * - DPI_NATIVE_TYPE_JSON_ARRAY 43 | - Data is passed as a JSON array in :member:`dpiDataBuffer.asJsonArray`. 44 | * - DPI_NATIVE_TYPE_JSON_OBJECT 45 | - Data is passed as a JSON object in 46 | :member:`dpiDataBuffer.asJsonObject`. 47 | * - DPI_NATIVE_TYPE_LOB 48 | - Data is passed as a reference to a LOB in 49 | :member:`dpiDataBuffer.asLOB`. 50 | * - DPI_NATIVE_TYPE_NULL 51 | - No data is being passed. This is used to identify the JSON singleton 52 | null value. 53 | * - DPI_NATIVE_TYPE_OBJECT 54 | - Data is passed as a reference to an object in 55 | :member:`dpiDataBuffer.asObject`. 56 | * - DPI_NATIVE_TYPE_ROWID 57 | - Data is passed as a reference to a rowid in 58 | :member:`dpiDataBuffer.asRowid`. 59 | * - DPI_NATIVE_TYPE_STMT 60 | - Data is passed as a reference to a statement in 61 | :member:`dpiDataBuffer.asStmt`. 62 | * - DPI_NATIVE_TYPE_TIMESTAMP 63 | - Data is passed as a timestamp in :member:`dpiDataBuffer.asTimestamp`. 64 | * - DPI_NATIVE_TYPE_UINT64 65 | - Data is passed as an unsigned 64-bit integer in 66 | :member:`dpiDataBuffer.asUint64`. 67 | * - DPI_NATIVE_TYPE_VECTOR 68 | - Data is passed as a reference to a vector in 69 | :member:`dpiDataBuffer.asVector`. 70 | -------------------------------------------------------------------------------- /doc/src/enums/dpiOpCode.rst: -------------------------------------------------------------------------------- 1 | .. _dpiOpCode: 2 | 3 | ODPI-C Enumeration dpiOpCode 4 | ---------------------------- 5 | 6 | This enumeration identifies the types of operations that can take place during 7 | object change and query change notification. It is used both as a filter when 8 | determining which operations to consider when sending notifications as well as 9 | identifying the operation that took place on a particular table or row when a 10 | notification is sent. Multiple values can be OR'ed together to specify multiple 11 | types of operations at the same time. 12 | 13 | .. list-table-with-summary:: 14 | :header-rows: 1 15 | :class: wy-table-responsive 16 | :widths: 15 35 17 | :summary: The first column displays the value of the dpiOpCode 18 | enumeration. The second column displays the description of the 19 | dpiOpCode enumeration value. 20 | 21 | * - Value 22 | - Description 23 | * - DPI_OPCODE_ALL_OPS 24 | - Indicates that notifications should be sent for all operations on the 25 | table or query. 26 | * - DPI_OPCODE_ALL_ROWS 27 | - Indicates that all rows have been changed in the table or query (or 28 | too many rows were changed or row information was not requested). 29 | * - DPI_OPCODE_ALTER 30 | - Indicates that the registered table or query has been altered. 31 | * - DPI_OPCODE_DELETE 32 | - Indicates that a delete operation has taken place in the table or 33 | query. 34 | * - DPI_OPCODE_DROP 35 | - Indicates that the registered table or query has been dropped. 36 | * - DPI_OPCODE_INSERT 37 | - Indicates that an insert operation has taken place in the table or 38 | query. 39 | * - DPI_OPCODE_UPDATE 40 | - Indicates that an update operation has taken place in the table or 41 | query. 42 | * - DPI_OPCODE_UNKNOWN 43 | - An unknown operation has taken place. 44 | -------------------------------------------------------------------------------- /doc/src/enums/dpiPoolCloseMode.rst: -------------------------------------------------------------------------------- 1 | .. _dpiPoolCloseMode: 2 | 3 | ODPI-C Enumeration dpiPoolCloseMode 4 | ----------------------------------- 5 | 6 | This enumeration identifies the mode to use when closing pools. 7 | 8 | .. list-table-with-summary:: 9 | :header-rows: 1 10 | :class: wy-table-responsive 11 | :widths: 15 35 12 | :summary: The first column displays the value of the dpiPoolCloseMode 13 | enumeration. The second column displays the description of the 14 | dpiPoolCloseMode enumeration value. 15 | 16 | * - Value 17 | - Description 18 | * - DPI_MODE_POOL_CLOSE_DEFAULT 19 | - Default value used when closing pools. If there are any active sessions 20 | in the pool an error will be raised. 21 | * - DPI_MODE_POOL_CLOSE_FORCE 22 | - Causes all of the active connections in the pool to be closed before 23 | closing the pool itself. 24 | -------------------------------------------------------------------------------- /doc/src/enums/dpiPoolGetMode.rst: -------------------------------------------------------------------------------- 1 | .. _dpiPoolGetMode: 2 | 3 | ODPI-C Enumeration dpiPoolGetMode 4 | --------------------------------- 5 | 6 | This enumeration identifies the mode to use when getting sessions from a 7 | session pool. 8 | 9 | .. list-table-with-summary:: 10 | :header-rows: 1 11 | :class: wy-table-responsive 12 | :widths: 15 35 13 | :summary: The first column displays the value of the dpiPoolGetMode 14 | enumeration. The second column displays the description of the 15 | dpiPoolGetMode enumeration value. 16 | 17 | * - Value 18 | - Description 19 | * - DPI_MODE_POOL_GET_FORCEGET 20 | - Specifies that a new session should be created if all of the sessions 21 | in the pool are busy, even if this exceeds the maximum sessions 22 | allowable for the session pool (see 23 | :member:`dpiPoolCreateParams.maxSessions`). 24 | * - DPI_MODE_POOL_GET_NOWAIT 25 | - Specifies that the caller should return immediately, regardless of 26 | whether a session is available in the pool. If a session is not 27 | available an error is returned. 28 | * - DPI_MODE_POOL_GET_TIMEDWAIT 29 | - Specifies that the caller should block until a session is available 30 | from the pool, but only for the specified length of time defined in 31 | :member:`dpiPoolCreateParams.waitTimeout`. If a session is not 32 | available within the specified period of time an error is returned. 33 | * - DPI_MODE_POOL_GET_WAIT 34 | - Specifies that the caller should block until a session is available 35 | from the pool. 36 | -------------------------------------------------------------------------------- /doc/src/enums/dpiPurity.rst: -------------------------------------------------------------------------------- 1 | .. _dpiPurity: 2 | 3 | ODPI-C Enumeration dpiPurity 4 | ---------------------------- 5 | 6 | This enumeration identifies the purity of the sessions that are acquired when 7 | using connection classes during connection creation. 8 | 9 | .. list-table-with-summary:: 10 | :header-rows: 1 11 | :class: wy-table-responsive 12 | :widths: 15 35 13 | :summary: The first column displays the value of the dpiPurity 14 | enumeration. The second column displays the description of the 15 | dpiPurity enumeration value. 16 | 17 | * - Value 18 | - Description 19 | * - DPI_PURITY_DEFAULT 20 | - Default value used when creating connections. 21 | * - DPI_PURITY_NEW 22 | - A connection is required that has not been tainted with any prior 23 | session state. 24 | * - DPI_PURITY_SELF 25 | - A connection is permitted to have prior session state. 26 | -------------------------------------------------------------------------------- /doc/src/enums/dpiServerType.rst: -------------------------------------------------------------------------------- 1 | .. _dpiServerType: 2 | 3 | ODPI-C Enumeration dpiServerType 4 | -------------------------------- 5 | 6 | This enumeration identifies the type of server process associated with a 7 | connection. It is only available with Oracle Client libraries 23.4 or higher. 8 | 9 | .. list-table-with-summary:: 10 | :header-rows: 1 11 | :class: wy-table-responsive 12 | :widths: 15 35 13 | :summary: The first column displays the value of the dpiServerType 14 | enumeration. The second column displays the description of the 15 | dpiServerType enumeration value. 16 | 17 | * - Value 18 | - Description 19 | * - DPI_SERVER_TYPE_DEDICATED 20 | - A dedicated server process is being used with the connection. 21 | * - DPI_SERVER_TYPE_POOLED 22 | - A pooled server process (DRCP) is being used with the connection. 23 | * - DPI_SERVER_TYPE_SHARED 24 | - A shared server process is being used with the connection. 25 | * - DPI_SERVER_TYPE_UNKNOWN 26 | - The type of server process is unknown. 27 | -------------------------------------------------------------------------------- /doc/src/enums/dpiShutdownMode.rst: -------------------------------------------------------------------------------- 1 | .. _dpiShutdownMode: 2 | 3 | ODPI-C Enumeration dpiShutdownMode 4 | ---------------------------------- 5 | 6 | This enumeration identifies the mode to use when shutting down a database 7 | using :func:`dpiConn_shutdownDatabase()`. 8 | 9 | .. list-table-with-summary:: 10 | :header-rows: 1 11 | :class: wy-table-responsive 12 | :widths: 10 35 13 | :summary: The first column displays the value of the dpiShutdownMode 14 | enumeration. The second column displays the description of the 15 | dpiShutdownMode enumeration value. 16 | 17 | * - Value 18 | - Description 19 | * - DPI_MODE_SHUTDOWN_ABORT 20 | - All uncommitted transactions are terminated and are not rolled back. 21 | This is the fastest way to shut down the database but the next database 22 | startup may require instance recovery. 23 | * - DPI_MODE_SHUTDOWN_DEFAULT 24 | - Further connections to the database are prohibited. Wait for users to 25 | disconnect from the database. 26 | * - DPI_MODE_SHUTDOWN_FINAL 27 | - Shuts down the database. This mode should only be used in the second 28 | call to :func:`dpiConn_shutdownDatabase()`. 29 | * - DPI_MODE_SHUTDOWN_IMMEDIATE 30 | - All uncommitted transactions are terminated and rolled back and all 31 | connections to the database are closed immediately. 32 | * - DPI_MODE_SHUTDOWN_TRANSACTIONAL 33 | - Further connections to the database are prohibited and no new 34 | transactions are allowed to be started. Wait for active transactions 35 | to complete. 36 | * - DPI_MODE_SHUTDOWN_TRANSACTIONAL_LOCAL 37 | - Behaves the same way as DPI_MODE_SHUTDOWN_TRANSACTIONAL but only waits 38 | for local transactions to complete. 39 | -------------------------------------------------------------------------------- /doc/src/enums/dpiSodaFlags.rst: -------------------------------------------------------------------------------- 1 | .. _dpiSodaFlags: 2 | 3 | ODPI-C Enumeration dpiSodaFlags 4 | ------------------------------- 5 | 6 | This enumeration identifies the flags that can be used with SODA functions. 7 | 8 | .. list-table-with-summary:: 9 | :header-rows: 1 10 | :class: wy-table-responsive 11 | :widths: 15 35 12 | :summary: The first column displays the value of the dpiSodaFlags 13 | enumeration. The second column displays the description of the 14 | dpiSodaFlags enumeration value. 15 | 16 | * - Value 17 | - Description 18 | * - DPI_SODA_FLAGS_ATOMIC_COMMIT 19 | - If the function completes successfully the current transaction is 20 | committed. If it does not complete successfully, no changes to the 21 | database are made and the existing transaction is left untouched. 22 | * - DPI_SODA_FLAGS_CREATE_COLL_MAP 23 | - Create collection in MAP mode. This mode is only supported in 24 | :func:`dpiSodaDb_createCollection()`. 25 | * - DPI_SODA_FLAGS_DEFAULT 26 | - Default value. 27 | * - DPI_SODA_FLAGS_INDEX_DROP_FORCE 28 | - Forcibly drop the index. This mode is only supported in 29 | :func:`dpiSodaColl_dropIndex()`. 30 | -------------------------------------------------------------------------------- /doc/src/enums/dpiStartupMode.rst: -------------------------------------------------------------------------------- 1 | .. _dpiStartupMode: 2 | 3 | ODPI-C Enumeration dpiStartupMode 4 | --------------------------------- 5 | 6 | This enumeration identifies the mode to use when starting up a database using 7 | :func:`dpiConn_startupDatabase()`. 8 | 9 | .. list-table-with-summary:: 10 | :header-rows: 1 11 | :class: wy-table-responsive 12 | :widths: 15 35 13 | :summary: The first column displays the value of the dpiStartupMode 14 | enumeration. The second column displays the description of the 15 | dpiStartupMode enumeration value. 16 | 17 | * - Value 18 | - Description 19 | * - DPI_MODE_STARTUP_DEFAULT 20 | - Default mode for startup which permits database access to all users. 21 | * - DPI_MODE_STARTUP_FORCE 22 | - Shuts down a running instance (using ABORT) before starting a new one. 23 | This mode should only be used in unusual circumstances. 24 | * - DPI_MODE_STARTUP_RESTRICT 25 | - Only allows database access to users with both the CREATE SESSION and 26 | RESTRICTED SESSION privileges (normally the DBA). 27 | -------------------------------------------------------------------------------- /doc/src/enums/dpiStatementType.rst: -------------------------------------------------------------------------------- 1 | .. _dpiStatementType: 2 | 3 | ODPI-C Enumeration dpiStatementType 4 | ----------------------------------- 5 | 6 | This enumeration identifies the type of statement that has been prepared. It is 7 | available as part of the structure :ref:`dpiStmtInfo`. 8 | 9 | .. list-table-with-summary:: 10 | :header-rows: 1 11 | :class: wy-table-responsive 12 | :widths: 15 35 13 | :summary: The first column displays the value of the dpiStatementType 14 | enumeration. The second column displays the description of the 15 | dpiStatementType enumeration value. 16 | 17 | * - Value 18 | - Description 19 | * - DPI_STMT_TYPE_ALTER 20 | - Identifies an alter statement. The member :member:`dpiStmtInfo.isDDL` 21 | will be set to 1. 22 | * - DPI_STMT_TYPE_BEGIN 23 | - Identifies an anonymous PL/SQL block starting with the keyword begin. 24 | The member :member:`dpiStmtInfo.isPLSQL` will be set to 1. 25 | * - DPI_STMT_TYPE_CALL 26 | - Identifies a CALL statement used for calling stored procedures and 27 | functions. The member :member:`dpiStmtInfo.isPLSQL` will be set to 1. 28 | * - DPI_STMT_TYPE_COMMIT 29 | - Identifies a commit statement. 30 | * - DPI_STMT_TYPE_CREATE 31 | - Identifies a create statement. The member :member:`dpiStmtInfo.isDDL` 32 | will be set to 1. 33 | * - DPI_STMT_TYPE_DECLARE 34 | - Identifies an anonymous PL/SQL block starting with the keyword 35 | declare. The member :member:`dpiStmtInfo.isPLSQL` will be set to 1. 36 | * - DPI_STMT_TYPE_DELETE 37 | - Identifies a delete statement. The member :member:`dpiStmtInfo.isDML` 38 | will be set to 1. 39 | * - DPI_STMT_TYPE_DROP 40 | - Identifies a drop statement. The member :member:`dpiStmtInfo.isDDL` 41 | will be set to 1. 42 | * - DPI_STMT_TYPE_EXPLAIN_PLAN 43 | - Identifies an explain plan statement. The member 44 | :member:`dpiStmtInfo.isDML` will be set to 1. 45 | * - DPI_STMT_TYPE_INSERT 46 | - Identifies an insert statement. The member :member:`dpiStmtInfo.isDML` 47 | will be set to 1. 48 | * - DPI_STMT_TYPE_MERGE 49 | - Identifies a merge statement. The member :member:`dpiStmtInfo.isDML` 50 | will be set to 1. 51 | * - DPI_STMT_TYPE_ROLLBACK 52 | - Identifies a rollback statement. 53 | * - DPI_STMT_TYPE_SELECT 54 | - Identifies a select statement. The member :member:`dpiStmtInfo.isQuery` 55 | will be set to 1. 56 | * - DPI_STMT_TYPE_UPDATE 57 | - Identifies an update statement. The member :member:`dpiStmtInfo.isDML` 58 | will be set to 1. 59 | * - DPI_STMT_TYPE_UNKNOWN 60 | - Indicates that the statement type is unknown. 61 | -------------------------------------------------------------------------------- /doc/src/enums/dpiSubscrGroupingClass.rst: -------------------------------------------------------------------------------- 1 | .. _dpiSubscrGroupingClass: 2 | 3 | ODPI-C Enumeration dpiSubscrGroupingClass 4 | ----------------------------------------- 5 | 6 | This enumeration identifies the grouping class. Instead of individual events 7 | being delivered to the callback, events are grouped before being sent to the 8 | callback. This enumeration is used in the 9 | :ref:`dpiSubscrCreateParams` structure. 10 | 11 | .. list-table-with-summary:: 12 | :header-rows: 1 13 | :class: wy-table-responsive 14 | :widths: 15 35 15 | :summary: The first column displays the value of the dpiSubscrGroupingClass 16 | enumeration. The second column displays the description of the 17 | dpiSubscrGroupingClass enumeration value. 18 | 19 | * - Value 20 | - Description 21 | * - DPI_SUBSCR_GROUPING_CLASS_TIME 22 | - Events are grouped by the period of time in which they are received. 23 | -------------------------------------------------------------------------------- /doc/src/enums/dpiSubscrGroupingType.rst: -------------------------------------------------------------------------------- 1 | .. _dpiSubscrGroupingType: 2 | 3 | ODPI-C Enumeration dpiSubscrGroupingType 4 | ---------------------------------------- 5 | 6 | This enumeration identifies the grouping type. It is used in the 7 | :ref:`dpiSubscrCreateParams` structure. 8 | 9 | .. list-table-with-summary:: 10 | :header-rows: 1 11 | :class: wy-table-responsive 12 | :widths: 15 35 13 | :summary: The first column displays the value of the dpiSubscrGroupingType 14 | enumeration. The second column displays the description of the 15 | dpiSubscrGroupingType enumeration value. 16 | 17 | * - Value 18 | - Description 19 | * - DPI_SUBSCR_GROUPING_TYPE_LAST 20 | - The last event in the group is sent. 21 | * - DPI_SUBSCR_GROUPING_TYPE_SUMMARY 22 | - A summary of all events in the group is sent. This is also the default 23 | value. 24 | -------------------------------------------------------------------------------- /doc/src/enums/dpiSubscrNamespace.rst: -------------------------------------------------------------------------------- 1 | .. _dpiSubscrNamespace: 2 | 3 | ODPI-C Enumeration dpiSubscrNamespace 4 | ------------------------------------- 5 | 6 | This enumeration identifies the namespaces supported by subscriptions. 7 | 8 | .. list-table-with-summary:: 9 | :header-rows: 1 10 | :class: wy-table-responsive 11 | :widths: 15 35 12 | :summary: The first column displays the value of the dpiSubscrNamespace 13 | enumeration. The second column displays the description of the 14 | dpiSubscrNamespace enumeration value. 15 | 16 | * - Value 17 | - Description 18 | * - DPI_SUBSCR_NAMESPACE_AQ 19 | - Identifies the namespace used for receiving notifications when messages 20 | are available to be dequeued in advanced queueing (AQ). 21 | * - DPI_SUBSCR_NAMESPACE_DBCHANGE 22 | - Identifies the namespace used for receiving notifications for database 23 | object changes and query changes (CQN). 24 | -------------------------------------------------------------------------------- /doc/src/enums/dpiSubscrProtocol.rst: -------------------------------------------------------------------------------- 1 | .. _dpiSubscrProtocol: 2 | 3 | ODPI-C Enumeration dpiSubscrProtocol 4 | ------------------------------------ 5 | 6 | This enumeration identifies the protocol used for sending notifications to 7 | subscriptions. 8 | 9 | .. list-table-with-summary:: 10 | :header-rows: 1 11 | :class: wy-table-responsive 12 | :widths: 15 35 13 | :summary: The first column displays the value of the dpiSubscrProtocol 14 | enumeration. The second column displays the description of the 15 | dpiSubscrProtocol enumeration value. 16 | 17 | * - Value 18 | - Description 19 | * - DPI_SUBSCR_PROTO_CALLBACK 20 | - Notifications are sent by calling the callback specified when the 21 | subscription was registered. 22 | * - DPI_SUBSCR_PROTO_HTTP 23 | - Notifications are sent to the URL specified when the subscription 24 | was registered. 25 | * - DPI_SUBSCR_PROTO_MAIL 26 | - Notifications are sent by sending an e-mail to the e-mail address 27 | specified when the subscription was registered. 28 | * - DPI_SUBSCR_PROTO_PLSQL 29 | - Notifications are sent by calling the PL/SQL procedure specified when 30 | the subscription was registered. 31 | -------------------------------------------------------------------------------- /doc/src/enums/dpiSubscrQOS.rst: -------------------------------------------------------------------------------- 1 | .. _dpiSubscrQOS: 2 | 3 | ODPI-C Enumeration dpiSubscrQOS 4 | ------------------------------- 5 | 6 | This enumeration identifies the quality of service flags for sending 7 | notifications to subscriptions. 8 | 9 | .. list-table-with-summary:: 10 | :header-rows: 1 11 | :class: wy-table-responsive 12 | :widths: 15 35 13 | :summary: The first column displays the value of the dpiSubscrQOS 14 | enumeration. The second column displays the description of the 15 | dpiSubscrQOS enumeration value. 16 | 17 | * - Value 18 | - Description 19 | * - DPI_SUBSCR_QOS_BEST_EFFORT 20 | - Perform query notification in best effort mode which may result in 21 | notifications being sent when the query has not in fact changed. This 22 | is needed for complex queries that cannot be registered in guaranteed 23 | mode. 24 | * - DPI_SUBSCR_QOS_DEREG_NFY 25 | - When the notification has been received, the subscription is removed. 26 | * - DPI_SUBSCR_QOS_QUERY 27 | - Perform query notification instead of database change notification. 28 | Notification is done in guaranteed mode which guarantees that the query 29 | has in fact changed. 30 | * - DPI_SUBSCR_QOS_RELIABLE 31 | - Notifications are sent reliably. If the database fails, the notifications 32 | are not lost. This is not supported for nonpersistent queues or buffered 33 | messaging. 34 | * - DPI_SUBSCR_QOS_ROWIDS 35 | - Information on the rows affected by the database or query change is 36 | sent along with the notification. 37 | -------------------------------------------------------------------------------- /doc/src/enums/dpiTpcBeginFlags.rst: -------------------------------------------------------------------------------- 1 | .. _dpiTpcBeginFlags: 2 | 3 | ODPI-C Enumeration dpiTpcBeginFlags 4 | ----------------------------------- 5 | 6 | This enumeration identifies the flags that can be used when calling 7 | :func:`dpiConn_tpcBegin()`. 8 | 9 | .. list-table-with-summary:: 10 | :header-rows: 1 11 | :class: wy-table-responsive 12 | :widths: 15 35 13 | :width: 100% 14 | :summary: The first column displays the value of the dpiTpcBeginFlags 15 | enumeration. The second column displays the description of the 16 | dpiTpcBeginFlags enumeration value. 17 | 18 | * - Value 19 | - Description 20 | * - DPI_TPC_BEGIN_JOIN 21 | - Joins an existing global transaction. 22 | * - DPI_TPC_BEGIN_NEW 23 | - Creates a new global transaction. 24 | * - DPI_TPC_BEGIN_PROMOTE 25 | - Promotes a local transaction to a global transaction. 26 | * - DPI_TPC_BEGIN_RESUME 27 | - Resumes an existing global transaction. 28 | -------------------------------------------------------------------------------- /doc/src/enums/dpiTpcEndFlags.rst: -------------------------------------------------------------------------------- 1 | .. _dpiTpcEndFlags: 2 | 3 | ODPI-C Enumeration dpiTpcEndFlags 4 | --------------------------------- 5 | 6 | This enumeration identifies the flags that can be used when calling 7 | :func:`dpiConn_tpcEnd()`. 8 | 9 | .. list-table-with-summary:: 10 | :header-rows: 1 11 | :class: wy-table-responsive 12 | :widths: 15 35 13 | :width: 100% 14 | :summary: The first column displays the value of the dpiTpcEndFlags 15 | enumeration. The second column displays the description of the 16 | dpiTpcEndFlags enumeration value. 17 | 18 | * - Value 19 | - Description 20 | * - DPI_TPC_END_NORMAL 21 | - Normal ending of the transaction. 22 | * - DPI_TPC_END_SUSPEND 23 | - Transaction is suspended and may be resumed at some later point. 24 | -------------------------------------------------------------------------------- /doc/src/enums/dpiVectorFlags.rst: -------------------------------------------------------------------------------- 1 | .. _dpiVectorFlags: 2 | 3 | ODPI-C Enumeration dpiVectorFlags 4 | ---------------------------------- 5 | 6 | This enumeration identifies the possible values for 7 | :member:`dpiDataTypeInfo.vectorFlags`. 8 | 9 | .. list-table-with-summary:: 10 | :header-rows: 1 11 | :class: wy-table-responsive 12 | :widths: 15 35 13 | :summary: The first column displays the value of the dpiVectorFlags 14 | enumeration. The second column displays the description of the 15 | dpiVectorFlags enumeration value. 16 | 17 | * - Value 18 | - Description 19 | * - DPI_VECTOR_FLAGS_FLEXIBLE_DIM 20 | - The vector column uses a flexible number of dimensions. 21 | * - DPI_VECTOR_FLAGS_SPARSE 22 | - The vector column contains sparse vectors 23 | -------------------------------------------------------------------------------- /doc/src/enums/dpiVectorFormat.rst: -------------------------------------------------------------------------------- 1 | .. _dpiVectorFormat: 2 | 3 | ODPI-C Enumeration dpiVectorFormat 4 | ---------------------------------- 5 | 6 | This enumeration identifies the storage format for a vector's dimensions. 7 | 8 | .. list-table-with-summary:: 9 | :header-rows: 1 10 | :class: wy-table-responsive 11 | :widths: 15 35 12 | :summary: The first column displays the value of the dpiVectorFormat 13 | enumeration. The second column displays the description of the 14 | dpiVectorFormat enumeration value. 15 | 16 | * - Value 17 | - Description 18 | * - DPI_VECTOR_FORMAT_BINARY 19 | - The vector dimension storage format is single bits, represented in 20 | groups of 8 as single byte unsigned integers. 21 | * - DPI_VECTOR_FORMAT_FLOAT32 22 | - The vector dimension storage format is single-precision floating point 23 | numbers. 24 | * - DPI_VECTOR_FORMAT_FLOAT64 25 | - The vector dimension storage format is double-precision floating point 26 | numbers. 27 | * - DPI_VECTOR_FORMAT_INT8 28 | - The vector dimension storage format is single byte signed integers. 29 | -------------------------------------------------------------------------------- /doc/src/enums/dpiVisibility.rst: -------------------------------------------------------------------------------- 1 | .. _dpiVisibility: 2 | 3 | ODPI-C Enumeration dpiVisibility 4 | -------------------------------- 5 | 6 | This enumeration identifies the visibility of messages in advanced queuing. 7 | 8 | .. list-table-with-summary:: 9 | :header-rows: 1 10 | :class: wy-table-responsive 11 | :widths: 15 35 12 | :summary: The first column displays the value of the dpiVisibility 13 | enumeration. The second column displays the description of the 14 | dpiVisibility enumeration value. 15 | 16 | * - Value 17 | - Description 18 | * - DPI_VISIBILITY_IMMEDIATE 19 | - The message is not part of the current transaction but constitutes 20 | a transaction of its own. 21 | * - DPI_VISIBILITY_ON_COMMIT 22 | - The message is part of the current transaction. This is the default 23 | value. 24 | -------------------------------------------------------------------------------- /doc/src/enums/index.rst: -------------------------------------------------------------------------------- 1 | ******************* 2 | ODPI-C Enumerations 3 | ******************* 4 | 5 | This chapter details the enumerations available in the ODPI-C library. 6 | 7 | .. toctree:: 8 | :maxdepth: 1 9 | :hidden: 10 | 11 | dpiAuthMode 12 | dpiConnCloseMode 13 | dpiCreateMode 14 | dpiDeqMode 15 | dpiDeqNavigation 16 | dpiEventType 17 | dpiExecMode 18 | dpiFetchMode 19 | dpiJsonOptions 20 | dpiMessageDeliveryMode 21 | dpiMessageState 22 | dpiNativeTypeNum 23 | dpiOpCode 24 | dpiOracleTypeNum 25 | dpiPoolCloseMode 26 | dpiPoolGetMode 27 | dpiPurity 28 | dpiServerType 29 | dpiShutdownMode 30 | dpiSodaFlags 31 | dpiStartupMode 32 | dpiStatementType 33 | dpiSubscrGroupingClass 34 | dpiSubscrGroupingType 35 | dpiSubscrNamespace 36 | dpiSubscrProtocol 37 | dpiSubscrQOS 38 | dpiTpcBeginFlags 39 | dpiTpcEndFlags 40 | dpiVectorFlags 41 | dpiVectorFormat 42 | dpiVisibility 43 | -------------------------------------------------------------------------------- /doc/src/functions/dpiObjectAttr.rst: -------------------------------------------------------------------------------- 1 | .. _dpiObjectAttrFunctions: 2 | 3 | ODPI-C Object Attribute Functions 4 | --------------------------------- 5 | 6 | Object attribute handles are used to represent the attributes of types such as 7 | those created by the SQL command CREATE OR REPLACE TYPE. They are created by 8 | calling the function :func:`dpiObjectType_getAttributes()` and are destroyed 9 | when the last reference is released by calling the function 10 | :func:`dpiObjectAttr_release()`. 11 | 12 | .. function:: int dpiObjectAttr_addRef(dpiObjectAttr* attr) 13 | 14 | Adds a reference to the attribute. This is intended for situations where a 15 | reference to the attribute needs to be maintained independently of the 16 | reference returned when the attribute was created. 17 | 18 | The function returns DPI_SUCCESS for success and DPI_FAILURE for failure. 19 | 20 | .. parameters-table:: 21 | 22 | * - ``attr`` 23 | - IN 24 | - The attribute to which a reference is to be added. If the 25 | reference is NULL or invalid, an error is returned. 26 | 27 | .. function:: int dpiObjectAttr_getInfo(dpiObjectAttr* attr, \ 28 | dpiObjectAttrInfo* info) 29 | 30 | Returns information about the attribute. 31 | 32 | The function returns DPI_SUCCESS for success and DPI_FAILURE for failure. 33 | 34 | .. parameters-table:: 35 | 36 | * - ``attr`` 37 | - IN 38 | - A reference to the attribute whose information is to be retrieved. 39 | If the reference is NULL or invalid, an error is returned. 40 | * - ``info`` 41 | - OUT 42 | - A pointer to a :ref:`dpiObjectAttrInfo` 43 | structure which will be populated with information about the 44 | attribute. 45 | 46 | .. function:: int dpiObjectAttr_release(dpiObjectAttr* attr) 47 | 48 | Releases a reference to the attribute. A count of the references to the 49 | attribute is maintained and when this count reaches zero, the memory 50 | associated with the attribute is freed. 51 | 52 | The function returns DPI_SUCCESS for success and DPI_FAILURE for failure. 53 | 54 | .. parameters-table:: 55 | 56 | * - ``attr`` 57 | - IN 58 | - The attribute from which a reference is to be released. If the 59 | reference is NULL or invalid, an error is returned. 60 | -------------------------------------------------------------------------------- /doc/src/functions/dpiRowid.rst: -------------------------------------------------------------------------------- 1 | .. _dpiRowidFunctions: 2 | 3 | ODPI-C Rowid Functions 4 | ---------------------- 5 | 6 | Rowid handles are used to represent the unique identifier of a row in the 7 | database. They cannot be created or set directly but are created implicitly 8 | when a variable of type DPI_ORACLE_TYPE_ROWID is created. They are destroyed 9 | when the last reference is released by a call to the function 10 | :func:`dpiRowid_release()`. 11 | 12 | .. function:: int dpiRowid_addRef(dpiRowid* rowid) 13 | 14 | Adds a reference to the rowid. This is intended for situations where a 15 | reference to the rowid needs to be maintained independently of the 16 | reference returned when the rowid was created. 17 | 18 | The function returns DPI_SUCCESS for success and DPI_FAILURE for failure. 19 | 20 | .. parameters-table:: 21 | 22 | * - ``rowid`` 23 | - IN 24 | - The rowid to which a reference is to be added. If the reference is 25 | NULL or invalid, an error is returned. 26 | 27 | .. function:: int dpiRowid_getStringValue(dpiRowid* rowid, \ 28 | const char** value, uint32_t* valueLength) 29 | 30 | Returns the sting (base64) representation of the rowid. 31 | 32 | The function returns DPI_SUCCESS for success and DPI_FAILURE for failure. 33 | 34 | .. parameters-table:: 35 | 36 | * - ``rowid`` 37 | - IN 38 | - The rowid from which the string representation is to be returned. 39 | If the reference is NULL or invalid, an error is returned. 40 | * - ``value`` 41 | - OUT 42 | - A pointer to the value as a byte string in the encoding used for 43 | CHAR data, which will be populated upon successful completion of 44 | this function. The string returned will remain valid as long as a 45 | reference is held to the rowid. 46 | * - ``valueLength`` 47 | - OUT 48 | - A pointer to the length of the value parameter, in bytes, which 49 | will be populated upon successful completion of this function. 50 | 51 | .. function:: int dpiRowid_release(dpiRowid* rowid) 52 | 53 | Releases a reference to the rowid. A count of the references to the rowid 54 | is maintained and when this count reaches zero, the memory associated with 55 | the rowid is freed. 56 | 57 | The function returns DPI_SUCCESS for success and DPI_FAILURE for failure. 58 | 59 | .. parameters-table:: 60 | 61 | * - ``rowid`` 62 | - IN 63 | - The rowid from which a reference is to be released. If the 64 | reference is NULL or invalid, an error is returned. 65 | -------------------------------------------------------------------------------- /doc/src/functions/dpiSodaCollCursor.rst: -------------------------------------------------------------------------------- 1 | .. _dpiSodaCollCursorFunctions: 2 | 3 | ODPI-C SODA Collection Cursor Functions 4 | --------------------------------------- 5 | 6 | SODA collection cursor handles are used to represent SODA collection cursors. 7 | They are created by calling the function :func:`dpiSodaDb_getCollections()` 8 | and are destroyed when the last reference is released by calling the function 9 | :func:`dpiSodaCollCursor_release()`. 10 | 11 | See `this tracking issue `__ for 12 | known issues with SODA. 13 | 14 | .. function:: int dpiSodaCollCursor_addRef(dpiSodaCollCursor* cursor) 15 | 16 | Adds a reference to the SODA collection cursor. This is intended for 17 | situations where a reference to the cursor needs to be maintained 18 | independently of the reference returned when the cursor was created. 19 | 20 | The function returns DPI_SUCCESS for success and DPI_FAILURE for failure. 21 | 22 | .. parameters-table:: 23 | 24 | * - ``cursor`` 25 | - IN 26 | - The cursor to which a reference is to be added. If the reference 27 | is NULL or invalid, an error is returned. 28 | 29 | .. function:: int dpiSodaCollCursor_close(dpiSodaCollCursor* cursor) 30 | 31 | Closes the cursor and makes it unusable for further work immediately, 32 | rather than when the reference count reaches zero. 33 | 34 | The function returns DPI_SUCCESS for success and DPI_FAILURE for failure. 35 | 36 | .. parameters-table:: 37 | 38 | * - ``cursor`` 39 | - IN 40 | - A reference to the cursor which is to be closed. If the reference 41 | is NULL or invalid, an error is returned. 42 | 43 | .. function:: int dpiSodaCollCursor_getNext(dpiSodaCollCursor* cursor, \ 44 | uint32_t flags, dpiSodaColl** coll) 45 | 46 | Gets the next collection from the cursor, if there is one. 47 | 48 | The function returns DPI_SUCCESS for success and DPI_FAILURE for failure. 49 | 50 | .. parameters-table:: 51 | 52 | * - ``cursor`` 53 | - IN 54 | - The cursor from which the next collection is to be retrieved. The 55 | reference is NULL or invalid, an error is returned. 56 | * - ``flags`` 57 | - IN 58 | - One or more of the values from the enumeration 59 | :ref:`dpiSodaFlags`, OR'ed together. Only the value 60 | DPI_SODA_FLAGS_DEFAULT is currently supported. 61 | * - ``coll`` 62 | - OUT 63 | - A pointer to a reference to the next collection in the cursor, if 64 | one exists. If no further collections are available from the 65 | cursor, NULL is returned instead. The function 66 | :func:`dpiSodaColl_release()` should be called when the collection 67 | is no longer required. 68 | 69 | .. function:: int dpiSodaCollCursor_release(dpiSodaCollCursor* cursor) 70 | 71 | Releases a reference to the SODA collection cursor. A count of the 72 | references to the cursor is maintained and when this count reaches zero, 73 | the memory associated with the cursor is freed. 74 | 75 | The function returns DPI_SUCCESS for success and DPI_FAILURE for failure. 76 | 77 | .. parameters-table:: 78 | 79 | * - ``cursor`` 80 | - IN 81 | - The cursor from which a reference is to be released. If the 82 | reference is NULL or invalid, an error is returned. 83 | -------------------------------------------------------------------------------- /doc/src/functions/dpiSodaDocCursor.rst: -------------------------------------------------------------------------------- 1 | .. _dpiSodaDocCursorFunctions: 2 | 3 | ODPI-C SODA Document Cursor Functions 4 | ------------------------------------- 5 | 6 | SODA document cursor handles are used to represent SODA document cursors. 7 | They are created by calling the function :func:`dpiSodaColl_find()` 8 | and are destroyed when the last reference is released by calling the function 9 | :func:`dpiSodaDocCursor_release()`. 10 | 11 | See `this tracking issue `__ for 12 | known issues with SODA. 13 | 14 | .. function:: int dpiSodaDocCursor_addRef(dpiSodaDocCursor* cursor) 15 | 16 | Adds a reference to the SODA document cursor. This is intended for 17 | situations where a reference to the cursor needs to be maintained 18 | independently of the reference returned when the cursor was created. 19 | 20 | The function returns DPI_SUCCESS for success and DPI_FAILURE for failure. 21 | 22 | .. parameters-table:: 23 | 24 | * - ``cursor`` 25 | - IN 26 | - The cursor to which a reference is to be added. If the reference 27 | is NULL or invalid, an error is returned. 28 | 29 | .. function:: int dpiSodaDocCursor_close(dpiSodaDocCursor* cursor) 30 | 31 | Closes the cursor and makes it unusable for further work immediately, 32 | rather than when the reference count reaches zero. 33 | 34 | The function returns DPI_SUCCESS for success and DPI_FAILURE for failure. 35 | 36 | .. parameters-table:: 37 | 38 | * - ``cursor`` 39 | - IN 40 | - A reference to the cursor which is to be closed. If the reference 41 | is NULL or invalid, an error is returned. 42 | 43 | .. function:: int dpiSodaDocCursor_getNext(dpiSodaDocCursor* cursor, \ 44 | uint32_t flags, dpiSodaDoc** doc) 45 | 46 | Gets the next document from the cursor, if there is one. 47 | 48 | The function returns DPI_SUCCESS for success and DPI_FAILURE for failure. 49 | 50 | .. parameters-table:: 51 | 52 | * - ``cursor`` 53 | - IN 54 | - The cursor from which the next document is to be retrieved. The 55 | reference is NULL or invalid, an error is returned. 56 | * - ``flags`` 57 | - IN 58 | - One or more of the values from the enumeration 59 | :ref:`dpiSodaFlags`, OR'ed together. Only the value 60 | DPI_SODA_FLAGS_DEFAULT is currently supported. 61 | * - ``doc`` 62 | - OUT 63 | - A pointer to a reference to the next document in the cursor, if 64 | one exists. If no further documents are available from the cursor, 65 | NULL is returned instead. The function 66 | :func:`dpiSodaDoc_release()` should be called when the document 67 | is no longer required. 68 | 69 | .. function:: int dpiSodaDocCursor_release(dpiSodaDocCursor* cursor) 70 | 71 | Releases a reference to the SODA document cursor. A count of the 72 | references to the cursor is maintained and when this count reaches zero, 73 | the memory associated with the cursor is freed. 74 | 75 | The function returns DPI_SUCCESS for success and DPI_FAILURE for failure. 76 | 77 | .. parameters-table:: 78 | 79 | * - ``cursor`` 80 | - IN 81 | - The cursor from which a reference is to be released. If the 82 | reference is NULL or invalid, an error is returned. 83 | -------------------------------------------------------------------------------- /doc/src/functions/dpiSubscr.rst: -------------------------------------------------------------------------------- 1 | .. _dpiSubscrFunctions: 2 | 3 | ODPI-C Subscription Functions 4 | ----------------------------- 5 | 6 | Subscription handles are used to represent subscriptions to events such as 7 | continuous query notification and object change notification. They are created 8 | by calling the function :func:`dpiConn_subscribe()` and are destroyed 9 | by calling the function :func:`dpiConn_unsubscribe()` or releasing the last 10 | reference by calling the function :func:`dpiSubscr_release()`. 11 | 12 | .. function:: int dpiSubscr_addRef(dpiSubscr* subscr) 13 | 14 | Adds a reference to the subscription. This is intended for situations where 15 | a reference to the subscription needs to be maintained independently of the 16 | reference returned when the subscription was created. 17 | 18 | The function returns DPI_SUCCESS for success and DPI_FAILURE for failure. 19 | 20 | .. parameters-table:: 21 | 22 | * - ``subscr`` 23 | - IN 24 | - The subscription to which a reference is to be added. If the 25 | reference is NULL or invalid, an error is returned. 26 | 27 | .. function:: int dpiSubscr_prepareStmt(dpiSubscr* subscr, const char* sql, \ 28 | uint32_t sqlLength, dpiStmt** stmt) 29 | 30 | Prepares a statement for registration on the subscription. The statement is 31 | then registered by calling the function :func:`dpiStmt_execute()`. The 32 | reference to the statement that is returned should be released as soon as 33 | it is no longer needed. 34 | 35 | The function returns DPI_SUCCESS for success and DPI_FAILURE for failure. 36 | 37 | .. parameters-table:: 38 | 39 | * - ``subscr`` 40 | - IN 41 | - A reference to the subscription on which the statement is to be 42 | prepared for registration. If the reference is NULL or invalid, an 43 | error is returned. 44 | * - ``sql`` 45 | - IN 46 | - The SQL that is to be prepared, as a byte string in the encoding 47 | used for CHAR data. 48 | * - ``sqlLength`` 49 | - IN 50 | - The length of the sql parameter, in bytes. 51 | * - ``stmt`` 52 | - OUT 53 | - A reference to the statement that was prepared, which will be 54 | populated when the function completes successfully. 55 | 56 | .. function:: int dpiSubscr_release(dpiSubscr* subscr) 57 | 58 | Releases a reference to the subscription. A count of the references to the 59 | subscription is maintained and when this count reaches zero, the memory 60 | associated with the subscription is freed. The subscription is also 61 | deregistered so that notifications are no longer sent, if this was not 62 | already done using the function :func:`dpiConn_unsubscribe()`. 63 | 64 | The function returns DPI_SUCCESS for success and DPI_FAILURE for failure. 65 | 66 | .. parameters-table:: 67 | 68 | * - ``subscr`` 69 | - IN 70 | - The subscription from which a reference is to be released. If the 71 | reference is NULL or invalid, an error is returned. 72 | -------------------------------------------------------------------------------- /doc/src/functions/dpiVector.rst: -------------------------------------------------------------------------------- 1 | .. _dpiVectorFunctions: 2 | 3 | ODPI-C Vector Functions 4 | ----------------------- 5 | 6 | Vector handles are used to represent vector values stored in the database. They 7 | are only available from Oracle Client and Database 23.4 and higher. They can be 8 | created explicitly by a call to :func:`dpiConn_newVector()` or implicitly when 9 | a variable of type DPI_ORACLE_TYPE_VECTOR is created. They are destroyed when 10 | the last reference is released by a call to the function 11 | :func:`dpiVector_release()`. 12 | 13 | .. function:: int dpiVector_addRef(dpiVector* vector) 14 | 15 | Adds a reference to the vector value. This is intended for situations where 16 | a reference to the vector value needs to be maintained independently of the 17 | reference returned when the vector value was created. 18 | 19 | The function returns DPI_SUCCESS for success and DPI_FAILURE for failure. 20 | 21 | .. parameters-table:: 22 | 23 | * - ``vector`` 24 | - IN 25 | - The vector value to which a reference is to be added. If the 26 | reference is NULL or invalid, an error is returned. 27 | 28 | .. function:: int dpiVector_getValue(dpiVector* vector, dpiVectorInfo* info) 29 | 30 | Returns information about the vector. 31 | 32 | The function returns DPI_SUCCESS for success and DPI_FAILURE for failure. 33 | 34 | .. parameters-table:: 35 | 36 | * - ``vector`` 37 | - IN 38 | - The vector value from which the information is to be extracted. If 39 | the reference is NULL or invalid, an error is returned. 40 | * - ``info`` 41 | - OUT 42 | - A pointer to a structure of type 43 | :ref:`dpiVectorInfo` which will be populated upon 44 | successful completion of this function. The structure's contents 45 | will remain valid as long as a reference is held to the vector 46 | value and the vector value itself is not modified. 47 | 48 | .. function:: int dpiVector_release(dpiVector* vector) 49 | 50 | Releases a reference to the vector value. A count of the references to the 51 | vector value is maintained and when this count reaches zero, the memory 52 | associated with the vector value is freed. 53 | 54 | The function returns DPI_SUCCESS for success and DPI_FAILURE for failure. 55 | 56 | .. parameters-table:: 57 | 58 | * - ``vector`` 59 | - IN 60 | - The vector value from which a reference is to be released. If the 61 | reference is NULL or invalid, an error is returned. 62 | 63 | .. function:: int dpiVector_setValue(dpiVector* vector, dpiVectorInfo* info) 64 | 65 | Sets the vector value from the supplied information. 66 | 67 | The function returns DPI_SUCCESS for success and DPI_FAILURE for failure. 68 | 69 | .. parameters-table:: 70 | 71 | * - ``vector`` 72 | - IN 73 | - The vector value which is to be modified using the supplied 74 | information. If the reference is NULL or invalid, an error is 75 | returned. 76 | * - ``info`` 77 | - IN 78 | - A pointer to a structure of type 79 | :ref:`dpiVectorInfo` which contains the information 80 | to be set on the vector. 81 | -------------------------------------------------------------------------------- /doc/src/functions/index.rst: -------------------------------------------------------------------------------- 1 | **************** 2 | ODPI-C Functions 3 | **************** 4 | 5 | This chapter details the functions available in the ODPI-C library. 6 | 7 | .. toctree:: 8 | :maxdepth: 1 9 | :hidden: 10 | 11 | Connection Functions 12 | Context Functions 13 | Data Functions 14 | Dequeue Options Functions 15 | Enqueue Options Functions 16 | JSON Functions 17 | LOB Functions 18 | Message Properties Functions 19 | Object Functions 20 | Object Attribute Functions 21 | Object Type Functions 22 | Pool Functions 23 | Queue Functions 24 | Rowid Functions 25 | SODA Collection Functions 26 | SODA Collection Cursor Functions 27 | SODA Database Functions 28 | SODA Document Functions 29 | SODA Document Cursor Functions 30 | Statement Functions 31 | Subscription Functions 32 | Variable Functions 33 | Vector Functions 34 | -------------------------------------------------------------------------------- /doc/src/index.rst: -------------------------------------------------------------------------------- 1 | .. ODPI-C documentation main file. 2 | 3 | Welcome to ODPI-C's |release| documentation! 4 | ============================================ 5 | 6 | **ODPI-C** is a C library that simplifies the use of common Oracle Call 7 | Interface (OCI_) features for drivers and applications. 8 | 9 | The ODPI-C project home page can be found 10 | `here `__ and the source code can be found 11 | `here `__. 12 | 13 | .. _OCI: http://www.oracle.com/technetwork/database/features/oci/index.html 14 | 15 | .. toctree:: 16 | :numbered: 17 | :maxdepth: 2 18 | 19 | user_guide/introduction.rst 20 | user_guide/installation.rst 21 | Debugging 22 | Data Types 23 | Round-Trips 24 | Enumerations 25 | Structures 26 | Unions 27 | Functions 28 | Release Notes 29 | Licenses 30 | -------------------------------------------------------------------------------- /doc/src/structs/dpiAccessToken.rst: -------------------------------------------------------------------------------- 1 | .. _dpiAccessToken: 2 | 3 | ODPI-C Structure dpiAccessToken 4 | ------------------------------- 5 | 6 | This structure is used when creating connection pools and standalone 7 | connections using token based authentication. Oracle Client libraries 8 | must be 19.14 (or later), or 21.5 (or later). 9 | 10 | The externalAuth must be set to 1 and in addition, homogeneous must be 11 | set to 1 when creating a pool. The user (or username) and password properties 12 | should not be set. 13 | 14 | Both token and privateKey (and their lengths) must be set while using IAM 15 | for token based authentication. 16 | 17 | Only token and it's length must be set while using OAuth for token based 18 | authentication. 19 | 20 | .. member:: const char* dpiAccessToken.token 21 | 22 | Specifies the database authentication token string used for token based 23 | authentication. 24 | 25 | .. member:: uint32_t dpiAccessToken.tokenLength 26 | 27 | Specifies the database authentication token string length used for token 28 | based authentication. 29 | 30 | .. member:: const char* dpiAccessToken.privateKey 31 | 32 | Specifies the database authentication private key string used for token 33 | based authentication. 34 | 35 | .. member:: uint32_t dpiAccessToken.privateKeyLength 36 | 37 | Specifies the database authentication private key string length used for 38 | token based authentication. 39 | -------------------------------------------------------------------------------- /doc/src/structs/dpiAnnotation.rst: -------------------------------------------------------------------------------- 1 | .. _dpiAnnotation: 2 | 3 | ODPI-C Structure dpiAnnotation 4 | ------------------------------ 5 | 6 | This structure is part of the structure :ref:`dpiDataTypeInfo` 7 | and provides information about `annotations 8 | `__ 9 | associated with columns that are fetched from the database. Annotations are 10 | only available with Oracle Database 23ai (or later). Oracle Client libraries 11 | must also be 23.1 (or later). 12 | 13 | .. member:: const char* dpiAnnotation.key 14 | 15 | Specifies the annoation key. 16 | 17 | .. member:: uint32_t dpiAnnotation.keyLength 18 | 19 | Specifies the length of the annotation key, in bytes. 20 | 21 | .. member:: const char* dpiAnnotation.value 22 | 23 | Specifies the annoation value. 24 | 25 | .. member:: uint32_t dpiAnnotation.valueLength 26 | 27 | Specifies the length of the annotation value, in bytes. 28 | -------------------------------------------------------------------------------- /doc/src/structs/dpiAppContext.rst: -------------------------------------------------------------------------------- 1 | .. _dpiAppContext: 2 | 3 | ODPI-C Structure dpiAppContext 4 | ------------------------------ 5 | 6 | This structure is used for passing application context to the database during 7 | the process of creating standalone connections. These values are ignored when 8 | acquiring a connection from a session pool or when using DRCP (Database 9 | Resident Connection Pooling). All values must be set to valid values prior to 10 | being used in the :ref:`dpiConnCreateParams` structure and 11 | must remain valid until the execution of :func:`dpiConn_create()` completes. 12 | Values set using this structure are available in logon triggers by using the 13 | sys_context() SQL function. 14 | 15 | .. member:: const char* dpiAppContext.namespaceName 16 | 17 | Specifies the value of the "namespace" parameter to sys_context(). It is 18 | expected to be a byte string in the encoding specified in the 19 | :ref:`dpiConnCreateParams` structure and must not be 20 | NULL. 21 | 22 | .. member:: uint32_t dpiAppContext.namespaceNameLength 23 | 24 | Specifies the length of the :member:`dpiAppContext.namespaceName` member, 25 | in bytes. 26 | 27 | .. member:: const char* dpiAppContext.name 28 | 29 | Specifies the value of the "parameter" parameter to sys_context(). It is 30 | expected to be a byte string in the encoding specified in the 31 | :ref:`dpiConnCreateParams` structure and must not be 32 | NULL. 33 | 34 | .. member:: uint32_t dpiAppContext.nameLength 35 | 36 | Specifies the length of the :member:`dpiAppContext.name` member, in bytes. 37 | 38 | .. member:: const char* dpiAppContext.value 39 | 40 | Specifies the value that will be returned from sys_context(). It is 41 | expected to be a byte string in the encoding specified in the 42 | :ref:`dpiConnCreateParams` structure and must not be 43 | NULL. 44 | 45 | .. member:: uint32_t dpiAppContext.valueLength 46 | 47 | Specifies the length of the :member:`dpiAppContext.value` member, in bytes. 48 | -------------------------------------------------------------------------------- /doc/src/structs/dpiBytes.rst: -------------------------------------------------------------------------------- 1 | .. _dpiBytes: 2 | 3 | ODPI-C Structure dpiBytes 4 | ------------------------- 5 | 6 | This structure is used for passing byte strings to and from the database in 7 | the structure :ref:`dpiData`. 8 | 9 | .. member:: char* dpiBytes.ptr 10 | 11 | Specifies the pointer to the memory allocated by ODPI-C for the variable. 12 | For strings, data written to this memory should be in the encoding 13 | appropriate to the type of data being transferred. When data is transferred 14 | from the database it will be in the correct encoding already. 15 | 16 | .. member:: uint32_t dpiBytes.length 17 | 18 | Specifies the length of the byte string, in bytes. 19 | 20 | .. member:: const char* dpiBytes.encoding 21 | 22 | Specifies the encoding for character data. This value is populated when 23 | data is transferred from the database. It is ignored when data is being 24 | transferred to the database. 25 | -------------------------------------------------------------------------------- /doc/src/structs/dpiConnInfo.rst: -------------------------------------------------------------------------------- 1 | .. _dpiConnInfo: 2 | 3 | ODPI-C Structure dpiConnInfo 4 | ---------------------------- 5 | 6 | This structure is used for passing information about a connection from ODPI-C. 7 | It is used by the function :func:`dpiConn_getInfo()`. 8 | 9 | .. member:: const char* dpiConnInfo.dbDomain 10 | 11 | A pointer to the name of the Oracle Database Domain name associated with 12 | the connection, encoded in the encoding used for CHAR data. This is the 13 | same value returned by the SQL expression 14 | ``SELECT VALUE FROM V$PARAMETER WHERE NAME = 'db_domain'``. 15 | 16 | .. member:: uint32_t dpiConnInfo.dbDomainLength 17 | 18 | Contains the length of the :member:`dpiConnInfo.dbDomain` member, in bytes. 19 | 20 | .. member:: const char* dpiConnInfo.dbName 21 | 22 | A pointer to the Oracle Database name associated with the connection, 23 | encoded in the encoding used for CHAR data. This is the same value returned 24 | by the SQL expression ``SELECT NAME FROM V$DATABASE``. Note the values may 25 | have different cases. 26 | 27 | .. member:: uint32_t dpiConnInfo.dbNameLength 28 | 29 | Contains the length of the :member:`dpiConnInfo.dbName` member, in bytes. 30 | 31 | .. member:: const char* dpiConnInfo.instanceName 32 | 33 | A pointer to the Oracle Database instance name associated with the 34 | connection, encoded in the encoding used for CHAR data. This is the same 35 | value returned by the SQL expression 36 | ``SELECT SYS_CONTEXT('USERENV', 'INSTANCE_NAME') FROM DUAL``. Note the 37 | values may have different cases. 38 | 39 | .. member:: uint32_t dpiConnInfo.instanceNameLength 40 | 41 | Contains the length of the :member:`dpiConnInfo.instanceName` member, in 42 | bytes. 43 | 44 | .. member:: const char* dpiConnInfo.serviceName 45 | 46 | A pointer to the Oracle Database service name associated with the 47 | connection, encoded in the encoding used for CHAR data. This is the same 48 | value returned by the SQL expression 49 | ``SELECT SYS_CONTEXT('USERENV', 'SERVICE_NAME') FROM DUAL``. 50 | 51 | .. member:: uint32_t dpiConnInfo.serviceNameLength 52 | 53 | Contains the length of the :member:`dpiConnInfo.serviceName` member, in 54 | bytes. 55 | 56 | .. member:: uint32_t dpiConnInfo.maxIdentifierLength 57 | 58 | Specifies the maximum length of identifiers (in bytes) supported by the 59 | database to which the connection has been established. See `Database Object 60 | Naming Rules `__. The value 62 | may be 0, 30, or 128. The value 0 indicates the size cannot be reliably 63 | determined by ODPI-C, which occurs when using Oracle Client libraries 12.1 64 | (or older) and also connected to Oracle Database 12.2, or later. 65 | 66 | .. member:: uint32_t dpiConnInfo.maxOpenCursors 67 | 68 | Specifies the maximum number of cursors that can be opened. This is the 69 | same value returned by the SQL expression 70 | ``SELECT VALUE FROM V$PARAMETER WHERE NAME = 'open_cursors'``. The value 71 | will be 0 when using Oracle Client libraries 11.2. 72 | 73 | .. member:: uint8_t dpiConnInfo.serverType 74 | 75 | Specifies the type of server process used by the connection. This value 76 | will be one of the values in the enumeration 77 | :ref:`dpiServerType `. 78 | -------------------------------------------------------------------------------- /doc/src/structs/dpiContextCreateParams.rst: -------------------------------------------------------------------------------- 1 | .. _dpiContextCreateParams: 2 | 3 | ODPI-C Structure dpiContextCreateParams 4 | --------------------------------------- 5 | 6 | This structure is used for specifying parameters when creating an ODPI-C 7 | context by calling :func:`dpiContext_createWithParams()`. 8 | 9 | .. member:: const char* dpiContextCreateParams.defaultDriverName 10 | 11 | A null-terminated string defining the default driver name to use when 12 | creating pools or standalone connections. 13 | 14 | The standard is to set this value to ``" : "``, where 15 | is the name of the driver and is its version. There should be a 16 | single space character before and after the colon. 17 | 18 | This value is shown in database views that give information about 19 | connections. For example, it is in the ``CLIENT_DRIVER`` column 20 | of ``V$SESSION_CONNECT_INFO``. 21 | 22 | If this member is NULL, then the default value will be the value of 23 | ``DPI_DEFAULT_DRIVER_NAME`` from `dpi.h 24 | `__. 25 | 26 | This member is propagated to the :member:`dpiCommonCreateParams.driverName` 27 | and :member:`dpiCommonCreateParams.driverNameLength` members when the 28 | function :func:`dpiContext_initCommonCreateParams()` is called. 29 | 30 | .. member:: const char* dpiContextCreateParams.defaultEncoding 31 | 32 | A null-terminated string defining the default encoding to use for all 33 | string data (including NCHAR, NVARCHAR2 and NCLOB data) passed into or 34 | returned from the database. 35 | 36 | If this member is NULL, then the default value will be "UTF-8". The Oracle 37 | equivalent of this is "AL32UTF8". 38 | 39 | This member is propagated to the :member:`dpiCommonCreateParams.encoding` 40 | and :member:`dpiCommonCreateParams.nencoding` members when the 41 | function :func:`dpiContext_initCommonCreateParams()` is called. 42 | 43 | .. member:: const char* dpiContextCreateParams.loadErrorUrl 44 | 45 | A null-terminated UTF-8 encoded string defining the URL that should be 46 | provided in the error message returned when the Oracle Client library 47 | cannot be loaded. This URL should direct the user to the installation 48 | instructions for the application or driver using ODPI-C. If this value is 49 | NULL then the default ODPI-C URL is provided in the error message instead. 50 | 51 | .. member:: const char* dpiContextCreateParams.oracleClientLibDir 52 | 53 | A null-terminated UTF-8 encoded string defining the location from which to 54 | load the Oracle Client library. If this value is not NULL it is the only 55 | location that is searched; otherwise, if this value is NULL the Oracle 56 | Client library is searched for in the usual fashion as noted in 57 | :ref:`Oracle Client Library Loading `. Also see that 58 | section for limitations on using this member. 59 | 60 | .. member:: const char* dpiContextCreateParams.oracleClientConfigDir 61 | 62 | A null-terminated UTF-8 encoded string defining the location the Oracle 63 | client library will search for configuration files. This is equivalent to 64 | setting the environment variable ``TNS_ADMIN``. If this value is not NULL, 65 | it overrides any value set by the environment variable ``TNS_ADMIN``. 66 | 67 | .. member:: int dpiContextCreateParams.sodaUseJsonDesc 68 | 69 | A boolean value indicating whether or not to use JSON descriptors with 70 | SODA. This requires Oracle Client 23.4 or higher and setting this value to 71 | 1 in earlier versions will simply be ignored. Once a call to 72 | :func:`dpiContext_createWithParams()` is made with this structure, this 73 | member will be cleared if JSON descriptors cannot be used. 74 | 75 | .. member:: int dpiContextCreateParams.useJsonId 76 | 77 | A boolean value indicating whether or not to treat JSON ID values 78 | distinctly from other binary data. 79 | -------------------------------------------------------------------------------- /doc/src/structs/dpiData.rst: -------------------------------------------------------------------------------- 1 | .. _dpiData: 2 | 3 | ODPI-C Structure dpiData 4 | ------------------------ 5 | 6 | This structure is used for passing data to and from the database in variables 7 | and for getting and setting object attributes and collection values. The data 8 | that is stored in the structure will remain valid for differing durations 9 | depending on the source of the data. 10 | 11 | For data that is supplied by the application (for passing data into the 12 | database) the duration of the data is under the control of the application 13 | itself and the application should ensure that it remains valid for as long as 14 | any call that uses that data. 15 | 16 | For data that is supplied by the database in a variable (either fetching data 17 | or binding data out) the data will remain valid as long as a reference to the 18 | variable is retained; the contents of the data may change however if a 19 | statement to which the variable is bound or defined is executed or fetched 20 | again. 21 | 22 | For data that is acquired from an object attribute or a collection element the 23 | data will remain valid as long as a reference to the object is retained; the 24 | contents of the data may change however if the object is modified. 25 | 26 | .. member:: int dpiData.isNull 27 | 28 | Specifies if the value refers to a null value (1) or not (0). 29 | 30 | .. member:: dpiDataBuffer dpiData.value 31 | 32 | Specifies the value that is being passed or received. It is only examined 33 | when the member :member:`dpiData.isNull` is 0. It is a union of type 34 | :ref:`dpiDataBuffer`. 35 | -------------------------------------------------------------------------------- /doc/src/structs/dpiEncodingInfo.rst: -------------------------------------------------------------------------------- 1 | .. _dpiEncodingInfo: 2 | 3 | ODPI-C Structure dpiEncodingInfo 4 | -------------------------------- 5 | 6 | This structure is used for transferring encoding information from ODPI-C. All of 7 | the information here remains valid as long as a reference is held to the 8 | standalone connection (by calling :func:`dpiConn_getEncodingInfo()`) or session 9 | pool (by calling :func:`dpiPool_getEncodingInfo()`) from which the information 10 | was taken. 11 | 12 | .. member:: const char* dpiEncodingInfo.encoding 13 | 14 | The encoding used for CHAR data, as a null-terminated ASCII string. 15 | 16 | .. member:: int32_t dpiEncodingInfo.maxBytesPerCharacter 17 | 18 | The maximum number of bytes required for each character in the encoding 19 | used for CHAR data. This value is used when calculating the size of 20 | buffers required when lengths in characters are provided. 21 | 22 | .. member:: const char* dpiEncodingInfo.nencoding 23 | 24 | The encoding used for NCHAR data, as a null-terminated ASCII string. 25 | 26 | .. member:: int32_t dpiEncodingInfo.nmaxBytesPerCharacter 27 | 28 | The maximum number of bytes required for each character in the encoding 29 | used for NCHAR data. Since this information is not directly available 30 | from Oracle it is only accurate if the encodings used for CHAR and NCHAR 31 | data are identical or one of ASCII or UTF-8; otherwise a value of 4 is 32 | assumed. This value is used when calculating the size of buffers required 33 | when lengths in characters are provided. 34 | -------------------------------------------------------------------------------- /doc/src/structs/dpiErrorInfo.rst: -------------------------------------------------------------------------------- 1 | .. _dpiErrorInfo: 2 | 3 | ODPI-C Structure dpiErrorInfo 4 | ----------------------------- 5 | 6 | This structure is used for transferring error information from ODPI-C. All of the 7 | strings referenced here may become invalid as soon as the next ODPI-C call is 8 | made. 9 | 10 | .. member:: int32_t dpiErrorInfo.code 11 | 12 | The OCI error code if an OCI error has taken place. If no OCI error has 13 | taken place the value is 0. 14 | 15 | .. member:: uint16_t dpiErrorInfo.offset16 16 | 17 | The 16-bit value of :member:`~dpiErrorInfo.offset` retained for backwards 18 | compatibility. This member will be removed at some point in the future. 19 | 20 | .. member:: const char* dpiErrorInfo.message 21 | 22 | The error message as a byte string in the encoding specified by the 23 | :member:`dpiErrorInfo.encoding` member. 24 | 25 | .. member:: uint32_t dpiErrorInfo.messageLength 26 | 27 | The length of the :member:`dpiErrorInfo.message` member, in bytes. 28 | 29 | .. member:: const char* dpiErrorInfo.encoding 30 | 31 | The encoding in which the error message is encoded as a null-terminated 32 | string. For OCI errors this is the CHAR encoding used when the connection 33 | was created. For ODPI-C specific errors this is UTF-8. 34 | 35 | .. member:: const char* dpiErrorInfo.fnName 36 | 37 | The public ODPI-C function name which was called in which the error took 38 | place. This is a null-terminated ASCII string. 39 | 40 | .. member:: const char* dpiErrorInfo.action 41 | 42 | The internal action that was being performed when the error took place. 43 | This is a null-terminated ASCII string. 44 | 45 | .. member:: const char* dpiErrorInfo.sqlState 46 | 47 | The SQLSTATE code associated with the error. This is a 5 character 48 | null-terminated string. 49 | 50 | .. member:: int dpiErrorInfo.isRecoverable 51 | 52 | A boolean value indicating if the error is recoverable. This member always 53 | has a value of 0 unless both client and server are at release 12.1 or 54 | higher. 55 | 56 | .. member:: int dpiErrorInfo.isWarning 57 | 58 | A boolean value indicating if the error information is for a warning 59 | returned by Oracle that does not prevent the requested operation from 60 | proceeding. Examples include connecting to the database with a password 61 | that is about to expire (within the grace period) and creating a stored 62 | procedure with compilation errors. 63 | 64 | .. member:: uint32_t dpiErrorInfo.offset 65 | 66 | The parse error offset (in bytes) when executing a statement or the row 67 | offset when performing bulk operations or fetching batch error information. 68 | If neither of these cases are true, the value is 0. 69 | -------------------------------------------------------------------------------- /doc/src/structs/dpiIntervalDS.rst: -------------------------------------------------------------------------------- 1 | .. _dpiIntervalDS: 2 | 3 | ODPI-C Structure dpiIntervalDS 4 | ------------------------------ 5 | 6 | This structure is used for passing interval (days to seconds) data to and from 7 | the database in the structure :ref:`dpiData`. 8 | 9 | .. member:: int32_t dpiIntervalDS.days 10 | 11 | Specifies the number of days in the interval. 12 | 13 | .. member:: int32_t dpiIntervalDS.hours 14 | 15 | Specifies the number of hours in the interval. 16 | 17 | .. member:: int32_t dpiIntervalDS.minutes 18 | 19 | Specifies the number of minutes in the interval. 20 | 21 | .. member:: int32_t dpiIntervalDS.seconds 22 | 23 | Specifies the number of seconds in the interval. 24 | 25 | .. member:: int32_t dpiIntervalDS.fseconds 26 | 27 | Specifies the number of fractional seconds in the interval (in 28 | nanoseconds). 29 | -------------------------------------------------------------------------------- /doc/src/structs/dpiIntervalYM.rst: -------------------------------------------------------------------------------- 1 | .. _dpiIntervalYM: 2 | 3 | ODPI-C Structure dpiIntervalYM 4 | ------------------------------ 5 | 6 | This structure is used for passing interval (years to months) data to and from 7 | the database in the structure :ref:`dpiData`. 8 | 9 | .. member:: int32_t dpiIntervalYM.years 10 | 11 | Specifies the number of years in the interval. 12 | 13 | .. member:: int32_t dpiIntervalYM.months 14 | 15 | Specifies the number of months in the interval. 16 | -------------------------------------------------------------------------------- /doc/src/structs/dpiJsonArray.rst: -------------------------------------------------------------------------------- 1 | .. _dpiJsonArray: 2 | 3 | ODPI-C Structure dpiJsonArray 4 | ----------------------------- 5 | 6 | This structure is used for passing JSON objects to and from the database. 7 | 8 | .. member:: uint32_t dpiJsonArray.numElements 9 | 10 | Specifies the number of elements that are found in the JSON array. This 11 | also identifies the number of elements in each of the remaining arrays. 12 | 13 | .. member:: dpiJsonNode* dpiJsonArray.elements 14 | 15 | Specifies an array of JSON nodes that are the values of the elements found 16 | in the JSON array. Each of these is a structure of type 17 | :ref:`dpiJsonNode`. 18 | 19 | .. member:: dpiDataBuffer* dpiJsonArray.elementValues 20 | 21 | Specifies an array of buffers that contain the data for the values of the 22 | elements found in the JSON array. This member should not be used directly. 23 | Instead, the :member:`dpiJsonNode.value` member of the corresponding node 24 | in the member :member:`~dpiJsonArray.elements` should be used. 25 | -------------------------------------------------------------------------------- /doc/src/structs/dpiJsonNode.rst: -------------------------------------------------------------------------------- 1 | .. _dpiJsonNode: 2 | 3 | ODPI-C Structure dpiJsonNode 4 | ---------------------------- 5 | 6 | This structure is used for passing JSON node data to and from the database in 7 | the structure :ref:`dpiData`. Nodes can consist of scalar values, 8 | objects, or arrays. 9 | 10 | .. member:: dpiOracleTypeNum dpiJsonNode.oracleTypeNum 11 | 12 | The Oracle type of the data that is stored in the node. It will be one of 13 | the values from the enumeration :ref:`dpiOracleTypeNum`. 14 | 15 | .. member:: dpiNativeTypeNum dpiJsonNode.nativeTypeNum 16 | 17 | The native type of the data that is stored in the node. It will be one of 18 | the values from the enumeration :ref:`dpiNativeTypeNum`. 19 | 20 | .. member:: dpiDataBuffer* dpiJsonNode.value 21 | 22 | The value that is stored in the node. It is a union of type 23 | :ref:`dpiDataBuffer`. 24 | -------------------------------------------------------------------------------- /doc/src/structs/dpiJsonObject.rst: -------------------------------------------------------------------------------- 1 | .. _dpiJsonObject: 2 | 3 | ODPI-C Structure dpiJsonObject 4 | ------------------------------ 5 | 6 | This structure is used for passing JSON objects to and from the database. 7 | 8 | .. member:: uint32_t dpiJsonObject.numFields 9 | 10 | Specifies the number of fields that are found in the JSON object. This also 11 | identifies the number of elements in each of the remaining arrays. 12 | 13 | .. member:: char** dpiJsonObject.fieldNames 14 | 15 | Specifies an array of field names that are found in the JSON object. Each 16 | element is a byte string encoded in UTF-8. The length of each byte string 17 | is found in the :member:`~dpiJsonObject.fieldNameLengths` member. 18 | 19 | .. member:: uint32_t* dpiJsonObject.fieldNameLengths 20 | 21 | Specifies an array of lengths for the names of the fields found in the JSON 22 | object. 23 | 24 | .. member:: dpiJsonNode* dpiJsonObject.fields 25 | 26 | Specifies an array of JSON nodes that are the values of the fields found in 27 | the JSON object. Each of these is a structure of type 28 | :ref:`dpiJsonNode`. 29 | 30 | .. member:: dpiDataBuffer* dpiJsonObject.fieldValues 31 | 32 | Specifies an array of buffers that contain the data for the values of the 33 | fields found in the JSON object. This member should not be used directly. 34 | Instead, the :member:`dpiJsonNode.value` member of the corresponding node 35 | in the member :member:`~dpiJsonObject.fields` should be used. 36 | -------------------------------------------------------------------------------- /doc/src/structs/dpiMsgRecipient.rst: -------------------------------------------------------------------------------- 1 | .. _dpiMsgRecipient: 2 | 3 | ODPI-C Structure dpiMsgRecipient 4 | -------------------------------- 5 | 6 | This structure is used to set recipients for an AQ message. 7 | 8 | A list of recipient names can be associated with a message at the time 9 | a message is enqueued. This allows a limited set of recipients to 10 | dequeue each message. The recipient list associated with the message 11 | overrides the queue subscriber list, if there is one. The recipient 12 | names need not be in the subscriber list but can be, if desired. 13 | 14 | To dequeue a message, the consumername attribute can be set to one of 15 | the recipient names. The original message recipient list is not 16 | available on dequeued messages. All recipients have to dequeue a 17 | message before it gets removed from the queue. 18 | 19 | Subscribing to a queue is like subscribing to a magazine: each 20 | subscriber can dequeue all the messages placed into a specific queue, 21 | just as each magazine subscriber has access to all its articles. Being 22 | a recipient, however, is like getting a letter: each recipient is a 23 | designated target of a particular message. 24 | 25 | .. member:: const char* dpiMsgRecipient.name 26 | 27 | Specifies the name of the message recipient, in the encoding used for 28 | CHAR data. 29 | 30 | .. member:: uint32_t dpiMsgRecipient.nameLength 31 | 32 | Specifies the length of the :member:`dpiMsgRecipient.name` member, in 33 | bytes. 34 | -------------------------------------------------------------------------------- /doc/src/structs/dpiObjectAttrInfo.rst: -------------------------------------------------------------------------------- 1 | .. _dpiObjectAttrInfo: 2 | 3 | ODPI-C Structure dpiObjectAttrInfo 4 | ---------------------------------- 5 | 6 | This structure is used for passing information about an object type from ODPI-C. 7 | It is used by the function :func:`dpiObjectAttr_getInfo()`. 8 | 9 | .. member:: const char* dpiObjectAttrInfo.name 10 | 11 | Specifies the name of the attribute, as a byte string in the encoding used 12 | for CHAR data. 13 | 14 | .. member:: uint32_t dpiObjectAttrInfo.nameLength 15 | 16 | Specifies the length of the :member:`dpiObjectAttrInfo.name` member, in 17 | bytes. 18 | 19 | .. member:: dpiDataTypeInfo dpiObjectAttrInfo.typeInfo 20 | 21 | Specifies the type of data of the attribute. It is a structure of type 22 | :ref:`dpiDataTypeInfo`. 23 | -------------------------------------------------------------------------------- /doc/src/structs/dpiObjectTypeInfo.rst: -------------------------------------------------------------------------------- 1 | .. _dpiObjectTypeInfo: 2 | 3 | ODPI-C Structure dpiObjectTypeInfo 4 | ---------------------------------- 5 | 6 | This structure is used for passing information about an object type from ODPI-C. 7 | It is used by the function :func:`dpiObjectType_getInfo()`. 8 | 9 | .. member:: const char* dpiObjectTypeInfo.schema 10 | 11 | Specifies the schema which owns the object type, as a byte string in the 12 | encoding used for CHAR data. 13 | 14 | .. member:: uint32_t dpiObjectTypeInfo.schemaLength 15 | 16 | Specifies the length of the :member:`dpiObjectTypeInfo.schema` member, in 17 | bytes. 18 | 19 | .. member:: const char* dpiObjectTypeInfo.name 20 | 21 | Specifies the name of the object type, as a byte string in the encoding 22 | used for CHAR data. 23 | 24 | .. member:: uint32_t dpiObjectTypeInfo.nameLength 25 | 26 | Specifies the length of the :member:`dpiObjectTypeInfo.name` member, in 27 | bytes. 28 | 29 | .. member:: int dpiObjectTypeInfo.isCollection 30 | 31 | Specifies if the object type is a collection (1) or not (0). 32 | 33 | .. member:: dpiDataTypeInfo dpiObjectTypeInfo.elementTypeInfo 34 | 35 | Specifies the type of data of the elements in the collection. It is a 36 | structure of type :ref:`dpiDataTypeInfo` which is only 37 | valid if the object type is a collection. 38 | 39 | .. member:: uint16_t dpiObjectTypeInfo.numAttributes 40 | 41 | Specifies the number of attributes that the object type has. 42 | 43 | .. member:: const char* dpiObjectTypeInfo.packageName 44 | 45 | Specifies the name of the name of the package for a PL/SQL type, as a byte 46 | string in the encoding used for CHAR data. If the type is not a PL/SQL 47 | type, this value is NULL. 48 | 49 | .. member:: uint32_t dpiObjectTypeInfo.packageNameLength 50 | 51 | Specifies the length of the :member:`dpiObjectTypeInfo.packageName` member, 52 | in bytes. 53 | -------------------------------------------------------------------------------- /doc/src/structs/dpiQueryInfo.rst: -------------------------------------------------------------------------------- 1 | .. _dpiQueryInfo: 2 | 3 | ODPI-C Structure dpiQueryInfo 4 | ----------------------------- 5 | 6 | This structure is used for passing query metadata from ODPI-C. It is populated 7 | by the function :func:`dpiStmt_getQueryInfo()`. All values remain valid as long 8 | as a reference is held to the statement and the statement is not re-executed or 9 | closed. 10 | 11 | .. member:: const char* dpiQueryInfo.name 12 | 13 | Specifies the name of the column which is being queried, as a byte string 14 | in the encoding used for CHAR data. 15 | 16 | .. member:: uint32_t dpiQueryInfo.nameLength 17 | 18 | Specifies the length of the :member:`dpiQueryInfo.name` member, in bytes. 19 | 20 | .. member:: dpiDataTypeInfo dpiQueryInfo.typeInfo 21 | 22 | Specifies the type of data of the column that is being queried. It is a 23 | structure of type :ref:`dpiDataTypeInfo`. 24 | 25 | .. member:: int dpiQueryInfo.nullOk 26 | 27 | Specifies if the data that is being queried may return null values (1) or 28 | not (0). 29 | -------------------------------------------------------------------------------- /doc/src/structs/dpiShardingKeyColumn.rst: -------------------------------------------------------------------------------- 1 | .. _dpiShardingKeyColumn: 2 | 3 | ODPI-C Structure dpiShardingKeyColumn 4 | ------------------------------------- 5 | 6 | This structure is used for passing sharding key column values to the database. 7 | It is part of the structure :ref:`dpiConnCreateParams`. 8 | 9 | .. member:: dpiOracleTypeNum dpiShardingKeyColumn.oracleTypeNum 10 | 11 | Specifies the Oracle type of the column which makes up the sharding key. It 12 | is expected to be one of the values from the enumeration 13 | :ref:`dpiOracleTypeNum` but currently only the value 14 | DPI_ORACLE_TYPE_VARCHAR is supported. 15 | 16 | .. member:: dpiNativeTypeNum dpiShardingKeyColumn.nativeTypeNum 17 | 18 | Specifies the native type of the column which makes up the sharding key. It 19 | is expected to be one of the values from the enumeration 20 | :ref:`dpiNativeTypeNum` but currently only the value 21 | DPI_NATIVE_TYPE_BYTES is supported. 22 | 23 | .. member:: dpiDataBuffer dpiShardingKeyColumn.value 24 | 25 | Specifies the value of the column which makes up the sharding key. It is a 26 | union of type :ref:`dpiDataBuffer` and the member of the 27 | union that is set must correspond to the value of the member 28 | :member:`dpiShardingKeyColumn.nativeTypeNum`. 29 | -------------------------------------------------------------------------------- /doc/src/structs/dpiStmtInfo.rst: -------------------------------------------------------------------------------- 1 | .. _dpiStmtInfo: 2 | 3 | ODPI-C Structure dpiStmtInfo 4 | ---------------------------- 5 | 6 | This structure is used for passing information about a statement from ODPI-C. It 7 | is used by the function :func:`dpiStmt_getInfo()`. 8 | 9 | .. member:: int dpiStmtInfo.isQuery 10 | 11 | Specifies if the statement refers to a query (1) or not (0). 12 | 13 | .. member:: int dpiStmtInfo.isPLSQL 14 | 15 | Specifies if the statement refers to a PL/SQL block (1) or not (0). 16 | 17 | .. member:: int dpiStmtInfo.isDDL 18 | 19 | Specifies if the statement refers to DDL (data definition language) such 20 | as creating a table (1) or not (0). 21 | 22 | .. member:: int dpiStmtInfo.isDML 23 | 24 | Specifies if the statement refers to DML (data manipulation language) such 25 | as inserting, updating and deleting (1) or not (0). 26 | 27 | .. member:: dpiStatementType dpiStmtInfo.statementType 28 | 29 | Specifies the type of statement that has been prepared. The members 30 | :member:`dpiStmtInfo.isQuery`, :member:`dpiStmtInfo.isPLSQL`, 31 | :member:`dpiStmtInfo.isDDL` and :member:`dpiStmtInfo.isDML` are all 32 | categorizations of this value. It will be one of the values from the 33 | enumeration :ref:`dpiStatementType`. 34 | 35 | .. member:: int dpiStmtInfo.isReturning 36 | 37 | Specifies if the statement has a returning clause in it (1) or not (0). 38 | -------------------------------------------------------------------------------- /doc/src/structs/dpiStringList.rst: -------------------------------------------------------------------------------- 1 | .. _dpiStringList: 2 | 3 | ODPI-C Structure dpiStringList 4 | ------------------------------ 5 | 6 | This structure is used for receiving a list of strings from such functions as 7 | :func:`dpiSodaDb_getCollectionNames()` and :func:`dpiSodaColl_listIndexes()`. 8 | The memory referenced by this structure should be freed by the function 9 | :func:`dpiContext_freeStringList()` and should not be manipulated directly. 10 | 11 | .. member:: uint32_t dpiStringList.numStrings 12 | 13 | Specifies the number of elements in the strings and stringLengths arrays. 14 | 15 | .. member:: const char** dpiStringList.strings 16 | 17 | Specifies an array of pointers to strings. The length of this array is 18 | specified by the numStrings attribute. 19 | 20 | .. member:: uint32_t* dpiStringList.stringLengths 21 | 22 | Specifies an array of lengths. Each element in this array is the length of 23 | the string found in the corresponding element in the strings array, in 24 | bytes. The length of this array is specified by the numStrings attribute. 25 | -------------------------------------------------------------------------------- /doc/src/structs/dpiSubscrMessageQuery.rst: -------------------------------------------------------------------------------- 1 | .. _dpiSubscrMessageQuery: 2 | 3 | ODPI-C Structure dpiSubscrMessageQuery 4 | -------------------------------------- 5 | 6 | This structure is used for passing information on query change notification 7 | events and is part of the :ref:`dpiSubscrMessage` structure. 8 | 9 | .. member:: uint64_t dpiSubscrMessageQuery.id 10 | 11 | Specifies the id of the query that was registered as part of the 12 | subscription that generated this notification. 13 | 14 | .. member:: dpiOpCode dpiSubscrMessageQuery.operation 15 | 16 | Specifies the operations that took place on the registered query. It will 17 | be one or more of the values from the enumeration 18 | :ref:`dpiOpCode`, OR'ed together. 19 | 20 | .. member:: dpiSubscrMessageTable* dpiSubscrMessageQuery.tables 21 | 22 | Specifies a pointer to an array of 23 | :ref:`dpiSubscrMessageTable` structures representing 24 | the list of tables that were modified by the event which generated this 25 | notification. 26 | 27 | .. member:: uint32_t dpiSubscrMessageQuery.numTables 28 | 29 | Specifies the number of structures available in the 30 | :member:`dpiSubscrMessageQuery.tables` member. 31 | -------------------------------------------------------------------------------- /doc/src/structs/dpiSubscrMessageRow.rst: -------------------------------------------------------------------------------- 1 | .. _dpiSubscrMessageRow: 2 | 3 | ODPI-C Structure dpiSubscrMessageRow 4 | ------------------------------------ 5 | 6 | This structure is used for passing information on the rows that were changed 7 | and resulted in the notification message of which this structure is a part. 8 | 9 | .. member:: dpiOpCode dpiSubscrMessageRow.operation 10 | 11 | Specifies the operations that took place on the registered query. It will 12 | be one or more of the values from the enumeration 13 | :ref:`dpiOpCode`, OR'ed together. 14 | 15 | .. member:: const char* dpiSubscrMessageRow.rowid 16 | 17 | Specifies the rowid of the row that was changed, in the encoding used for 18 | CHAR data. 19 | 20 | .. member:: uint32_t dpiSubscrMessageRow.rowidLength 21 | 22 | Specifies the length of the :member:`dpiSubscrMessageRow.rowid` member, in 23 | bytes. 24 | -------------------------------------------------------------------------------- /doc/src/structs/dpiSubscrMessageTable.rst: -------------------------------------------------------------------------------- 1 | .. _dpiSubscrMessageTable: 2 | 3 | ODPI-C Structure dpiSubscrMessageTable 4 | -------------------------------------- 5 | 6 | This structure is used for passing information on the tables that were changed 7 | and resulted in the notification message of which this structure is a part. 8 | 9 | .. member:: dpiOpCode dpiSubscrMessageTable.operation 10 | 11 | Specifies the operations that took place on the modified table. It will 12 | be one or more of the values from the enumeration 13 | :ref:`dpiOpCode`, OR'ed together. 14 | 15 | .. member:: const char* dpiSubscrMessageRow.name 16 | 17 | Specifies the name of the table that was changed, in the encoding used for 18 | CHAR data. 19 | 20 | .. member:: uint32_t dpiSubscrMessageRow.nameLength 21 | 22 | Specifies the length of the :member:`dpiSubscrMessageRow.name` member, in 23 | bytes. 24 | 25 | .. member:: dpiSubscrMessageRow* dpiSubscrMessageTable.rows 26 | 27 | Specifies a pointer to an array of 28 | :ref:`dpiSubscrMessageRow` structures representing the 29 | list of rows that were modified by the event which generated this 30 | notification. 31 | 32 | .. member:: uint32_t dpiSubscrMessageTable.numRows 33 | 34 | Specifies the number of structures available in the 35 | :member:`dpiSubscrMessageTable.rows` member. 36 | -------------------------------------------------------------------------------- /doc/src/structs/dpiTimestamp.rst: -------------------------------------------------------------------------------- 1 | .. _dpiTimestamp: 2 | 3 | ODPI-C Structure dpiTimestamp 4 | ----------------------------- 5 | 6 | This structure is used for passing timestamp data to and from the database in 7 | the structure :ref:`dpiData`. 8 | 9 | .. member:: int16_t dpiTimestamp.year 10 | 11 | Specifies the year for the timestamp. 12 | 13 | .. member:: uint8_t dpiTimestamp.month 14 | 15 | Specifies the month for the timestamp. This should be between 1 and 12. 16 | 17 | .. member:: uint8_t dpiTimestamp.day 18 | 19 | Specifies the day for the timestamp. This should be between 1 and 31. 20 | 21 | .. member:: uint8_t dpiTimestamp.hour 22 | 23 | Specifies the hour for the timestamp. This should be between 0 and 23. 24 | 25 | .. member:: uint8_t dpiTimestamp.minute 26 | 27 | Specifies the minute for the timestamp. This should be between 0 and 59. 28 | 29 | .. member:: uint8_t dpiTimestamp.second 30 | 31 | Specifies the second for the timestamp. This should be between 0 and 59. 32 | 33 | .. member:: uint32_t dpiTimestamp.fsecond 34 | 35 | Specifies the fractional seconds for the timestamp, in nanoseconds. 36 | 37 | .. member:: int8_t dpiTimestamp.tzHourOffset 38 | 39 | Specifies the hours offset from UTC. This value is only used for timestamp 40 | with time zone and timestamp with local time zone columns. 41 | 42 | .. member:: int8_t dpiTimestamp.tzMinuteOffset 43 | 44 | Specifies the minutes offset from UTC. This value is only used for 45 | timestamp with time zone and timestamp with local time zone columns. Note 46 | that this value will be negative in the western hemisphere. For example, 47 | when the timezone is -03:30, tzHourOffset will be -3 and tzMinuteOffset 48 | will be -30. 49 | -------------------------------------------------------------------------------- /doc/src/structs/dpiVectorInfo.rst: -------------------------------------------------------------------------------- 1 | .. _dpiVectorInfo: 2 | 3 | ODPI-C Structure dpiVectorInfo 4 | ------------------------------- 5 | 6 | This structure is used for providing or receiving information about a vector. 7 | 8 | .. member:: uint8_t dpiVectorInfo.format 9 | 10 | Specifies the storage format for the vector. It should be one of the values 11 | from the enumeration :ref:`dpiVectorFormat`. 12 | 13 | .. member:: uint32_t dpiVectorInfo.numDimensions 14 | 15 | Specifies the number of dimensions the vector contains. 16 | 17 | .. member:: uint8_t dpiVectorInfo.dimensionSize 18 | 19 | Specifies the size (in bytes) of each dimension of the vector. This value 20 | does not need to be specified on input but is populated on output as a 21 | convenience. 22 | 23 | .. member:: dpiVectorDimensionBuffer dpiVectorInfo.dimensions 24 | 25 | Specifies the buffer for the dimensions. On input the buffer must remain 26 | valid for the duration of the call into ODPI-C. On output the buffer will 27 | remain valid as long as the vector object remains valid and the contents of 28 | the vector are not changed. See the 29 | :ref:`dpiVectorDimensionBuffer` union for more 30 | information. 31 | 32 | For dense vectors, the length of this array is defined by the 33 | :member:`~dpiVectorInfo.numDimensions` member. For sparse vectors, the 34 | length of this array is defined by the 35 | :member:`~dpiVectorInfo.numSparseValues` member. 36 | 37 | .. member:: uint32_t dpiVectorInfo.numSparseValues 38 | 39 | Specifies the number of values that a sparse vector contains that are 40 | non-zero. If this value is 0, the vector is considered a dense vector. 41 | 42 | .. member:: uint32_t* dpiVectorInfo.sparseIndices 43 | 44 | Specifies an array of sparse vector indices. Each element in this array is 45 | the index of a non-zero value in the vector. The length of this array is 46 | defined by the :member:`~dpiVectorInfo.numSparseValues` member. If the 47 | vector is not a sparse vector, this value will be NULL. 48 | -------------------------------------------------------------------------------- /doc/src/structs/dpiVersionInfo.rst: -------------------------------------------------------------------------------- 1 | .. _dpiVersionInfo: 2 | 3 | ODPI-C Structure dpiVersionInfo 4 | ------------------------------- 5 | 6 | This structure is used for returning Oracle version information about the 7 | Oracle Client (:func:`dpiContext_getClientVersion()`) and Oracle Database 8 | (:func:`dpiConn_getServerVersion()`). 9 | 10 | .. member:: int dpiVersionInfo.versionNum 11 | 12 | Specifies the major version of the Oracle Client or Database. 13 | 14 | .. member:: int dpiVersionInfo.releaseNum 15 | 16 | Specifies the release version of the Oracle Client or Database. 17 | 18 | .. member:: int dpiVersionInfo.updateNum 19 | 20 | Specifies the update version of the Oracle Client or Database. 21 | 22 | .. member:: int dpiVersionInfo.portReleaseNum 23 | 24 | Specifies the port specific release version of the Oracle Client or 25 | Database. 26 | 27 | .. member:: int dpiVersionInfo.portUpdateNum 28 | 29 | Specifies the port specific update version of the Oracle Client or 30 | Database. 31 | 32 | .. member:: uint32_t dpiVersionInfo.fullVersionNum 33 | 34 | Specifies the full version (all five components) as a number that is 35 | suitable for comparison with the result of the macro 36 | DPI_ORACLE_VERSION_TO_NUMBER. 37 | -------------------------------------------------------------------------------- /doc/src/structs/dpiXid.rst: -------------------------------------------------------------------------------- 1 | .. _dpiXid: 2 | 3 | ODPI-C Structure dpiXid 4 | ------------------------------- 5 | 6 | This structure is used for identifying a TPC (two-phase commit) transaction. It 7 | is used by the TPC functions :func:`dpiConn_tpcBegin()`, 8 | :func:`dpiConn_tpcCommit()`, :func:`dpiConn_tpcEnd()`, 9 | :func:`dpiConn_tpcForget()`, :func:`dpiConn_tpcPrepare()` and 10 | :func:`dpiConn_tpcRollback()`. 11 | 12 | .. member:: long dpiXid.formatId 13 | 14 | An integer identifying the format the transaction id is expected to take. 15 | A value of -1 implies that the XID value is NULL. 16 | 17 | .. member:: const char* dpiXid.globalTransactionId 18 | 19 | Specifies the global transaction identifier of the XID. 20 | 21 | .. member:: uint32_t dpiXid.globalTransactionIdLength 22 | 23 | Specifies the length of the :data:`dpiXid.globalTransactionId` member, in 24 | bytes. The maximum supported length is 64 bytes. 25 | 26 | .. member:: const char* dpiXid.branchQualifier 27 | 28 | Specifies the branch qualifier of the XID. 29 | 30 | .. member:: uint32_t dpiXid.branchQualifierLength 31 | 32 | Specifies the length of the :data:`dpiXid.branchQualifier` member, in 33 | bytes. The maximum supported length is 64 bytes. 34 | -------------------------------------------------------------------------------- /doc/src/structs/index.rst: -------------------------------------------------------------------------------- 1 | ***************** 2 | ODPI-C Structures 3 | ***************** 4 | 5 | This chapter details the structures available in the ODPI-C library. 6 | 7 | .. toctree:: 8 | :maxdepth: 1 9 | :hidden: 10 | 11 | dpiAccessToken 12 | dpiAnnotation 13 | dpiAppContext 14 | dpiBytes 15 | dpiCommonCreateParams 16 | dpiConnCreateParams 17 | dpiConnInfo 18 | dpiContextCreateParams 19 | dpiData 20 | dpiDataTypeInfo 21 | dpiEncodingInfo 22 | dpiErrorInfo 23 | dpiIntervalDS 24 | dpiIntervalYM 25 | dpiJsonArray 26 | dpiJsonNode 27 | dpiJsonObject 28 | dpiMsgRecipient 29 | dpiObjectAttrInfo 30 | dpiObjectTypeInfo 31 | dpiPoolCreateParams 32 | dpiQueryInfo 33 | dpiShardingKeyColumn 34 | dpiSodaOperOptions 35 | dpiStmtInfo 36 | dpiStringList 37 | dpiSubscrCreateParams 38 | dpiSubscrMessage 39 | dpiSubscrMessageQuery 40 | dpiSubscrMessageRow 41 | dpiSubscrMessageTable 42 | dpiTimestamp 43 | dpiVectorInfo 44 | dpiVersionInfo 45 | dpiXid 46 | -------------------------------------------------------------------------------- /doc/src/unions/dpiVectorDimensionBuffer.rst: -------------------------------------------------------------------------------- 1 | .. _dpiVectorDimensionBuffer: 2 | 3 | ODPI-C Union dpiVectorDimensionBuffer 4 | -------------------------------------- 5 | 6 | This union is used for passing vector dimensions to and from the database 7 | without requiring casts. 8 | 9 | .. member:: void* dpiVectorDimensionBuffer.asPtr 10 | 11 | Raw pointer to dimension buffer. 12 | 13 | .. member:: int8_t* dpiVectorDimensionBuffer.asInt8 14 | 15 | Pointer to dimension buffer when vector format is VECTOR_FORMAT_INT8. 16 | 17 | .. member:: float* dpiVectorDimensionBuffer.asFloat 18 | 19 | Pointer to dimension buffer when vector format is VECTOR_FORMAT_FLOAT32. 20 | 21 | .. member:: double* dpiVectorDimensionBuffer.asDouble 22 | 23 | Pointer to dimension buffer when vector format is VECTOR_FORMAT_FLOAT64. 24 | -------------------------------------------------------------------------------- /doc/src/unions/index.rst: -------------------------------------------------------------------------------- 1 | ************* 2 | ODPI-C Unions 3 | ************* 4 | 5 | This chapter details the unions available in the ODPI-C library. 6 | 7 | .. toctree:: 8 | :maxdepth: 1 9 | :hidden: 10 | 11 | dpiDataBuffer 12 | dpiVectorDimensionBuffer 13 | -------------------------------------------------------------------------------- /doc/src/user_guide/debugging.rst: -------------------------------------------------------------------------------- 1 | .. _debugging: 2 | 3 | **************** 4 | ODPI-C Debugging 5 | **************** 6 | 7 | .. _level: 8 | 9 | Level 10 | ===== 11 | 12 | The environment variable DPI_DEBUG_LEVEL can be used to selectively turn on 13 | the printing of various logging messages as defined in the following table. All 14 | messages are printed to stderr. Each level is independent of all other levels 15 | and the values of each level can be added to one another to choose which 16 | messages will be printed. 17 | 18 | .. list-table-with-summary:: 19 | :header-rows: 1 20 | :class: wy-table-responsive 21 | :widths: 10 5 7 30 22 | :summary: The first column displays the level. The second column displays 23 | the hex value. The third column displays the decimal value. The fourth 24 | column displays the description of the debug level. 25 | 26 | * - Level 27 | - Hex Value 28 | - Decimal Value 29 | - Description 30 | * - DPI_DEBUG_LEVEL_UNREPORTED_ERRORS 31 | - 0x0001 32 | - 1 33 | - Prints messages when unreported errors take place (such as when an 34 | error takes place during the freeing of OCI handles and descriptors). 35 | * - DPI_DEBUG_LEVEL_REFS 36 | - 0x0002 37 | - 2 38 | - Prints messages when reference counts are added and released. 39 | * - DPI_DEBUG_LEVEL_FNS 40 | - 0x0004 41 | - 4 42 | - Prints messages when a public ODPI-C function is called. 43 | * - DPI_DEBUG_LEVEL_ERRORS 44 | - 0x0008 45 | - 8 46 | - Prints messages when an error is raised. 47 | * - DPI_DEBUG_LEVEL_SQL 48 | - 0x0010 49 | - 16 50 | - Prints the text of all SQL that is prepared. Bind values are not 51 | displayed. 52 | * - DPI_DEBUG_LEVEL_MEM 53 | - 0x0020 54 | - 32 55 | - Prints the location and size of all memory allocations and frees 56 | performed by the library. 57 | * - DPI_DEBUG_LEVEL_LOAD_LIB 58 | - 0x0040 59 | - 64 60 | - Prints the methods and locations searched for the Oracle Client library 61 | in addition to any errors that took place. 62 | 63 | .. _prefix: 64 | 65 | Prefix 66 | ====== 67 | 68 | The environment variable DPI_DEBUG_PREFIX can be used to specify the prefix 69 | that is printed in front of each debugging message. If not set, the default 70 | prefix is ``"ODPI [%i] %d %t: "``. The maximum length of the prefix string that 71 | can be set is 64 characters. If an attempt is made to set a value longer than 72 | that, it is ignored and the default prefix is used instead. 73 | 74 | The following directives can be used within the prefix: 75 | 76 | .. list-table-with-summary:: 77 | :header-rows: 1 78 | :class: wy-table-responsive 79 | :widths: 15 30 80 | :summary: The first column displays the directive. The second column displays 81 | the comments. 82 | 83 | * - Directive 84 | - Comments 85 | * - %i 86 | - Replaced by the identifier of the thread that is printing the message 87 | * - %d 88 | - Replaced by the date the message is printed, in the format YYYY/MM/DD 89 | * - %t 90 | - Replaced by the time the message is printed, in the format HH:MM:SS.SSS 91 | 92 | All other characters in the prefix are copied unchanged to the output. 93 | 94 | .. _memtracing: 95 | 96 | Memory Tracing 97 | ============== 98 | 99 | The Python script `mem_leak.py 100 | `__ can be used to 101 | search for memory leaks. The script's argument should be the name of a file 102 | containing trace output when DPI_DEBUG_LEVEL is set to DPI_DEBUG_LEVEL_MEM:: 103 | 104 | export DPI_DEBUG_LEVEL=32 105 | ./myprog >& mem.log 106 | python mem_leak.py mem.log 107 | -------------------------------------------------------------------------------- /doc/src/user_guide/introduction.rst: -------------------------------------------------------------------------------- 1 | .. _introduction: 2 | 3 | Introduction to ODPI-C 4 | ---------------------- 5 | 6 | Oracle Database Programming Interface for C (ODPI-C) is an open source library 7 | of C code that simplifies access to Oracle Database for applications written 8 | in C or C++. It is a wrapper over `Oracle Call Interface (OCI) 9 | `__ that 10 | makes applications and language interfaces easier to develop. 11 | 12 | ODPI-C supports basic and advanced features of Oracle Database and Oracle 13 | Client. A complete list of features can be seen 14 | `here `__. 15 | -------------------------------------------------------------------------------- /embed/README.md: -------------------------------------------------------------------------------- 1 | This directory contains the file dpi.c which can be used to embed ODPI-C 2 | within your project without having to manage the individual files that make up 3 | the library. The files can also be compiled independently if that is preferred. 4 | -------------------------------------------------------------------------------- /embed/dpi.c: -------------------------------------------------------------------------------- 1 | //----------------------------------------------------------------------------- 2 | // Copyright (c) 2018, 2024, Oracle and/or its affiliates. 3 | // 4 | // This software is dual-licensed to you under the Universal Permissive License 5 | // (UPL) 1.0 as shown at https://oss.oracle.com/licenses/upl and Apache License 6 | // 2.0 as shown at http://www.apache.org/licenses/LICENSE-2.0. You may choose 7 | // either license. 8 | // 9 | // If you elect to accept the software under the Apache License, Version 2.0, 10 | // the following applies: 11 | // 12 | // Licensed under the Apache License, Version 2.0 (the "License"); 13 | // you may not use this file except in compliance with the License. 14 | // You may obtain a copy of the License at 15 | // 16 | // https://www.apache.org/licenses/LICENSE-2.0 17 | // 18 | // Unless required by applicable law or agreed to in writing, software 19 | // distributed under the License is distributed on an "AS IS" BASIS, 20 | // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 21 | // See the License for the specific language governing permissions and 22 | // limitations under the License. 23 | //----------------------------------------------------------------------------- 24 | 25 | //----------------------------------------------------------------------------- 26 | // dpi.c 27 | // Include this file in your project in order to embed ODPI-C source without 28 | // having to compile files individually. Only the definitions in the file 29 | // include/dpi.h are intended to be used publicly. Each file can also be 30 | // compiled independently if that is preferable. 31 | //----------------------------------------------------------------------------- 32 | 33 | #include "../src/dpiConn.c" 34 | #include "../src/dpiContext.c" 35 | #include "../src/dpiData.c" 36 | #include "../src/dpiDebug.c" 37 | #include "../src/dpiDeqOptions.c" 38 | #include "../src/dpiEnqOptions.c" 39 | #include "../src/dpiEnv.c" 40 | #include "../src/dpiError.c" 41 | #include "../src/dpiGen.c" 42 | #include "../src/dpiGlobal.c" 43 | #include "../src/dpiHandleList.c" 44 | #include "../src/dpiHandlePool.c" 45 | #include "../src/dpiJson.c" 46 | #include "../src/dpiLob.c" 47 | #include "../src/dpiMsgProps.c" 48 | #include "../src/dpiObjectAttr.c" 49 | #include "../src/dpiObject.c" 50 | #include "../src/dpiObjectType.c" 51 | #include "../src/dpiOci.c" 52 | #include "../src/dpiOracleType.c" 53 | #include "../src/dpiPool.c" 54 | #include "../src/dpiQueue.c" 55 | #include "../src/dpiRowid.c" 56 | #include "../src/dpiSodaColl.c" 57 | #include "../src/dpiSodaCollCursor.c" 58 | #include "../src/dpiSodaDb.c" 59 | #include "../src/dpiSodaDoc.c" 60 | #include "../src/dpiSodaDocCursor.c" 61 | #include "../src/dpiStmt.c" 62 | #include "../src/dpiStringList.c" 63 | #include "../src/dpiSubscr.c" 64 | #include "../src/dpiUtils.c" 65 | #include "../src/dpiVar.c" 66 | #include "../src/dpiVector.c" 67 | -------------------------------------------------------------------------------- /samples/DemoCallProc.c: -------------------------------------------------------------------------------- 1 | //----------------------------------------------------------------------------- 2 | // Copyright (c) 2016, 2022, Oracle and/or its affiliates. 3 | // 4 | // This software is dual-licensed to you under the Universal Permissive License 5 | // (UPL) 1.0 as shown at https://oss.oracle.com/licenses/upl and Apache License 6 | // 2.0 as shown at http://www.apache.org/licenses/LICENSE-2.0. You may choose 7 | // either license. 8 | // 9 | // If you elect to accept the software under the Apache License, Version 2.0, 10 | // the following applies: 11 | // 12 | // Licensed under the Apache License, Version 2.0 (the "License"); 13 | // you may not use this file except in compliance with the License. 14 | // You may obtain a copy of the License at 15 | // 16 | // https://www.apache.org/licenses/LICENSE-2.0 17 | // 18 | // Unless required by applicable law or agreed to in writing, software 19 | // distributed under the License is distributed on an "AS IS" BASIS, 20 | // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 21 | // See the License for the specific language governing permissions and 22 | // limitations under the License. 23 | //----------------------------------------------------------------------------- 24 | 25 | //----------------------------------------------------------------------------- 26 | // DemoCallProc.c 27 | // Demos simple call of stored procedure with in, in/out and out variables. 28 | //----------------------------------------------------------------------------- 29 | 30 | #include "SampleLib.h" 31 | #define SQL_TEXT "begin proc_Demo(:1, :2, :3); end;" 32 | 33 | //----------------------------------------------------------------------------- 34 | // main() 35 | //----------------------------------------------------------------------------- 36 | int main(int argc, char **argv) 37 | { 38 | dpiData *inOutValue, *outValue, inValue; 39 | dpiVar *inOutVar, *outVar; 40 | uint32_t numQueryColumns; 41 | dpiStmt *stmt; 42 | dpiConn *conn; 43 | 44 | // connect to database and create statement 45 | conn = dpiSamples_getConn(0, NULL); 46 | if (dpiConn_prepareStmt(conn, 0, SQL_TEXT, strlen(SQL_TEXT), NULL, 0, 47 | &stmt) < 0) 48 | return dpiSamples_showError(); 49 | 50 | // bind IN value 51 | inValue.isNull = 0; 52 | inValue.value.asBytes.ptr = "In value for demoing"; 53 | inValue.value.asBytes.length = strlen("In value for demoing"); 54 | if (dpiStmt_bindValueByPos(stmt, 1, DPI_NATIVE_TYPE_BYTES, &inValue) < 0) 55 | return dpiSamples_showError(); 56 | 57 | // bind IN/OUT variable 58 | if (dpiConn_newVar(conn, DPI_ORACLE_TYPE_NUMBER, DPI_NATIVE_TYPE_INT64, 1, 59 | 0, 0, 0, NULL, &inOutVar, &inOutValue) < 0) 60 | return dpiSamples_showError(); 61 | inOutValue->isNull = 0; 62 | inOutValue->value.asInt64 = 347; 63 | if (dpiStmt_bindByPos(stmt, 2, inOutVar) < 0) 64 | return dpiSamples_showError(); 65 | 66 | // bind OUT variable 67 | if (dpiConn_newVar(conn, DPI_ORACLE_TYPE_NUMBER, DPI_NATIVE_TYPE_INT64, 1, 68 | 0, 0, 0, NULL, &outVar, &outValue) < 0) 69 | return dpiSamples_showError(); 70 | if (dpiStmt_bindByPos(stmt, 3, outVar) < 0) 71 | return dpiSamples_showError(); 72 | 73 | // perform execution 74 | if (dpiStmt_execute(stmt, 0, &numQueryColumns) < 0) 75 | return dpiSamples_showError(); 76 | 77 | // display value of IN/OUT variable 78 | printf("IN/OUT value (after call) is %" PRId64 "\n", 79 | inOutValue->value.asInt64); 80 | dpiVar_release(inOutVar); 81 | 82 | // display value of OUT variable 83 | printf("OUT value (after call) is %" PRId64 "\n", outValue->value.asInt64); 84 | dpiVar_release(outVar); 85 | 86 | // clean up 87 | dpiStmt_release(stmt); 88 | dpiConn_release(conn); 89 | 90 | printf("Done.\n"); 91 | return 0; 92 | } 93 | -------------------------------------------------------------------------------- /samples/DemoCreateSodaColl.c: -------------------------------------------------------------------------------- 1 | //----------------------------------------------------------------------------- 2 | // Copyright (c) 2018, 2022, Oracle and/or its affiliates. 3 | // 4 | // This software is dual-licensed to you under the Universal Permissive License 5 | // (UPL) 1.0 as shown at https://oss.oracle.com/licenses/upl and Apache License 6 | // 2.0 as shown at http://www.apache.org/licenses/LICENSE-2.0. You may choose 7 | // either license. 8 | // 9 | // If you elect to accept the software under the Apache License, Version 2.0, 10 | // the following applies: 11 | // 12 | // Licensed under the Apache License, Version 2.0 (the "License"); 13 | // you may not use this file except in compliance with the License. 14 | // You may obtain a copy of the License at 15 | // 16 | // https://www.apache.org/licenses/LICENSE-2.0 17 | // 18 | // Unless required by applicable law or agreed to in writing, software 19 | // distributed under the License is distributed on an "AS IS" BASIS, 20 | // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 21 | // See the License for the specific language governing permissions and 22 | // limitations under the License. 23 | //----------------------------------------------------------------------------- 24 | 25 | //----------------------------------------------------------------------------- 26 | // DemoCreateSodaColl.c 27 | // Demos creating a SODA collection with the specified name. 28 | //----------------------------------------------------------------------------- 29 | 30 | #include "SampleLib.h" 31 | 32 | //----------------------------------------------------------------------------- 33 | // main() 34 | //----------------------------------------------------------------------------- 35 | int main(int argc, char **argv) 36 | { 37 | uint32_t tempLength; 38 | const char *temp; 39 | dpiSodaColl *coll; 40 | dpiSodaDb *db; 41 | char *name; 42 | 43 | // determine name of collection to create 44 | if (argc != 2) { 45 | fprintf(stderr, "Usage: DemoCreateSodaColl \n"); 46 | return 1; 47 | } 48 | name = argv[1]; 49 | printf("Creating SODA collection named %s\n", name); 50 | 51 | // connect to database 52 | db = dpiSamples_getSodaDb(); 53 | 54 | // create new SODA collection 55 | if (dpiSodaDb_createCollection(db, name, strlen(name), NULL, 0, 56 | DPI_SODA_FLAGS_DEFAULT, &coll) < 0) 57 | return dpiSamples_showError(); 58 | 59 | // get the name of the collection 60 | if (dpiSodaColl_getName(coll, &temp, &tempLength) < 0) 61 | return dpiSamples_showError(); 62 | printf("Name of created collection: %.*s\n", tempLength, temp); 63 | 64 | // get the metadata of the collection 65 | if (dpiSodaColl_getMetadata(coll, &temp, &tempLength) < 0) 66 | return dpiSamples_showError(); 67 | printf("Metadata of created collection: %.*s\n", tempLength, temp); 68 | 69 | // clean up 70 | dpiSodaColl_release(coll); 71 | dpiSodaDb_release(db); 72 | 73 | printf("Done.\n"); 74 | return 0; 75 | } 76 | -------------------------------------------------------------------------------- /samples/DemoDropSodaColl.c: -------------------------------------------------------------------------------- 1 | //----------------------------------------------------------------------------- 2 | // Copyright (c) 2018, 2022, Oracle and/or its affiliates. 3 | // 4 | // This software is dual-licensed to you under the Universal Permissive License 5 | // (UPL) 1.0 as shown at https://oss.oracle.com/licenses/upl and Apache License 6 | // 2.0 as shown at http://www.apache.org/licenses/LICENSE-2.0. You may choose 7 | // either license. 8 | // 9 | // If you elect to accept the software under the Apache License, Version 2.0, 10 | // the following applies: 11 | // 12 | // Licensed under the Apache License, Version 2.0 (the "License"); 13 | // you may not use this file except in compliance with the License. 14 | // You may obtain a copy of the License at 15 | // 16 | // https://www.apache.org/licenses/LICENSE-2.0 17 | // 18 | // Unless required by applicable law or agreed to in writing, software 19 | // distributed under the License is distributed on an "AS IS" BASIS, 20 | // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 21 | // See the License for the specific language governing permissions and 22 | // limitations under the License. 23 | //----------------------------------------------------------------------------- 24 | 25 | //----------------------------------------------------------------------------- 26 | // DemoDropSodaColl.c 27 | // Demos dropping a SODA collection with the specified name. 28 | //----------------------------------------------------------------------------- 29 | 30 | #include "SampleLib.h" 31 | 32 | //----------------------------------------------------------------------------- 33 | // main() 34 | //----------------------------------------------------------------------------- 35 | int main(int argc, char **argv) 36 | { 37 | dpiSodaColl *coll; 38 | dpiSodaDb *db; 39 | char *name; 40 | 41 | // determine name of collection to drop 42 | if (argc != 2) { 43 | fprintf(stderr, "Usage: DemoDropSodaColl \n"); 44 | return 1; 45 | } 46 | name = argv[1]; 47 | 48 | // connect to database 49 | db = dpiSamples_getSodaDb(); 50 | 51 | // open the SODA collection first 52 | if (dpiSodaDb_openCollection(db, name, strlen(name), 53 | DPI_SODA_FLAGS_DEFAULT, &coll) < 0) 54 | return dpiSamples_showError(); 55 | if (!coll) { 56 | printf("No collection named %s\n", name); 57 | return 1; 58 | } 59 | 60 | // drop collection 61 | printf("Dropping SODA collection named %s\n", name); 62 | if (dpiSodaColl_drop(coll, DPI_SODA_FLAGS_DEFAULT, NULL) < 0) 63 | return dpiSamples_showError(); 64 | 65 | // clean up 66 | dpiSodaColl_release(coll); 67 | dpiSodaDb_release(db); 68 | 69 | printf("Done.\n"); 70 | return 0; 71 | } 72 | -------------------------------------------------------------------------------- /samples/DemoGetSodaCollNames.c: -------------------------------------------------------------------------------- 1 | //----------------------------------------------------------------------------- 2 | // Copyright (c) 2018, 2022, Oracle and/or its affiliates. 3 | // 4 | // This software is dual-licensed to you under the Universal Permissive License 5 | // (UPL) 1.0 as shown at https://oss.oracle.com/licenses/upl and Apache License 6 | // 2.0 as shown at http://www.apache.org/licenses/LICENSE-2.0. You may choose 7 | // either license. 8 | // 9 | // If you elect to accept the software under the Apache License, Version 2.0, 10 | // the following applies: 11 | // 12 | // Licensed under the Apache License, Version 2.0 (the "License"); 13 | // you may not use this file except in compliance with the License. 14 | // You may obtain a copy of the License at 15 | // 16 | // https://www.apache.org/licenses/LICENSE-2.0 17 | // 18 | // Unless required by applicable law or agreed to in writing, software 19 | // distributed under the License is distributed on an "AS IS" BASIS, 20 | // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 21 | // See the License for the specific language governing permissions and 22 | // limitations under the License. 23 | //----------------------------------------------------------------------------- 24 | 25 | //----------------------------------------------------------------------------- 26 | // DemoGetSodaCollNames.c 27 | // Demos getting the names of all SODA collections using the method 28 | // dpiSodaDb_getCollectionNames(). 29 | //----------------------------------------------------------------------------- 30 | 31 | #include "SampleLib.h" 32 | 33 | //----------------------------------------------------------------------------- 34 | // main() 35 | //----------------------------------------------------------------------------- 36 | int main(int argc, char **argv) 37 | { 38 | uint32_t startingNameLength, i; 39 | dpiSodaCollNames collNames; 40 | const char *startingName; 41 | dpiSodaDb *db; 42 | 43 | // determine starting name to use; no parameters means all collections 44 | if (argc < 2) { 45 | startingName = NULL; 46 | startingNameLength = 0; 47 | printf("Getting all SODA collection names\n"); 48 | } else { 49 | startingName = argv[1]; 50 | startingNameLength = strlen(startingName); 51 | printf("Getting all SODA collection names starting with %s\n", 52 | startingName); 53 | } 54 | 55 | // connect to database 56 | db = dpiSamples_getSodaDb(); 57 | 58 | // get all collection names 59 | if (dpiSodaDb_getCollectionNames(db, startingName, startingNameLength, 0, 60 | DPI_SODA_FLAGS_DEFAULT, &collNames) < 0) 61 | return dpiSamples_showError(); 62 | for (i = 0; i < collNames.numNames; i++) 63 | printf("Collection: %.*s\n", collNames.nameLengths[i], 64 | collNames.names[i]); 65 | 66 | // clean up 67 | dpiSodaDb_freeCollectionNames(db, &collNames); 68 | dpiSodaDb_release(db); 69 | 70 | printf("Done.\n"); 71 | return 0; 72 | } 73 | -------------------------------------------------------------------------------- /samples/DemoIterSodaColls.c: -------------------------------------------------------------------------------- 1 | //----------------------------------------------------------------------------- 2 | // Copyright (c) 2018, 2022, Oracle and/or its affiliates. 3 | // 4 | // This software is dual-licensed to you under the Universal Permissive License 5 | // (UPL) 1.0 as shown at https://oss.oracle.com/licenses/upl and Apache License 6 | // 2.0 as shown at http://www.apache.org/licenses/LICENSE-2.0. You may choose 7 | // either license. 8 | // 9 | // If you elect to accept the software under the Apache License, Version 2.0, 10 | // the following applies: 11 | // 12 | // Licensed under the Apache License, Version 2.0 (the "License"); 13 | // you may not use this file except in compliance with the License. 14 | // You may obtain a copy of the License at 15 | // 16 | // https://www.apache.org/licenses/LICENSE-2.0 17 | // 18 | // Unless required by applicable law or agreed to in writing, software 19 | // distributed under the License is distributed on an "AS IS" BASIS, 20 | // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 21 | // See the License for the specific language governing permissions and 22 | // limitations under the License. 23 | //----------------------------------------------------------------------------- 24 | 25 | //----------------------------------------------------------------------------- 26 | // DemoIterSodaColls.c 27 | // Demos iterating over the SODA collections that are available and displays 28 | // their names. 29 | //----------------------------------------------------------------------------- 30 | 31 | #include "SampleLib.h" 32 | 33 | //----------------------------------------------------------------------------- 34 | // main() 35 | //----------------------------------------------------------------------------- 36 | int main(int argc, char **argv) 37 | { 38 | uint32_t startingNameLength, collectionNameLength; 39 | const char *startingName, *collectionName; 40 | dpiSodaCollCursor *cursor; 41 | dpiSodaColl *coll; 42 | dpiSodaDb *db; 43 | 44 | // determine starting name to use; no parameters means all collections 45 | if (argc < 2) { 46 | startingName = NULL; 47 | startingNameLength = 0; 48 | printf("Iterating all SODA collections\n"); 49 | } else { 50 | startingName = argv[1]; 51 | startingNameLength = strlen(startingName); 52 | printf("Iterating SODA collections starting with %s\n", startingName); 53 | } 54 | 55 | // connect to database 56 | db = dpiSamples_getSodaDb(); 57 | 58 | // get cursor to iterate over SODA collections 59 | if (dpiSodaDb_getCollections(db, startingName, startingNameLength, 60 | DPI_SODA_FLAGS_DEFAULT, &cursor) < 0) 61 | return dpiSamples_showError(); 62 | 63 | // iterate over collections until no more are found 64 | while (1) { 65 | 66 | // get next collection 67 | if (dpiSodaCollCursor_getNext(cursor, DPI_SODA_FLAGS_DEFAULT, 68 | &coll) < 0) 69 | return dpiSamples_showError(); 70 | if (!coll) 71 | break; 72 | 73 | // get the name of the collection 74 | if (dpiSodaColl_getName(coll, &collectionName, 75 | &collectionNameLength) < 0) 76 | return dpiSamples_showError(); 77 | printf("Collection: %.*s\n", collectionNameLength, collectionName); 78 | if (dpiSodaColl_release(coll) < 0) 79 | return dpiSamples_showError(); 80 | } 81 | 82 | // clean up 83 | dpiSodaCollCursor_release(cursor); 84 | dpiSodaDb_release(db); 85 | 86 | printf("Done.\n"); 87 | return 0; 88 | } 89 | -------------------------------------------------------------------------------- /samples/DemoRawAQ.c: -------------------------------------------------------------------------------- 1 | //----------------------------------------------------------------------------- 2 | // Copyright (c) 2019, 2022, Oracle and/or its affiliates. 3 | // 4 | // This software is dual-licensed to you under the Universal Permissive License 5 | // (UPL) 1.0 as shown at https://oss.oracle.com/licenses/upl and Apache License 6 | // 2.0 as shown at http://www.apache.org/licenses/LICENSE-2.0. You may choose 7 | // either license. 8 | // 9 | // If you elect to accept the software under the Apache License, Version 2.0, 10 | // the following applies: 11 | // 12 | // Licensed under the Apache License, Version 2.0 (the "License"); 13 | // you may not use this file except in compliance with the License. 14 | // You may obtain a copy of the License at 15 | // 16 | // https://www.apache.org/licenses/LICENSE-2.0 17 | // 18 | // Unless required by applicable law or agreed to in writing, software 19 | // distributed under the License is distributed on an "AS IS" BASIS, 20 | // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 21 | // See the License for the specific language governing permissions and 22 | // limitations under the License. 23 | //----------------------------------------------------------------------------- 24 | 25 | //----------------------------------------------------------------------------- 26 | // DemoRawAQ.c 27 | // Demos simple enqueuing and dequeuing RAW data using advanced queuing. 28 | //----------------------------------------------------------------------------- 29 | 30 | #include "SampleLib.h" 31 | #define QUEUE_NAME "DEMO_RAW_QUEUE" 32 | #define NUM_MESSAGES 4 33 | 34 | const char *payloads[NUM_MESSAGES] = { 35 | "The first message", 36 | "The second message", 37 | "The third message", 38 | "The fourth and final message" 39 | }; 40 | 41 | 42 | //----------------------------------------------------------------------------- 43 | // main() 44 | //----------------------------------------------------------------------------- 45 | int main(int argc, char **argv) 46 | { 47 | dpiDeqOptions *deqOptions; 48 | uint32_t payloadLength; 49 | dpiMsgProps *msgProps; 50 | const char *payload; 51 | dpiQueue *queue; 52 | dpiConn *conn; 53 | uint32_t i; 54 | 55 | // connect to database 56 | conn = dpiSamples_getConn(0, NULL); 57 | 58 | // create queue and message properties 59 | if (dpiConn_newQueue(conn, QUEUE_NAME, strlen(QUEUE_NAME), NULL, 60 | &queue) < 0) 61 | return dpiSamples_showError(); 62 | if (dpiConn_newMsgProps(conn, &msgProps) < 0) 63 | return dpiSamples_showError(); 64 | dpiConn_release(conn); 65 | 66 | // enqueue messages 67 | printf("Enqueuing messages...\n"); 68 | for (i = 0; i < NUM_MESSAGES; i++) { 69 | printf("%s\n", payloads[i]); 70 | if (dpiMsgProps_setPayloadBytes(msgProps, payloads[i], 71 | strlen(payloads[i])) < 0) 72 | return dpiSamples_showError(); 73 | if (dpiQueue_enqOne(queue, msgProps) < 0) 74 | return dpiSamples_showError(); 75 | } 76 | dpiMsgProps_release(msgProps); 77 | 78 | // get dequeue options from queue and set some options 79 | if (dpiQueue_getDeqOptions(queue, &deqOptions) < 0) 80 | return dpiSamples_showError(); 81 | if (dpiDeqOptions_setNavigation(deqOptions, DPI_DEQ_NAV_FIRST_MSG) < 0) 82 | return dpiSamples_showError(); 83 | if (dpiDeqOptions_setWait(deqOptions, DPI_DEQ_WAIT_NO_WAIT) < 0) 84 | return dpiSamples_showError(); 85 | 86 | // dequeue messages 87 | printf("\nDequeuing messages...\n"); 88 | while (1) { 89 | if (dpiQueue_deqOne(queue, &msgProps) < 0) 90 | return dpiSamples_showError(); 91 | if (!msgProps) 92 | break; 93 | if (dpiMsgProps_getPayload(msgProps, NULL, &payload, 94 | &payloadLength) < 0) 95 | return dpiSamples_showError(); 96 | printf("%.*s\n", payloadLength, payload); 97 | dpiMsgProps_release(msgProps); 98 | } 99 | 100 | printf("\nDone.\n"); 101 | return 0; 102 | } 103 | -------------------------------------------------------------------------------- /samples/DemoRefCursors.c: -------------------------------------------------------------------------------- 1 | //----------------------------------------------------------------------------- 2 | // Copyright (c) 2016, 2022, Oracle and/or its affiliates. 3 | // 4 | // This software is dual-licensed to you under the Universal Permissive License 5 | // (UPL) 1.0 as shown at https://oss.oracle.com/licenses/upl and Apache License 6 | // 2.0 as shown at http://www.apache.org/licenses/LICENSE-2.0. You may choose 7 | // either license. 8 | // 9 | // If you elect to accept the software under the Apache License, Version 2.0, 10 | // the following applies: 11 | // 12 | // Licensed under the Apache License, Version 2.0 (the "License"); 13 | // you may not use this file except in compliance with the License. 14 | // You may obtain a copy of the License at 15 | // 16 | // https://www.apache.org/licenses/LICENSE-2.0 17 | // 18 | // Unless required by applicable law or agreed to in writing, software 19 | // distributed under the License is distributed on an "AS IS" BASIS, 20 | // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 21 | // See the License for the specific language governing permissions and 22 | // limitations under the License. 23 | //----------------------------------------------------------------------------- 24 | 25 | //----------------------------------------------------------------------------- 26 | // DemoRefCursors.c 27 | // Demos simple fetch of REF cursors. 28 | //----------------------------------------------------------------------------- 29 | 30 | #include "SampleLib.h" 31 | #define SQL_TEXT "begin " \ 32 | " open :1 for select 'X' StrVal from dual; " \ 33 | "end;" 34 | 35 | //----------------------------------------------------------------------------- 36 | // main() 37 | //----------------------------------------------------------------------------- 38 | int main(int argc, char **argv) 39 | { 40 | uint32_t numQueryColumns, bufferRowIndex, i; 41 | dpiData *refCursorValue, *strValue; 42 | dpiNativeTypeNum nativeTypeNum; 43 | dpiQueryInfo queryInfo; 44 | dpiVar *refCursorVar; 45 | dpiStmt *stmt; 46 | dpiConn *conn; 47 | int found; 48 | 49 | // connect to database 50 | conn = dpiSamples_getConn(1, NULL); 51 | 52 | // prepare and execute statement 53 | if (dpiConn_prepareStmt(conn, 0, SQL_TEXT, strlen(SQL_TEXT), NULL, 0, 54 | &stmt) < 0) 55 | return dpiSamples_showError(); 56 | if (dpiConn_newVar(conn, DPI_ORACLE_TYPE_STMT, DPI_NATIVE_TYPE_STMT, 1, 0, 57 | 0, 0, NULL, &refCursorVar, &refCursorValue) < 0) 58 | return dpiSamples_showError(); 59 | if (dpiStmt_bindByPos(stmt, 1, refCursorVar) < 0) 60 | return dpiSamples_showError(); 61 | if (dpiStmt_execute(stmt, 0, &numQueryColumns) < 0) 62 | return dpiSamples_showError(); 63 | 64 | // get ref cursor 65 | dpiStmt_release(stmt); 66 | stmt = refCursorValue->value.asStmt; 67 | 68 | // fetch data from ref cursor 69 | while (1) { 70 | if (dpiStmt_fetch(stmt, &found, &bufferRowIndex) < 0) 71 | return dpiSamples_showError(); 72 | if (!found) 73 | break; 74 | if (dpiStmt_getQueryValue(stmt, 1, &nativeTypeNum, &strValue) < 0) 75 | return dpiSamples_showError(); 76 | printf("Row: StrVal = '%.*s'\n", strValue->value.asBytes.length, 77 | strValue->value.asBytes.ptr); 78 | } 79 | 80 | // display description of each fetched column 81 | if (dpiStmt_getNumQueryColumns(stmt, &numQueryColumns) < 0) 82 | return dpiSamples_showError(); 83 | for (i = 0; i < numQueryColumns; i++) { 84 | if (dpiStmt_getQueryInfo(stmt, i + 1, &queryInfo) < 0) 85 | return dpiSamples_showError(); 86 | printf("('%*s', %d, %d, %d, %d, %d, %d)\n", queryInfo.nameLength, 87 | queryInfo.name, queryInfo.typeInfo.oracleTypeNum, 88 | queryInfo.typeInfo.sizeInChars, 89 | queryInfo.typeInfo.clientSizeInBytes, 90 | queryInfo.typeInfo.precision, queryInfo.typeInfo.scale, 91 | queryInfo.nullOk); 92 | } 93 | 94 | // clean up 95 | dpiVar_release(refCursorVar); 96 | dpiConn_release(conn); 97 | 98 | printf("Done.\n"); 99 | return 0; 100 | } 101 | -------------------------------------------------------------------------------- /samples/DemoRemoveSodaDoc.c: -------------------------------------------------------------------------------- 1 | //----------------------------------------------------------------------------- 2 | // Copyright (c) 2018, 2022, Oracle and/or its affiliates. 3 | // 4 | // This software is dual-licensed to you under the Universal Permissive License 5 | // (UPL) 1.0 as shown at https://oss.oracle.com/licenses/upl and Apache License 6 | // 2.0 as shown at http://www.apache.org/licenses/LICENSE-2.0. You may choose 7 | // either license. 8 | // 9 | // If you elect to accept the software under the Apache License, Version 2.0, 10 | // the following applies: 11 | // 12 | // Licensed under the Apache License, Version 2.0 (the "License"); 13 | // you may not use this file except in compliance with the License. 14 | // You may obtain a copy of the License at 15 | // 16 | // https://www.apache.org/licenses/LICENSE-2.0 17 | // 18 | // Unless required by applicable law or agreed to in writing, software 19 | // distributed under the License is distributed on an "AS IS" BASIS, 20 | // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 21 | // See the License for the specific language governing permissions and 22 | // limitations under the License. 23 | //----------------------------------------------------------------------------- 24 | 25 | //----------------------------------------------------------------------------- 26 | // DemoRemoveSodaDoc.c 27 | // Demos removing a document from a SODA collection with the specified key. 28 | //----------------------------------------------------------------------------- 29 | 30 | #include "SampleLib.h" 31 | 32 | //----------------------------------------------------------------------------- 33 | // main() 34 | //----------------------------------------------------------------------------- 35 | int main(int argc, char **argv) 36 | { 37 | const char *collectionName, *key; 38 | dpiSodaOperOptions options; 39 | dpiSampleParams *params; 40 | dpiSodaColl *coll; 41 | uint64_t numDocs; 42 | dpiSodaDb *db; 43 | 44 | // determine name of collection and key of document to retrieve 45 | if (argc != 3) { 46 | fprintf(stderr, "Usage: DemoGetSodaDoc \n"); 47 | return 1; 48 | } 49 | collectionName = argv[1]; 50 | key = argv[2]; 51 | 52 | // connect to database 53 | db = dpiSamples_getSodaDb(); 54 | 55 | // open existing SODA collection 56 | if (dpiSodaDb_openCollection(db, collectionName, strlen(collectionName), 57 | DPI_SODA_FLAGS_DEFAULT, &coll) < 0) 58 | return dpiSamples_showError(); 59 | if (!coll) { 60 | printf("No collection named %s\n", collectionName); 61 | return 1; 62 | } 63 | 64 | // build options 65 | params = dpiSamples_getParams(); 66 | if (dpiContext_initSodaOperOptions(params->context, &options) < 0) 67 | return dpiSamples_showError(); 68 | options.key = key; 69 | options.keyLength = strlen(key); 70 | 71 | // remove document from the collection 72 | if (dpiSodaColl_remove(coll, &options, DPI_SODA_FLAGS_ATOMIC_COMMIT, 73 | &numDocs) < 0) 74 | return dpiSamples_showError(); 75 | printf("%" PRIu64 " documents removed.\n", numDocs); 76 | 77 | // clean up 78 | dpiSodaColl_release(coll); 79 | dpiSodaDb_release(db); 80 | 81 | printf("Done.\n"); 82 | return 0; 83 | } 84 | -------------------------------------------------------------------------------- /samples/DemoTokenStandalone.c: -------------------------------------------------------------------------------- 1 | //----------------------------------------------------------------------------- 2 | // Copyright (c) 2016, 2022, Oracle and/or its affiliates. 3 | // 4 | // This software is dual-licensed to you under the Universal Permissive License 5 | // (UPL) 1.0 as shown at https://oss.oracle.com/licenses/upl and Apache License 6 | // 2.0 as shown at http://www.apache.org/licenses/LICENSE-2.0. You may choose 7 | // either license. 8 | // 9 | // If you elect to accept the software under the Apache License, Version 2.0, 10 | // the following applies: 11 | // 12 | // Licensed under the Apache License, Version 2.0 (the "License"); 13 | // you may not use this file except in compliance with the License. 14 | // You may obtain a copy of the License at 15 | // 16 | // https://www.apache.org/licenses/LICENSE-2.0 17 | // 18 | // Unless required by applicable law or agreed to in writing, software 19 | // distributed under the License is distributed on an "AS IS" BASIS, 20 | // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 21 | // See the License for the specific language governing permissions and 22 | // limitations under the License. 23 | //----------------------------------------------------------------------------- 24 | 25 | //----------------------------------------------------------------------------- 26 | // NAME 27 | // DemoTokenStandalone.c 28 | // 29 | // DESCRIPTION 30 | // This Demo file shows standalone connection using token based authentication 31 | // to Oracle Autonomous Database from Oracle Compute Infrastructure. 32 | // 33 | // PREQUISITES 34 | // - Oracle Client libraries 19.14 (or later), or 21.5 (or later). 35 | // 36 | // - The Oracle Cloud Infrastructure command line interface (OCI-CLI). The 37 | // command line interface (CLI) is a tool that enables you to work with 38 | // Oracle Cloud Infrastructure objects and services at a command line, see 39 | // https://docs.oracle.com/en-us/iaas/Content/API/Concepts/cliconcepts.htm 40 | // 41 | // - Set these environment variables (see the code explanation): 42 | // ODPIC_SAMPLES_ACCESS_TOKEN_LOC 43 | // ODPIC_SAMPLES_CONNECT_STRING 44 | //----------------------------------------------------------------------------- 45 | 46 | #include "SampleLib.h" 47 | 48 | //----------------------------------------------------------------------------- 49 | // main() 50 | //----------------------------------------------------------------------------- 51 | int main(int argc, char **argv) 52 | { 53 | dpiConn *conn; 54 | dpiSampleParams *params; 55 | dpiAccessToken *accessToken; 56 | 57 | accessToken = dpiSamples_getAccessToken(); 58 | params = dpiSamples_getParams(); 59 | 60 | dpiConnCreateParams connCreateParams; 61 | if (dpiContext_initConnCreateParams(params->context, 62 | &connCreateParams) < 0) 63 | return dpiSamples_showError(); 64 | 65 | // params for token based authentication: 66 | // externalAuth: Must be set to true for token based authentication 67 | connCreateParams.externalAuth = 1; 68 | 69 | dpiCommonCreateParams commonCreateParams; 70 | if (dpiContext_initCommonCreateParams(params->context, 71 | &commonCreateParams) < 0) 72 | return dpiSamples_showError(); 73 | commonCreateParams.accessToken = accessToken; 74 | 75 | if (dpiConn_create(params->context, NULL, 0, NULL, 0, 76 | params->connectString, params->connectStringLength, 77 | &commonCreateParams, &connCreateParams, &conn) < 0) 78 | return dpiSamples_showError(); 79 | 80 | printf("Standalone connection is created\n"); 81 | printf("Done.\n"); 82 | return 0; 83 | } 84 | -------------------------------------------------------------------------------- /samples/Makefile: -------------------------------------------------------------------------------- 1 | #------------------------------------------------------------------------------ 2 | # Copyright (c) 2016, 2022, Oracle and/or its affiliates. 3 | # 4 | # This software is dual-licensed to you under the Universal Permissive License 5 | # (UPL) 1.0 as shown at https://oss.oracle.com/licenses/upl and Apache License 6 | # 2.0 as shown at http://www.apache.org/licenses/LICENSE-2.0. You may choose 7 | # either license. 8 | # 9 | # If you elect to accept the software under the Apache License, Version 2.0, 10 | # the following applies: 11 | # 12 | # Licensed under the Apache License, Version 2.0 (the "License"); 13 | # you may not use this file except in compliance with the License. 14 | # You may obtain a copy of the License at 15 | # 16 | # https://www.apache.org/licenses/LICENSE-2.0 17 | # 18 | # Unless required by applicable law or agreed to in writing, software 19 | # distributed under the License is distributed on an "AS IS" BASIS, 20 | # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 21 | # See the License for the specific language governing permissions and 22 | # limitations under the License. 23 | # 24 | #------------------------------------------------------------------------------ 25 | # 26 | # Sample Makefile if you wish to build the ODPI-C sample executables. 27 | # 28 | # Look at README.md for information on how to build and run the samples. 29 | #------------------------------------------------------------------------------ 30 | 31 | BUILD_DIR = build 32 | INCLUDE_DIR = ../include 33 | LIB_DIR = ../lib 34 | 35 | CC=gcc 36 | LD=gcc 37 | CFLAGS=-I$(INCLUDE_DIR) -O2 -g -Wall 38 | LIBS=-L$(LIB_DIR) -lodpic 39 | COMMON_OBJS = $(BUILD_DIR)/SampleLib.o 40 | 41 | SOURCES = DemoBLOB.c DemoCLOB.c DemoFetch.c DemoInsert.c DemoInsertAsArray.c \ 42 | DemoCallProc.c DemoRefCursors.c DemoImplicitResults.c \ 43 | DemoFetchObjects.c DemoBindObjects.c DemoFetchDates.c \ 44 | DemoBindArrays.c DemoBFILE.c DemoAppContext.c DemoDistribTrans.c \ 45 | DemoObjectAQ.c DemoRawAQ.c DemoBulkAQ.c DemoCQN.c DemoLongs.c \ 46 | DemoLongRaws.c DemoDMLReturning.c DemoInOutTempLobs.c \ 47 | DemoConvertNumbers.c DemoCreateSodaColl.c DemoIterSodaColls.c \ 48 | DemoDropSodaColl.c DemoInsertSodaColl.c DemoGetSodaDoc.c \ 49 | DemoRemoveSodaDoc.c DemoReplaceSodaDoc.c DemoGetAllSodaDocs.c \ 50 | DemoGetSodaCollNames.c DemoCLOBsAsStrings.c DemoBLOBsAsBytes.c \ 51 | DemoInsertManySodaColl.c DemoShardingNumberKey.c DemoFetchJSON.c \ 52 | DemoBindJSON.c DemoTokenStandalone.c DemoTokenPoolWithCallback.c 53 | BINARIES = $(SOURCES:%.c=$(BUILD_DIR)/%) 54 | 55 | all: $(BUILD_DIR) $(BINARIES) 56 | 57 | clean: 58 | rm -rf $(BUILD_DIR) 59 | 60 | $(BUILD_DIR): 61 | mkdir -p $@ 62 | 63 | $(BUILD_DIR)/%.o: %.c SampleLib.h 64 | $(CC) -c $(CFLAGS) -o $@ $< 65 | 66 | $(BUILD_DIR)/%: $(BUILD_DIR)/%.o $(COMMON_OBJS) 67 | $(LD) $(LDFLAGS) $< -o $@ $(COMMON_OBJS) $(LIBS) 68 | -------------------------------------------------------------------------------- /samples/Makefile.win32: -------------------------------------------------------------------------------- 1 | #------------------------------------------------------------------------------ 2 | # Copyright (c) 2017, 2022, Oracle and/or its affiliates. 3 | # 4 | # This software is dual-licensed to you under the Universal Permissive License 5 | # (UPL) 1.0 as shown at https://oss.oracle.com/licenses/upl and Apache License 6 | # 2.0 as shown at http://www.apache.org/licenses/LICENSE-2.0. You may choose 7 | # either license. 8 | # 9 | # If you elect to accept the software under the Apache License, Version 2.0, 10 | # the following applies: 11 | # 12 | # Licensed under the Apache License, Version 2.0 (the "License"); 13 | # you may not use this file except in compliance with the License. 14 | # You may obtain a copy of the License at 15 | # 16 | # https://www.apache.org/licenses/LICENSE-2.0 17 | # 18 | # Unless required by applicable law or agreed to in writing, software 19 | # distributed under the License is distributed on an "AS IS" BASIS, 20 | # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 21 | # See the License for the specific language governing permissions and 22 | # limitations under the License. 23 | # 24 | #------------------------------------------------------------------------------ 25 | # 26 | # Sample nmake Makefile for building the ODPI-C samples on Windows. 27 | # 28 | # This file is expected to be processed by nmake as in the following: 29 | # nmake /f Makefile.win32 30 | # 31 | # Look at README.md for information on how to build and run the samples. 32 | # 33 | #------------------------------------------------------------------------------ 34 | 35 | BUILD_DIR = build 36 | INCLUDE_DIR = ..\include 37 | LIB_DIR = ..\lib 38 | 39 | LIBS = $(LIB_DIR)\odpic.lib 40 | COMMON_OBJS = $(BUILD_DIR)\SampleLib.obj 41 | 42 | EXES = $(BUILD_DIR)\DemoBLOB.exe \ 43 | $(BUILD_DIR)\DemoCLOB.exe \ 44 | $(BUILD_DIR)\DemoFetch.exe \ 45 | $(BUILD_DIR)\DemoInsert.exe \ 46 | $(BUILD_DIR)\DemoInsertAsArray.exe \ 47 | $(BUILD_DIR)\DemoCallProc.exe \ 48 | $(BUILD_DIR)\DemoRefCursors.exe \ 49 | $(BUILD_DIR)\DemoImplicitResults.exe \ 50 | $(BUILD_DIR)\DemoFetchObjects.exe \ 51 | $(BUILD_DIR)\DemoBindObjects.exe \ 52 | $(BUILD_DIR)\DemoFetchDates.exe \ 53 | $(BUILD_DIR)\DemoBindArrays.exe \ 54 | $(BUILD_DIR)\DemoBFILE.exe \ 55 | $(BUILD_DIR)\DemoAppContext.exe \ 56 | $(BUILD_DIR)\DemoDistribTrans.exe \ 57 | $(BUILD_DIR)\DemoObjectAQ.exe \ 58 | $(BUILD_DIR)\DemoRawAQ.exe \ 59 | $(BUILD_DIR)\DemoBulkAQ.exe \ 60 | $(BUILD_DIR)\DemoCQN.exe \ 61 | $(BUILD_DIR)\DemoLongs.exe \ 62 | $(BUILD_DIR)\DemoLongRaws.exe \ 63 | $(BUILD_DIR)\DemoDMLReturning.exe \ 64 | $(BUILD_DIR)\DemoInOutTempLobs.exe \ 65 | $(BUILD_DIR)\DemoConvertNumbers.exe \ 66 | $(BUILD_DIR)\DemoCreateSodaColl.exe \ 67 | $(BUILD_DIR)\DemoIterSodaColls.exe \ 68 | $(BUILD_DIR)\DemoDropSodaColl.exe \ 69 | $(BUILD_DIR)\DemoInsertSodaColl.exe \ 70 | $(BUILD_DIR)\DemoGetSodaDoc.exe \ 71 | $(BUILD_DIR)\DemoRemoveSodaDoc.exe \ 72 | $(BUILD_DIR)\DemoReplaceSodaDoc.exe \ 73 | $(BUILD_DIR)\DemoGetAllSodaDocs.exe \ 74 | $(BUILD_DIR)\DemoGetSodaCollNames.exe \ 75 | $(BUILD_DIR)\DemoInsertManySodaColl.exe 76 | $(BUILD_DIR)\DemoInsertManySodaColl.exe \ 77 | $(BUILD_DIR)\DemoShardingNumberKey.exe \ 78 | $(BUILD_DIR)\DemoFetchJSON.exe \ 79 | $(BUILD_DIR)\DemoBindJSON.exe 80 | 81 | all: $(EXES) $(BUILD_DIR) 82 | 83 | $(EXES): $(BUILD_DIR) $(COMMON_OBJS) $*.obj 84 | 85 | clean: 86 | @if exist $(BUILD_DIR) rmdir /S /Q $(BUILD_DIR) 87 | 88 | $(BUILD_DIR): 89 | @if not exist $(BUILD_DIR) mkdir $(BUILD_DIR) 90 | 91 | {.}.c{$(BUILD_DIR)}.obj :: 92 | cl /nologo /c /Fo$(BUILD_DIR)\ /I$(INCLUDE_DIR) $< 93 | 94 | {$(BUILD_DIR)}.obj{$(BUILD_DIR)}.exe: 95 | link /nologo /out:$@ $< $(COMMON_OBJS) $(LIBS) 96 | -------------------------------------------------------------------------------- /samples/README.md: -------------------------------------------------------------------------------- 1 | This directory contains samples for ODPI-C. All of the executables can be built 2 | using the supplied Makefile (Makefile.win32 for use with nmake on Windows). The 3 | executables will be placed in the subdirectory "build" and can be run from 4 | there. 5 | 6 | See the top level [README](../README.md) for the platforms and compilers that 7 | have been tested and are known to work. 8 | 9 | Some samples require the latest Database features. TestBFILE needs to 10 | write to the physical directory that the database can read from, so it 11 | will generally fail unless it is run on the same machine as the database. 12 | 13 | To run the samples: 14 | 15 | - Ensure that installation of the ODPI-C library has been completed as 16 | explained [here](https://oracle.github.io/odpi/doc/installation.html). 17 | 18 | - Optionally edit the file sql/SampleEnv.sql and edit the parameters defined 19 | there. If you don't change any of the parameters, make the sure the schemas 20 | odpicdemo and odpicdemo_proxy can be dropped. If you do edit the parameters 21 | defined there, also set the corresponding environment variables indicated 22 | on the right of the defined variable. 23 | 24 | - Optionally set the environment variable ODPIC_SAMPLES_CONNECT_STRING to 25 | point to the database in which you plan to run the tests. If this 26 | environment variable is not set, the connect string will be assumed to be 27 | the EZ connect string "localhost/orclpdb". 28 | 29 | - Run 'make clean' and 'make' to build the samples 30 | 31 | - Run SQL\*Plus as SYSDBA and create the sample SQL objects with 32 | sql/SetupSamples.sql. The syntax is: 33 | 34 | sqlplus sys/syspassword@hostname/servicename as sysdba @SetupSamples 35 | 36 | - Change to the 'build' directory and run each sample individually. 37 | On Linux you will need to set LD_LIBRARY_PATH to point to the location of 38 | the library, for example: 39 | 40 | LD_LIBRARY_PATH=$LD_LIBRARY_PATH:../../lib ./TestAppContext 41 | 42 | 43 | - After running the samples, drop the SQL objects by running the 44 | script sql/DropSamples.sql. The syntax is: 45 | 46 | sqlplus sys/syspassword@hostname/servicename as sysdba @DropSamples 47 | -------------------------------------------------------------------------------- /samples/SampleLib.h: -------------------------------------------------------------------------------- 1 | //----------------------------------------------------------------------------- 2 | // Copyright (c) 2016, 2022, Oracle and/or its affiliates. 3 | // 4 | // This software is dual-licensed to you under the Universal Permissive License 5 | // (UPL) 1.0 as shown at https://oss.oracle.com/licenses/upl and Apache License 6 | // 2.0 as shown at http://www.apache.org/licenses/LICENSE-2.0. You may choose 7 | // either license. 8 | // 9 | // If you elect to accept the software under the Apache License, Version 2.0, 10 | // the following applies: 11 | // 12 | // Licensed under the Apache License, Version 2.0 (the "License"); 13 | // you may not use this file except in compliance with the License. 14 | // You may obtain a copy of the License at 15 | // 16 | // https://www.apache.org/licenses/LICENSE-2.0 17 | // 18 | // Unless required by applicable law or agreed to in writing, software 19 | // distributed under the License is distributed on an "AS IS" BASIS, 20 | // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 21 | // See the License for the specific language governing permissions and 22 | // limitations under the License. 23 | //----------------------------------------------------------------------------- 24 | 25 | //----------------------------------------------------------------------------- 26 | // SampleLib.h 27 | // Header file for common code used in all samples. 28 | //----------------------------------------------------------------------------- 29 | 30 | #include 31 | #include 32 | #include 33 | #include 34 | #include 35 | 36 | #ifdef _MSC_VER 37 | #if _MSC_VER < 1900 38 | #define PRId64 "I64d" 39 | #define PRIu64 "I64u" 40 | #endif 41 | #endif 42 | 43 | #ifndef PRIu64 44 | #include 45 | #endif 46 | 47 | // buffer length for token and private key 48 | #define TOKENBUFLEN 8000 49 | 50 | typedef struct { 51 | const char *mainUserName; 52 | uint32_t mainUserNameLength; 53 | const char *mainPassword; 54 | uint32_t mainPasswordLength; 55 | const char *proxyUserName; 56 | uint32_t proxyUserNameLength; 57 | const char *proxyPassword; 58 | uint32_t proxyPasswordLength; 59 | const char *connectString; 60 | uint32_t connectStringLength; 61 | const char *dirName; 62 | uint32_t dirNameLength; 63 | dpiContext *context; 64 | } dpiSampleParams; 65 | 66 | // connect to the database 67 | dpiConn *dpiSamples_getConn(int withPool, dpiCommonCreateParams *commonParams); 68 | 69 | // acquire parameters 70 | dpiSampleParams *dpiSamples_getParams(void); 71 | 72 | // acquire SODA database 73 | dpiSodaDb *dpiSamples_getSodaDb(void); 74 | 75 | // show error to stderr 76 | int dpiSamples_showError(void); 77 | 78 | // get token and private key 79 | dpiAccessToken *dpiSamples_getAccessToken(void); 80 | 81 | // populate access token 82 | void dpiSamples_populateAccessToken(dpiAccessToken* accessToken, 83 | const char* envName); 84 | -------------------------------------------------------------------------------- /samples/sql/DropSamples.sql: -------------------------------------------------------------------------------- 1 | /*----------------------------------------------------------------------------- 2 | * Copyright (c) 2016, 2022, Oracle and/or its affiliates. 3 | * 4 | * This software is dual-licensed to you under the Universal Permissive License 5 | * (UPL) 1.0 as shown at https://oss.oracle.com/licenses/upl and Apache License 6 | * 2.0 as shown at http://www.apache.org/licenses/LICENSE-2.0. You may choose 7 | * either license.* 8 | * 9 | * If you elect to accept the software under the Apache License, Version 2.0, 10 | * the following applies: 11 | * 12 | * Licensed under the Apache License, Version 2.0 (the "License"); 13 | * you may not use this file except in compliance with the License. 14 | * You may obtain a copy of the License at 15 | * 16 | * https://www.apache.org/licenses/LICENSE-2.0 17 | * 18 | * Unless required by applicable law or agreed to in writing, software 19 | * distributed under the License is distributed on an "AS IS" BASIS, 20 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 21 | * See the License for the specific language governing permissions and 22 | * limitations under the License. 23 | *---------------------------------------------------------------------------*/ 24 | 25 | /*----------------------------------------------------------------------------- 26 | * DropSamples.sql 27 | * Drops database objects used for samples. 28 | * 29 | * Run this like: 30 | * sqlplus / as sysdba @DropSamples 31 | * 32 | * Note that the script SampleEnv.sql should be modified if you would like to 33 | * use something other than the default configuration. 34 | *---------------------------------------------------------------------------*/ 35 | 36 | whenever sqlerror exit failure 37 | 38 | -- setup environment 39 | @@SampleEnv.sql 40 | 41 | -- drop schemas 42 | begin 43 | 44 | for r in 45 | ( select username 46 | from dba_users 47 | where username in (upper('&main_user'), upper('&proxy_user')) 48 | ) loop 49 | execute immediate 'drop user ' || r.username || ' cascade'; 50 | end loop; 51 | 52 | end; 53 | / 54 | 55 | -- drop directory 56 | begin 57 | for r in 58 | ( select directory_name 59 | from dba_directories 60 | where directory_name = upper('&dir_name') 61 | ) loop 62 | execute immediate 'drop directory ' || r.directory_name; 63 | end loop; 64 | end; 65 | / 66 | -------------------------------------------------------------------------------- /samples/sql/SampleEnv.sql: -------------------------------------------------------------------------------- 1 | /*----------------------------------------------------------------------------- 2 | * Copyright (c) 2017, 2022, Oracle and/or its affiliates. 3 | * 4 | * This software is dual-licensed to you under the Universal Permissive License 5 | * (UPL) 1.0 as shown at https://oss.oracle.com/licenses/upl and Apache License 6 | * 2.0 as shown at http://www.apache.org/licenses/LICENSE-2.0. You may choose 7 | * either license.* 8 | * 9 | * If you elect to accept the software under the Apache License, Version 2.0, 10 | * the following applies: 11 | * 12 | * Licensed under the Apache License, Version 2.0 (the "License"); 13 | * you may not use this file except in compliance with the License. 14 | * You may obtain a copy of the License at 15 | * 16 | * https://www.apache.org/licenses/LICENSE-2.0 17 | * 18 | * Unless required by applicable law or agreed to in writing, software 19 | * distributed under the License is distributed on an "AS IS" BASIS, 20 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 21 | * See the License for the specific language governing permissions and 22 | * limitations under the License. 23 | *---------------------------------------------------------------------------*/ 24 | 25 | /*----------------------------------------------------------------------------- 26 | * SampleEnv.sql 27 | * Sets up configuration for the SetupSamples.sql and DropSamples.sql 28 | * scripts. Change the values below if you would like to use something other 29 | * than the default values. Note that the environment variables noted below 30 | * will also need to be set, if non-default values are used. 31 | * The directory path must be one that both the server and the client can 32 | * read simultaneously. 33 | *---------------------------------------------------------------------------*/ 34 | 35 | set echo off termout on feedback off verify off 36 | 37 | define main_user = "odpicdemo" -- $ODPIC_SAMPLES_MAIN_USER 38 | define main_password = "welcome" -- $ODPIC_SAMPLES_MAIN_PASSWORD 39 | define proxy_user = "odpicdemo_proxy" -- $ODPIC_SAMPLES_PROXY_USER 40 | define proxy_password = "welcome" -- $ODPIC_SAMPLES_PROXY_PASSWORD 41 | define dir_name = "odpicdemo_dir" -- $ODPIC_SAMPLES_DIR_NAME 42 | define dir_path = "/tmp" 43 | 44 | prompt ************************************************************************ 45 | prompt CONFIGURATION 46 | prompt ************************************************************************ 47 | prompt Main Schema: &main_user 48 | prompt Proxy Schema: &proxy_user 49 | prompt Directory Name: &dir_name 50 | prompt Directory Path: &dir_path 51 | prompt 52 | 53 | set echo on verify on feedback on 54 | -------------------------------------------------------------------------------- /test/Makefile: -------------------------------------------------------------------------------- 1 | #------------------------------------------------------------------------------ 2 | # Copyright (c) 2016, 2025, Oracle and/or its affiliates. 3 | # 4 | # This software is dual-licensed to you under the Universal Permissive License 5 | # (UPL) 1.0 as shown at https://oss.oracle.com/licenses/upl and Apache License 6 | # 2.0 as shown at http://www.apache.org/licenses/LICENSE-2.0. You may choose 7 | # either license. 8 | # 9 | # If you elect to accept the software under the Apache License, Version 2.0, 10 | # the following applies: 11 | # 12 | # Licensed under the Apache License, Version 2.0 (the "License"); 13 | # you may not use this file except in compliance with the License. 14 | # You may obtain a copy of the License at 15 | # 16 | # https://www.apache.org/licenses/LICENSE-2.0 17 | # 18 | # Unless required by applicable law or agreed to in writing, software 19 | # distributed under the License is distributed on an "AS IS" BASIS, 20 | # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 21 | # See the License for the specific language governing permissions and 22 | # limitations under the License. 23 | # 24 | #------------------------------------------------------------------------------ 25 | # 26 | # Sample Makefile if you wish to build the ODPI-C test executables. 27 | # 28 | # Look at README.md for information on how to build and run the tests. 29 | #------------------------------------------------------------------------------ 30 | 31 | BUILD_DIR = build 32 | INCLUDE_DIR = ../include 33 | LIB_DIR = ../lib 34 | 35 | CC = gcc 36 | LD = gcc 37 | CFLAGS = -I$(INCLUDE_DIR) -O2 -g -Wall 38 | LIBS = -L$(LIB_DIR) -lodpic 39 | COMMON_OBJS = $(BUILD_DIR)/TestLib.o 40 | 41 | SOURCES = TestSuiteRunner.c \ 42 | test_1000_context.c \ 43 | test_1100_numbers.c \ 44 | test_1200_conn.c \ 45 | test_1300_conn_properties.c \ 46 | test_1400_pool.c \ 47 | test_1500_pool_properties.c \ 48 | test_1600_queries.c \ 49 | test_1700_transactions.c \ 50 | test_1800_misc.c \ 51 | test_1900_variables.c \ 52 | test_2000_statements.c \ 53 | test_2100_data_types.c \ 54 | test_2200_object_types.c \ 55 | test_2300_objects.c \ 56 | test_2400_enq_options.c \ 57 | test_2500_deq_options.c \ 58 | test_2600_msg_props.c \ 59 | test_2700_aq.c \ 60 | test_2800_lobs.c \ 61 | test_2900_implicit_results.c \ 62 | test_3000_scroll_cursors.c \ 63 | test_3100_subscriptions.c \ 64 | test_3200_batch_errors.c \ 65 | test_3300_dml_returning.c \ 66 | test_3400_soda_db.c \ 67 | test_3500_soda_coll.c \ 68 | test_3600_soda_coll_cursor.c \ 69 | test_3700_soda_doc.c \ 70 | test_3800_soda_doc_cursor.c \ 71 | test_3900_sess_tags.c \ 72 | test_4000_queue.c \ 73 | test_4100_binds.c \ 74 | test_4200_rowids.c \ 75 | test_4300_json.c \ 76 | test_4400_vector.c 77 | BINARIES = $(SOURCES:%.c=$(BUILD_DIR)/%) 78 | 79 | all: $(BUILD_DIR) $(BINARIES) 80 | 81 | clean: 82 | rm -rf $(BUILD_DIR) 83 | 84 | $(BUILD_DIR): 85 | mkdir -p $@ 86 | 87 | $(BUILD_DIR)/%.o: %.c TestLib.h 88 | $(CC) -c $(CFLAGS) -o $@ $< 89 | 90 | $(BUILD_DIR)/%: $(BUILD_DIR)/%.o $(COMMON_OBJS) 91 | $(LD) $(LDFLAGS) $< -o $@ $(COMMON_OBJS) $(LIBS) 92 | -------------------------------------------------------------------------------- /test/Makefile.win32: -------------------------------------------------------------------------------- 1 | #------------------------------------------------------------------------------ 2 | # Copyright (c) 2017, 2025, Oracle and/or its affiliates. 3 | # 4 | # This software is dual-licensed to you under the Universal Permissive License 5 | # (UPL) 1.0 as shown at https://oss.oracle.com/licenses/upl and Apache License 6 | # 2.0 as shown at http://www.apache.org/licenses/LICENSE-2.0. You may choose 7 | # either license. 8 | # 9 | # If you elect to accept the software under the Apache License, Version 2.0, 10 | # the following applies: 11 | # 12 | # Licensed under the Apache License, Version 2.0 (the "License"); 13 | # you may not use this file except in compliance with the License. 14 | # You may obtain a copy of the License at 15 | # 16 | # https://www.apache.org/licenses/LICENSE-2.0 17 | # 18 | # Unless required by applicable law or agreed to in writing, software 19 | # distributed under the License is distributed on an "AS IS" BASIS, 20 | # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 21 | # See the License for the specific language governing permissions and 22 | # limitations under the License. 23 | # 24 | #------------------------------------------------------------------------------ 25 | # 26 | # Sample nmake Makefile if you wish to build the ODPI-C test executables. 27 | # 28 | # Look at README.md for information on how to build and run the tests. 29 | #------------------------------------------------------------------------------ 30 | 31 | BUILD_DIR = build 32 | INCLUDE_DIR = ..\include 33 | LIB_DIR = ..\lib 34 | 35 | LIBS = $(LIB_DIR)\odpic.lib 36 | COMMON_OBJS = $(BUILD_DIR)\TestLib.obj 37 | 38 | EXES = $(BUILD_DIR)\test_1000_context.exe \ 39 | $(BUILD_DIR)\test_1100_numbers.exe \ 40 | $(BUILD_DIR)\test_1200_conn.exe \ 41 | $(BUILD_DIR)\test_1300_conn_properties.exe \ 42 | $(BUILD_DIR)\test_1400_pool.exe \ 43 | $(BUILD_DIR)\test_1500_pool_properties.exe \ 44 | $(BUILD_DIR)\test_1600_queries.exe \ 45 | $(BUILD_DIR)\test_1700_transactions.exe \ 46 | $(BUILD_DIR)\test_1800_misc.exe \ 47 | $(BUILD_DIR)\test_1900_variables.exe \ 48 | $(BUILD_DIR)\test_2000_statements.exe \ 49 | $(BUILD_DIR)\test_2100_data_types.exe \ 50 | $(BUILD_DIR)\test_2200_object_types.exe \ 51 | $(BUILD_DIR)\test_2300_objects.exe \ 52 | $(BUILD_DIR)\test_2400_enq_options.exe \ 53 | $(BUILD_DIR)\test_2500_deq_options.exe \ 54 | $(BUILD_DIR)\test_2600_msg_props.exe \ 55 | $(BUILD_DIR)\test_2700_aq.exe \ 56 | $(BUILD_DIR)\test_2800_lobs.exe \ 57 | $(BUILD_DIR)\test_2900_implicit_results.exe \ 58 | $(BUILD_DIR)\test_3000_scroll_cursors.exe \ 59 | $(BUILD_DIR)\test_3100_subscriptions.exe \ 60 | $(BUILD_DIR)\test_3200_batch_errors.exe \ 61 | $(BUILD_DIR)\test_3300_dml_returning.exe \ 62 | $(BUILD_DIR)\test_3400_soda_db.exe \ 63 | $(BUILD_DIR)\test_3500_soda_coll.exe \ 64 | $(BUILD_DIR)\test_3600_soda_coll_cursor.exe \ 65 | $(BUILD_DIR)\test_3700_soda_doc.exe \ 66 | $(BUILD_DIR)\test_3800_soda_doc_cursor.exe \ 67 | $(BUILD_DIR)\test_3900_sess_tags.exe \ 68 | $(BUILD_DIR)\test_4000_queue.exe \ 69 | $(BUILD_DIR)\test_4100_binds.exe \ 70 | $(BUILD_DIR)\test_4200_rowids.exe \ 71 | $(BUILD_DIR)\test_4300_json.exe \ 72 | $(BUILD_DIR)\test_4400_vector.exe \ 73 | $(BUILD_DIR)\TestSuiteRunner.exe 74 | 75 | all: $(EXES) $(BUILD_DIR) 76 | 77 | $(EXES): $(BUILD_DIR) $(COMMON_OBJS) $*.obj 78 | 79 | clean: 80 | @if exist $(BUILD_DIR) rmdir /S /Q $(BUILD_DIR) 81 | 82 | $(BUILD_DIR): 83 | @if not exist $(BUILD_DIR) mkdir $(BUILD_DIR) 84 | 85 | {.}.c{$(BUILD_DIR)}.obj :: 86 | cl /nologo /c /Fo$(BUILD_DIR)\ /I$(INCLUDE_DIR) $< 87 | 88 | {$(BUILD_DIR)}.obj{$(BUILD_DIR)}.exe: 89 | link /nologo /out:$@ $< $(COMMON_OBJS) $(LIBS) 90 | -------------------------------------------------------------------------------- /test/README.md: -------------------------------------------------------------------------------- 1 | This directory contains tests for ODPI-C. All of the test executables are built 2 | using the supplied Makefile (Makefile.win32 for use with nmake on Windows). The 3 | test executables will be placed in the subdirectory "build". 4 | 5 | See the top level [README](../README.md) for the platforms and compilers that 6 | have been tested and are known to work. 7 | 8 | To run the tests: 9 | 10 | - Ensure that installation of the ODPI-C library has been completed as 11 | explained [here](https://oracle.github.io/odpi/doc/installation.html). 12 | 13 | - Optionally edit the file sql/TestEnv.sql and edit the parameters defined 14 | there. If you don't change any of the parameters, make the sure the schemas 15 | odpic and odpic_proxy can be dropped. If you do edit the parameters defined 16 | there, also set the corresponding environment variables indicated on the 17 | right of the defined variable. 18 | 19 | - Optionally set the environment variable ODPIC_TEST_CONNECT_STRING to point 20 | to the database in which you plan to run the tests. If this environment 21 | variable is not set, the connect string will be assumed to be the 22 | EZ connect string "localhost/orclpdb". 23 | 24 | - Run 'make clean' and 'make' to build the tests 25 | 26 | - Run SQL\*Plus as SYSDBA and create the test suite SQL objects with 27 | sql/SetupTest.sql. The syntax is: 28 | 29 | sqlplus sys/syspassword@hostname/servicename as sysdba @SetupTest 30 | 31 | - Change to the 'build' directory and run the TestSuiteRunner executable 32 | found there. It will run all of the tests in the other executables and 33 | report on success or failure when it finishes running all of the tests. 34 | On Linux you will need to set LD_LIBRARY_PATH to point to the location of 35 | the library, as in: 36 | 37 | LD_LIBRARY_PATH=$LD_LIBRARY_PATH:../../lib ./TestSuiteRunner 38 | 39 | - After running the tests, drop the SQL objects by running the 40 | script sql/DropTest.sql. The syntax is: 41 | 42 | sqlplus sys/syspassword@hostname/servicename as sysdba @DropTest 43 | 44 | NOTES: 45 | 46 | - if you are using the BEQ connection method (setting the environment 47 | variable ORACLE_SID and using an empty connection string) then you will 48 | need to add the configuration bequeath_detach=yes to your sqlnet.ora file 49 | -------------------------------------------------------------------------------- /test/sql/DropTest.sql: -------------------------------------------------------------------------------- 1 | /*----------------------------------------------------------------------------- 2 | * Copyright (c) 2016, 2022, Oracle and/or its affiliates. 3 | * 4 | * This software is dual-licensed to you under the Universal Permissive License 5 | * (UPL) 1.0 as shown at https://oss.oracle.com/licenses/upl and Apache License 6 | * 2.0 as shown at http://www.apache.org/licenses/LICENSE-2.0. You may choose 7 | * either license.* 8 | * 9 | * If you elect to accept the software under the Apache License, Version 2.0, 10 | * the following applies: 11 | * 12 | * Licensed under the Apache License, Version 2.0 (the "License"); 13 | * you may not use this file except in compliance with the License. 14 | * You may obtain a copy of the License at 15 | * 16 | * https://www.apache.org/licenses/LICENSE-2.0 17 | * 18 | * Unless required by applicable law or agreed to in writing, software 19 | * distributed under the License is distributed on an "AS IS" BASIS, 20 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 21 | * See the License for the specific language governing permissions and 22 | * limitations under the License. 23 | *---------------------------------------------------------------------------*/ 24 | 25 | /*----------------------------------------------------------------------------- 26 | * DropTest.sql 27 | * Drops database objects used for testing 28 | * 29 | * Run this like: 30 | * sqlplus / as sysdba @DropTest 31 | * 32 | * Note that the script TestEnv.sql should be modified if you would like to use 33 | * something other than the default configuration. 34 | *---------------------------------------------------------------------------*/ 35 | 36 | whenever sqlerror exit failure 37 | 38 | -- setup environment 39 | @@TestEnv.sql 40 | 41 | -- drop schemas 42 | begin 43 | 44 | for r in 45 | ( select username 46 | from dba_users 47 | where username in (upper('&main_user'), upper('&proxy_user'), 48 | upper('&edition_user')) 49 | ) loop 50 | execute immediate 'drop user ' || r.username || ' cascade'; 51 | end loop; 52 | 53 | end; 54 | / 55 | 56 | -- drop directory 57 | begin 58 | for r in 59 | ( select directory_name 60 | from dba_directories 61 | where directory_name = upper('&dir_name') 62 | ) loop 63 | execute immediate 'drop directory ' || r.directory_name; 64 | end loop; 65 | end; 66 | / 67 | 68 | -- drop edition 69 | begin 70 | for r in 71 | ( select edition_name 72 | from dba_editions 73 | where edition_name in (upper('&edition_name')) 74 | ) loop 75 | execute immediate 'drop edition ' || r.edition_name || ' cascade'; 76 | end loop; 77 | end; 78 | / 79 | -------------------------------------------------------------------------------- /test/sql/TestEnv.sql: -------------------------------------------------------------------------------- 1 | /*----------------------------------------------------------------------------- 2 | * Copyright (c) 2016, 2022, Oracle and/or its affiliates. 3 | * 4 | * This software is dual-licensed to you under the Universal Permissive License 5 | * (UPL) 1.0 as shown at https://oss.oracle.com/licenses/upl and Apache License 6 | * 2.0 as shown at http://www.apache.org/licenses/LICENSE-2.0. You may choose 7 | * either license.* 8 | * 9 | * If you elect to accept the software under the Apache License, Version 2.0, 10 | * the following applies: 11 | * 12 | * Licensed under the Apache License, Version 2.0 (the "License"); 13 | * you may not use this file except in compliance with the License. 14 | * You may obtain a copy of the License at 15 | * 16 | * https://www.apache.org/licenses/LICENSE-2.0 17 | * 18 | * Unless required by applicable law or agreed to in writing, software 19 | * distributed under the License is distributed on an "AS IS" BASIS, 20 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 21 | * See the License for the specific language governing permissions and 22 | * limitations under the License. 23 | *---------------------------------------------------------------------------*/ 24 | 25 | /*----------------------------------------------------------------------------- 26 | * TestEnv.sql 27 | * Sets up configuration for the SetupTest.sql and DropTest.sql scripts. 28 | * Change the values below if you would like to use something other than the 29 | * default values. Note that the environment variables noted below will also 30 | * need to be set, if non-default values are used. 31 | * The directory path must be one that both the server and the client can 32 | * read simultaneously. 33 | *---------------------------------------------------------------------------*/ 34 | 35 | set echo off termout on feedback off verify off 36 | 37 | define main_user = "odpic" -- $ODPIC_TEST_MAIN_USER 38 | define main_password = "welcome" -- $ODPIC_TEST_MAIN_PASSWORD 39 | define proxy_user = "odpic_proxy" -- $ODPIC_TEST_PROXY_USER 40 | define proxy_password = "welcome" -- $ODPIC_TEST_PROXY_PASSWORD 41 | define edition_user = "odpic_edition" -- $ODPIC_TEST_EDITION_USER 42 | define edition_password = "welcome" -- $ODPIC_TEST_EDITION_PASSWORD 43 | define edition_name = "odpic_e1" -- $ODPIC_TEST_EDITION_NAME 44 | define dir_name = "odpic_dir" -- $ODPIC_TEST_DIR_NAME 45 | define dir_path = "/tmp" 46 | 47 | prompt ************************************************************************ 48 | prompt CONFIGURATION 49 | prompt ************************************************************************ 50 | prompt Main Schema: &main_user 51 | prompt Proxy Schema: &proxy_user 52 | prompt Edition Schema: &edition_user 53 | prompt Edition Name: &edition_name 54 | prompt Directory Name: &dir_name 55 | prompt Directory Path: &dir_path 56 | prompt 57 | 58 | set echo on verify on feedback on 59 | -------------------------------------------------------------------------------- /test/valgrind/run.sh: -------------------------------------------------------------------------------- 1 | #------------------------------------------------------------------------------ 2 | # Copyright (c) 2017, 2022, Oracle and/or its affiliates. 3 | # 4 | # This software is dual-licensed to you under the Universal Permissive License 5 | # (UPL) 1.0 as shown at https://oss.oracle.com/licenses/upl and Apache License 6 | # 2.0 as shown at http://www.apache.org/licenses/LICENSE-2.0. You may choose 7 | # either license. 8 | # 9 | # If you elect to accept the software under the Apache License, Version 2.0, 10 | # the following applies: 11 | # 12 | # Licensed under the Apache License, Version 2.0 (the "License"); 13 | # you may not use this file except in compliance with the License. 14 | # You may obtain a copy of the License at 15 | # 16 | # https://www.apache.org/licenses/LICENSE-2.0 17 | # 18 | # Unless required by applicable law or agreed to in writing, software 19 | # distributed under the License is distributed on an "AS IS" BASIS, 20 | # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 21 | # See the License for the specific language governing permissions and 22 | # limitations under the License. 23 | # 24 | #------------------------------------------------------------------------------ 25 | # 26 | # Sample script for running valgrind. 27 | # 28 | #------------------------------------------------------------------------------ 29 | 30 | echo "Running valgrind on $1..." 31 | 32 | valgrind \ 33 | --num-callers=40 \ 34 | --error-markers=-------------------------,------------------------- \ 35 | --redzone-size=256 \ 36 | --leak-check=yes \ 37 | --track-origins=yes \ 38 | --free-fill=0xaa \ 39 | --leak-check=full \ 40 | --error-limit=no \ 41 | --trace-children=yes \ 42 | --show-leak-kinds=definite,possible \ 43 | --suppressions=$(dirname $0)/suppressions.txt \ 44 | --gen-suppressions=all \ 45 | $@ 46 | -------------------------------------------------------------------------------- /util/tracing/mem_leak.py: -------------------------------------------------------------------------------- 1 | #! /usr/bin/env python 2 | #----------------------------------------------------------------------------- 3 | # Copyright (c) 2021, 2022, Oracle and/or its affiliates. 4 | # 5 | # This software is dual-licensed to you under the Universal Permissive License 6 | # (UPL) 1.0 as shown at https://oss.oracle.com/licenses/upl and Apache License 7 | # 2.0 as shown at http://www.apache.org/licenses/LICENSE-2.0. You may choose 8 | # either license. 9 | # 10 | # If you elect to accept the software under the Apache License, Version 2.0, 11 | # the following applies: 12 | # 13 | # Licensed under the Apache License, Version 2.0 (the "License"); 14 | # you may not use this file except in compliance with the License. 15 | # You may obtain a copy of the License at 16 | # 17 | # https://www.apache.org/licenses/LICENSE-2.0 18 | # 19 | # Unless required by applicable law or agreed to in writing, software 20 | # distributed under the License is distributed on an "AS IS" BASIS, 21 | # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 22 | # See the License for the specific language governing permissions and 23 | # limitations under the License. 24 | #----------------------------------------------------------------------------- 25 | 26 | """ 27 | A script to help identify memory leaks. 28 | 29 | The script argument should be the name of a file containing the trace output 30 | when DPI_DEBUG_LEVEL is set to DPI_DEBUG_LEVEL_MEM (32): 31 | 32 | export DPI_DEBUG_LEVEL=32 33 | ./myprog >& mem.log 34 | python mem_leak.py mem.log 35 | """ 36 | 37 | import sys 38 | 39 | ALLOCATED_STRING = ": allocated " 40 | FREED_STRING = ": freed " 41 | 42 | OCI_ALLOCATED_STRING = ": OCI allocated " 43 | OCI_FREED_STRING = ": OCI freed " 44 | 45 | def check_memory_use(file_name): 46 | """ 47 | Checks memory use found in the given file. This file is assumed to have 48 | been generated by setting DPI_DEBUG_LEVEL to the value 32. 49 | """ 50 | memory_locations = {} 51 | for line in open(file_name): 52 | 53 | # check for ODPI-C allocation 54 | pos = line.find(ALLOCATED_STRING) 55 | if pos > 0: 56 | parts = line[pos + len(ALLOCATED_STRING):].split() 57 | size = int(parts[0]) 58 | memory_location = parts[3] 59 | memory_locations.setdefault(memory_location, []).append(size) 60 | continue 61 | 62 | # check for ODPI-C free 63 | pos = line.find(FREED_STRING) 64 | if pos > 0: 65 | parts = line[pos + len(FREED_STRING):].split() 66 | memory_location = parts[2] 67 | memory_locations[memory_location].pop(0) 68 | if not memory_locations[memory_location]: 69 | del memory_locations[memory_location] 70 | continue 71 | 72 | # check for OCI allocation 73 | pos = line.find(OCI_ALLOCATED_STRING) 74 | if pos > 0: 75 | parts = line[pos + len(OCI_ALLOCATED_STRING):].split() 76 | size = int(parts[0]) 77 | memory_location = parts[3] 78 | memory_locations.setdefault(memory_location, []).append(size) 79 | continue 80 | 81 | # check for OCI free 82 | pos = line.find(OCI_FREED_STRING) 83 | if pos > 0: 84 | parts = line[pos + len(OCI_FREED_STRING):].split() 85 | memory_location = parts[2] 86 | memory_locations[memory_location].pop(0) 87 | if not memory_locations[memory_location]: 88 | del memory_locations[memory_location] 89 | continue 90 | 91 | print("Potential Memory Leaks") 92 | for memory_location in memory_locations: 93 | print(memory_location, "-> size", 94 | sum(memory_locations[memory_location])) 95 | 96 | check_memory_use(sys.argv[1]) 97 | --------------------------------------------------------------------------------