diff --git a/Manuals/Altibase_7.1/eng/CLI User's Manual.md b/Manuals/Altibase_7.1/eng/CLI User's Manual.md index 4718e87d0..e6409f7da 100644 --- a/Manuals/Altibase_7.1/eng/CLI User's Manual.md +++ b/Manuals/Altibase_7.1/eng/CLI User's Manual.md @@ -172,6 +172,7 @@ Homepage : http://www.altibase. - [SQLTables](#sqltables) - [SQLTransact](#sqltransact) - [3. LOB Interface](#3-lob-interface) + - [How to Process LOB Data](#How-to-Process-LOB-Data) - [LOB data types](#lob-data-types) - [LOB Function Overview](#lob-function-overview) - [SQLBindFileToCol](#sqlbindfiletocol) @@ -242,6 +243,9 @@ This manual is organized as follows: - Chapter 3: LOB Interface This chapter describes the functions and data types necessary for using LOB data. +- Chapter 4: Using Cursors + This chapter introduces how to use cursors that the Altibase CLI driver provides. + - Appendix A. Sample Codes This appendix shows all the sample codes used in this document. @@ -260,7 +264,7 @@ This section describes the conventions used in this manual. Understanding these There are two sets of conventions: -- Syntax diagram convetions +- Syntax diagram conventions - Sample code conventions ##### Syntax Diagram Conventions @@ -271,13 +275,13 @@ This manual describes command syntax using diagrams composed of the following el | ------------------------------------------------------------ | ------------------------------------------------------------ | | [![image1](https://github.com/ALTIBASE/Documents/raw/master/Manuals/Altibase_7.1/eng/media/SQL/image1.gif)](https://github.com/ALTIBASE/Documents/blob/master/Manuals/Altibase_7.1/eng/media/SQL/image1.gif) | Indicates the start of a command. If a syntactic element starts with an arrow, it is not a complete command. | | [![image2](https://github.com/ALTIBASE/Documents/raw/master/Manuals/Altibase_7.1/eng/media/SQL/image2.gif)](https://github.com/ALTIBASE/Documents/blob/master/Manuals/Altibase_7.1/eng/media/SQL/image2.gif) | Indicates that the command continues to the next line. If a syntactic element ends with this symbol, it is not a complete command. | -| [![image3](https://github.com/ALTIBASE/Documents/raw/master/Manuals/Altibase_7.1/eng/media/SQL/image3.gif)](https://github.com/ALTIBASE/Documents/blob/master/Manuals/Altibase_7.1/eng/media/SQL/image3.gif) | Indicates taht the command continues from the previous line. If a syntactic element starts witht his symbol, it is not a complete command. | +| [![image3](https://github.com/ALTIBASE/Documents/raw/master/Manuals/Altibase_7.1/eng/media/SQL/image3.gif)](https://github.com/ALTIBASE/Documents/blob/master/Manuals/Altibase_7.1/eng/media/SQL/image3.gif) | Indicates that the command continues from the previous line. If a syntactic element starts with this symbol, it is not a complete command. | | [![image4](https://github.com/ALTIBASE/Documents/raw/master/Manuals/Altibase_7.1/eng/media/SQL/image4.gif)](https://github.com/ALTIBASE/Documents/blob/master/Manuals/Altibase_7.1/eng/media/SQL/image4.gif) | Indicates the end of a statement. | -| [![image5](https://github.com/ALTIBASE/Documents/raw/master/Manuals/Altibase_7.1/eng/media/SQL/image5.gif)](https://github.com/ALTIBASE/Documents/blob/master/Manuals/Altibase_7.1/eng/media/SQL/image5.gif) | Indicates a manatory element. | +| [![image5](https://github.com/ALTIBASE/Documents/raw/master/Manuals/Altibase_7.1/eng/media/SQL/image5.gif)](https://github.com/ALTIBASE/Documents/blob/master/Manuals/Altibase_7.1/eng/media/SQL/image5.gif) | Indicates a mandatory element. | | [![image6](https://github.com/ALTIBASE/Documents/raw/master/Manuals/Altibase_7.1/eng/media/SQL/image6.gif)](https://github.com/ALTIBASE/Documents/blob/master/Manuals/Altibase_7.1/eng/media/SQL/image6.gif) | Indicates an optional element. | | [![image7](https://github.com/ALTIBASE/Documents/raw/master/Manuals/Altibase_7.1/eng/media/SQL/image7.gif)](https://github.com/ALTIBASE/Documents/blob/master/Manuals/Altibase_7.1/eng/media/SQL/image7.gif) | Indicates a mandatory element comprised of options. One, and only one, option must be specified. | | [![image8](https://github.com/ALTIBASE/Documents/raw/master/Manuals/Altibase_7.1/eng/media/SQL/image8.gif)](https://github.com/ALTIBASE/Documents/blob/master/Manuals/Altibase_7.1/eng/media/SQL/image8.gif) | Indicates an optional element comprised of options. | -| [![image9](https://github.com/ALTIBASE/Documents/raw/master/Manuals/Altibase_7.1/eng/media/SQL/image9.gif)](https://github.com/ALTIBASE/Documents/blob/master/Manuals/Altibase_7.1/eng/media/SQL/image9.gif) | Indicates an optional element in which multiple elements may be specified. A comman must precede all but the first element. | +| [![image9](https://github.com/ALTIBASE/Documents/raw/master/Manuals/Altibase_7.1/eng/media/SQL/image9.gif)](https://github.com/ALTIBASE/Documents/blob/master/Manuals/Altibase_7.1/eng/media/SQL/image9.gif) | Indicates an optional element in which multiple elements may be specified. A comma must precede all but the first element. | ##### Sample Code Conventions @@ -2840,22 +2844,8 @@ SQLRETURN SQLEndTran ( SQLSMALLINT type ); ``` +#### Arguments - -#### 
-Altibase Application Development Database Link User’s Manual
-Release 7.1
-Copyright ⓒ 2001~2023 Altibase Corp. All Rights Reserved.

-This manual contains proprietary information of Altibase® Corporation; it is provided under a license agreement containing restrictions on use and disclosure and is also protected by copyright patent and other intellectual property law. Reverse engineering of the
-software is prohibited.

-All trademarks, registered or otherwise, are the property of their respective owners.

-Altibase Corp
-10F, Daerung PostTower II,
-306, Digital-ro, Guro-gu, Seoul 08378, Korea
-Telephone : +82-2-2082-1000 
-Fax       : +82-2-2082-1099
-Customer Service Portal : http://support.altibase.com/en/
-Homepage                : http://www.altibase.com
| Data Type | Argument | In/Output | Description | | ----------- | ---------- | --------- | ------------------------------------------------------------ | | SQLSMALLINT | handleType | Input | Handle type identifier. it should be eitherSQL_HANDLE_ENV or SQL_HANDLE_DBC.
| @@ -6280,39 +6270,93 @@ SQLTransact(SQL_NULL_HENV, dbc, SQL_COMMIT); # 3. LOB Interface -This chapter describes functions and data types that can be used for handling LOB data. +This chapter describes how CLI processes LOB data, and functions and data types that can be used for handling LOB data. + +### How to Process LOB Data + +Altibase uses a **LOB Locator** in the CLI to handle LOB data processing. The LOB Locator is an internal data structure of the Altibase server corresponding to a unique value for LOB data and allows users to read or write LOB data. Therefore, the LOB Locator should be obtained first to process LOB data. Since the LOB Locator points to LOB data at a specific point in time with respect to MVCC, the LOB Locator is bound to the transaction that generated it and shares its lifecycle. + +#### NON-AUTOCOMMIT Mode + +Because LOB Locators are transaction-bound, **when using LOB Locators in the CLI to handle LOB data, it is essential to disable auto-commit mode,i.e., NON-AUTOCOMMIT mode.** + +NON-AUTOCOMMIT mode allows CLI functions for obtaining LOB Locators and for reading and writing LOB data to operate as individual tasks within a single transaction, enabling sharing of the LOB Locator. Conversely, in auto-commit mode, each CLI function operates within its transaction, preventing the sharing of the LOB Locator between two transactions. + +> **Considerations When Committing Transactions Using LOB Locators** + +1. In NON-AUTOCOMMIT mode, if an unexpected error occurs during CLI functions for reading from or writing to LOB data, it is essential to **rollback the transaction** to ensure that internally initialized data is cleared. +2. Attempting to INSERT or UPDATE the NULL value into a LOB type column with NOT NULL constraint will result in the error message [Unable to insert (or update) NULL into NOT NULL column.]. In this case, it is essential to **rollback the transaction** as internally initialized data may persist. + +#### Obtaining LOB Locator + +LOB Locator is obtained when executing the following CLI functions: + +- SQLBindCol / SQLFetch + +- SQLBindParameter / SQLExecute + + > ⚠️ The SQLExecute function initializes LOB data to null when executing INSERT and UPDATE statements. + +#### Reading and Writing LOB Data + +After obtaining a LOB Locator, users can use it to read or write LOB data. The relevant CLI functions are as follows: + +- SQLBindFileToParam +- SQLGetLob +- SQLGetLobLength +- SQLPutLob +- SQLTrimLob + +#### Retrieving LOB Data (SELECT) + +When performing SELECT LOB data, it is internally processed by obtaining a LOB Locator, resulting in an open transaction. Therefore, the user must explicitly perform transaction-ending operations such as COMMIT or ROLLBACK. + +> [!Caution] +> +> If users do not perform explicit transaction-ending operation such as COMMIT or ROLLBACK, database memory usage may increase. + +#### Releasing Resources + +Once LOB data-related operations are complete, the associated resources must be released. The relevant CLI functions are as follows: + +- [SQLFreeLob](#sqlfreelob) +- [SQLEndTran](#sqlendtran) + +> The SQLFreeLob function only releases resources related to the LOB Locator and does not end the transaction. ### LOB data types +#### SQL Data Type + The following table shows SQL data type identifiers that support LOB: -| SQL Type Identifier | Data Type | Description | -| ------------------- | --------- | ----------------------------------------------------- | -| SQL_BLOB | BLOB | BLOB is a binary data type with a variable length. | -| SQL_CLOB | CLOB | CLOB is a character data type with a variable length. | +| SQL Type Identifier | Altibase Data Type | Description | +| ------------------- | ------------------ | ----------------------------------------------------- | +| SQL_BLOB | BLOB | BLOB is a binary data type with a variable length. | +| SQL_CLOB | CLOB | CLOB is a character data type with a variable length. | [Table 3‑1] Identifier of the SQL data type -The following table shows C data type identifiers that support LOB. It lists C data type of ODBC for each identifier and their definition. - -| C Type Identifier | ODBC C Type | C Type Definition | -| ------------------ | ----------- | ----------------- | -| SQL_C_BLOB_LOCATOR | SQLUBIGINT | unsigned \_int64 | -| SQL_C_CLOB_LOCATOR | SQLUBIGINT | unsigned \_int64 | +#### C Data Type -[Table 3‑2] Identifier for LOB-supported C data types - -The name of a 64-bit integer type may vary depending on platform. The _int64 shown in the above table is the name of a 64-bit integer that is used in several platforms. +The following table shows C data type identifiers that support LOB. It lists C data type of ODBC for each identifier and their definition. Use SQL_C_CHAR for CLOB data and SQL_C_BINARY for BLOB data to bind user variables. -To obtain a LOB locator, bind SQL_C_CLOB_LOCATOR or SQL_C_BLOB_LOCATOR appropriately based on the LOB column type. A LOB locator in this context, – a LOB location input scheme – is a handle that is used during LOB data operation like a file pointer in an operating system. +To obtain a LOB locator, bind SQL_C_CLOB_LOCATOR or SQL_C_BLOB_LOCATOR appropriately based on the LOB column type. -The LOB location input scheme for Read can be obtained after SELECT LOB column name FROM table where… and select are executed. The LOB location input scheme for Write can be obtained after SELECT LOB column name FROM table where… FOR UPDATE are executed. +| C Type Identifier | Altibase Data Type | ODBC C Type | C Type Definition | +| ------------------ | ------------------ | ----------- | ----------------- | +| SQL_C_BINARY | BLOB | SQLCHAR * | unsigned char * | +| SQL_C_CHAR | CLOB | SQLSCHAR * | char * | +| SQL_C_BLOB_LOCATOR | | SQLUBIGINT | unsigned \_int64 | +| SQL_C_CLOB_LOCATOR | | SQLUBIGINT | unsigned \_int64 | -Since a LOB location input scheme refers to LOB data at a certain point in relation to MVCC, it has the same life cycle with the transaction that has created itself. Therefore, to perform LOB operation with a LOB location input scheme, a connection should be always established in Non-Autocommit Mode. +[Table 3‑2] Identifier for LOB-supported C data types -Care must be taken as there is no LOB type of a user variable such as SQL_C_BLOB or SQL_C_CLOB. +> SQL_C_BLOB and SQL_C_CLOB are not supported as a C type identifier. + +> The name of a 64-bit integer type may vary depending on platform. The _int64 shown in the above table is the name of a 64-bit integer that is used in several platforms. ### LOB Function Overview @@ -6343,7 +6387,9 @@ The functions that are available for manipulating LOB data are as follows: Among the above functions, the functions #1 through #6 are special functions that are provided by Altibase for LOB manipulation, and they are not ODBC standard functions. -ODBC standard functions such as #7 and #8 can be used to access LOB data whether the database column type is LOB or not. However, when only a standard function is used, the functions for partial update and partial retrieve are not available. If a user wants to do programming with ODBC Driver Manager, he should add the following entry to the odbc.ini file: +ODBC standard functions such as #7 and #8 can be used to access LOB data whether the database column type is LOB or not. However, when only a standard function is used, the functions for partial update and partial retrieve are not available. + +If a user wants to do programming with ODBC Driver Manager, he should add the following entry to the odbc.ini file: ``` LongDataCompat = yes diff --git a/Manuals/Altibase_7.1/eng/JDBC User's Manual.md b/Manuals/Altibase_7.1/eng/JDBC User's Manual.md index 26f8e08e3..77cba295c 100644 --- a/Manuals/Altibase_7.1/eng/JDBC User's Manual.md +++ b/Manuals/Altibase_7.1/eng/JDBC User's Manual.md @@ -2634,12 +2634,14 @@ while(sRs.next()) ##### Reading BLOB Data +When reading LOB data, it is essential to include explicit transaction termination such as commit or rollback because Lob Locator is internally utilized. + ###### Using the getBinaryStream method with an InputStream object -``` +```java ... -PreparedStatement sPstmt = connection().prepareStatement("SELECT BLOB_COLUMN -FROM BLOB_TABLE"); +sCon = getConnection(); +PreparedStatement sPstmt = sCon.prepareStatement("SELECT BLOB_COLUMN FROM BLOB_TABLE"); ResultSet sRs = sPstmt.executeQuery(); while(sRs.next()) { @@ -2648,16 +2650,17 @@ while(sRs.next()) ... } ... +sCon.commit(); ``` ###### Using the getBlob method with an InputStream object -``` +```java ... -PreparedStatement sPstmt = connection().prepareStatement("SELECT BLOB_COLUMN -FROM BLOB_TABLE"); +sCon = getConnection(); +PreparedStatement sPstmt = sCon.prepareStatement("SELECT BLOB_COLUMN FROM BLOB_TABLE"); ResultSet sRs = sPstmt.executeQuery(); while(sRs.next()) { @@ -2667,17 +2670,19 @@ while(sRs.next()) ... } ... +sCon.commit(); ``` ###### Using the getBlob method with a byte array -``` +```java ... final int sReadLength = 100; - -PreparedStatement sPstmt = connection().prepareStatement("SELECT BLOB_COLUMN FROM BLOB_TABLE"); + +sCon = getConnection(); +PreparedStatement sPstmt = connection().prepareStatement("SELECT BLOB_COLUMN FROM LOB_TABLE"); ResultSet sRs = sPstmt.executeQuery(); @@ -2696,8 +2701,8 @@ while(sRs.next()) } ... } - ... +sCon.commit(); ``` diff --git a/Manuals/Altibase_7.1/kor/CLI User's Manual.md b/Manuals/Altibase_7.1/kor/CLI User's Manual.md index fc5da3e64..b9108cc0b 100644 --- a/Manuals/Altibase_7.1/kor/CLI User's Manual.md +++ b/Manuals/Altibase_7.1/kor/CLI User's Manual.md @@ -265,6 +265,10 @@ Copyright ⓒ 2001~2023 Altibase Corp. All Rights Reserved.
- 제 3장 LOB 인터페이스 이 장은 LOB 데이터를 사용하는데 필요한 함수 및 데이터 타입을 설명한다. +- 제 4장 커서 사용 + + 이 장은 Altibase CLI 드라이버가 제공하는 커서의 사용법을 설명한다. + - A. 부록: Sample Code 본 매뉴얼에서 전반적으로 사용된 예에 대한 전체 코드 리스트를 나타낸다. diff --git a/Manuals/Altibase_7.3/eng/CLI User's Manual.md b/Manuals/Altibase_7.3/eng/CLI User's Manual.md index 864b024b6..addc1e943 100644 --- a/Manuals/Altibase_7.3/eng/CLI User's Manual.md +++ b/Manuals/Altibase_7.3/eng/CLI User's Manual.md @@ -261,7 +261,7 @@ This section describes the conventions used in this manual. Understanding these There are two sets of conventions: -- Syntax diagram convetions +- Syntax diagram conventions - Sample code conventions ##### Syntax Diagram Conventions @@ -272,13 +272,13 @@ This manual describes command syntax using diagrams composed of the following el | ------------------------------------------------------------ | ------------------------------------------------------------ | | [![image1](https://github.com/ALTIBASE/Documents/raw/master/Manuals/Altibase_7.1/eng/media/SQL/image1.gif)](https://github.com/ALTIBASE/Documents/blob/master/Manuals/Altibase_7.1/eng/media/SQL/image1.gif) | Indicates the start of a command. If a syntactic element starts with an arrow, it is not a complete command. | | [![image2](https://github.com/ALTIBASE/Documents/raw/master/Manuals/Altibase_7.1/eng/media/SQL/image2.gif)](https://github.com/ALTIBASE/Documents/blob/master/Manuals/Altibase_7.1/eng/media/SQL/image2.gif) | Indicates that the command continues to the next line. If a syntactic element ends with this symbol, it is not a complete command. | -| [![image3](https://github.com/ALTIBASE/Documents/raw/master/Manuals/Altibase_7.1/eng/media/SQL/image3.gif)](https://github.com/ALTIBASE/Documents/blob/master/Manuals/Altibase_7.1/eng/media/SQL/image3.gif) | Indicates taht the command continues from the previous line. If a syntactic element starts witht his symbol, it is not a complete command. | +| [![image3](https://github.com/ALTIBASE/Documents/raw/master/Manuals/Altibase_7.1/eng/media/SQL/image3.gif)](https://github.com/ALTIBASE/Documents/blob/master/Manuals/Altibase_7.1/eng/media/SQL/image3.gif) | Indicates that the command continues from the previous line. If a syntactic element starts with this symbol, it is not a complete command. | | [![image4](https://github.com/ALTIBASE/Documents/raw/master/Manuals/Altibase_7.1/eng/media/SQL/image4.gif)](https://github.com/ALTIBASE/Documents/blob/master/Manuals/Altibase_7.1/eng/media/SQL/image4.gif) | Indicates the end of a statement. | -| [![image5](https://github.com/ALTIBASE/Documents/raw/master/Manuals/Altibase_7.1/eng/media/SQL/image5.gif)](https://github.com/ALTIBASE/Documents/blob/master/Manuals/Altibase_7.1/eng/media/SQL/image5.gif) | Indicates a manatory element. | +| [![image5](https://github.com/ALTIBASE/Documents/raw/master/Manuals/Altibase_7.1/eng/media/SQL/image5.gif)](https://github.com/ALTIBASE/Documents/blob/master/Manuals/Altibase_7.1/eng/media/SQL/image5.gif) | Indicates a mandatory element. | | [![image6](https://github.com/ALTIBASE/Documents/raw/master/Manuals/Altibase_7.1/eng/media/SQL/image6.gif)](https://github.com/ALTIBASE/Documents/blob/master/Manuals/Altibase_7.1/eng/media/SQL/image6.gif) | Indicates an optional element. | | [![image7](https://github.com/ALTIBASE/Documents/raw/master/Manuals/Altibase_7.1/eng/media/SQL/image7.gif)](https://github.com/ALTIBASE/Documents/blob/master/Manuals/Altibase_7.1/eng/media/SQL/image7.gif) | Indicates a mandatory element comprised of options. One, and only one, option must be specified. | | [![image8](https://github.com/ALTIBASE/Documents/raw/master/Manuals/Altibase_7.1/eng/media/SQL/image8.gif)](https://github.com/ALTIBASE/Documents/blob/master/Manuals/Altibase_7.1/eng/media/SQL/image8.gif) | Indicates an optional element comprised of options. | -| [![image9](https://github.com/ALTIBASE/Documents/raw/master/Manuals/Altibase_7.1/eng/media/SQL/image9.gif)](https://github.com/ALTIBASE/Documents/blob/master/Manuals/Altibase_7.1/eng/media/SQL/image9.gif) | Indicates an optional element in which multiple elements may be specified. A comman must precede all but the first element. | +| [![image9](https://github.com/ALTIBASE/Documents/raw/master/Manuals/Altibase_7.1/eng/media/SQL/image9.gif)](https://github.com/ALTIBASE/Documents/blob/master/Manuals/Altibase_7.1/eng/media/SQL/image9.gif) | Indicates an optional element in which multiple elements may be specified. A comma must precede all but the first element. | ##### Sample Code Conventions @@ -6270,6 +6270,70 @@ SQLTransact(SQL_NULL_HENV, dbc, SQL_COMMIT); This chapter describes functions and data types that can be used for handling LOB data. +### LOB 데이터 처리 방식 + + + +Altibase는 CLI에서 LOB데이터를 처리하기위해 LOB 위치 입력기(LOB Locator)를 이용한다. LOB 데이터에 대응되는 고유값으로 Altibase 서버의 내부 자료구조이다. LOB 데이터를 연산하기 위해서는 먼저 LOB Locator를 획득해야 하며, 이를 통해 LOB 데이터를 읽거나 쓸 수 있다. LOB Locator는 MVCC와 관련하여 특정 시점의 LOB 데이터를 가리키기 때문에, LOB Locator를 발생시킨 트랜잭션과 생명주기를 같이하며, 그 트랜잭션에 종속된다. + +#### 자동 커밋 모드 해제 + + + +LOB 위치 입력기는 트랜잭션에 종속적이기 때문에 **CLI에서 LOB 위치 입력기를 이용하여 LOB 데이터를 처리하려면 반드시 자동 커밋 모드를 해제해야 한다.** + +자동 커밋 모드를 해제하면 LOB 위치 입력기를 얻어오는 CLI 함수와 LOB 데이터를 읽고 쓰는 CLI 함수는 하나의 트랜잭션에서 개별 작업이 되어 LOB 위치 입력기를 공유할 수 있다. 반면, 자동 커밋 모드에서는 각각의 개별 트랜잭션으로 동작하기 때문에 두 트랜잭션 간에 LOB 위치 입력기를 공유할 수 없다. + +> **LOB 위치 입력기를 이용한 트랜잭션 커밋 시 주의사항** + +1. 자동 커밋 해제 모드에서 LOB 데이터를 읽고 쓰는 CLI 함수 수행 중 예상치 못한 에러가 발생하면, 내부적으로 초기화된 데이터가 남아 있을 수 있어 **반드시 트랜잭션을 롤백해야 한다.** +2. NOT NULL 제약이 있는 LOB 타입 컬럼에 NULL 값을 INSERT 혹은 UPDATE 수행하면 [Unable to insert (or update) NULL into NOT NULL column.] 에러가 발생한다. 이 경우 초기화된 데이터가 남아 있어 **반드시 트랜잭션을 롤백해야 한다.** + +#### LOB 위치 입력기 얻기 + + + +LOB 위치 입력기는 아래의 CLI 함수들을 실행할 때 얻는다. + +- SQLBindCol / SQLFetch + +- SQLBindParameter / SQLExecute + + > ⚠️ SQLExecute 함수는 INSERT와 UPDATE 문을 실행할 때 LOB 데이터를 널로 초기화한다. + +#### LOB 데이터 읽고 쓰기 + + + +LOB 위치 입력기를 얻은 후에 이것을 이용하여 LOB 데이터를 읽거나 쓸 수 있다. 관련 CLI 함수는 아래와 같다. + +- SQLBindFileToParam +- SQLGetLob +- SQLGetLobLength +- SQLPutLob +- SQLTrimLob + +#### LOB 데이터의 조회(SELECT) + + + +LOB 데이터를 SELECT 할때, 내부적으로는 LOB Locator를 얻어와서 처리되기 때문에 연관된 트랜잭션이 열린 상태가 된다. 따라서 사용자는 명시적으로 commit 또는 rollback과 같은 트랜잭션 종료 작업을 추가로 해주어야 한다. + +> [!Caution] +> +> 만약, 사용자가 명시적으로 commit 또는 rollback 과 같은 트랜잭션 종료 작업을 하지 않으면, 데이터베이스의 메모리 사용량이 증가할 수 있다. + +#### 자원 해제하기 + + + +LOB 데이터와 관련한 작업이 완료된 경우, 관련된 자원을 해제해주어야 한다. 관련 CLI 함수는 아래와 같다. + +- [SQLFreeLob](https://github.com/ALTIBASE/Documents/blob/8b65902599c5168fc2650bae077001ca57e04326/Manuals/Altibase_7.1/kor/CLI User's Manual.md#sqlfreelob) +- [SQLEndTran](https://github.com/ALTIBASE/Documents/blob/8b65902599c5168fc2650bae077001ca57e04326/Manuals/Altibase_7.1/kor/CLI User's Manual.md#sqlendtran) + +SQLFreeLob 함수는 Lob Locator와 관련된 자원을 해제할 뿐, 트랜잭션을 종료하지는 않는다. + ### LOB data types The following table shows SQL data type identifiers that support LOB: diff --git a/Manuals/Altibase_7.3/eng/JDBC User's Manual.md b/Manuals/Altibase_7.3/eng/JDBC User's Manual.md index a1df4388c..d9552fb35 100644 --- a/Manuals/Altibase_7.3/eng/JDBC User's Manual.md +++ b/Manuals/Altibase_7.3/eng/JDBC User's Manual.md @@ -2631,12 +2631,14 @@ while(sRs.next()) ##### Reading BLOB Data +When reading LOB data, it is essential to include explicit transaction termination such as commit or rollback because Lob Locator is internally utilized. + ###### Using the getBinaryStream method with an InputStream object -``` +```java ... -PreparedStatement sPstmt = connection().prepareStatement("SELECT BLOB_COLUMN -FROM BLOB_TABLE"); +sCon = getConnection(); +PreparedStatement sPstmt = sCon.prepareStatement("SELECT BLOB_COLUMN FROM BLOB_TABLE"); ResultSet sRs = sPstmt.executeQuery(); while(sRs.next()) { @@ -2645,16 +2647,17 @@ while(sRs.next()) ... } ... +sCon.commit(); ``` ###### Using the getBlob method with an InputStream object -``` +```java ... -PreparedStatement sPstmt = connection().prepareStatement("SELECT BLOB_COLUMN -FROM BLOB_TABLE"); +sCon = getConnection(); +PreparedStatement sPstmt = sCon.prepareStatement("SELECT BLOB_COLUMN FROM BLOB_TABLE"); ResultSet sRs = sPstmt.executeQuery(); while(sRs.next()) { @@ -2664,16 +2667,18 @@ while(sRs.next()) ... } ... +sCon.commit(); ``` ###### Using the getBlob method with a byte array -``` +```java ... final int sReadLength = 100; - + +sCon = getConnection(); PreparedStatement sPstmt = connection().prepareStatement("SELECT BLOB_COLUMN FROM BLOB_TABLE"); ResultSet sRs = sPstmt.executeQuery(); @@ -2692,9 +2697,9 @@ while(sRs.next()) ... } ... -} - +} ... +sCon.commit(); ``` diff --git a/Manuals/Altibase_trunk/eng/CLI User's Manual.md b/Manuals/Altibase_trunk/eng/CLI User's Manual.md index b8114cc33..1c21e47fb 100644 --- a/Manuals/Altibase_trunk/eng/CLI User's Manual.md +++ b/Manuals/Altibase_trunk/eng/CLI User's Manual.md @@ -260,7 +260,7 @@ This section describes the conventions used in this manual. Understanding these There are two sets of conventions: -- Syntax diagram convetions +- Syntax diagram conventions - Sample code conventions ##### Syntax Diagram Conventions @@ -271,13 +271,13 @@ This manual describes command syntax using diagrams composed of the following el | ------------------------------------------------------------ | ------------------------------------------------------------ | | [![image1](https://github.com/ALTIBASE/Documents/raw/master/Manuals/Altibase_7.1/eng/media/SQL/image1.gif)](https://github.com/ALTIBASE/Documents/blob/master/Manuals/Altibase_7.1/eng/media/SQL/image1.gif) | Indicates the start of a command. If a syntactic element starts with an arrow, it is not a complete command. | | [![image2](https://github.com/ALTIBASE/Documents/raw/master/Manuals/Altibase_7.1/eng/media/SQL/image2.gif)](https://github.com/ALTIBASE/Documents/blob/master/Manuals/Altibase_7.1/eng/media/SQL/image2.gif) | Indicates that the command continues to the next line. If a syntactic element ends with this symbol, it is not a complete command. | -| [![image3](https://github.com/ALTIBASE/Documents/raw/master/Manuals/Altibase_7.1/eng/media/SQL/image3.gif)](https://github.com/ALTIBASE/Documents/blob/master/Manuals/Altibase_7.1/eng/media/SQL/image3.gif) | Indicates taht the command continues from the previous line. If a syntactic element starts witht his symbol, it is not a complete command. | +| [![image3](https://github.com/ALTIBASE/Documents/raw/master/Manuals/Altibase_7.1/eng/media/SQL/image3.gif)](https://github.com/ALTIBASE/Documents/blob/master/Manuals/Altibase_7.1/eng/media/SQL/image3.gif) | Indicates that the command continues from the previous line. If a syntactic element starts with this symbol, it is not a complete command. | | [![image4](https://github.com/ALTIBASE/Documents/raw/master/Manuals/Altibase_7.1/eng/media/SQL/image4.gif)](https://github.com/ALTIBASE/Documents/blob/master/Manuals/Altibase_7.1/eng/media/SQL/image4.gif) | Indicates the end of a statement. | -| [![image5](https://github.com/ALTIBASE/Documents/raw/master/Manuals/Altibase_7.1/eng/media/SQL/image5.gif)](https://github.com/ALTIBASE/Documents/blob/master/Manuals/Altibase_7.1/eng/media/SQL/image5.gif) | Indicates a manatory element. | +| [![image5](https://github.com/ALTIBASE/Documents/raw/master/Manuals/Altibase_7.1/eng/media/SQL/image5.gif)](https://github.com/ALTIBASE/Documents/blob/master/Manuals/Altibase_7.1/eng/media/SQL/image5.gif) | Indicates a mandatory element. | | [![image6](https://github.com/ALTIBASE/Documents/raw/master/Manuals/Altibase_7.1/eng/media/SQL/image6.gif)](https://github.com/ALTIBASE/Documents/blob/master/Manuals/Altibase_7.1/eng/media/SQL/image6.gif) | Indicates an optional element. | | [![image7](https://github.com/ALTIBASE/Documents/raw/master/Manuals/Altibase_7.1/eng/media/SQL/image7.gif)](https://github.com/ALTIBASE/Documents/blob/master/Manuals/Altibase_7.1/eng/media/SQL/image7.gif) | Indicates a mandatory element comprised of options. One, and only one, option must be specified. | | [![image8](https://github.com/ALTIBASE/Documents/raw/master/Manuals/Altibase_7.1/eng/media/SQL/image8.gif)](https://github.com/ALTIBASE/Documents/blob/master/Manuals/Altibase_7.1/eng/media/SQL/image8.gif) | Indicates an optional element comprised of options. | -| [![image9](https://github.com/ALTIBASE/Documents/raw/master/Manuals/Altibase_7.1/eng/media/SQL/image9.gif)](https://github.com/ALTIBASE/Documents/blob/master/Manuals/Altibase_7.1/eng/media/SQL/image9.gif) | Indicates an optional element in which multiple elements may be specified. A comman must precede all but the first element. | +| [![image9](https://github.com/ALTIBASE/Documents/raw/master/Manuals/Altibase_7.1/eng/media/SQL/image9.gif)](https://github.com/ALTIBASE/Documents/blob/master/Manuals/Altibase_7.1/eng/media/SQL/image9.gif) | Indicates an optional element in which multiple elements may be specified. A comma must precede all but the first element. | ##### Sample Code Conventions @@ -6269,6 +6269,70 @@ SQLTransact(SQL_NULL_HENV, dbc, SQL_COMMIT); This chapter describes functions and data types that can be used for handling LOB data. +### LOB 데이터 처리 방식 + + + +Altibase는 CLI에서 LOB데이터를 처리하기위해 LOB 위치 입력기(LOB Locator)를 이용한다. LOB 데이터에 대응되는 고유값으로 Altibase 서버의 내부 자료구조이다. LOB 데이터를 연산하기 위해서는 먼저 LOB Locator를 획득해야 하며, 이를 통해 LOB 데이터를 읽거나 쓸 수 있다. LOB Locator는 MVCC와 관련하여 특정 시점의 LOB 데이터를 가리키기 때문에, LOB Locator를 발생시킨 트랜잭션과 생명주기를 같이하며, 그 트랜잭션에 종속된다. + +#### 자동 커밋 모드 해제 + + + +LOB 위치 입력기는 트랜잭션에 종속적이기 때문에 **CLI에서 LOB 위치 입력기를 이용하여 LOB 데이터를 처리하려면 반드시 자동 커밋 모드를 해제해야 한다.** + +자동 커밋 모드를 해제하면 LOB 위치 입력기를 얻어오는 CLI 함수와 LOB 데이터를 읽고 쓰는 CLI 함수는 하나의 트랜잭션에서 개별 작업이 되어 LOB 위치 입력기를 공유할 수 있다. 반면, 자동 커밋 모드에서는 각각의 개별 트랜잭션으로 동작하기 때문에 두 트랜잭션 간에 LOB 위치 입력기를 공유할 수 없다. + +> **LOB 위치 입력기를 이용한 트랜잭션 커밋 시 주의사항** + +1. 자동 커밋 해제 모드에서 LOB 데이터를 읽고 쓰는 CLI 함수 수행 중 예상치 못한 에러가 발생하면, 내부적으로 초기화된 데이터가 남아 있을 수 있어 **반드시 트랜잭션을 롤백해야 한다.** +2. NOT NULL 제약이 있는 LOB 타입 컬럼에 NULL 값을 INSERT 혹은 UPDATE 수행하면 [Unable to insert (or update) NULL into NOT NULL column.] 에러가 발생한다. 이 경우 초기화된 데이터가 남아 있어 **반드시 트랜잭션을 롤백해야 한다.** + +#### LOB 위치 입력기 얻기 + + + +LOB 위치 입력기는 아래의 CLI 함수들을 실행할 때 얻는다. + +- SQLBindCol / SQLFetch + +- SQLBindParameter / SQLExecute + + > ⚠️ SQLExecute 함수는 INSERT와 UPDATE 문을 실행할 때 LOB 데이터를 널로 초기화한다. + +#### LOB 데이터 읽고 쓰기 + + + +LOB 위치 입력기를 얻은 후에 이것을 이용하여 LOB 데이터를 읽거나 쓸 수 있다. 관련 CLI 함수는 아래와 같다. + +- SQLBindFileToParam +- SQLGetLob +- SQLGetLobLength +- SQLPutLob +- SQLTrimLob + +#### LOB 데이터의 조회(SELECT) + + + +LOB 데이터를 SELECT 할때, 내부적으로는 LOB Locator를 얻어와서 처리되기 때문에 연관된 트랜잭션이 열린 상태가 된다. 따라서 사용자는 명시적으로 commit 또는 rollback과 같은 트랜잭션 종료 작업을 추가로 해주어야 한다. + +> [!Caution] +> +> 만약, 사용자가 명시적으로 commit 또는 rollback 과 같은 트랜잭션 종료 작업을 하지 않으면, 데이터베이스의 메모리 사용량이 증가할 수 있다. + +#### 자원 해제하기 + + + +LOB 데이터와 관련한 작업이 완료된 경우, 관련된 자원을 해제해주어야 한다. 관련 CLI 함수는 아래와 같다. + +- [SQLFreeLob](https://github.com/ALTIBASE/Documents/blob/8b65902599c5168fc2650bae077001ca57e04326/Manuals/Altibase_7.1/kor/CLI User's Manual.md#sqlfreelob) +- [SQLEndTran](https://github.com/ALTIBASE/Documents/blob/8b65902599c5168fc2650bae077001ca57e04326/Manuals/Altibase_7.1/kor/CLI User's Manual.md#sqlendtran) + +SQLFreeLob 함수는 Lob Locator와 관련된 자원을 해제할 뿐, 트랜잭션을 종료하지는 않는다. + ### LOB data types The following table shows SQL data type identifiers that support LOB: diff --git a/Manuals/Altibase_trunk/eng/JDBC User's Manual.md b/Manuals/Altibase_trunk/eng/JDBC User's Manual.md index 5cacdd571..67c09df3b 100644 --- a/Manuals/Altibase_trunk/eng/JDBC User's Manual.md +++ b/Manuals/Altibase_trunk/eng/JDBC User's Manual.md @@ -2744,12 +2744,14 @@ while(sRs.next()) ##### Reading BLOB Data +When reading LOB data, it is essential to include explicit transaction termination such as commit or rollback because Lob Locator is internally utilized. + ###### Using the getBinaryStream method with an InputStream object -``` +```java ... -PreparedStatement sPstmt = connection().prepareStatement("SELECT BLOB_COLUMN -FROM BLOB_TABLE"); +sCon = getConnection(); +PreparedStatement sPstmt = sCon.prepareStatement("SELECT BLOB_COLUMN FROM BLOB_TABLE"); ResultSet sRs = sPstmt.executeQuery(); while(sRs.next()) { @@ -2758,16 +2760,17 @@ while(sRs.next()) ... } ... +sCon.commit(); ``` ###### Using the getBlob method with an InputStream object -``` +```java ... -PreparedStatement sPstmt = connection().prepareStatement("SELECT BLOB_COLUMN -FROM BLOB_TABLE"); +sCon = getConnection(); +PreparedStatement sPstmt = sCon.prepareStatement("SELECT BLOB_COLUMN FROM BLOB_TABLE"); ResultSet sRs = sPstmt.executeQuery(); while(sRs.next()) { @@ -2777,16 +2780,18 @@ while(sRs.next()) ... } ... +sCon.commit(); ``` ###### Using the getBlob method with a byte array -``` +```java ... final int sReadLength = 100; - + +sCon = getConnection(); PreparedStatement sPstmt = connection().prepareStatement("SELECT BLOB_COLUMN FROM BLOB_TABLE"); ResultSet sRs = sPstmt.executeQuery(); @@ -2806,8 +2811,8 @@ while(sRs.next()) } ... } - ... +sCon.commit(); ```