bcp_bind

  • 아티클

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일 수 있습니다. pData가 NULL이면 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로 종결되는 빈 문자열은 1바이트(종결자 바이트 자체)이므로 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에서는 eDataType 매개 변수의 SQLXML 및 SQLUDT 데이터 형식 토큰에 대한 지원이 새롭게 도입되었습니다.

  • 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_init eDirection 매개 변수가 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 행 전송에 영향을 주지 않습니다.

bcp_moretext 호출을 통해 열 값을 제공하기 위해 특정 열의 pData를 NULL로 설정한 경우 eDataType이 SQLTEXT, SQLNTEXT, SQLXML, SQLUDT, SQLCHARACTER, SQLVARCHAR, SQLVARBINARY, SQLBINARY, SQLNCHAR 또는 SQLIMAGE로 설정된 이후의 모든 열도 NULL로 설정된 pData에 바인딩되며 해당하는 값 역시 bcp_moretext 호출을 통해 제공됩니다.

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

cbTerm이 0이 아니면 접두사(cbIndicator)에 대해 모든 값(1, 2, 4 또는 8)이 유효합니다. 이러한 경우 SQL Server Native Client는 종결자를 검색하고, 해당 종결자(i)에 따라 데이터 길이를 계산하며, i와 접두사 값 중 작은 값으로 cbData를 설정합니다.

cbTerm이 0이고 cbIndicator(접두사)가 0이 아닌 경우 cbIndicator는 8입니다. 8바이트 접두사는 다음과 같은 값을 가질 수 있습니다.

  • 0xFFFFFFFFFFFFFFFF는 필드의 Null 값을 의미합니다.

  • 0xFFFFFFFFFFFFFFFE는 청크의 데이터를 효과적으로 서버에 보내는 데 사용할 수 있는 특수한 접두사 값입니다. 이 특수한 접두사를 사용한 데이터의 형식은 다음과 같습니다.

  • <SPECIAL_PREFIX> <0 이상 DATA CHUNKS> <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);

참고 항목

참조

대량 복사 함수