ODBC 테이블 반환 매개 변수 사용
이 항목에서는 ODBC에서 테이블 반환 매개 변수를 사용하는 기본 사용자 시나리오를 설명합니다.
완전히 바인딩된 여러 행 버퍼를 사용하는 테이블 반환 매개 변수(모든 값을 메모리에 로드하여 TVP로 데이터 전송)
행 스트리밍을 사용하는 테이블 반환 매개 변수(실행 시 데이터를 사용하여 TVP로 데이터 전송)
시스템 카탈로그에서 테이블 반환 매개 변수 메타데이터 검색
준비된 문에서 테이블 반환 매개 변수 메타데이터 검색
완전히 바인딩된 여러 행 버퍼를 사용하는 테이블 반환 매개 변수(모든 값을 메모리에 로드하여 TVP로 데이터 전송)
완전히 바인딩된 여러 행 버퍼와 함께 사용하는 경우 모든 매개 변수 값을 메모리에서 사용할 수 있습니다. 이는 테이블 반환 매개 변수를 단일 저장 프로시저로 패키지할 수 있는 OLTP 트랜잭션의 대표적인 예입니다. 테이블 반환 매개 변수가 없다면 복잡한 다중 문 일괄 처리를 동적으로 생성하거나 서버를 여러 번 호출해야 할 수 있습니다.
테이블 반환 매개 변수 자체는 SQLBindParameter와 다른 매개 변수를 함께 사용하여 바인딩합니다. 모든 매개 변수가 바인딩되면 응용 프로그램은 각 테이블 반환 매개 변수의 매개 변수 포커스 특성 SQL_SOPT_SS_PARAM_FOCUS를 설정하고 테이블 반환 매개 변수의 열에 대해 SQLBindParameter를 호출합니다.
테이블 반환 매개 변수의 서버 유형은 새로운 SQL Server 고유 형식인 SQL_SS_TABLE입니다. SQL_SS_TABLE의 바인딩 C 형식은 항상 SQL_C_DEFAULT여야 합니다. 테이블 반환 매개 변수 바인딩 매개 변수에 대해서는 데이터가 전송되지 않습니다. 이 매개 변수는 테이블 메타데이터를 전달하고, 테이블 반환 매개 변수 구성 열의 데이터 전달 방법을 제어하는 데 사용됩니다.
테이블 반환 매개 변수의 길이는 서버로 전송되는 행 수로 설정됩니다. 테이블 반환 매개 변수에 대한 SQLBindParameter의 ColumnSize 매개 변수는 전송할 수 있는 최대 행 수를 지정합니다. 이 값은 열 버퍼의 배열 크기에 해당합니다. ParameterValuePtr은 SQLBindParameter의 테이블 반환 매개 변수에 사용되는 매개 변수 버퍼입니다. ParameterValuePtr과 여기에 연결된 BufferLength는 필요할 때 테이블 반환 매개 변수의 형식 이름을 전달하는 데 사용됩니다. 형식 이름은 저장 프로시저 호출에는 필요하지 않지만 SQL 문에는 필요합니다.
SQLBindParameter 호출에서 테이블 반환 매개 변수 형식 이름을 지정한 경우 ANSI 응용 프로그램으로 빌드된 응용 프로그램에서도 항상 유니코드 값으로 지정해야 합니다. SQLSetDescField를 사용하여 테이블 반환 매개 변수 형식 이름을 지정하는 경우 응용 프로그램 빌드 방법에 맞는 리터럴을 사용할 수 있습니다. ODBC 드라이버 관리자에서 필요한 모든 유니코드 변환을 수행합니다.
테이블 반환 매개 변수와 테이블 반환 매개 변수 열의 메타데이터는 SQLGetDescRec, SQLSetDescRec, SQLGetDescField 및 SQLSetDescField를 사용하여 개별적 및 명시적으로 조작할 수 있습니다. 그러나 일반적으로 SQLBindParameter를 오버로드하면 더욱 편리하며 대부분의 경우 명시적 설명자 액세스가 필요하지 않습니다. 이 방법은 다른 데이터 형식의 SQLBindParameter 정의와도 일치합니다. 단, 테이블 반환 매개 변수의 경우 영향을 받는 설명자 필드가 약간 다릅니다.
응용 프로그램에서 동적 SQL에 테이블 반환 매개 변수가 사용되어 테이블 반환 매개 변수의 형식 이름을 반드시 제공해야 하는 경우도 있습니다. 이 경우 연결에 대한 현재 기본 스키마에 테이블 반환 매개 변수가 정의되어 있지 않으면 SQLSetDescField를 사용하여 SQL_CA_SS_TYPE_CATALOG_NAME 및 SQL_CA_SS_TYPE_SCHEMA_NAME을 설정해야 합니다. 테이블 형식 정의와 테이블 반환 매개 변수는 동일한 데이터베이스에 있어야 하므로 응용 프로그램에서 테이블 반환 매개 변수를 사용하는 경우 SQL_CA_SS_TYPE_CATALOG_NAME을 설정해서는 안 됩니다. 그렇지 않으면 SQLSetDescField에서 오류가 발생합니다.
이 시나리오의 예제 코드는 CodePlex에서 사용할 수 있는 예제 응용 프로그램의 demo_fixed_table-valued parameter_binding 프로시저에 나와 있습니다. 자세한 내용은 SQL Server 데이터베이스 엔진 예제를 참조하십시오.
행 스트리밍을 사용하는 테이블 반환 매개 변수(실행 시 데이터를 사용하여 TVP로 데이터 전송)
이 시나리오에서 응용 프로그램은 드라이버가 요청하면 행을 제공하며 제공된 행은 서버로 스트리밍됩니다. 따라서 모든 행을 메모리에 버퍼링할 필요가 없습니다. 이는 대량 삽입/업데이트 시나리오를 나타냅니다. 테이블 반환 매개 변수는 매개 변수 배열과 대량 복사의 중간 정도 수준에 해당하는 성능을 제공합니다. 즉, 테이블 반환 매개 변수는 매개 변수 배열만큼 프로그래밍하기 쉬우면서도 서버에서 더 뛰어난 융통성을 제공합니다.
테이블 반환 매개 변수와 해당 열은 완전히 바인딩된 여러 행 버퍼를 사용하는 테이블 반환 매개 변수 섹션에서 설명한 대로 바인딩되지만 테이블 반환 매개 변수 자체의 길이 표시기는 SQL_DATA_AT_EXEC로 설정됩니다. 드라이버는 실행 시 데이터 매개 변수에 사용되는 일반적인 방법, 즉 SQL_NEED_DATA를 반환하는 방법으로 SQLExecute 또는 SQLExecuteDirect에 응답합니다. 드라이버에서 테이블 반환 매개 변수의 데이터를 받을 준비가 되면 SQLParamData가 SQLBindParameter의 ParameterValuePtr 값을 반환합니다.
응용 프로그램에서는 테이블 반환 매개 변수에 대한 SQLPutData를 사용하여 테이블 반환 매개 변수 구성 열의 데이터 가용성을 나타냅니다. 테이블 반환 매개 변수에 대해 SQLPutData가 호출되면 DataPtr이 항상 Null이 되어야 하고 StrLen_or_Ind는 0 또는 테이블 반환 매개 변수 버퍼에 대해 지정된 배열 크기(SQLBindParameter의 ColumnSize 매개 변수)보다 작거나 같은 값으로 설정되어야 합니다. 0은 테이블 반환 매개 변수에 대한 행이 더 이상 없어 드라이버가 다음 실제 프로시저 매개 변수를 처리하게 됨을 나타냅니다. StrLen_or_Ind가 0이 아닌 경우 드라이버는 비테이블 반환 매개 변수 바인딩 매개 변수와 같은 방법으로 테이블 반환 매개 변수 구성 열을 처리합니다. 각 테이블 반환 매개 변수 열은 SQL_NULL_DATA에 자신의 실제 데이터 길이를 지정하거나 해당 길이/표시기 버퍼를 통해 실행 시 데이터를 지정할 수 있습니다. 테이블 반환 매개 변수 열 값은 문자 또는 이진 값을 개별적으로 전달해야 하는 경우와 마찬가지로 SQLPutData에 대한 반복적인 호출을 통해 전달할 수 있습니다.
테이블 반환 매개 변수 열이 모두 처리되면 드라이버가 다시 테이블 반환 매개 변수로 돌아와서 테이블 반환 매개 변수 데이터의 행을 추가로 처리하기 시작합니다. 따라서 실행 시 데이터 테이블 반환 매개 변수의 경우 드라이버가 바인딩된 매개 변수를 순차적으로 검색하는 일반적인 방식을 따르지 않습니다. 바인딩된 테이블 반환 매개 변수는 0으로 설정된 StrLen_Or_IndPtr로 SQLPutData가 호출될 때까지, 즉 드라이버가 테이블 반환 매개 변수 열을 건너뛰고 다음 실제 저장 프로시저 매개 변수로 이동할 때까지 폴링됩니다. SQLPutData가 1보다 크거나 같은 표시기 값을 전달하면 드라이버는 바인딩된 모든 행과 열의 값을 얻을 때까지 테이블 반환 매개 변수 열 및 행을 순서대로 처리합니다. 그런 다음 드라이버는 테이블 반환 매개 변수로 돌아갑니다. 응용 프로그램은 SQLParamData에서 테이블 반환 매개 변수의 토큰을 받고 테이블 반환 매개 변수의 **SQLPutData(hstmt, NULL, n)**를 호출하는 사이에 서버로 전달할 하나 이상의 다음 행에 대한 테이블 반환 매개 변수 구성 열 데이터와 표시기 버퍼 내용을 설정해야 합니다.
이 시나리오의 예제 코드는 CodePlex에서 사용할 수 있는 예제 응용 프로그램의 demo_variable_table-valued parameter_binding 루틴에 나와 있습니다. 자세한 내용은 SQL Server 데이터베이스 엔진 예제를 참조하십시오.
시스템 카탈로그에서 테이블 반환 매개 변수 메타데이터 검색
응용 프로그램이 테이블 반환 매개 변수가 있는 프로시저에 대해 SQLProcedureColumns를 호출하면 DATA_TYPE이 SQL_SS_TABLE로 반환됩니다. TYPE_NAME은 테이블 반환 매개 변수의 테이블 형식 이름입니다. SQLProcedureColumns에서 반환된 결과 집합에는 열이 두 개 추가됩니다. 그 중 SS_TYPE_CATALOG_NAME은 테이블 반환 매개 변수의 테이블 형식이 정의되는 카탈로그의 이름을 반환하고 SS_TYPE_SCHEMA_NAME은 테이블 반환 매개 변수의 테이블 형식이 정의되는 스키마의 이름을 반환합니다. ODBC 사양에 따라 SS_TYPE_CATALOG_NAME 및 SS_TYPE_SCHEMA_NAME은 이전 버전의 SQL Server에 추가된 모든 드라이버 관련 열 앞에, 그리고 ODBC 자체에서 위임한 모든 열 뒤에 표시됩니다.
새 열은 테이블 반환 매개 변수뿐만 아니라 CLR 사용자 정의 형식 매개 변수에 대해서도 채워집니다. UDT 매개 변수의 기존 스키마와 카탈로그 열도 채워지지만 스키마와 카탈로그 열이 필요한 데이터 형식에 공용 스키마 및 카탈로그 열을 사용함으로써 이후 응용 프로그램 개발 과정이 간단해집니다. XML 스키마 컬렉션은 다소 다르며 이 변경 사항이 적용되지 않습니다.
응용 프로그램에서는 영구 테이블, 시스템 테이블 및 뷰의 경우와 마찬가지로 SQLTables를 사용하여 테이블 형식의 이름을 확인합니다. 응용 프로그램에서 테이블 반환 매개 변수와 연결된 테이블 형식을 식별할 수 있도록 TABLE TYPE이라는 새로운 테이블 형식이 도입되었습니다. 테이블 형식과 일반 테이블은 서로 다른 네임스페이스를 사용합니다. 즉, 테이블 형식과 실제 테이블에 동일한 이름을 사용할 수 있습니다. 이를 처리하기 위해 SQL_SOPT_SS_NAME_SCOPE라는 새로운 문 특성이 도입되었습니다. 이 특성은 테이블 이름을 매개 변수로 사용하는 SQLTables 및 기타 카탈로그 함수에서 테이블 이름을 실제 테이블 이름으로 해석해야 하는지, 테이블 형식의 이름으로 해석해야 하는지를 지정합니다.
응용 프로그램에서는 영구 테이블의 경우와 마찬가지로 SQLColumns를 사용하여 테이블 형식의 열을 확인하지만 먼저 SQL_SOPT_SS_NAME_SCOPE를 설정하여 작업 대상이 실제 테이블이 아니라 테이블 형식임을 나타내야 합니다. 마찬가지로 SQL_SOPT_SS_NAME_SCOPE를 설정하여 SQLPrimaryKeys를 테이블 형식에 사용할 수도 있습니다.
이 시나리오의 예제 코드는 CodePlex에서 사용할 수 있는 예제 응용 프로그램의 demo_metadata_from_catalog_APIs 루틴에 나와 있습니다. 자세한 내용은 SQL Server 데이터베이스 엔진 예제를 참조하십시오.
준비된 문에서 테이블 반환 매개 변수 메타데이터 검색
이 시나리오에서는 응용 프로그램이 SQLNumParameters 및 SQLDescribeParam을 사용하여 테이블 반환 매개 변수의 메타데이터를 검색합니다.
테이블 반환 매개 변수의 형식 이름을 검색하는 데는 SQL_CA_SS_TYPE_NAME이라는 IPD 필드가 사용되고, 스키마와 카탈로그를 검색하는 데는 각각 SQL_CA_SS_TYPE_SCHEMA_NAME과 SQL_CA_SS_TYPE_CATALOG_NAME이라는 IPD 필드가 사용됩니다.
테이블 형식 정의와 테이블 반환 매개 변수는 동일한 데이터베이스에 있어야 합니다. 응용 프로그램에서 테이블 반환 매개 변수를 사용할 때 SQL_CA_SS_TYPE_CATALOG_NAME을 설정하면 SQLSetDescField에서 오류가 발생합니다.
SQL_CA_SS_TYPE_CATALOG_NAME 및 SQL_CA_SS_TYPE_SCHEMA_NAME을 함께 사용하여 CLR 사용자 정의 형식 매개 변수와 연결된 카탈로그와 스키마를 검색할 수도 있습니다. SQL_CA_SS_TYPE_CATALOG_NAME 및 SQL_CA_SS_TYPE_SCHEMA_NAME은 CLR UDT 형식에 대한 기존 형식 관련 카탈로그 스키마 특성을 대체합니다.
SQLDescribeParam은 테이블 반환 매개 변수 열의 열에 대한 메타데이터를 반환하지 않으므로 이 시나리오에서도 응용 프로그램은 SQLColumns를 사용하여 테이블 반환 매개 변수의 열 메타데이터를 검색합니다.
이 사례의 예제 코드는 CodePlex에서 사용할 수 있는 예제 응용 프로그램의 demo_metadata_from_prepared_statement 루틴에 나와 있습니다. 자세한 내용은 SQL Server 데이터베이스 엔진 예제를 참조하십시오.