bcp_bind

아티클
01/10/2024

적용 대상: SQL Server Azure SQL 데이터베이스 Azure SQL Managed Instance Azure Synapse Analytics Analytics Platform System(PDW)

SQL Server로 대량 복사를 위해 프로그램 변수의 데이터를 테이블 열에 바인딩합니다.

구문

  
RETCODE bcp_bind (  
        HDBC hdbc,
        LPCBYTE pData,  
        INT cbIndicator,  
        DBINT cbData,  
        LPCBYTE pTerm,  
        INT cbTerm,  
        INT eDataType,  
        INT idxServerCol);

인수

hdbc
대량 복사 사용 ODBC 연결 핸들입니다.

pData
복사된 데이터에 대한 포인터입니다. eDataType이 SQLTEXT, SQLNTEXT, SQLXML, SQLUDT, SQLCHARACTER, SQLVARCHAR, SQLVARBINARY, SQLBINARY, SQLNCHAR 또는 SQLIMAGE인 경우 pData는 NULL일 수 있습니다. NULL pData는 긴 데이터 값이 bcp_moretext 사용하여 청크로 SQL Server로 전송됨을 나타냅니다. 사용자가 바인딩된 사용자 필드에 해당하는 열이 BLOB 열인 경우에만 pData를 NULL로 설정해야 합니다. 그렇지 않으면 bcp_bind 실패합니다.

데이터에 표시자가 있으면 이는 메모리에서 데이터 바로 앞에 표시됩니다. 이 경우 pData 매개 변수는 표시기 변수를 가리키며, cbIndicator 매개 변수인 표시기의 너비는 대량 복사를 통해 사용자 데이터를 올바르게 처리하는 데 사용됩니다.

cbIndicator
열 데이터에 대한 길이 또는 null 표시기의 길이(바이트)입니다. 올바른 표시기 길이 값은 0(표시기를 사용하지 않을 경우), 1, 2, 4 또는 8입니다. 표시기가 데이터 바로 앞에 메모리에 표시됩니다. 예를 들어 다음 구조체 형식 정의를 사용하여 대량 복사를 사용하여 SQL Server 테이블에 정수 값을 삽입할 수 있습니다.

typedef struct tagBCPBOUNDINT  
    {  
    int iIndicator;  
    int Value;  
    } BCPBOUNDINT;

예제의 경우 pData 매개 변수는 선언된 구조체 인스턴스의 주소, BCPBOUNDINT iIndicator 구조체 멤버의 주소로 설정됩니다. cbIndicator 매개 변수는 정수(sizeof(int))의 크기로 설정되고 cbData 매개 변수는 다시 정수(sizeof(int))의 크기로 설정됩니다. 바인딩된 열에 대한 NULL 값이 포함된 서버에 행을 대량 복사하려면 인스턴스의 iIndicator 멤버 값을 SQL_NULL_DATA 설정해야 합니다.

cbData
길이나 null 표시기 또는 종결자의 길이를 포함하지 않는 프로그램 변수의 데이터 바이트 수입니다.

cbData를 SQL_NULL_DATA 설정하면 서버에 복사된 모든 행에 열에 대한 NULL 값이 포함됩니다.

cbData를 SQL_VARLEN_DATA 설정하면 시스템에서 문자열 종결자 또는 다른 메서드를 사용하여 복사된 데이터의 길이를 결정합니다.

정수와 같은 고정 길이 데이터 형식의 경우 데이터 형식은 시스템에 대한 데이터의 길이를 나타냅니다. 따라서 고정 길이 데이터 형식 의 경우 cbData 를 안전하게 SQL_VARLEN_DATA 또는 데이터의 길이를 지정할 수 있습니다.

SQL Server 문자 및 이진 데이터 형식 의 경우 cbData 는 SQL_VARLEN_DATA, SQL_NULL_DATA, 일부 양수 값 또는 0일 수 있습니다. cbData가 SQL_VARLEN_DATA 경우 시스템은 길이/null 표시기(있는 경우) 또는 종결자 시퀀스를 사용하여 데이터의 길이를 확인합니다. 둘 다 제공된 경우 시스템은 복사되는 데이터의 양이 가장 적은 데이터를 사용합니다. cbData가 SQL_VARLEN_DATA 경우 열의 데이터 형식은 SQL Server 문자 또는 이진 형식이며 길이 표시기나 종결자 시퀀스를 지정하지 않으면 시스템에서 오류 메시지를 반환합니다.

cbData가 0이거나 양수이면 시스템에서 cbData를 데이터 길이로 사용합니다. 그러나 양수 cbData 값 외에도 길이 표시기 또는 종결자 시퀀스가 제공된 경우 시스템은 복사되는 데이터의 양이 가장 적은 메서드를 사용하여 데이터 길이를 결정합니다.

cbData 매개 변수 값은 데이터 바이트 수를 나타냅니다. 문자 데이터가 유니코드 와이드 문자로 표현되는 경우 양수 cbData 매개 변수 값은 각 문자의 크기(바이트)를 곱한 문자 수를 나타냅니다.

pTerm
이 프로그램 변수의 끝을 표시하는 바이트 패턴(있는 경우)에 대한 포인터입니다. 예를 들어 ANSI 및 MBCS C 문자열에는 일반적으로 1 바이트 종결자(\0)가 있습니다.

변수에 대한 종결자가 없는 경우 pTerm을 NULL로 설정합니다.

빈 문자열("")을 사용하여 C null 종결자를 프로그램 변수 종결자로 지정할 수 있습니다. null로 끝나는 빈 문자열은 단일 바이트(종결자 바이트 자체)를 구성하므로 cbTerm을 1로 설정합니다. 예를 들어 szName의 문자열이 null로 종료되고 종결자를 사용하여 길이를 나타내야 함을 나타냅니다.

bcp_bind(hdbc, szName, 0,  
   SQL_VARLEN_DATA, "", 1,  
   SQLCHARACTER, 2)

이 예제의 수정되지 않은 형식은 szName 변수에서 바인딩된 테이블의 두 번째 열로 15자를 복사함을 나타낼 수 있습니다.

bcp_bind(hdbc, szName, 0, 15,
   NULL, 0, SQLCHARACTER, 2)

대량 복사 API는 필요에 따라 유니코드-MBCS 문자 변환을 수행합니다. 종결자 바이트 문자열과 바이트 문자열의 길이가 모두 올바르게 설정되었는지 확인합니다. 예를 들어 szName의 문자열이 유니코드 와이드 문자열임을 나타내려면 유니코드 null 종결자 값으로 종료됩니다.

bcp_bind(hdbc, szName, 0,
   SQL_VARLEN_DATA, L"",  
   sizeof(WCHAR), SQLNCHAR, 2)

바인딩된 SQL Server 열이 와이드 문자인 경우 bcp_sendrow 변환이 수행되지 않습니다. SQL Server 열이 MBCS 문자 형식인 경우 데이터가 SQL Server로 전송될 때 와이드 문자에서 멀티바이트 문자 변환이 수행됩니다.

cbTerm
프로그램 변수의 종결자에 있는 바이트 수(있는 경우)입니다. 변수에 대한 종결자가 없으면 cbTerm을 0으로 설정합니다.

eDataType 은 프로그램 변수의 C 데이터 형식입니다. 프로그램 변수의 데이터는 데이터베이스 열의 형식으로 변환됩니다. 이 매개 변수가 0이면 변환이 수행되지 않습니다.

eDataType 매개 변수는 ODBC C 데이터 형식 열거자가 아닌 sqlncli.h의 SQL Server 데이터 형식 토큰에 의해 열거됩니다. 예를 들어 SQL Server 관련 형식 SQLINT2 사용하여 2바이트 정수 ODBC 형식 SQL_C_SHORT 지정할 수 있습니다.

SQL Server 2005(9.x)는 eDataType 매개 변수에서 SQLXML 및 SQLUDT 데이터 형식 토큰에 대한 지원을 도입했습니다.

다음 표에서는 유효한 열거형 데이터 형식 및 해당 ODBC C 데이터 형식을 나열합니다.

eDataType	C 형식
SQLTEXT	char *
SQLNTEXT	wchar_t *
SQLCHARACTER	char *
SQLBIGCHAR	char *
SQLVARCHAR	char *
SQLBIGVARCHAR	char *
SQLNCHAR	wchar_t *
SQLNVARCHAR	wchar_t *
SQLBINARY	unsigned char *
SQLBIGBINARY	unsigned char *
SQLVARBINARY	unsigned char *
SQLBIGVARBINARY	unsigned char *
SQLBIT	char
SQLBITN	char
SQLINT1	char
SQLINT2	short int
SQLINT4	int
SQLINT8	_int64
SQLINTN	cbIndicator 1: SQLINT1 2: SQLINT2 4: SQLINT4 8: SQLINT8
SQLFLT4	float
SQLFLT8	float
SQLFLTN	cbIndicator 4: SQLFLT4 8: SQLFLT8
SQLDECIMALN	SQL_NUMERIC_STRUCT
SQLNUMERICN	SQL_NUMERIC_STRUCT
SQLMONEY	DBMONEY
SQLMONEY4	DBMONEY4
SQLMONEYN	cbIndicator 4: SQLMONEY4 8: SQLMONEY
SQLTIMEN	SQL_SS_TIME2_STRUCT
SQLDATEN	SQL_DATE_STRUCT
SQLDATETIM4	DBDATETIM4
SQLDATETIME	DBDATETIME
SQLDATETIMN	cbIndicator 4: SQLDATETIM4 8: SQLDATETIME
SQLDATETIME2N	SQL_TIMESTAMP_STRUCT
SQLDATETIMEOFFSETN	SQL_SS_TIMESTAMPOFFSET_STRUCT
SQLIMAGE	unsigned char *
SQLUDT	unsigned char *
SQLUNIQUEID	SQLGUID
SQLVARIANT	다음을 제외한 모든 데이터 형식: - text - ntext - image - varchar(max) - varbinary(max) - nvarchar(max) - xml - timestamp
SQLXML	지원되는 C 데이터 형식: - char* - wchar_t * - 부호 없는 문자 *

idxServerCol 은 데이터가 복사되는 데이터베이스 테이블에 있는 열의 서수 위치입니다. 테이블의 첫 번째 열은 열 1입니다. 열의 서수 위치는 SQLColumns에서 보고됩니다.

반품

SUCCEED 또는 FAIL

설명

bcp_bind 사용하여 프로그램 변수에서 SQL Server의 테이블로 데이터를 빠르고 효율적으로 복사할 수 있습니다.

이 함수 또는 다른 대량 복사 함수를 호출하기 전에 bcp_init 호출합니다. bcp_init 호출하면 대량 복사를 위한 SQL Server 대상 테이블이 설정됩니다. bcp_bind 및 bcp_sendrow 사용하기 위해 bcp_init 호출하는 경우 데이터 파일을 나타내는 bcp_init szDataFile 매개 변수가 NULL로 설정되고 bcp_initeDirection 매개 변수가 DB_IN 설정됩니다.

복사하려는 SQL Server 테이블의 모든 열에 대해 별도의 bcp_bind 호출합니다. 필요한 bcp_bind 호출한 후 bcp_sendrow 호출하여 프로그램 변수에서 SQL Server로 데이터 행을 보냅니다. 열 다시 바인딩은 지원되지 않습니다.

SQL Server가 이미 수신한 행을 커밋하도록 할 때마다 bcp_batch 호출합니다. 예를 들어 삽입된 1000개 행마다 또는 다른 간격으로 bcp_batch 한 번 호출 합니다.

삽입할 행이 더 이상 없으면 bcp_done 호출합니다. 이렇게 하지 않으면 오류가 발생합니다.

bcp_control 지정된 컨트롤 매개 변수 설정은 bcp_bind 행 전송에 영향을 주지 않습니다.

열의 pData 값이 bcp_moretext 호출에 의해 제공되므로 열의 pData가 NULL로 설정된 경우 eDataType이 SQLTEXT, SQLNTEXT, SQLXML, SQLUDT, SQLCHARACTER, SQLVARCHAR, SQLVARBINARY, SQLBINARY, SQLBINARY, SQLNCHAR 또는 SQLIMAGE로 설정된 후속 열도 pData를 NULL로 설정하여 바인딩해야 하며 해당 값도 bcp_moretext 호출로 제공해야 합니다.

varchar(max), varbinary(max) 또는 nvarchar(max)와 같은 새로운 큰 값 형식의 경우 eDataType 매개 변수의 형식 표시자로 SQLCHARACTER, SQLVARCHAR, SQLVARCHAR, SQLVARBINARY, SQLBINARY 및 SQLNCHAR를 사용할 수 있습니다.

cbTerm이 0이 아니면 모든 값(1, 2, 4 또는 8)이 접두사(cbIndicator)에 유효합니다. 이 경우 SQL Server Native Client는 종결자를 검색하고, 종결자(i)와 관련하여 데이터 길이를 계산하고, cbData를 i의 더 작은 값과 접두사 값으로 설정합니다.

cbTerm이 0이고 cbIndicator(접두사)가 0이 아닌 경우 cbIndicator는 8이어야 합니다. 8 바이트 접두사는 다음 값을 사용할 수 있습니다.

0xFFFFFFFFFFFFFFFF 필드에 대한 null 값을 의미합니다.
0xFFFFFFFFFFFFFFFE 특수 접두사 값으로 처리되며, 이 값은 청크의 데이터를 서버로 효율적으로 보내는 데 사용됩니다. 이 특수 접두사를 가진 데이터 형식은 다음과 같습니다.
<><SPECIAL_PREFIX 0개 이상의 데이터 청크><ZERO_CHUNK> 위치:
SPECIAL_PREFIX는 0xFFFFFFFFFFFFFFFE입니다.
DATA_CHUNK 청크의 길이를 포함하는 4 바이트 접두사이며, 그 뒤에 길이가 4 바이트 접두사로 지정된 실제 데이터가 뒤따릅니다.
ZERO_CHUNK 데이터의 끝을 나타내는 모든 0(00000000)을 포함하는 4 바이트 값입니다.
다른 유효한 8 바이트 길이는 일반 데이터 길이로 처리됩니다.

bcp_bind 사용할 때 bcp_columns 호출하면 오류가 발생합니다.

향상된 날짜 및 시간 기능을 위한 bcp_bind 지원

날짜/시간 형식에 대한 eDataType 매개 변수와 함께 사용되는 형식에 대한 자세한 내용은 향상된 날짜 및 시간 형식에 대한 대량 복사 변경 내용(OLE DB 및 ODBC)을 참조하세요.

자세한 내용은 날짜 및 시간 개선 사항(ODBC)을 참조하세요.

예시

#include sql.h  
#include sqlext.h  
#include odbcss.h  
// Variables like henv not specified.  
HDBC      hdbc;  
char         szCompanyName[MAXNAME];  
DBINT      idCompany;  
DBINT      nRowsProcessed;  
DBBOOL      bMoreData;  
char*      pTerm = "\t\t";  
  
// Application initiation, get an ODBC environment handle, allocate the  
// hdbc, and so on.  
...
  
// Enable bulk copy prior to connecting on allocated hdbc.  
SQLSetConnectAttr(hdbc, SQL_COPT_SS_BCP, (SQLPOINTER) SQL_BCP_ON,  
   SQL_IS_INTEGER);  
  
// Connect to the data source; return on error.  
if (!SQL_SUCCEEDED(SQLConnect(hdbc, _T("myDSN"), SQL_NTS,  
   _T("myUser"), SQL_NTS, _T("myPwd"), SQL_NTS)))  
   {  
   // Raise error and return.  
   return;  
   }  
  
// Initialize bcp.
if (bcp_init(hdbc, "comdb..accounts_info", NULL, NULL  
   DB_IN) == FAIL)  
   {  
   // Raise error and return.  
   return;  
   }  
  
// Bind program variables to table columns.
if (bcp_bind(hdbc, (LPCBYTE) &idCompany, 0, sizeof(DBINT), NULL, 0,  
   SQLINT4, 1)    == FAIL)  
   {  
   // Raise error and return.  
   return;  
   }  
if (bcp_bind(hdbc, (LPCBYTE) szCompanyName, 0, SQL_VARLEN_DATA,  
   (LPCBYTE) pTerm, strnlen(pTerm, sizeof(pTerm)), SQLCHARACTER, 2) == FAIL)  
   {  
   // Raise error and return.  
   return;  
   }  
  
while (TRUE)  
   {  
   // Retrieve and process program data.
   if ((bMoreData = getdata(&idCompany, szCompanyName)) == TRUE)  
      {  
      // Send the data.
      if (bcp_sendrow(hdbc) == FAIL)  
         {  
         // Raise error and return.  
         return;  
         }  
      }  
   else  
      {  
      // Break out of loop.  
      break;  
      }  
   }  
  
// Terminate the bulk copy operation.  
if ((nRowsProcessed = bcp_done(hdbc)) == -1)  
   {  
   printf_s("Bulk-copy unsuccessful.\n");  
   return;  
   }  
  
printf_s("%ld rows copied.\n", nRowsProcessed);

참고 항목

대량 복사 함수

다음을 통해 공유

bcp_bind

구문

인수

반품

설명

향상된 날짜 및 시간 기능을 위한 bcp_bind 지원

예시

참고 항목

피드백

추가 리소스