테이블 반환 매개 변수 및 열 값에 대한 바인딩 및 데이터 전송
테이블 반환 매개 변수는 다른 매개 변수처럼 서버에 전달되기 전에 바인딩되어야 합니다. 애플리케이션은 SQLBindParameter 또는 SQLSetDescField 또는 SQLSetDescRec에 해당하는 호출을 사용하여 다른 매개 변수를 바인딩하는 것과 동일한 방식으로 테이블 반환 매개 변수를 바인딩합니다. 테이블 반환 매개 변수의 서버 데이터 형식은 SQL_SS_TABLE입니다. C 형식은 SQL_C_DEFAULT 또는 SQL_C_BINARY로 지정할 수 있습니다.
SQL Server 2008 이상에서는 입력 테이블 반환 매개 변수만 지원됩니다. 따라서 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 | 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 또는 이름의 문자열 길이에 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 테이블 반환 매개 변수의 경우 데이터 길이가 아닌 행 수입니다. |
테이블 반환 매개 변수에 대해서는 고정 행 바인딩과 가변 행 바인딩의 두 가지 데이터 전송 모드가 지원됩니다.
고정 테이블 반환 매개 변수 행 바인딩
고정 행 바인딩에서는 애플리케이션이 가능한 모든 입력 열 값을 수용할 수 있는 크기의 버퍼 또는 버퍼 배열을 할당합니다. 이 애플리케이션에서는 다음 작업을 수행합니다.
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이어야 합니다"라는 메시지가 포함된 진단 레코드가 생성됩니다.
행이 없는 테이블 반환 매개 변수 또는 테이블 반환 매개 변수에 행이 있는 경우 SQLExecute 또는 SQLExecDirect의 다음 호출에서 전송할 행 수에 대해 SQL_DEFAULT_PARAM StrLen_or_IndPtr 또는 SQL_DESC_OCTET_LENGTH_PTR 설정합니다. 테이블 반환 매개 변수는 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은 값이 필요한 매개 변수를 고유하게 식별하는 토큰으로 간주될 수 있습니다. 이 "토큰"은 바인딩 시 애플리케이션에서 드라이버로 전달된 다음 실행 시 애플리케이션으로 다시 전달됩니다.
테이블 반환 매개 변수에 대해 테이블 반환 매개 변수 행 데이터를 보내려면 테이블 반환 매개 변수에 행이 없는 경우 애플리케이션은 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 값을 다시 반환하고 애플리케이션이 다시 시작됩니다.