SQLPutData 함수
규칙
버전 소개: ODBC 1.0 표준 준수: ISO 92
요약
SQLPutData 를 사용하면 애플리케이션이 명령문 실행 시 매개 변수 또는 열에 대한 데이터를 드라이버에 보낼 수 있습니다. 이 함수는 문자, 이진 또는 데이터 원본별 데이터 형식(예: SQL_LONGVARBINARY 또는 SQL_LONGVARCHAR 형식의 매개 변수)이 있는 열에 부분의 문자 또는 이진 데이터 값을 보내는 데 사용할 수 있습니다. SQLPutData 는 기본 드라이버가 유니코드 데이터를 지원하지 않는 경우에도 유니코드 C 데이터 형식에 대한 바인딩을 지원합니다.
구문
SQLRETURN SQLPutData(
SQLHSTMT StatementHandle,
SQLPOINTER DataPtr,
SQLLEN StrLen_or_Ind);
인수
StatementHandle
[입력] 문 핸들입니다.
DataPtr
[입력] 매개 변수 또는 열의 실제 데이터를 포함하는 버퍼에 대한 포인터입니다. 데이터는 SQLBindParameter의 ValueType 인수(매개 변수 데이터의 경우) 또는 SQLBindCol의 TargetType 인수(열 데이터의 경우)에 지정된 C 데이터 형식이어야 합니다.
StrLen_or_Ind
[입력] *DataPtr의 길이입니다. SQLPutData 호출 에서 보낸 데이터의 양을 지정합니다. 데이터의 양은 지정된 매개 변수 또는 열에 대한 각 호출에 따라 달라질 수 있습니다. StrLen_or_Ind 다음 조건 중 하나를 충족하지 않는 한 무시됩니다.
StrLen_or_Ind SQL_NTS, SQL_NULL_DATA 또는 SQL_DEFAULT_PARAM.
SQLBindParameter 또는 SQLBindCol에 지정된 C 데이터 형식이 SQL_C_CHAR 또는 SQL_C_BINARY.
C 데이터 형식은 SQL_C_DEFAULT 지정한 SQL 데이터 형식의 기본 C 데이터 형식은 SQL_C_CHAR 또는 SQL_C_BINARY.
다른 모든 유형의 C 데이터의 경우 StrLen_or_Ind SQL_NULL_DATA 또는 SQL_DEFAULT_PARAM 않은 경우 드라이버는 *DataPtr 버퍼의 크기가 ValueType 또는 TargetType으로 지정된 C 데이터 형식의 크기라고 가정하고 전체 데이터 값을 보냅니다. 자세한 내용은 부록 D: 데이터 형식의 C에서 SQL 데이터 형식으로 데이터 변환을 참조하세요.
반품
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_STILL_EXECUTING, SQL_ERROR 또는 SQL_INVALID_HANDLE.
진단
SQLPutData가 SQL_ERROR 또는 SQL_SUCCESS_WITH_INFO 반환하는 경우 SQL_HANDLE_STMT HandleType 및 Handle of StatementHandle을 사용하여 SQLGetDiagRec 를 호출하여 관련 SQLSTATE 값을 가져올 수 있습니다. 다음 표에서는 SQLPutData에서 일반적으로 반환되는 SQLSTATE 값을 나열하고 이 함수의 컨텍스트에서 각 값을 설명합니다. 표기법 "(DM)"은 드라이버 관리자가 반환한 SQLSTATE에 대한 설명 앞에 나와 있습니다. 달리 명시되지 않는 한 각 SQLSTATE 값과 연결된 반환 코드는 SQL_ERROR.
| SQLSTATE | 오류 | 설명 |
|---|---|---|
| 01000 | 일반 경고 | 드라이버 관련 정보 메시지입니다. 함수는 SQL_SUCCESS_WITH_INFO 반환합니다. |
| 01004 | 문자열 데이터, 오른쪽 잘림 | 출력 매개 변수에 대해 반환된 문자열 또는 이진 데이터는 비블랭크 문자 또는 NULL이 아닌 이진 데이터의 잘림을 초래했습니다. 문자열 값인 경우 오른쪽에서 잘렸습니다. 함수는 SQL_SUCCESS_WITH_INFO 반환합니다. |
| 07006 | 제한된 데이터 형식 특성 위반 | 바인딩된 매개 변수에 대한 SQLBindParameter의 ValueType 인수로 식별된 데이터 값을 SQLBindParameter의 ParameterType 인수로 식별된 데이터 형식으로 변환할 수 없습니다. |
| 07S01 | 기본 매개 변수를 잘못 사용했습니다. | SQLBindParameter로 설정된 매개 변수 값이 SQL_DEFAULT_PARAM 해당 매개 변수에 기본값이 없습니다. |
| 08S01 | 통신 링크 실패 | 드라이버와 드라이버가 연결된 데이터 원본 간의 통신 링크는 함수가 처리를 완료하기 전에 실패했습니다. |
| 22001 | 문자열 데이터, 오른쪽 잘림 | 열에 문자 또는 이진 값을 할당하면 비블랭크(문자) 또는 null이 아닌(이진) 문자 또는 바이트가 잘리게 됩니다. SQLGetInfo의 SQL_NEED_LONG_DATA_LEN 정보 형식은 "Y"이고 SQLBindParameter의 StrLen_or_IndPtr 인수로 지정된 것보다 긴 매개 변수(데이터 형식이 SQL_LONGVARCHAR, SQL_LONGVARBINARY 또는 긴 데이터 원본별 데이터 형식임)에 대해 더 많은 데이터가 전송되었습니다. SQLGetInfo의 SQL_NEED_LONG_DATA_LEN 정보 유형은 "Y"이고, SQLBulkOperations로 추가되거나 업데이트되거나 SQLSetPos로 업데이트된 데이터 행의 열에 해당하는 길이 버퍼에 지정된 것보다 긴 열(데이터 형식이 SQL_LONGVARCHAR, SQL_LONGVARBINARY 또는 긴 데이터 원본별 데이터 형식)에 대해 더 많은 데이터를 보냈습니다. |
| 22003 | 숫자 값이 범위를 벗어났습니다. | 바인딩된 숫자 매개 변수 또는 열에 대해 전송된 데이터로 인해 연결된 테이블 열에 할당될 때 숫자의 전체 부분(소수 부분이 아닌)이 잘렸습니다. 하나 이상의 입력/출력 또는 출력 매개 변수에 대해 숫자 값(숫자 또는 문자열)을 반환하면 숫자의 전체 부분(소수 부분이 아닌)이 잘렸을 것입니다. |
| 22007 | 날짜/시간 형식이 잘못되었습니다. | 날짜, 시간 또는 타임스탬프 구조에 바인딩된 매개 변수 또는 열에 대해 전송된 데이터는 각각 잘못된 날짜, 시간 또는 타임스탬프였습니다. 입력/출력 또는 출력 매개 변수가 날짜, 시간 또는 타임스탬프 C 구조에 바인딩되었고 반환된 매개 변수의 값은 각각 잘못된 날짜, 시간 또는 타임스탬프였습니다. 함수는 SQL_SUCCESS_WITH_INFO 반환합니다. |
| 22008 | 날짜/시간 필드 오버플로 | 입력/출력 또는 출력 매개 변수에 대해 계산된 datetime 식으로 인해 날짜, 시간 또는 타임스탬프 C 구조가 잘못되었습니다. |
| 22012 | 0으로 나누기 | 입력/출력 또는 출력 매개 변수에 대해 계산된 산술 식으로 인해 나누기가 0으로 생성되었습니다. |
| 22015 | 간격 필드 오버플로 | SQL 데이터 형식의 정확한 숫자 또는 간격 열 또는 매개 변수에 대해 전송된 데이터로 인해 상당한 자릿수가 손실되었습니다. 둘 이상의 필드가 있는 간격 열 또는 매개 변수에 대해 데이터가 전송되었고, 숫자 데이터 형식으로 변환되었으며, 숫자 데이터 형식에 표현이 없었습니다. 열 또는 매개 변수 데이터에 대해 전송된 데이터는 간격 SQL 형식에 할당되었으며 간격 SQL 형식에서 C 형식의 값을 표현하지 않았습니다. 정확한 숫자 또는 간격 C 열 또는 매개 변수를 위해 C 형식 간격으로 전송된 데이터로 인해 상당한 자릿수가 손실되었습니다. 열 또는 매개 변수 데이터에 대해 전송된 데이터는 간격 C 구조에 할당되었으며 간격 데이터 구조에는 데이터의 표현이 없었습니다. |
| 22018 | 캐스트 사양에 잘못된 문자 값 | C 형식은 정확히 또는 근사치 숫자, 날짜/시간 또는 간격 데이터 형식입니다. 열의 SQL 형식은 문자 데이터 형식입니다. 열 또는 매개 변수의 값이 바인딩된 C 형식의 유효한 리터럴이 아니었습니다. SQL 형식은 정확히 또는 근사치 숫자, 날짜/시간 또는 간격 데이터 형식입니다. C 형식이 SQL_C_CHAR; 열 또는 매개 변수의 값이 바인딩된 SQL 형식의 유효한 리터럴이 아니었습니다. |
| HY000 | 일반 오류 | 특정 SQLSTATE가 없고 구현별 SQLSTATE가 정의되지 않은 오류가 발생했습니다. *MessageText 버퍼의 SQLGetDiagRec에서 반환된 오류 메시지는 오류와 그 원인을 설명합니다. |
| HY001 | 메모리 할당 오류 | 드라이버가 함수 실행 또는 완료를 지원하는 데 필요한 메모리를 할당할 수 없습니다. |
| HY008 | 작업이 취소됨 | StatementHandle에 대해 비동기 처리를 사용하도록 설정했습니다. 함수가 호출되었고 실행이 완료되기 전에 StatementHandle에서 SQLCancel 또는 SQLCancelHandle이 호출되었습니다. 그런 다음 StatementHandle에서 함수가 다시 호출되었습니다. 함수가 호출되었고 실행을 완료하기 전에 다중 스레드 애플리케이션의 다른 스레드에서 StatementHandle에서 SQLCancel 또는 SQLCancelHandle이 호출되었습니다. |
| HY009 | null 포인터를 잘못 사용했습니다. | (DM) DataPtr 인수가 null 포인터이고 인수 StrLen_or_Ind 0, SQL_DEFAULT_PARAM 또는 SQL_NULL_DATA 않았습니다. |
| HY010 | 함수 시퀀스 오류 | (DM) 이전 함수 호출은 SQLPutData 또는 SQLParamData에 대한 호출이 아니었습니다. (DM) StatementHandle과 연결된 연결 핸들에 대해 비동기적으로 실행되는 함수가 호출되었습니다. 이 비동기 함수는 SQLPutData 함수가 호출되었을 때 계속 실행되었습니다. (DM) SQLExecute, SQLExecDirect 또는 SQLMoreResults가 StatementHandle에 대해 호출되고 SQL_PARAM_DATA_AVAILABLE 반환되었습니다. 이 함수는 모든 스트리밍된 매개 변수에 대해 데이터를 검색하기 전에 호출되었습니다. (DM) 이 함수가 아닌 비동기 실행 함수가 StatementHandle에 대해 호출되었고 이 함수가 호출되었을 때 계속 실행되고 있었습니다. |
| HY013 | 메모리 관리 오류 | 메모리 조건이 낮기 때문에 기본 메모리 개체에 액세스할 수 없기 때문에 함수 호출을 처리할 수 없습니다. |
| HY019 | 문자가 아닌 데이터와 이진 데이터가 아닌 데이터로 전송됨 | SQLPutData 는 매개 변수 또는 열에 대해 두 번 이상 호출되었으며 문자, 이진 또는 데이터 원본별 데이터 형식이 있는 열에 문자 C 데이터를 보내거나 문자, 이진 또는 데이터 원본별 데이터 형식이 있는 열에 이진 C 데이터를 보내는 데 사용되지 않았습니다. |
| HY020 | null 값을 연결하려고 시도합니다. | SQLPutData 는 SQL_NEED_DATA 반환된 호출 이후 두 번 이상 호출되었으며, 이러한 호출 중 하나에서 StrLen_or_Ind 인수에는 SQL_NULL_DATA 또는 SQL_DEFAULT_PARAM 포함되어 있습니다. |
| HY090 | 잘못된 문자열 또는 버퍼 길이 | DataPtr 인수는 null 포인터가 아니며 인수 StrLen_or_Ind 0보다 작지만 SQL_NTS 또는 SQL_NULL_DATA 같지 않았습니다. |
| HY117 | 알 수 없는 트랜잭션 상태로 인해 연결이 일시 중단됩니다. 연결 끊기 및 읽기 전용 함수만 허용됩니다. | (DM) 일시 중단 상태에 대한 자세한 내용은 SQLEndTran 함수를 참조 하세요. |
| HYT01 | 연결 제한 시간이 만료됨 | 데이터 원본이 요청에 응답하기 전에 연결 제한 시간이 만료되었습니다. 연결 제한 시간은 SQL_ATTR_CONNECTION_TIMEOUT SQLSetConnectAttr를 통해 설정됩니다. |
| IM001 | 드라이버는 이 함수를 지원하지 않습니다. | (DM) StatementHandle과 연결된 드라이버는 함수를 지원하지 않습니다. |
| IM017 | 비동기 알림 모드에서 폴링을 사용할 수 없습니다. | 알림 모델을 사용할 때마다 폴링이 비활성화됩니다. |
| IM018 | 이 핸들에서 이전 비동기 작업을 완료하기 위해 SQLCompleteAsync 가 호출되지 않았습니다. | 핸들의 이전 함수 호출이 SQL_STILL_EXECUTING 반환하고 알림 모드가 활성화된 경우 사후 처리를 수행하고 작업을 완료하려면 핸들에서 SQLCompleteAsync 를 호출해야 합니다. |
SQL 문에서 매개 변수에 대한 데이터를 보내는 동안 SQLPutData가 호출되면 문을 실행하기 위해 호출된 함수에서 반환할 수 있는 모든 SQLSTATE(SQLExecute 또는 SQLExecDirect)를 반환할 수 있습니다. SQLBulkOperations를 사용하여 업데이트 또는 추가되거나 SQLSetPos로 업데이트되는 열에 대한 데이터를 보내는 동안 호출되는 경우 SQLBulkOperations 또는 SQLSetPos에서 반환할 수 있는 모든 SQLSTATE를 반환할 수 있습니다.
설명
SQLPutData는 SQLExecute 또는 SQLExecDirect 호출에 사용할 매개 변수 데이터 또는 SQLBulkOperations 호출에 의해 행이 업데이트되거나 추가되거나 SQLSetPos 호출에 의해 업데이트될 때 사용할 열 데이터라는 두 가지 용도로 실행 시 데이터 데이터를 제공하도록 호출할 수 있습니다.
애플리케이션이 SQLParamData를 호출하여 보낼 데이터를 결정할 때 드라이버는 애플리케이션이 보낼 매개 변수 데이터 또는 열 데이터를 찾을 수 있는 위치를 결정하는 데 사용할 수 있는 표시기를 반환합니다. 또한 데이터를 보내기 위해 SQLPutData를 호출해야 하는 애플리케이션에 대한 표시기인 SQL_NEED_DATA 반환합니다. SqlPutData에 대한 DataPtr 인수에서 애플리케이션은 매개 변수 또는 열에 대한 실제 데이터가 포함된 버퍼에 대한 포인터를 전달합니다.
드라이버가 SQLPutData에 대한 SQL_SUCCESS 반환하면 애플리케이션은 SQLParamData를 다시 호출합니다. SQLParamData는 더 많은 데이터를 보내야 하는 경우 SQL_NEED_DATA 반환하며, 이 경우 애플리케이션은 SQLPutData를 다시 호출합니다. 실행 중인 모든 데이터가 전송된 경우 SQL_SUCCESS 반환합니다. 그런 다음 애플리케이션은 SQLParamData를 다시 호출합니다. 드라이버가 *ValuePtrPtr에서 SQL_NEED_DATA 및 다른 표시기를 반환하는 경우 다른 매개 변수 또는 열 에 대한 데이터가 필요하며 SQLPutData 가 다시 호출됩니다. 드라이버가 SQL_SUCCESS 반환하는 경우 실행 시 모든 데이터가 전송되고 SQL 문을 실행하거나 SQLBulkOperations 또는 SQLSetPos 호출을 처리할 수 있습니다.
실행 시 데이터 매개 변수 데이터가 문 실행 시 전달되는 방법에 대한 자세한 내용은 SQLBindParameter 및 긴 데이터 보내기의 "매개 변수 값 전달"을 참조하세요. 실행 시 데이터 열 데이터가 업데이트되거나 추가되는 방법에 대한 자세한 내용은 SQLSetPos의 "SQLSetPos 사용" 섹션, SQLBulkOperations에서 "책갈피를 사용하여 대량 업데이트 수행" 및 Long Data 및 SQLSetPos 및 SQLBulkOperations 섹션을 참조하세요.
참고 항목
애플리케이션은 문자, 이진 또는 데이터 원본별 데이터 형식이 있는 열에 문자 C 데이터를 보내거나 문자, 이진 또는 데이터 원본별 데이터 형식이 있는 열에 이진 C 데이터를 보낼 때만 SQLPutData를 사용하여 데이터를 파트로 보낼 수 있습니다. SQLPutData가 다른 조건에서 두 번 이상 호출되면 SQL_ERROR 및 SQLSTATE HY019(문자가 아닌 데이터와 이진이 아닌 데이터가 하나씩 전송됨)를 반환합니다.
예시
다음 샘플에서는 Test라는 데이터 원본 이름을 가정합니다. 연결된 데이터베이스에는 다음과 같이 만들 수 있는 테이블이 있어야 합니다.
CREATE TABLE emp4 (NAME char(30), AGE int, BIRTHDAY datetime, Memo1 text)
// SQLPutData.cpp
// compile with: odbc32.lib user32.lib
#include <stdio.h>
#include <windows.h>
#include <sqlext.h>
#include <odbcss.h>
#define TEXTSIZE 12000
#define MAXBUFLEN 256
SQLHENV henv = SQL_NULL_HENV;
SQLHDBC hdbc1 = SQL_NULL_HDBC;
SQLHSTMT hstmt1 = SQL_NULL_HSTMT;
void Cleanup() {
if (hstmt1 != SQL_NULL_HSTMT)
SQLFreeHandle(SQL_HANDLE_STMT, hstmt1);
if (hdbc1 != SQL_NULL_HDBC) {
SQLDisconnect(hdbc1);
SQLFreeHandle(SQL_HANDLE_DBC, hdbc1);
}
if (henv != SQL_NULL_HENV)
SQLFreeHandle(SQL_HANDLE_ENV, henv);
}
int main() {
RETCODE retcode;
// SQLBindParameter variables.
SQLLEN cbTextSize, lbytes;
// SQLParamData variable.
PTR pParmID;
// SQLPutData variables.
UCHAR Data[] =
"abcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyz"
"abcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyz"
"abcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyz"
"abcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyz"
"abcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyz"
"abcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyz"
"abcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyz"
"abcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyz"
"abcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyz"
"abcdefghijklmnopqrstuvwxyz";
SDWORD cbBatch = (SDWORD)sizeof(Data) - 1;
// Allocate the ODBC environment and save handle.
retcode = SQLAllocHandle (SQL_HANDLE_ENV, NULL, &henv);
if ( (retcode != SQL_SUCCESS_WITH_INFO) && (retcode != SQL_SUCCESS)) {
printf("SQLAllocHandle(Env) Failed\n\n");
Cleanup();
return(9);
}
// Notify ODBC that this is an ODBC 3.0 app.
retcode = SQLSetEnvAttr(henv, SQL_ATTR_ODBC_VERSION, (SQLPOINTER) SQL_OV_ODBC3, SQL_IS_INTEGER);
if ( (retcode != SQL_SUCCESS_WITH_INFO) && (retcode != SQL_SUCCESS)) {
printf("SQLSetEnvAttr(ODBC version) Failed\n\n");
Cleanup();
return(9);
}
// Allocate ODBC connection handle and connect.
retcode = SQLAllocHandle(SQL_HANDLE_DBC, henv, &hdbc1);
if ( (retcode != SQL_SUCCESS_WITH_INFO) && (retcode != SQL_SUCCESS)) {
printf("SQLAllocHandle(hdbc1) Failed\n\n");
Cleanup();
return(9);
}
// Sample uses Integrated Security, create SQL Server DSN using Windows NT authentication.
retcode = SQLConnect(hdbc1, (UCHAR*)"Test", SQL_NTS, (UCHAR*)"",SQL_NTS, (UCHAR*)"", SQL_NTS);
if ( (retcode != SQL_SUCCESS) && (retcode != SQL_SUCCESS_WITH_INFO) ) {
printf("SQLConnect() Failed\n\n");
Cleanup();
return(9);
}
// Allocate statement handle.
retcode = SQLAllocHandle(SQL_HANDLE_STMT, hdbc1, &hstmt1);
if ( (retcode != SQL_SUCCESS) && (retcode != SQL_SUCCESS_WITH_INFO) ) {
printf("SQLAllocHandle(hstmt1) Failed\n\n");
Cleanup();
return(9);
}
// Set parameters based on total data to send.
lbytes = (SDWORD)TEXTSIZE;
cbTextSize = SQL_LEN_DATA_AT_EXEC(lbytes);
// Bind the parameter marker.
retcode = SQLBindParameter (hstmt1, // hstmt
1, // ipar
SQL_PARAM_INPUT, // fParamType
SQL_C_CHAR, // fCType
SQL_LONGVARCHAR, // FSqlType
lbytes, // cbColDef
0, // ibScale
(VOID *)1, // rgbValue
0, // cbValueMax
&cbTextSize); // pcbValue
if ( (retcode != SQL_SUCCESS) && (retcode != SQL_SUCCESS_WITH_INFO) ) {
printf("SQLBindParameter Failed\n\n");
Cleanup();
return(9);
}
// Execute the command.
retcode =
SQLExecDirect(hstmt1, (UCHAR*)"INSERT INTO emp4 VALUES('Paul Borm', 46,'1950-11-12 00:00:00', ?)", SQL_NTS);
if ( (retcode != SQL_SUCCESS) && (retcode != SQL_NEED_DATA) && (retcode != SQL_SUCCESS_WITH_INFO) ) {
printf("SQLExecDirect Failed\n\n");
Cleanup();
return(9);
}
// Check to see if NEED_DATA; if yes, use SQLPutData.
retcode = SQLParamData(hstmt1, &pParmID);
if (retcode == SQL_NEED_DATA) {
while (lbytes > cbBatch) {
SQLPutData(hstmt1, Data, cbBatch);
lbytes -= cbBatch;
}
// Put final batch.
retcode = SQLPutData(hstmt1, Data, lbytes);
}
if ( (retcode != SQL_SUCCESS) && (retcode != SQL_SUCCESS_WITH_INFO) ) {
printf("SQLParamData Failed\n\n");
Cleanup();
return(9);
}
// Make final SQLParamData call.
retcode = SQLParamData(hstmt1, &pParmID);
if ( (retcode != SQL_SUCCESS) && (retcode != SQL_SUCCESS_WITH_INFO) ) {
printf("Final SQLParamData Failed\n\n");
Cleanup();
return(9);
}
// Clean up.
SQLFreeHandle(SQL_HANDLE_STMT, hstmt1);
SQLDisconnect(hdbc1);
SQLFreeHandle(SQL_HANDLE_DBC, hdbc1);
SQLFreeHandle(SQL_HANDLE_ENV, henv);
}
관련 함수
| 추가 정보 | 참조 |
|---|---|
| 매개 변수에 버퍼 바인딩 | SQLBindParameter 함수 |
| 문 처리 취소 | SQLCancel 함수 |
| SQL 문 실행 | SQLExecDirect 함수 |
| 준비된 SQL 문 실행 | SQLExecute 함수 |
| 다음 매개 변수를 반환하여 에 대한 데이터를 보냅니다. | SQLParamData 함수 |