ODBC 테이블 반환 매개 변수 사용

적용 대상: SQL Server Azure SQL Database Azure SQL Managed Instance Azure Synapse Analytics Analytics Platform System(PDW)

이 항목에서는 ODBC에서 테이블 반환 매개 변수를 사용하는 기본 사용자 시나리오를 설명합니다.

• 완전히 바인딩된 다중 행 버퍼가 있는 테이블 반환 매개 변수(메모리의 모든 값을 사용하여 TVP로 데이터 보내기)

• 행 스트리밍을 사용하는 테이블 반환 매개 변수(실행 시 데이터를 사용하여 TVP로 데이터 보내기)

• 시스템 카탈로그에서 테이블 반환 매개 변수 메타데이터 검색

• 준비된 문에 대한 테이블 반환 매개 변수 메타데이터 검색

완전히 바인딩된 다중 행 버퍼가 있는 테이블 반환 매개 변수(메모리의 모든 값을 사용하여 TVP로 데이터 보내기)

완전히 바인딩된 다중 행 버퍼와 함께 사용하면 모든 매개 변수 값을 메모리에서 사용할 수 있습니다. 예를 들어 테이블 반환 매개 변수를 단일 저장 프로시저로 패키징할 수 있는 OLTP 트랜잭션의 일반적인 경우입니다. 테이블 반환 매개 변수가 없으면 복잡한 다중 문 일괄 처리를 동적으로 생성하거나 서버에 여러 번 호출하는 작업이 포함됩니다.

테이블 반환 매개 변수 자체는 다른 매개 변수와 함께 SQLBindParameter를 사용하여 바인딩됩니다. 모든 매개 변수가 바인딩된 후 애플리케이션은 각 테이블 반환 매개 변수에 SQL_SOPT_SS_PARAM_FOCUS 매개 변수 포커스 특성을 설정하고 테이블 반환 매개 변수의 열에 대해 SQLBindParameter를 호출합니다.

테이블 반환 매개 변수의 서버 형식은 SQL_SS_TABLE 새 SQL Server 관련 형식입니다. 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_SCHEMA_NAME 설정해야 합니다. 테이블 형식 정의 및 테이블 반환 매개 변수는 동일한 데이터베이스에 있어야 하므로 애플리케이션에서 테이블 반환 매개 변수를 사용하는 경우 SQL_CA_SS_CATALOG_NAME 설정해서는 안 됩니다. 그렇지 않으면 SQLSetDescField에서 오류를 보고합니다.

이 시나리오에 대한 샘플 코드는 ODBC(테이블 반환 매개 변수) 사용 절차 demo_fixed_TVP_binding 입니다.

행 스트리밍을 사용하는 테이블 반환 매개 변수(실행 시 데이터를 사용하여 TVP로 데이터 보내기)

이 시나리오에서 애플리케이션은 드라이버가 요청하는 행을 드라이버에 제공하고 서버로 스트리밍됩니다. 따라서 모든 행을 메모리에 버퍼링할 필요가 없습니다. 이는 대량 삽입/업데이트 시나리오를 나타냅니다. 테이블 반환 매개 변수는 매개 변수 배열과 대량 복사 사이의 어딘가에 성능 지점을 제공합니다. 즉, 테이블 반환 매개 변수는 매개 변수 배열만큼 쉽게 프로그래밍할 수 있지만 서버에서 더 큰 유연성을 제공합니다.

테이블 반환 매개 변수와 해당 열은 이전 섹션에서 설명한 대로 바인딩됩니다. 완전 바인딩된 다중 행 버퍼가 있는 테이블 반환 매개 변수이지만 테이블 반환 매개 변수 자체의 길이 표시기는 SQL_DATA_AT_EXEC 설정됩니다. 드라이버는 실행 시 데이터 매개 변수, 즉 SQL_NEED_DATA 반환하는 일반적인 방법으로 SQLExecute 또는 SQLExecuteDirect에 응답합니다. 드라이버가 테이블 반환 매개 변수에 대한 데이터를 수락할 준비가 되면 SQLParamData는 SQLBindParameter에서 ParameterValuePtr 값을 반환합니다.

애플리케이션은 테이블 반환 매개 변수에 SQLPutData를 사용하여 테이블 반환 매개 변수 구성 열에 대한 데이터의 가용성을 나타냅니다. 테이블 반환 매개 변수 에 대해 SQLPutData를 호출하는 경우 DataPtr 은 항상 null이어야 하며 StrLen_or_Ind 테이블 반환 매개 변수 버퍼( SQLBindParameter의 ColumnSize 매개 변수)에 대해 지정된 배열 크기보다 작거나 같아야 합니다. 0은 테이블 반환 매개 변수에 대한 행이 더 이상 없어 드라이버가 다음 실제 프로시저 매개 변수를 처리하게 됨을 나타냅니다. StrLen_or_Ind 0이 아닌 경우 드라이버는 테이블 반환 매개 변수 바인딩되지 않은 매개 변수 바인딩된 매개 변수와 동일한 방식으로 테이블 반환 매개 변수 구성 열을 처리합니다. 각 테이블 반환 매개 변수 열은 실제 데이터 길이, SQL_NULL_DATA 지정하거나 길이/표시기 버퍼를 통해 실행 시 데이터를 지정할 수 있습니다. 테이블 반환 매개 변수 열 값은 문자 또는 이진 값이 조각으로 전달될 때 평소와 같이 SQLPutData에 대한 반복 호출을 통해 전달될 수 있습니다.

모든 테이블 반환 매개 변수 열이 처리되면 드라이버는 테이블 반환 매개 변수로 돌아와 테이블 반환 매개 변수 데이터의 추가 행을 처리합니다. 따라서 실행 시 데이터 테이블 반환 매개 변수의 경우 드라이버가 바인딩된 매개 변수를 순차적으로 검색하는 일반적인 방식을 따르지 않습니다. 바인딩된 테이블 반환 매개 변수는 SQLPutData가 0과 같은 StrLen_Or_IndPtr 호출될 때까지 폴링되며, 이때 드라이버는 테이블 반환 매개 변수 열을 건너뛰고 다음 실제 저장 프로시저 매개 변수로 이동합니다. SQLPutData가 1보다 크거나 같은 표시기 값을 전달하면 드라이버는 모든 바인딩된 행 및 열에 대한 값이 있을 때까지 테이블 반환 매개 변수 열과 행을 순차적으로 처리합니다. 그런 다음 드라이버는 테이블 반환 매개 변수로 돌아갑니다. SQLParamData에서 테이블 반환 매개 변수에 대한 토큰을 받고 테이블 반환 매개 변수에 대해 SQLPutData(hstmt, NULL, n)를 호출하는 동안 애플리케이션은 서버에 전달될 다음 행 또는 행에 대해 테이블 반환 매개 변수 구성 열 데이터 및 표시기 버퍼 콘텐츠를 설정해야 합니다.

이 시나리오에 대한 샘플 코드는 ODBC(테이블 반환 매개 변수 사용)의 루틴 demo_variable_TVP_binding 에 있습니다.

시스템 카탈로그에서 테이블 반환 매개 변수 메타데이터 검색

애플리케이션에서 테이블 반환 매개 변수 매개 변수가 있는 프로시저에 대해 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 스키마 컬렉션은 약간 다르며 이 변경에 포함되지 않습니다.)

애플리케이션은 SQLTable을 사용하여 영구 테이블, 시스템 테이블 및 뷰와 동일한 방식으로 테이블 형식의 이름을 결정합니다. 애플리케이션이 테이블 반환 매개 변수와 연결된 테이블 형식을 식별할 수 있도록 새로운 테이블 형식인 TABLE TYPE이 도입되었습니다. 테이블 형식과 일반 테이블은 서로 다른 네임스페이스를 사용합니다. 즉, 테이블 형식과 실제 테이블에 동일한 이름을 사용할 수 있습니다. 이를 처리하기 위해 SQL_SOPT_SS_NAME_SCOPE라는 새로운 문 특성이 도입되었습니다. 이 특성은 테이블 이름을 매개 변수로 사용하는 SQLTable 및 기타 카탈로그 함수가 테이블 이름을 실제 테이블의 이름 또는 테이블 형식의 이름으로 해석해야 하는지 여부를 지정합니다.

애플리케이션은 SQLColumns를 사용하여 영구 테이블에 대해 수행하는 것과 동일한 방식으로 테이블 형식의 열을 결정하지만, 먼저 실제 테이블이 아닌 테이블 형식으로 작업 중임을 나타내기 위해 SQL_SOPT_SS_NAME_SCOPE 설정해야 합니다. SQLPrimaryKeys는 SQL_SOPT_SS_NAME_SCOPE 사용하여 테이블 형식과 함께 다시 사용할 수도 있습니다.

이 시나리오에 대한 샘플 코드는 ODBC(테이블 반환 매개 변수 사용)의 루틴 demo_metadata_from_catalog_APIs 에 있습니다.

준비된 문에 대한 테이블 반환 매개 변수 메타데이터 검색

이 시나리오에서 애플리케이션은 SQLNumParameters 및 SQLDescribeParam을 사용하여 테이블 반환 매개 변수에 대한 메타데이터를 검색합니다.

테이블 반환 매개 변수의 형식 이름을 검색하는 데는 SQL_CA_SS_TYPE_NAME이라는 IPD 필드가 사용되고, SQL_CA_SS_SCHEMA_NAME 및 SQL_CA_SS_CATALOG_NAME IPD 필드는 각각 카탈로그와 스키마를 검색하는 데 사용됩니다.

테이블 형식 정의 및 테이블 반환 매개 변수는 동일한 데이터베이스에 있어야 합니다. SQLSetDescField는 테이블 반환 매개 변수를 사용할 때 애플리케이션이 SQL_CA_SS_CATALOG_NAME 설정하는 경우 오류를 보고합니다.

SQL_CA_SS_CATALOG_NAME 및 SQL_CA_SS_SCHEMA_NAME 사용하여 CLR 사용자 정의 형식 매개 변수와 연결된 카탈로그 및 스키마를 검색할 수도 있습니다. SQL_CA_SS_CATALOG_NAME 및 SQL_CA_SS_SCHEMA_NAME CLR UDT 형식에 대한 기존 형식 특정 카탈로그 스키마 특성의 대안입니다.

SQLDescribeParam은 테이블 반환 매개 변수 열의 열에 대한 메타데이터를 반환하지 않으므로 애플리케이션은 SQLColumns를 사용하여 이 시나리오에서 테이블 반환 매개 변수에 대한 열 메타데이터를 검색합니다.

이 사용 사례에 대한 샘플 코드는 ODBC(테이블 반환 매개 변수 사용)의 루틴 demo_metadata_from_prepared_statement 에 있습니다.

참고 항목

테이블 반환 매개 변수(ODBC)