다른 매개 변수와 마찬가지로 테이블 반환 매개 변수는 서버에 전달되기 전에 바인딩되어야 합니다. 애플리케이션은 SQLBindParameter 또는 SQLSetDescField 또는 SQLSetDescRec에 해당하는 호출을 사용하여 다른 매개 변수를 바인딩하는 것과 동일한 방식으로 테이블 반환 매개 변수를 바인딩합니다. 테이블 반환 매개 변수의 서버 데이터 형식은 SQL_SS_TABLE. C 형식은 SQL_C_DEFAULT 또는 SQL_C_BINARY 지정할 수 있습니다.
SQL Server 2008 이상에서는 입력 테이블 반환 매개 변수만 지원됩니다. 따라서 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의 서수입니다.
테이블 반환 매개 변수를 바인딩한 후 애플리케이션은 각 테이블 반환 매개 변수 열을 바인딩해야 합니다. 이를 위해 애플리케이션은 먼저 SQLSetStmtAttr을 호출하여 테이블 반환 매개 변수의 서수로 SQL_SOPT_SS_PARAM_FOCUS 설정합니다. 그런 다음, 애플리케이션은 SQLBindParameter, SQLSetDescRec 및 SQLSetDescField 루틴을 호출하여 테이블 반환 매개 변수의 열을 바인딩합니다. SQL_SOPT_SS_PARAM_FOCUS 0으로 설정하면 일반적인 최상위 매개 변수에서 작동하는 SQLBindParameter, SQLSetDescRec 및 SQLSetDescField의 일반적인 효과가 복원됩니다.
테이블 반환 매개 변수 자체에 대한 실제 데이터는 전송되거나 수신되지 않지만 각 구성 열에 대해 데이터가 전송되고 수신됩니다. 테이블 반환 매개 변수는 의사 열이므로 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 문에 대해 지정해야 합니다. 이 매개 변수는 변수 행 바인딩을 사용할 때 애플리케이션에서 테이블 반환 매개 변수를 식별하는 데 사용할 수 있는 고유한 값으로도 사용됩니다. 자세한 내용은 이 항목의 뒷부분에 있는 "변수 Table-Valued 매개 변수 행 바인딩" 섹션을 참조하세요. SQLBindParameter 호출 시 테이블 반환 매개 변수 형식 이름을 지정하는 경우 ANSI 애플리케이션으로 빌드된 애플리케이션에서도 유니코드 값으로 지정해야 합니다. 매개 변수 StrLen_or_IndPtr 사용되는 값은 SQL_NTS 또는 이름의 문자열 길이에 sizeof(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. 테이블 반환 매개 변수의 경우 데이터 길이가 아닌 행 수입니다. |
테이블 반환 매개 변수에는 고정 행 바인딩 및 변수 행 바인딩이라는 두 가지 데이터 전송 모드가 지원됩니다.
Table-Valued 매개 변수 행 바인딩 수정
고정 행 바인딩의 경우 애플리케이션은 가능한 모든 입력 열 값에 대해 충분히 큰 버퍼(또는 버퍼 배열)를 할당합니다. 애플리케이션은 다음을 수행합니다.
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는 드라이버가 데이터를 요청하는 배열의 행을 나타내지 않습니다. 애플리케이션이 이 작업을 처리해야 합니다. 애플리케이션은 드라이버가 값을 요청하는 순서에 대해 어떠한 가정도 할 수 없습니다.
변수 Table-Valued 매개 변수 행 바인딩
가변 행 바인딩의 경우 행은 실행 시 일괄 처리로 전송되고 애플리케이션은 요청 시 드라이버에 행을 전달합니다. 이는 개별 매개 변수 값에 대한 실행 시 데이터와 유사합니다. 변수 행 바인딩의 경우 애플리케이션은 다음을 수행합니다.
이전 섹션인 "고정 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은 값이 필요한 매개 변수를 고유하게 식별하는 토큰으로 간주될 수 있습니다. 이 "토큰"은 바인딩 시 애플리케이션에서 드라이버로 전달된 다음 실행 시 애플리케이션에 다시 전달됩니다.
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 값을 다시 반환하고 애플리케이션이 다시 시작됩니다.