SQLSetPos
SQLSetPos#
행집합 내에서 커서 위치를 지정한다.
구 문#
SQLRETURN SQLSetPos (
SQLHSTMT stmt,
SQLSETPOSIROW rowNumber,
SQLUSMALLINT operation,
SQLUSMALLINT lockType);
인 자#
| 자료유형 | 인자 | 사용 | 설명 |
|---|---|---|---|
| SQLHSTMT | stmt | 입력 | 명령문 핸들 |
| SQLSETPOSIROW | rowNumber | 입력 | 행집합에서 operation 인자로 지정한 작업을 수행할 행의 위치. 1부터 시작한다. 0이면 행집합의 모든 행에 작업을 적용한다. |
| SQLUSMALLINT | operation | 입력 | 수행할 작업. 다음 중 하나가 올 수 있다: - SQL_POSITION - SQL_REFRESH - SQL_UPDATE - SQL_DELETE |
| SQLUSMALLINT | lockType | 입력 | 잠금 유형. 현재 미지원. |
결괏값#
SQL_SUCCESS
SQL_SUCCESS_WITH_INFO
SQL_NEED_DATA
SQL_STILL_EXECUTING
SQL_INVALID_HANDLE
SQL_ERROR
설 명#
SQLSetPos는 행집합 내에서 커서의 위치를 지정하고, 그 위치의 데이터를 새로 가져오거나 갱신 또는 삭제하도록 해준다. rowNumber는 행집합 내에서 작업을 수행할 행의 번호를 지정한다. rowNumber가 1이면 행집합에서 첫 번째 행을 가리킨다. rowNumber가 0이면 행집합 내의 모든 행에 작업이 적용된다. 하지만 operation이 SQL_POSITION일 때, rowNumber는 0일 수 없다.
커서 위치는 아래의 작업에 요구된다:
-
SQLGetData 호출 시
-
SQL_DELETE, SQL_REFRESH, 또는 SQL_UPDATE 옵션으로 SQLSetPos 호출 시
SELECT문 실행 후 처음 fetch를 하면 행집합 내에서 커서의 위치는 1이다.
SQLSetPos 함수의 operation 인자에는 아래의 옵션이 지원된다:
| 옵션 | 설명 |
|---|---|
| SQL_POSITION | 드라이버는 rowNumber로 지정한 행에 커서를 둔다. |
| SQL_REFRESH | 드라이버는 rowNumber로 지정한 행에 커서를 두고, 행집합 버퍼 내의 그 행의 데이터를 새로 가져온다. 만약 rowNumber에 0을 지정하면, 행집합 내의 모든 행의 데이터를 새로 가져온다. 만약 드라이버가 HOLE을 감지하면 행 상태 값으로 SQL_ROW_DELETED를 반환한다. 커서가 Sensitive이면 드라이버는 데이터베이스에서 최신 데이터를 가져오고, 아니면 캐시에서 기존 데이터를 가져온다. |
| SQL_UPDATE | 드라이버는 rowNumber로 지정한 행에 커서를 두고, 행집합 버퍼 내의 그 행의 데이터로 데이터베이스의 데이터를 갱신한다. 만약 rowNumber에 0을 지정하면, 행집합 내의 모든 데이터로 데이터베이스를 갱신한다. SQLBindCol의 length/indicator 인자에 SQL_COLUMN_IGNORE를 지정하면 그 칼럼은 갱신되지 않는다. SQL_ATTR_ROW_OPERATION_PTR 명령문 속성에 의해 설정된 행 작업 배열에 SQL_ROW_IGNORE로 설정한 행이 있다면, 그 행은 무시하고 다음 행을 갱신한다. |
| SQL_DELETE | 드라이버는 rowNumber로 지정한 행에 커서를 두고, 그 행을 삭제한다. 만약 rowNumber에 0을 지정하면, 행집합 내의 모든 행을 삭제한다. SQL_ATTR_ROW_OPERATION_PTR 명령문 속성에 의해 설정된 행 작업 배열에 SQL_ROW_IGNORE로 설정한 행이 있다면, 그 행은 무시하고 다음 행을 삭제한다. |
SQLSetPos 사용하기#
애플리케이션에서 SQLSetPos을 호출하려면, 아래의 단계대로 프로그램을 작성하라:
-
SQLBindCol을 호출해서 버퍼 바인딩
-
SQLExecDirect등을 이용해서 SELECT 쿼리문 실행
-
SQL_UPDATE 옵션으로 SQLSetPos를 호출하려면,
-
한 버퍼의 데이터를 변경하고자 하는 값으로 변경
-
칼럼을 무시하려면 length/indicator를 SQL_COLUMN_IGNORE로 지정해서 SQLBindCol을 재호출
-
행을 작업 대상에서 제외하려면, SQL_ATTR_ROW_OPERATION_PTR 명령문 속성을 설정하고 그 행에 대응하는 배열 요소에 SQL_ROW_IGNORE를 설정
-
-
SQLSetPos 호출
- L_ATTR_ROW_STATUS_PTR 명령문 속성에 상태 배열을 설정했다면, 이 배열의 값을 통해 각 행의 수행 결과를 확인할 수 있다.
진 단#
| SQLSTATE | 설명 | 부연설명 |
|---|---|---|
| HY000 | 일반 오류 | |
| HY001 | 메모리 할당 오류 | Altibase CLI 드라이버가 함수를 실행하고 완료하기 위해 요구된 메모리를 할당할 수 없음 |
| 08S01 | 통신 회선 장애 (데이터 송수신 실패) | Altibase CLI 드라이버와 DB간에 함수 처리가 완료되기 전에 통신 회선 실패 |
| 08003 | stmt가 연결되지 않거나 connection이 끊어진 상태 | |
| HY010 | 함수 연속 오류 | 주어진 stmt는 이 함수를 수행할 수 없음. 비동기 방식은 미지원. |
| 24519 | 홀이 발견되었으나 지시자 변수가 없음 | |
| 01S01 | 행에서 오류 발생 | rowNumber가 0이었고, 작업 수행 중에 한 개 이상의 행에서 오류 발생 |
| HY107 | 범위를 벗어난 행 값 | rowNumber에 지정한 값이 행집합 내의 행의 개수보다 크다. |
| HY109 | 유효하지 않은 커서 위치 | |
| 01001 | 커서 작업 충돌 | |
| HY024 | 유효하지 않은 배열 크기 | |
| 21S02 | 테이블의 타입과 칼럼 개수가 칼럼 리스트와 일치하지 않음 | |
| HY092 | 유효하지 않은 속성/옵션 | |
| 24000 | 올바르지 않은 커서 상태 |
관련 함수#
SQLBindCol
SQLBulkOperations
SQLCancel
SQLFetchScroll
SQLGetDescField
SQLGetDescRec
SQLSetDescField
SQLSetDescRec
SQLSetStmtAttr