SQLSetCursorName 함수
규칙
버전 소개: ODBC 1.0 표준 준수: ISO 92
요약
SQLSetCursorName 은 커서 이름을 활성 문과 연결합니다. 애플리케이션에서 SQLSetCursorName을 호출하지 않는 경우 드라이버는 SQL 문 처리에 필요한 대로 커서 이름을 생성합니다.
구문
SQLRETURN SQLSetCursorName(
SQLHSTMT StatementHandle,
SQLCHAR * CursorName,
SQLSMALLINT NameLength);
인수
StatementHandle
[입력] 문 핸들입니다.
CursorName
[입력] 커서 이름입니다. 효율적인 처리를 위해 커서 이름에는 커서 이름에 선행 또는 후행 공백이 포함되지 않아야 하며 커서 이름에 구분 식별자가 포함된 경우 구분 기호는 커서 이름의 첫 번째 문자로 배치되어야 합니다.
NameLength
[입력] *CursorName 문자의 길이입니다.
반품
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR 또는 SQL_INVALID_HANDLE.
진단
SQLSetCursorName이 SQL_ERROR 또는 SQL_SUCCESS_WITH_INFO 반환하는 경우 SQL_HANDLE_STMT HandleType 및 Handle of StatementHandle을 사용하여 SQLGetDiagRec 를 호출하여 관련 SQLSTATE 값을 가져올 수 있습니다. 다음 표에서는 SQLSetCursorName에서 일반적으로 반환되는 SQLSTATE 값을 나열하고 이 함수의 컨텍스트에서 각각에 대해 설명합니다. 표기법 "(DM)"은 드라이버 관리자가 반환한 SQLSTATE에 대한 설명 앞에 나와 있습니다. 달리 명시되지 않는 한 각 SQLSTATE 값과 연결된 반환 코드는 SQL_ERROR.
| SQLSTATE | 오류 | 설명 |
|---|---|---|
| 01000 | 일반 경고 | 드라이버 관련 정보 메시지입니다. 함수는 SQL_SUCCESS_WITH_INFO 반환합니다. |
| 01004 | 문자열 데이터, 오른쪽 잘림 | 커서 이름이 최대 제한을 초과했기 때문에 허용되는 최대 문자 수만 사용되었습니다. |
| 24000 | 커서 상태가 잘못되었습니다. | StatementHandle에 해당하는 문이 이미 실행됨 또는 커서 위치 상태였습니다. |
| 34000 | 커서 이름이 잘못되었습니다. | *CursorName 에 지정된 커서 이름이 드라이버에서 정의한 최대 길이를 초과했거나 "SQLCUR" 또는 "SQL_CUR"로 시작했기 때문에 잘못되었습니다. |
| 3C000 | 중복 커서 이름 | *CursorName 에 지정된 커서 이름이 이미 있습니다. |
| HY000 | 일반 오류 | 특정 SQLSTATE가 없고 구현별 SQLSTATE가 정의되지 않은 오류가 발생했습니다. *MessageText 버퍼의 SQLGetDiagRec에서 반환된 오류 메시지는 오류와 그 원인을 설명합니다. |
| HY001 | 메모리 할당 오류 | 드라이버가 함수 실행 또는 완료를 지원하는 데 필요한 메모리를 할당할 수 없습니다. |
| HY009 | null 포인터를 잘못 사용했습니다. | (DM) CursorName 인수가 null 포인터였습니다. |
| HY010 | 함수 시퀀스 오류 | (DM) StatementHandle과 연결된 연결 핸들에 대해 비동기적으로 실행되는 함수가 호출되었습니다. 이 비동기 함수는 SQLSetCursorName 함수가 호출되었을 때 계속 실행되었습니다. (DM) StatementHandle에 대해 비동기적으로 실행되는 함수가 호출되었고 이 함수가 호출되었을 때에도 여전히 실행 중입니다. (DM) SQLExecute, SQLExecDirect, SQLBulkOperations 또는 SQLSetPos가 StatementHandle에 대해 호출되고 SQL_NEED_DATA 반환되었습니다. 이 함수는 모든 실행 시 데이터 매개 변수 또는 열에 대한 데이터를 보내기 전에 호출되었습니다. |
| HY013 | 메모리 관리 오류 | 메모리 조건이 낮기 때문에 기본 메모리 개체에 액세스할 수 없기 때문에 함수 호출을 처리할 수 없습니다. |
| HY090 | 잘못된 문자열 또는 버퍼 길이 | (DM) NameLength 인수가 0보다 작지만 SQL_NTS 같지 않았습니다. |
| HY117 | 알 수 없는 트랜잭션 상태로 인해 연결이 일시 중단됩니다. 연결 끊기 및 읽기 전용 함수만 허용됩니다. | (DM) 일시 중단 상태에 대한 자세한 내용은 SQLEndTran 함수를 참조 하세요. |
| HYT01 | 연결 제한 시간이 만료됨 | 데이터 원본이 요청에 응답하기 전에 연결 제한 시간이 만료되었습니다. 연결 제한 시간은 SQL_ATTR_CONNECTION_TIMEOUT SQLSetConnectAttr를 통해 설정됩니다. |
| IM001 | 드라이버는 이 함수를 지원하지 않습니다. | (DM) StatementHandle과 연결된 드라이버는 함수를 지원하지 않습니다. |
설명
커서 이름은 위치가 지정된 업데이트 및 삭제 문(예: UPDATE 테이블 이름...WHERE CURRENT OF cursor-name). 자세한 내용은 위치 지정 업데이트 및 삭제 문을 참조 하세요. 애플리케이션에서 커서 이름을 정의하기 위해 SQLSetCursorName을 호출하지 않는 경우 쿼리 문을 실행할 때 드라이버는 SQL_CUR 문자로 시작하고 길이가 18자를 초과하지 않는 이름을 생성합니다.
연결 내의 모든 커서 이름은 고유해야 합니다. 커서 이름의 최대 길이는 드라이버에 의해 정의됩니다. 상호 운용성을 극대화하려면 애플리케이션에서 커서 이름을 18자 이하로 제한하는 것이 좋습니다. ODBC 3*.x*에서 커서 이름이 따옴표 붙은 식별자인 경우 대/소문자를 구분하는 방식으로 처리되며 SQL 구문에서 허용하지 않거나 공백 또는 예약된 키워드와 같이 특별히 처리할 문자를 포함할 수 있습니다. 커서 이름을 대/소문자를 구분하는 방식으로 처리해야 하는 경우 따옴표 붙은 식별자로 전달되어야 합니다.
명시적으로 또는 암시적으로 설정된 커서 이름은 SQLFreeHandle을 사용하여 연결된 문이 삭제될 때까지 설정됩니다. 커서가 할당되거나 준비된 상태인 한 SQLSetCursorName 을 호출하여 문의 커서 이름을 바꿀 수 있습니다.
코드 예
다음 예제에서 애플리케이션은 SQLSetCursorName을 사용하여 문의 커서 이름을 설정합니다. 그런 다음 해당 문을 사용하여 CUSTOMERS 테이블에서 결과를 검색합니다. 마지막으로, 위치 업데이트를 수행하여 John Smith의 전화 번호를 변경합니다. 애플리케이션은 SELECT 및 UPDATE 문에 대해 서로 다른 문 핸들을 사용합니다.
다른 코드 예제는 SQLSetPos를 참조 하세요.
#define NAME_LEN 50
#define PHONE_LEN 10
SQLHSTMT hstmtSelect,
SQLHSTMT hstmtUpdate;
SQLRETURN retcode;
SQLHDBC hdbc;
SQLCHAR szName[NAME_LEN], szPhone[PHONE_LEN];
SQLINTEGER cbName, cbPhone;
/* Allocate the statements and set the cursor name. */
SQLAllocHandle(SQL_HANDLE_STMT, hdbc, &hstmtSelect);
SQLAllocHandle(SQL_HANDLE_STMT, hdbc, &hstmtUpdate);
SQLSetCursorName(hstmtSelect, "C1", SQL_NTS);
/* SELECT the result set and bind its columns to local buffers. */
SQLExecDirect(hstmtSelect,
"SELECT NAME, PHONE FROM CUSTOMERS",
SQL_NTS);
SQLBindCol(hstmtSelect, 1, SQL_C_CHAR, szName, NAME_LEN, &cbName);
SQLBindCol(hstmtSelect, 2, SQL_C_CHAR, szPhone, PHONE_LEN, &cbPhone);
/* Read through the result set until the cursor is */
/* positioned on the row for John Smith. */
do
retcode = SQLFetch(hstmtSelect);
while ((retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO) &&
(strcmp(szName, "Smith, John") != 0));
/* Perform a positioned update of John Smith's name. */
if (retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO) {
SQLExecDirect(hstmtUpdate,
"UPDATE EMPLOYEE SET PHONE=\"2064890154\" WHERE CURRENT OF C1",
SQL_NTS);
}
관련 함수
| 추가 정보 | 참조 |
|---|---|
| SQL 문 실행 | SQLExecDirect 함수 |
| 준비된 SQL 문 실행 | SQLExecute 함수 |
| 커서 이름 반환 | SQLGetCursorName 함수 |
| 커서 스크롤 옵션 설정 | SQLSetScrollOptions 함수 |