SQLPrepare 함수
규칙
버전 소개: ODBC 1.0 표준 준수: ISO 92
요약
SQLPrepare 은 실행을 위해 SQL 문자열을 준비합니다.
구문
SQLRETURN SQLPrepare(
SQLHSTMT StatementHandle,
SQLCHAR * StatementText,
SQLINTEGER TextLength);
인수
StatementHandle
[입력] 문 핸들입니다.
StatementText
[입력] SQL 텍스트 문자열입니다.
TextLength
[입력] *StatementText 문자의 길이입니다.
반품
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_STILL_EXECUTING, SQL_ERROR 또는 SQL_INVALID_HANDLE.
진단
SQLPrepare이 SQL_ERROR 또는 SQL_SUCCESS_WITH_INFO 반환하는 경우 SQL_HANDLE_STMT HandleType 및 Handle of StatementHandle을 사용하여 SQLGetDiagRec 를 호출하여 관련 SQLSTATE 값을 가져올 수 있습니다. 다음 표에서는 SQLPrepare에서 일반적으로 반환되는 SQLSTATE 값을 나열하고 이 함수의 컨텍스트에서 각 값을 설명합니다. "(DM)" 표기법은 드라이버 관리자가 반환한 SQLSTATE에 대한 설명 앞에 나와 있습니다. 달리 명시되지 않는 한 각 SQLSTATE 값과 연결된 반환 코드는 SQL_ERROR.
| SQLSTATE | 오류 | 설명 |
|---|---|---|
| 01000 | 일반 경고 | 드라이버 관련 정보 메시지입니다. 함수는 SQL_SUCCESS_WITH_INFO 반환합니다. |
| 01S02 | 옵션 값이 변경됨 | 구현 작업 조건으로 인해 지정된 문 특성이 잘못되었으므로 비슷한 값이 일시적으로 대체되었습니다. (SQLGetStmtAttr 을 호출하여 일시적으로 대체된 값이 무엇인지 확인할 수 있습니다.) 커서를 닫을 때까지는 StatementHandle 에 대한 대체 값이 유효합니다. 변경할 수 있는 문 특성은 다음과 같습니다. SQL_ATTR_CONCURRENCY SQL_ATTR_CURSOR_TYPE SQL_ATTR_KEYSET_SIZE SQL_ATTR_MAX_LENGTH SQL_ATTR_MAX_ROWS SQL_ATTR_QUERY_TIMEOUT SQL_ATTR_SIMULATE_CURSOR 함수는 SQL_SUCCESS_WITH_INFO 반환합니다. |
| 08S01 | 통신 링크 실패 | 드라이버와 드라이버가 연결된 데이터 원본 간의 통신 링크는 함수가 처리를 완료하기 전에 실패했습니다. |
| 21S01 | 값 삽입 목록이 열 목록과 일치하지 않음 | *StatementText 에는 INSERT 문이 포함되어 있으며 삽입할 값 수가 파생 테이블의 정도와 일치하지 않습니다. |
| 21S02 | 파생 테이블의 정도가 열 목록과 일치하지 않음 | *StatementText 에는 CREATE VIEW 문이 포함되어 있으며 지정된 이름 수는 쿼리 사양에 정의된 파생 테이블과 같지 않습니다. |
| 22018 | 캐스트 사양에 잘못된 문자 값 | *StatementText 에는 리터럴 또는 매개 변수가 포함된 SQL 문이 포함되어 있으며 이 값은 연결된 테이블 열의 데이터 형식과 호환되지 않습니다. |
| 22019 | 잘못된 이스케이프 문자 | StatementText 인수에는 WHERE 절에 ESCAPE가 있는 LIKE 조건자가 포함되어 있으며 ESCAPE 다음의 이스케이프 문자 길이가 1과 같지 않습니다. |
| 22025 | 잘못된 이스케이프 시퀀스 | StatementText 인수에는 WHERE 절에 "LIKE 패턴 값 ESCAPE 이스케이프 문자"가 포함되어 있으며 패턴 값의 이스케이프 문자 다음에 있는 문자는 "%" 또는 "_"이 아닙니다. |
| 24000 | 커서 상태가 잘못되었습니다. | (DM) StatementHandle에서 커서가 열려 있고 SQLFetch 또는 SQLFetchScroll이 호출되었습니다. StatementHandle에서 커서가 열려 있지만 SQLFetch 또는 SQLFetchScroll이 호출되지 않았습니다. |
| 34000 | 커서 이름이 잘못되었습니다. | *StatementText 에는 위치가 지정된 DELETE 또는 배치된 UPDATE가 포함되어 있으며 준비 중인 문에서 참조하는 커서가 열려 있지 않았습니다. |
| 3D000 | 카탈로그 이름이 잘못되었습니다. | StatementText에 지정된 카탈로그 이름이 잘못되었습니다. |
| 3F000 | 잘못된 스키마 이름 | StatementText에 지정된 스키마 이름이 잘못되었습니다. |
| 42000 | 구문 오류 또는 액세스 위반 | *StatementText 에는 준비할 수 없거나 구문 오류가 포함된 SQL 문이 포함되어 있습니다. *StatementText 에는 사용자에게 필요한 권한이 없는 문이 포함되어 있습니다. |
| 42S01 | 기본 테이블 또는 뷰가 이미 있음 | *StatementText 에는 CREATE TABLE 또는 CREATE VIEW 문이 포함되어 있으며 지정된 테이블 이름 또는 뷰 이름이 이미 있습니다. |
| 42S02 | 기본 테이블 또는 뷰를 찾을 수 없음 | *StatementText 에는 DROP TABLE 또는 DROP VIEW 문이 포함되어 있으며 지정된 테이블 이름 또는 뷰 이름이 없습니다. *StatementText 에 ALTER TABLE 문이 포함되어 있으며 지정된 테이블 이름이 없습니다. *StatementText 에는 CREATE VIEW 문이 포함되어 있으며 쿼리 사양에 정의된 테이블 이름 또는 뷰 이름이 없습니다. *StatementText 에 CREATE INDEX 문이 포함되어 있으며 지정된 테이블 이름이 없습니다. *StatementText 에 GRANT 또는 REVOKE 문이 포함되어 있으며 지정된 테이블 이름 또는 뷰 이름이 없습니다. *StatementText 에 SELECT 문이 포함되어 있고 지정된 테이블 이름 또는 뷰 이름이 없습니다. *StatementText 에는 DELETE, INSERT 또는 UPDATE 문이 포함되어 있으며 지정된 테이블 이름이 없습니다. *StatementText 에는 CREATE TABLE 문이 포함되어 있으며 제약 조건에 지정된 테이블(만들어지는 테이블이 아닌 다른 테이블 참조)이 없습니다. |
| 42S11 | 인덱스가 이미 있음 | *StatementText 에는 CREATE INDEX 문이 포함되어 있으며 지정된 인덱스 이름이 이미 있습니다. |
| 42S12 | 인덱스 찾을 수 없음 | *StatementText 에 DROP INDEX 문이 포함되어 있고 지정된 인덱스 이름이 없습니다. |
| 42S21 | 열이 이미 있음 | *StatementText에는 ALTER TABLE 문이 포함되어 있으며 ADD 절에 지정된 열이 고유하지 않거나 기본 테이블의 기존 열을 식별합니다. |
| 42S22 | 열을 찾을 수 없음 | *StatementText 에는 CREATE INDEX 문이 포함되어 있으며 열 목록에 지정된 열 이름 중 하나 이상이 없습니다. *StatementText 에 GRANT 또는 REVOKE 문이 포함되어 있으며 지정된 열 이름이 없습니다. *StatementText에 SELECT, DELETE, INSERT 또는 UPDATE 문이 포함되어 있으며 지정된 열 이름이 없습니다. *StatementText 에는 CREATE TABLE 문이 포함되어 있으며 제약 조건에 지정된 열(생성되는 테이블 이외의 테이블 참조)이 없습니다. |
| HY000 | 일반 오류 | 특정 SQLSTATE가 없고 구현별 SQLSTATE가 정의되지 않은 오류가 발생했습니다. *MessageText 버퍼의 SQLGetDiagRec에서 반환된 오류 메시지는 오류와 그 원인을 설명합니다. |
| HY001 | 메모리 할당 오류 | 드라이버가 함수 실행 또는 완료를 지원하는 데 필요한 메모리를 할당할 수 없습니다. |
| HY008 | 작업이 취소됨 | StatementHandle에 대해 비동기 처리를 사용하도록 설정했습니다. 함수가 호출되었고 실행이 완료되기 전에 StatementHandle에서 SQLCancel 또는 SQLCancelHandle이 호출된 후 StatementHandle에서 함수가 다시 호출되었습니다. 함수가 호출되었고 실행을 완료하기 전에 다중 스레드 애플리케이션의 다른 스레드에서 StatementHandle에서 SQLCancel 또는 SQLCancelHandle이 호출되었습니다. |
| HY009 | null 포인터를 잘못 사용했습니다. | (DM) StatementText 가 null 포인터였습니다. |
| HY010 | 함수 시퀀스 오류 | (DM) StatementHandle과 연결된 연결 핸들에 대해 비동기적으로 실행되는 함수가 호출되었습니다. 이 비동기 함수는 SQLPrepare 함수가 호출되었을 때 계속 실행되었습니다. (DM) SQLExecute, SQLExecDirect 또는 SQLMoreResults가 StatementHandle에 대해 호출되고 SQL_PARAM_DATA_AVAILABLE 반환되었습니다. 이 함수는 모든 스트리밍된 매개 변수에 대해 데이터를 검색하기 전에 호출되었습니다. (DM) 이 함수가 아닌 비동기 실행 함수가 StatementHandle에 대해 호출되었고 이 함수가 호출되었을 때 계속 실행되고 있었습니다. (DM) SQLExecute, SQLExecDirect, SQLBulkOperations 또는 SQLSetPos가 StatementHandle에 대해 호출되고 SQL_NEED_DATA 반환되었습니다. 이 함수는 모든 실행 시 데이터 매개 변수 또는 열에 대한 데이터를 보내기 전에 호출되었습니다. |
| HY013 | 메모리 관리 오류 | 메모리 조건이 낮기 때문에 기본 메모리 개체에 액세스할 수 없기 때문에 함수 호출을 처리할 수 없습니다. |
| HY090 | 잘못된 문자열 또는 버퍼 길이 | (DM) TextLength 인수가 0보다 작거나 같지만 SQL_NTS 같지 않았습니다. |
| HY117 | 알 수 없는 트랜잭션 상태로 인해 연결이 일시 중단됩니다. 연결 끊기 및 읽기 전용 함수만 허용됩니다. | (DM) 일시 중단 상태에 대한 자세한 내용은 SQLEndTran 함수를 참조 하세요. |
| HYC00 | 선택적 기능이 구현되지 않음 | 정의된 커서 형식에 대해 동시성 설정이 잘못되었습니다. SQL_ATTR_USE_BOOKMARKS 문 특성이 SQL_UB_VARIABLE 설정되었으며 SQL_ATTR_CURSOR_TYPE 문 특성은 드라이버가 책갈피를 지원하지 않는 커서 유형으로 설정되었습니다. |
| HYT00 | 시간 제한 만료됨 | 데이터 원본이 결과 집합을 반환하기 전에 시간 제한 기간이 만료되었습니다. 시간 제한 기간은 SQL_ATTR_QUERY_TIMEOUT SQLSetStmtAttr를 통해 설정됩니다. |
| HYT01 | 연결 제한 시간이 만료됨 | 데이터 원본이 요청에 응답하기 전에 연결 제한 시간이 만료되었습니다. 연결 제한 시간은 SQL_ATTR_CONNECTION_TIMEOUT SQLSetConnectAttr를 통해 설정됩니다. |
| IM001 | 드라이버는 이 함수를 지원하지 않습니다. | (DM) StatementHandle과 연결된 드라이버는 함수를 지원하지 않습니다. |
| IM017 | 비동기 알림 모드에서 폴링을 사용할 수 없습니다. | 알림 모델을 사용할 때마다 폴링이 비활성화됩니다. |
| IM018 | 이 핸들에서 이전 비동기 작업을 완료하기 위해 SQLCompleteAsync 가 호출되지 않았습니다. | 핸들의 이전 함수 호출이 SQL_STILL_EXECUTING 반환하고 알림 모드가 활성화된 경우 사후 처리를 수행하고 작업을 완료하려면 핸들에서 SQLCompleteAsync 를 호출해야 합니다. |
설명
애플리케이션은 SQLPrepare를 호출하여 준비를 위해 SQL 문을 데이터 원본에 보냅니다. 준비된 실행에 대한 자세한 내용은 준비된 실행을 참조하세요. 애플리케이션은 SQL 문에 하나 이상의 매개 변수 마커를 포함할 수 있습니다. 매개 변수 표식을 포함하기 위해 애플리케이션은 적절한 위치에 있는 SQL 문자열에 물음표(?)를 포함합니다. 매개 변수에 대한 자세한 내용은 문 매개 변수를 참조 하세요.
참고 항목
애플리케이션에서 SQLPrepare를 사용하여 COMMIT 또는 ROLLBACK 문을 준비하고 SQLExecute를 제출 하는 경우 DBMS 제품 간에 상호 운용할 수 없습니다. 트랜잭션을 커밋하거나 롤백하려면 SQLEndTran을 호출합니다.
드라이버는 데이터 원본에서 사용하는 SQL 형식을 사용하도록 문을 수정한 다음, 준비를 위해 데이터 원본에 제출할 수 있습니다. 특히 드라이버는 특정 기능에 대한 SQL 구문을 정의하는 데 사용되는 이스케이프 시퀀스를 수정합니다. (SQL 문 문법에 대한 설명은 다음을 참조하세요 .ODBC 및 부록 C: SQL 문법의 이스케이프 시퀀스입니다.) 드라이버의 경우 문 핸들은 포함된 SQL 코드의 문 식별자와 유사합니다. 데이터 원본이 문 식별자를 지원하는 경우 드라이버는 문 식별자 및 매개 변수 값을 데이터 원본에 보낼 수 있습니다.
문이 준비되면 애플리케이션은 문 핸들을 사용하여 이후 함수 호출에서 문을 참조합니다. 문 핸들과 연결된 준비된 문은 애플리케이션이 SQL_DROP 옵션을 사용하여 SQLFreeStmt를 호출하여 문을 해제하거나 SQLPrepare, SQLExecDirect 또는 카탈로그 함수 중 하나(SQLColumns, SQLTable 등)에 대한 호출에 문 핸들이 사용될 때까지 SQLExecute를 호출하여 다시 실행할 수 있습니다. 애플리케이션이 문을 준비하면 결과 집합의 형식에 대한 정보를 요청할 수 있습니다. 일부 구현의 경우 SQLPrepare 이후에 SQLDescribeCol 또는 SQLDescribeParam을 호출하는 것이 SQLExecute 또는 SQLExecDirect 이후에 함수를 호출하는 것만큼 효율적이지 않을 수 있습니다.
애플리케이션에서 SQLPrepare를 호출할 때 일부 드라이버는 구문 오류 또는 액세스 위반을 반환할 수 없습니다. 드라이버는 구문 오류 및 액세스 위반, 구문 오류만 처리하거나 구문 오류 또는 액세스 위반을 처리할 수 없습니다. 따라서 애플리케이션은 SQLNumResultCols, SQLDescribeCol, SQLColAttribute 및 SQLExecute와 같은 후속 관련 함수를 호출할 때 이러한 조건을 처리할 수 있어야 합니다.
드라이버 및 데이터 원본의 기능에 따라 문이 준비될 때(모든 매개 변수가 바인딩된 경우) 또는 실행될 때(모든 매개 변수가 바인딩되지 않은 경우) 매개 변수 정보(예: 데이터 형식)를 확인할 수 있습니다. 최대 상호 운용성을 위해 애플리케이션은 동일한 문에 새 SQL 문을 준비하기 전에 이전 SQL 문에 적용된 모든 매개 변수를 바인딩 해제해야 합니다. 이렇게 하면 이전 매개 변수 정보가 새 문에 적용되기 때문에 발생하는 오류를 방지할 수 있습니다.
Important
SQLEndTran을 명시적으로 호출하거나 자동 커밋 모드에서 작업하여 트랜잭션을 커밋하면 데이터 원본이 연결의 모든 문에 대한 액세스 계획을 삭제할 수 있습니다. 자세한 내용은 SQLGetInfo의 SQL_CURSOR_COMMIT_BEHAVIOR 및 SQL_CURSOR_ROLLBACK_BEHAVIOR 정보 유형과 커서 및 준비된 문에 대한 트랜잭션의 영향을 참조하세요.
코드 예
SQLBindParameter, SQLPutData 및 SQLSetPos를 참조하세요.
관련 함수
| 추가 정보 | 참조 |
|---|---|
| 문 핸들 할당 | SQLAllocHandle 함수 |
| 결과 집합의 열에 버퍼 바인딩 | SQLBindCol 함수 |
| 매개 변수에 버퍼 바인딩 | SQLBindParameter 함수 |
| 문 처리 취소 | SQLCancel 함수 |
| 커밋 또는 롤백 작업 실행 | SQLEndTran 함수 |
| SQL 문 실행 | SQLExecDirect 함수 |
| 준비된 SQL 문 실행 | SQLExecute 함수 |
| 문의 영향을 받는 행 수 반환 | SQLRowCount 함수 |
| 커서 이름 설정 | SQLSetCursorName 함수 |