테이블 반환 매개 변수 및 열 값에 대한 바인딩 및 데이터 전송
적용 대상: 
SQL Server Azure SQL 데이터베이스 Azure SQL Managed Instance Azure Synapse Analytics Analytics Platform 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 | SQL_DESC_TYPE, APD에서 SQL_DESC_CONCISE_TYPE. | SQL_DESC_TYPE, APD에서 SQL_DESC_CONCISE_TYPE. SQL_C_DEFAULT 또는 SQL_C_BINARY 합니다. |
| ParameterType | IPD에서 SQL_DESC_CONCISE_TYPE SQL_DESC_TYPE. | IPD에서 SQL_DESC_CONCISE_TYPE SQL_DESC_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이어야 함)" 메시지와 함께 진단 레코드가 생성됩니다.
행이 없는 테이블 반환 매개 변수에 대해 SQL_DEFAULT_PARAM StrLen_or_IndPtr 또는 SQL_DESC_OCTET_LENGTH_PTR 설정하거나 테이블 반환 매개 변수에 행이 있는 경우 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는 드라이버가 데이터를 요청하는 배열의 행을 나타내지 않습니다. 애플리케이션이 이 작업을 처리해야 합니다. 애플리케이션은 드라이버가 값을 요청하는 순서를 가정할 수 없습니다.
변수 테이블 반환 매개 변수 행 바인딩
가변 행 바인딩의 경우 행은 실행 시 일괄 처리로 전송되고 애플리케이션은 요청 시 드라이버에 행을 전달합니다. 이는 개별 매개 변수 값에 대한 실행 시 데이터와 유사합니다. 가변 행 바인딩에서 애플리케이션은 다음을 수행합니다.
이전 섹션인 "고정 테이블 반환 매개 변수 행 바인딩"의 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은 값이 고유하게 필요한 매개 변수를 식별하는 토큰으로 간주될 수 있습니다. 이 "토큰"은 바인딩 시 애플리케이션에서 드라이버로 전달된 다음 실행 시 애플리케이션에 다시 전달됩니다.
null 테이블 반환 매개 변수에 대한 테이블 반환 매개 변수 행 데이터를 보내려면 테이블 반환 매개 변수에 행이 없는 경우 애플리케이션은 StrLen_or_Ind SQL_DEFAULT_PARAM 설정된 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 값을 반환하고 애플리케이션이 다시 시작됩니다.