테이블 반환 매개 변수 및 열 값에 대한 바인딩 및 데이터 전송
적용 대상:
SQL Server Azure SQL DatabaseAzure SQL Managed InstanceAzure Synapse Analytics AnalyticsPlatform System(PDW)
다른 매개 변수와 마찬가지로 TVP(테이블 반환 매개 변수)는 서버에 전달되기 전에 바인딩되어야 합니다. 애플리케이션은 SQLBindParameter 또는 SQLSetDescField 또는 SQLSetDescRec에 대한 동등한 호출을 사용하여 다른 매개 변수를 바인딩하는 것과 동일한 방식으로 테이블 반환 매개 변수를 바인딩합니다. 테이블 반환 매개 변수의 서버 데이터 형식은 SQL_SS_TABLE입니다. C 형식은 SQL_C_DEFAULT 또는 SQL_C_BINARY로 지정할 수 있습니다.
SQL Server 2008(10.0.x) 이상에서는 입력 테이블 반환 매개 변수만 지원됩니다. 따라서 SQL_DESC_PARAMETER_TYPE SQL_PARAM_INPUT 이외의 값으로 설정하려는 시도는 SQLSTATE = HY105 및 "잘못된 매개 변수 형식"이라는 메시지와 함께 SQL_ERROR 반환합니다.
SQL_CA_SS_COL_HAS_DEFAULT_VALUE 특성을 사용하여 전체 테이블 반환 매개 변수 열에 기본값을 할당할 수 있습니다. 그러나 SQLBindParameter 와 함께 StrLen_or_IndPtr SQL_DEFAULT_PARAM 사용하여 개별 테이블 반환 매개 변수 열 값을 기본값으로 할당할 수 없습니다. SQLBindParameter 와 함께 StrLen_or_IndPtr SQL_DEFAULT_PARAM 사용하여 테이블 반환 매개 변수를 전체적으로 기본값으로 설정할 수 없습니다. 이러한 규칙을 따르지 않으면 SQLExecute 또는 SQLExecDirect는 SQL_ERROR 반환합니다. 진단 레코드는 SQLSTATE=07S01 및 "매개 <변수 p>에 대한 기본 매개 변수의 잘못된 사용"을 사용하여 생성됩니다. 여기서 <p> 는 쿼리 문에서 TVP의 서수입니다.
참고
테이블 반환 매개 변수에는 설정할 수 있는 기본값이 없습니다. SQL_DEFAULT_PARAM 행을 나타내지 않기 때문입니다. 따라서 행이 없으면 바인딩할 열이 없습니다.
테이블 반환 매개 변수를 바인딩한 후에는 애플리케이션에서 각 테이블 반환 매개 변수 열을 바인딩해야 합니다. 이를 위해 애플리케이션은 먼저 SQLSetStmtAttr를 호출하여 SQL_SOPT_SS_PARAM_FOCUS 테이블 반환 매개 변수의 서수로 설정합니다. 애플리케이션은 SQLBindParameter, SQLSetDescRec 및 SQLSetDescField 루틴을 호출하여 테이블 반환 매개 변수의 열을 바인딩합니다. SQL_SOPT_SS_PARAM_FOCUS 0으로 설정하면 일반 최상위 매개 변수에서 작동하는 SQLBindParameter, SQLSetDescRec 및 SQLSetDescField의 일반적인 효과가 복원됩니다.
참고
unixODBC 2.3.1에서 2.3.4로 구성된 Linux 및 Mac ODBC 드라이버의 경우 SQL_CA_SS_TYPE_NAME 설명자 필드를 사용하여 SQLSetDescField를 통해 TVP 이름을 설정할 때 unixODBC는 (SQLSetDescFieldA / SQLSetDescFieldW)라는 정확한 함수에 따라 ANSI와 유니코드 문자열 간에 자동으로 변환되지 않습니다. 항상 유니코드(UTF-16) 문자열과 함께 SQLBindParameter 또는 SQLSetDescFieldW를 사용하여 TVP 이름을 설정해야 합니다.
테이블 반환 매개 변수 자체에 대해 실제로 보내거나 받는 데이터는 없지만 매개 변수의 각 구성 열에 대해서는 데이터를 보내고 받습니다. 테이블 반환 매개 변수는 의사 열이므로 SQLBindParameter의 매개 변수는 다음과 같이 다른 데이터 형식과 다른 특성을 참조합니다.
| 매개 변수 | 열을 포함하여 테이블 반환이 아닌 매개 변수 형식에 대한 관련 특성 | 테이블 반환 매개 변수에 대한 관련 특성 |
|---|---|---|
| InputOutputType | IPD의 SQL_DESC_PARAMETER_TYPE 테이블 반환 매개 변수 열의 경우 이 값은 테이블 반환 매개 변수 자체에 대한 설정과 같습니다. |
IPD의 SQL_DESC_PARAMETER_TYPE SQL_PARAM_INPUT이여야 합니다. |
| ValueType | APD의 SQL_DESC_TYPE, SQL_DESC_CONCISE_TYPE | APD의 SQL_DESC_TYPE, SQL_DESC_CONCISE_TYPE SQL_C_DEFAULT 또는 SQL_C_BINARY여야 합니다. |
| ParameterType | IPD의 SQL_DESC_TYPE, SQL_DESC_CONCISE_TYPE | IPD의 SQL_DESC_TYPE, SQL_DESC_CONCISE_TYPE SQL_SS_TABLE이여야 합니다. |
| ColumnSize | IPD의 SQL_DESC_LENGTH 또는 SQL_DESC_PRECISION 이는 ParameterType의 값에 따라 달라집니다. |
SQL_DESC_ARRAY_SIZE 매개 변수 포커스를 테이블 반환 매개 변수로 설정할 때 SQL_ATTR_PARAM_SET_SIZE를 사용하여 설정할 수도 있습니다. 테이블 반환 매개 변수의 경우 이 값은 테이블 반환 매개 변수 열 버퍼의 행 수입니다. |
| DecimalDigits | IPD의 SQL_DESC_PRECISION 또는 SQL_DESC_SCALE | 사용되지 않습니다. 0이어야 합니다. 이 매개 변수가 0이 아니면 SQLBindParameter는 SQL_ERROR 반환하고 진단 레코드는 SQLSTATE= HY104 및 "잘못된 정밀도 또는 배율"을 사용하여 생성됩니다. |
| ParameterValuePtr | APD의 SQL_DESC_DATA_PTR | SQL_CA_SS_TYPE_NAME 저장 프로시저 호출의 경우 선택 사항이며 필요하지 않은 경우 NULL을 지정할 수 있습니다. 프로시저 호출이 아닌 SQL 문에 대해 지정해야 합니다. 또한 이 매개 변수는 변수 행 바인딩을 사용할 때 애플리케이션에서 이 테이블 반환 매개 변수를 식별하는 데 사용할 수 있는 고유 값으로도 사용됩니다. 자세한 내용은 이 항목의 뒷부분에 나오는 "가변 테이블 반환 매개 변수 행 바인딩" 섹션을 참조하십시오. SQLBindParameter 호출 시 테이블 반환 매개 변수 형식 이름을 지정하는 경우 ANSI 애플리케이션으로 빌드된 애플리케이션에서도 유니코드 값으로 지정해야 합니다. 매개 변수 StrLen_or_IndPtr 사용되는 값은 SQL_NTS 또는 이름의 문자열 길이에 크기(WCHAR)를 곱해야 합니다. |
| BufferLength | APD의 SQL_DESC_OCTET_LENGTH | 테이블 반환 매개 변수 형식 이름의 길이(바이트)입니다. 형식 이름이 null로 끝나는 경우 SQL_NTS, 테이블 반환 매개 변수 형식 이름이 필요하지 않은 경우 0일 수 있습니다. |
| StrLen_or_IndPtr | APD의 SQL_DESC_OCTET_LENGTH_PTR | APD의 SQL_DESC_OCTET_LENGTH_PTR 테이블 반환 매개 변수의 경우 데이터 길이가 아닌 행 수입니다. |
테이블 반환 매개 변수에 대해서는 고정 행 바인딩과 가변 행 바인딩의 두 가지 데이터 전송 모드가 지원됩니다.
고정 테이블 반환 매개 변수 행 바인딩
고정 행 바인딩에서는 애플리케이션이 가능한 모든 입력 열 값을 수용할 수 있는 크기의 버퍼 또는 버퍼 배열을 할당합니다. 이 애플리케이션에서는 다음 작업을 수행합니다.
SQLBindParameter, SQLSetDescRec 또는 SQLSetDescField 호출을 사용하여 모든 매개 변수를 바인딩합니다.
- SQL_DESC_ARRAY_SIZE를 각 테이블 반환 매개 변수에 대해 전송될 수 있는 최대 행 수로 설정합니다. 이 작업은 SQLBindParameter 호출에서 수행할 수 있습니다.
SQLSetStmtAttr을 호출하여 SQL_SOPT_SS_PARAM_FOCUS 각 테이블 반환 매개 변수의 서수로 설정합니다.
각 테이블 반환 매개 변수에 대해 는 SQLBindParameter, SQLSetDescRec 또는 SQLSetDescField 호출을 사용하여 테이블 반환 매개 변수 열을 바인딩합니다.
기본값을 갖는 각 테이블 반환 매개 변수 열에 대해 SQLSetDescField를 호출하여 SQL_CA_SS_COL_HAS_DEFAULT_VALUE 1로 설정합니다.
SQLSetStmtAttr을 호출하여 SQL_SOPT_SS_PARAM_FOCUS 0으로 설정합니다. SQLExecute 또는 SQLExecDirect가 호출되기 전에 이 작업을 수행해야 합니다. 그렇지 않으면 SQL_ERROR 반환되고 SQLSTATE=HY024 및 "잘못된 특성 값, SQL_SOPT_SS_PARAM_FOCUS(실행 시 0이어야 함)" 메시지와 함께 진단 레코드가 생성됩니다.
StrLen_or_IndPtr 또는 SQL_DESC_OCTET_LENGTH_PTR 행이 없는 테이블 반환 매개 변수에 대해 SQL_DEFAULT_PARAM 설정하거나 테이블 반환 매개 변수에 행이 있는 경우 SQLExecute 또는 SQLExecDirect의 다음 호출에서 전송할 행 수를 설정합니다. 테이블 반환 매개 변수는 null을 허용하지 않으므로 테이블 반환 매개 변수에 대해 StrLen_or_IndPtr 또는 SQL_DESC_OCTET_LENGTH_PTR SQL_NULL_DATA 설정할 수 없습니다(테이블 반환 매개 변수 구성 열은 null 허용일 수 있음). 이 값이 잘못된 값으로 설정된 경우 SQLExecute 또는 SQLExecDirect는 SQL_ERROR 반환하고 진단 레코드는 SQLSTATE=HY090 및 "매개 변수 <p>에 대한 잘못된 문자열 또는 버퍼 길이"를 사용하여 생성됩니다. 여기서 p는 매개 변수 번호입니다.
SQLExecute 또는 SQLExecDirect를 호출합니다.
입력 테이블 반환 매개 변수 열 값은 StrLen_or_IndPtr 열에 대한 SQL_LEN_DATA_AT_EXEC (길이) 또는 SQL_DATA_AT_EXEC 설정된 경우 조각으로 전달될 수 있습니다. 이는 매개 변수 배열을 사용할 때 값을 개별적으로 전달하는 것과 유사합니다. 모든 실행 시 데이터 매개 변수와 마찬가지로 SQLParamData는 드라이버가 데이터를 요청하는 배열의 행을 나타내지 않습니다. 애플리케이션에서 이 작업을 처리해야 합니다. 애플리케이션은 드라이버가 값을 요청하는 순서를 가정할 수 없습니다.
가변 테이블 반환 매개 변수 행 바인딩
가변 행 바인딩의 경우 행은 실행 시 일괄 처리로 전송되고 애플리케이션은 요청 시 드라이버에 행을 전달합니다. 이는 개별 매개 변수 값의 실행 시 데이터와 유사합니다. 가변 행 바인딩에서 애플리케이션은 다음을 수행합니다.
이전 섹션인 "고정 Table-Valued 매개 변수 행 바인딩"의 1~3단계에 설명된 대로 매개 변수 및 테이블 반환 매개 변수 열을 바인딩합니다.
실행 시 SQL_DATA_AT_EXEC 전달될 테이블 반환 매개 변수에 대한 StrLen_or_IndPtr 또는 SQL_DESC_OCTET_LENGTH_PTR 설정합니다. 둘 다 설정되지 않은 경우 매개 변수는 이전 섹션에 설명된 대로 처리됩니다.
SQLExecute 또는 SQLExecDirect를 호출합니다. 실행 시 데이터 매개 변수로 처리할 SQL_PARAM_INPUT 또는 SQL_PARAM_INPUT_OUTPUT 매개 변수가 있는 경우 SQL_NEED_DATA 반환합니다. 이 경우 애플리케이션을 다음을 수행합니다.
- SQLParamData를 호출합니다. 그러면 실행 시 데이터 매개 변수에 대한 ParameterValuePtr 값과 SQL_NEED_DATA 반환 코드가 반환됩니다. 모든 매개 변수 데이터가 드라이버에 전달되면 SQLParamData는 SQL_SUCCESS, SQL_SUCCESS_WITH_INFO 또는 SQL_ERROR 반환합니다. 실행 시 데이터 매개 변수의 경우 설명자 필드 SQL_DESC_DATA_PTR 동일한 ParameterValuePtr은 값이 고유하게 필요한 매개 변수를 식별하는 토큰으로 간주될 수 있습니다. 이 "토큰"은 바인딩 시 애플리케이션에서 드라이버로 전달된 다음 실행 시 애플리케이션으로 다시 전달됩니다.
테이블 반환 매개 변수에 대해 테이블 반환 매개 변수 행 데이터를 보내려면 테이블 반환 매개 변수에 행이 없는 경우 애플리케이션은 SQL_DEFAULT_PARAM StrLen_or_Ind 설정된 SQLPutData를 호출합니다.
NULL이 아닌 TVP의 경우 애플리케이션은 다음을 수행합니다.
모든 테이블 반환 매개 변수 열의 Str_Len_or_Ind 적절한 값으로 설정하고, 실행 시 데이터 매개 변수가 될 수 없는 테이블 반환 매개 변수 열에 대한 데이터 버퍼를 채웁니다. 일반 매개 변수를 드라이버에 개별적으로 전달할 수 있는 방법과 유사하게 테이블 반환 매개 변수 열에 실행 시 데이터를 사용할 수 있습니다.
Str_Len_or_Ind 서버로 보낼 행 수로 설정된 SQLPutData를 호출합니다. 범위 0에서 SQL_DESC_ARRAY_SIZE 또는 SQL_DEFAULT_PARAM 범위를 벗어난 값은 오류이며 "잘못된 문자열 또는 버퍼 길이"라는 메시지와 함께 SQLSTATE HY090을 반환합니다. 0은 모든 행이 전송되었으며 테이블 반환 매개 변수에 대한 데이터가 더 이상 없음을 나타냅니다(이 목록의 두 번째 글머리 기호 항목에 언급된 대로). SQL_DEFAULT_PARAM은 이 목록의 첫 번째 글머리 항목에 설명된 대로 드라이버에서 테이블 반환 매개 변수의 데이터를 처음으로 요청할 때에만 사용할 수 있습니다.
모든 행이 전송되면 Str_Len_or_Ind 값이 0인 테이블 반환 매개 변수에 대해 SQLPutData를 호출한 다음 위의 3a단계로 진행합니다.
SQLParamData를 다시 호출합니다. 테이블 반환 매개 변수 열 중 실행 시 데이터 매개 변수가 있는 경우 SQLParamData에서 반환된 ValuePtrPtr 값으로 식별됩니다. 모든 열 값을 사용할 수 있는 경우 SQLParamData는 테이블 반환 매개 변수에 대한 ParameterValuePtr 값을 반환하고 애플리케이션이 다시 시작됩니다.
다음 단계
피드백
출시 예정: 2024년 내내 콘텐츠에 대한 피드백 메커니즘으로 GitHub 문제를 단계적으로 폐지하고 이를 새로운 피드백 시스템으로 바꿀 예정입니다. 자세한 내용은 다음을 참조하세요. https://aka.ms/ContentUserFeedback
다음에 대한 사용자 의견 제출 및 보기