다음을 통해 공유


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 문이 포함되어 있으며 지정된 테이블 이름 또는 뷰 이름이 없습니다.

*StatementTextALTER TABLE 문이 포함되어 있으며 지정된 테이블 이름이 없습니다.

*StatementText 에는 CREATE VIEW 문이 포함되어 있으며 쿼리 사양에 정의된 테이블 이름 또는 뷰 이름이 없습니다.

*StatementTextCREATE INDEX 문이 포함되어 있으며 지정된 테이블 이름이 없습니다.

*StatementTextGRANT 또는 REVOKE 문이 포함되어 있으며 지정된 테이블 이름 또는 뷰 이름이 없습니다.

*StatementTextSELECT 문이 포함되어 있고 지정된 테이블 이름 또는 뷰 이름이 없습니다.

*StatementText 에는 DELETE, INSERT 또는 UPDATE 문이 포함되어 있으며 지정된 테이블 이름이 없습니다.

*StatementText 에는 CREATE TABLE 문이 포함되어 있으며 제약 조건에 지정된 테이블(만들어지는 테이블이 아닌 다른 테이블 참조)이 없습니다.
42S11 인덱스가 이미 있음 *StatementText 에는 CREATE INDEX 문이 포함되어 있으며 지정된 인덱스 이름이 이미 있습니다.
42S12 인덱스 찾을 수 없음 *StatementTextDROP INDEX 문이 포함되어 있고 지정된 인덱스 이름이 없습니다.
42S21 열이 이미 있음 *StatementText에는 ALTER TABLE 문이 포함되어 있으며 ADD 절에 지정된 열이 고유하지 않거나 기본 테이블의 기존 열을 식별합니다.
42S22 열을 찾을 수 없음 *StatementText 에는 CREATE INDEX 문이 포함되어 있으며 열 목록에 지정된 열 이름 중 하나 이상이 없습니다.

*StatementTextGRANT 또는 REVOKE 문이 포함되어 있으며 지정된 열 이름이 없습니다.

*StatementTextSELECT, 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, SQLPutDataSQLSetPos를 참조하세요.

추가 정보 참조
문 핸들 할당 SQLAllocHandle 함수
결과 집합의 열에 버퍼 바인딩 SQLBindCol 함수
매개 변수에 버퍼 바인딩 SQLBindParameter 함수
문 처리 취소 SQLCancel 함수
커밋 또는 롤백 작업 실행 SQLEndTran 함수
SQL 문 실행 SQLExecDirect 함수
준비된 SQL 문 실행 SQLExecute 함수
문의 영향을 받는 행 수 반환 SQLRowCount 함수
커서 이름 설정 SQLSetCursorName 함수

참고 항목

ODBC API 참조
ODBC 헤더 파일