SQLSetStmtAttr
적용 대상: 
SQL Server Azure SQL 데이터베이스 Azure SQL Managed Instance Azure Synapse Analytics Analytics Platform System(PDW)
SQL Server Native Client ODBC 드라이버는 혼합(키 집합/동적) 커서 모델을 지원하지 않습니다. 값 집합이 0과 같지 않으면 SQL_ATTR_KEYSET_SIZE 사용하여 키 집합 크기를 설정하려고 하면 실패합니다.
애플리케이션은 모든 문에서 SQL_ATTR_ROW_ARRAY_SIZE 설정하여 SQLFetch 또는 SQLFetchScroll 함수 호출에 반환된 행 수를 선언합니다. 서버 커서를 나타내는 문에서 드라이버는 SQL_ATTR_ROW_ARRAY_SIZE 사용하여 커서에서 페치 요청을 충족하기 위해 서버가 생성하는 행 블록의 크기를 결정합니다. 트랜잭션 격리 수준이 커밋된 트랜잭션의 반복 읽기를 보장하는 데 충분하다면 행 멤버 자격 및 정렬이 동적 커서의 블록 크기 내에서 고정됩니다. 커서는 이 값으로 표시된 블록 외부에서 완전히 동적입니다. 서버 커서 블록 크기는 완전히 동적이며 인출 처리 중 임의 시점에 변경될 수 있습니다.
SQLSetStmtAttr 및 테이블 반환 매개 변수
SQLSetStmtAttr은 테이블 반환 매개 변수 열에 대한 설명자 필드에 액세스하기 전에 APD(애플리케이션 매개 변수 설명자)에서 SQL_SOPT_SS_PARAM_FOCUS 설정하는 데 사용할 수 있습니다.
테이블 반환 매개 변수가 아닌 매개 변수의 서수로 SQL_SOPT_SS_PARAM_FOCUS 설정하려고 하면 SQLSetStmtAttr는 SQL_ERROR 반환하고 진단 레코드는 SQLSTATE = HY024 및 "잘못된 특성 값"으로 만들어집니다. SQL_SOPT_SS_PARAM_FOCUS는 SQL_ERROR가 반환될 때 변경되지 않습니다.
SQL_SOPT_SS_PARAM_FOCUS 0으로 설정해도 매개 변수에 대한 설명자 레코드에 대한 액세스가 복원됩니다.
SQLSetStmtAttr을 사용하여 SQL_SOPT_SS_NAME_SCOPE 설정할 수도 있습니다. 자세한 내용은 이 항목의 뒷부분에 있는 SQL_SOPT_SS_NAME_SCOPE 섹션을 참조하세요.
자세한 내용은 준비된 문에 대한 테이블 반환 매개 변수 메타데이터를 참조하세요.
테이블 반환 매개 변수에 대한 자세한 내용은 ODBC(테이블 반환 매개 변수)를 참조하세요.
스파스 열에 대한 SQLSetStmtAttr 지원
SQLSetStmtAttr을 사용하여 SQL_SOPT_SS_NAME_SCOPE 설정할 수 있습니다. 자세한 내용은 이 항목의 뒷부분에 있는 SQL_SOPT_SS_NAME_SCOPE 섹션을 참조하세요. 스파스 열에 대한 자세한 내용은 스파스 열 지원(ODBC)을 참조하세요.
문 특성
또한 SQL Server Native Client ODBC 드라이버는 다음과 같은 드라이버 관련 문 특성을 지원합니다.
SQL_SOPT_SS_CURSOR_OPTIONS
SQL_SOPT_SS_CURSOR 특성은 드라이버가 커서에서 드라이버별 성능 옵션을 사용할지 여부를 지정합니다. 이러한 옵션을 설정하면 SQLGetData 가 허용되지 않습니다. 기본 설정은 SQL_CO_OFF. ValuePtr 값은 SQLLEN 형식입니다.
| ValuePtr 값 | 설명 |
|---|---|
| SQL_CO_OFF | 기본값. 빠른 정방향 전용 읽기 전용 커서 및 자동 페치를 사용하지 않도록 설정하고, 정방향 전용 읽기 전용 커서에서 SQLGetData를 사용하도록 설정합니다. SQL_SOPT_SS_CURSOR_OPTIONS SQL_CO_OFF 설정하면 커서 형식이 변경되지 않습니다. 즉, 빠른 전달 전용 커서는 빠른 전달 전용 커서로 유지됩니다. 커서 유형을 변경하려면 이제 애플리케이션이 SQLSetStmtAttr/SQL_ATTR_CURSOR_TYPE 사용하여 다른 커서 형식을 설정해야 합니다. |
| SQL_CO_FFO | 빠른 정방향 전용 읽기 전용 커서를 사용하도록 설정하고, 정방향 전용 읽기 전용 커서에서 SQLGetData를 사용하지 않도록 설정합니다. |
| SQL_CO_AF | 모든 커서 형식에서 자동 페치 옵션을 사용하도록 설정합니다. 문 핸들 에 대해 이 옵션을 설정하면 SQLExecute 또는 SQLExecDirect 는 암시적 SQLFetchScroll (SQL_FIRST)을 생성합니다. 커서가 열리고 행의 첫 번째 일괄 처리가 서버에 대한 단일 왕복으로 반환됩니다. |
| SQL_CO_FFO_AF | 자동 인출 옵션을 사용하여 빠른 전달 전용 커서를 사용하도록 설정합니다. 이는 SQL_CO_AF 및 SQL_CO_FFO를 모두 지정한 것과 같습니다. |
이러한 옵션이 설정된 경우 서버는 마지막 행이 인출되면 자동으로 커서를 닫습니다. 애플리케이션은 여전히 SQLFreeStmt(SQL_CLOSE) 또는 SQLCloseCursor를 호출해야 하지만 드라이버는 서버에 닫기 알림을 보낼 필요가 없습니다.
선택 목록에 텍스트, ntext 또는 이미지 열이 포함된 경우 빠른 전달 전용 커서가 동적 커서로 변환되고 SQLGetData가 허용됩니다.
SQL_SOPT_SS_DEFER_PREPARE
SQL_SOPT_SS_DEFER_PREPARE 특성은 SQLExecute, SQLDescribeCol 또는 SQLDescribeParam이 실행될 때까지 문이 즉시 준비되는지 또는 지연되는지 여부를 결정합니다. SQL Server 7.0 이하에서는 이 속성이 무시됩니다(지연된 준비 없음). ValuePtr 값은 SQLLEN 형식입니다.
| ValuePtr 값 | 설명 |
|---|---|
| SQL_DP_ON | 기본값. SQLPrepare 함수를 호출한 후 SQLExecute가 호출되거나 메타 속성 작업(SQLDescribeCol 또는 SQLDescribeParam)이 실행될 때까지 문 준비가 지연됩니다. |
| SQL_DP_OFF | 이 문은 SQLPrepare이 실행되는 즉시 준비됩니다. |
SQL_SOPT_SS_REGIONALIZE
SQL_SOPT_SS_REGIONALIZE 특성은 문 수준에서 데이터 변환을 결정하는 데 사용됩니다. 이 특성은 날짜, 시간 및 통화 값을 문자 문자열로 변환할 때 드라이버가 클라이언트 로캘 설정을 적용하도록 합니다. SQL Server 네이티브 데이터 형식에서 문자열로만 변환됩니다.
ValuePtr 값은 SQLLEN 형식입니다.
| ValuePtr 값 | 설명 |
|---|---|
| SQL_RE_OFF | 기본값. 드라이버는 클라이언트 로캘 설정을 사용하여 날짜, 시간 및 통화 데이터를 문자 문자열 데이터로 변환하지 않습니다. |
| SQL_RE_ON | 드라이버는 날짜, 시간 및 통화 데이터를 문자 문자열 데이터로 변환할 때 클라이언트 로캘 설정을 사용합니다. |
지역 변환 설정은 통화, 숫자, 날짜 및 시간 데이터 형식에 적용됩니다. 변환 설정은 통화, 숫자, 날짜 또는 시간 값이 문자 문자열로 변환되는 경우에만 출력 변환에 적용됩니다.
참고 항목
문 옵션 SQL_SOPT_SS_REGIONALIZE가 사용되면 드라이버는 현재 사용자의 로캘 레지스트리 설정을 사용합니다. 애플리케이션에서 SetThreadLocale를 호출하는 경우 드라이버가 현재 스레드의 로캘을 적용하지 않습니다.
데이터 원본의 국가별 동작을 변경하면 애플리케이션에서 오류가 발생할 수 있습니다. 날짜 문자열을 구문 분석하고 날짜 문자열이 ODBC에 정의된 대로 표시될 것으로 예상하는 애플리케이션은 이 값을 변경하면 부정적인 영향을 받을 수 있습니다.
SQL_SOPT_SS_TEXTPTR_LOGGING
SQL_SOPT_SS_TEXTPTR_LOGGING 특성은 텍스트 또는 이미지 데이터를 포함하는 열에 대한 작업 로깅을 전환합니다. ValuePtr 값은 SQLLEN 형식입니다.
| ValuePtr 값 | 설명 |
|---|---|
| SQL_TL_OFF | 텍스트 및 이미지 데이터에 대해 수행되는 작업의 로깅을 사용하지 않도록 설정합니다. |
| SQL_TL_ON | 기본값. 텍스트 및 이미지 데이터에 대해 수행되는 작업의 로깅을 사용하도록 설정합니다. |
SQL_SOPT_SS_HIDDEN_COLUMNS
SQL_SOPT_SS_HIDDEN_COLUMNS 특성은 결과 집합에서 SQL Server SELECT FOR BROWSE 문에 숨겨진 열을 노출합니다. 드라이버는 기본적으로 이러한 열을 노출하지 않습니다. ValuePtr 값은 SQLLEN 형식입니다.
| ValuePtr 값 | 설명 |
|---|---|
| SQL_HC_OFF | 기본값. FOR BROWSE 열은 결과 집합에서 숨겨집니다. |
| SQL_HC_ON | FOR BROWSE 열을 노출합니다. |
SQL_SOPT_SS_QUERYNOTIFICATION_MSGTEXT
SQL_SOPT_SS_QUERYNOTIFICATION_MSGTEXT 특성은 쿼리 알림 요청에 대한 메시지 텍스트를 반환합니다.
SQL_SOPT_SS_QUERYNOTIFICATION_OPTIONS
SQL_SOPT_SS_QUERYNOTIFICATION_OPTIONS 특성은 쿼리 알림 요청에 사용되는 옵션을 지정합니다. 이러한 항목은 아래와 같이 구문이 있는 name=value 문자열에 지정됩니다. 애플리케이션은 서비스를 만들고 큐에서 알림을 읽어야 합니다.
쿼리 알림 옵션 문자열의 구문은 다음과 같습니다.
service=<service-name>[;(local database=<database>|broker instance=<broker instance>)]
예시:
service=mySSBService;local database=mydb
SQL_SOPT_SS_QUERYNOTIFICATION_TIMEOUT
SQL_SOPT_SS_QUERYNOTIFICATION_TIMEOUT 특성은 쿼리 알림이 활성 상태로 유지되는 시간(초)을 지정합니다. 기본값은 432000초(5일)입니다. ValuePtr 값은 SQLLEN 형식입니다.
SQL_SOPT_SS_PARAM_FOCUS
SQL_SOPT_SS_PARAM_FOCUS 특성은 후속 SQLBindParameter, SQLGetDescField, SQLSetDescField, SQLGetDescRec 및 SQLSetDescRec 호출에 대한 포커스를 지정합니다.
SQL_SOPT_SS_PARAM_FOCUS 형식은 SQLULEN입니다.
기본값은 0입니다. 즉, 이러한 호출은 SQL 문의 매개 변수 표식에 해당하는 주소 매개 변수를 호출합니다. 테이블 반환 매개 변수의 매개 변수 번호로 설정하면 이러한 호출이 해당 테이블 반환 매개 변수 열의 주소를 지정합니다. 테이블 반환 매개 변수의 매개 변수 번호가 아닌 값으로 설정하면 이러한 호출은 IM020 오류를 반환합니다. "매개 변수 포커스는 테이블 반환 매개 변수를 참조하지 않습니다.".
SQL_SOPT_SS_NAME_SCOPE
SQL_SOPT_SS_NAME_SCOPE 특성은 후속 카탈로그 함수 호출의 이름 범위를 지정합니다. SQLColumns에서 반환되는 결과 집합은 SQL_SOPT_SS_NAME_SCOPE 설정에 따라 달라집니다.
SQL_SOPT_SS_NAME_SCOPE 형식은 SQLULEN입니다.
| ValuePtr 값 | 설명 |
|---|---|
| SQL_SS_NAME_SCOPE_TABLE | 기본값. 테이블 반환 매개 변수를 사용하는 경우 실제 테이블에 대한 메타데이터가 반환되어야 임을 나타냅니다. 스파스 열 기능을 사용하는 경우 SQLColumns는 스파스 column_set 멤버가 아닌 열만 반환합니다. |
| SQL_SS_NAME_SCOPE_TABLE_TYPE | 애플리케이션이 실제 테이블이 아니라 테이블 형식의 메타데이터를 요구한다는 것을 나타냅니다. 카탈로그 함수가 테이블 형식의 메타데이터를 반환해야 합니다. 그런 다음, 애플리케이션은 테이블 반환 매개 변수의 TYPE_NAME TableName 매개 변수로 전달합니다. |
| SQL_SS_NAME_SCOPE_EXTENDED | 스파스 열 기능을 사용하는 경우 SQLColumns는 column_set 멤버 자격에 관계없이 모든 열을 반환합니다. |
| SQL_SS_NAME_SCOPE_SPARSE_COLUMN_SET | 스파스 열 기능을 사용하는 경우 SQLColumns는 스파스 column_set 멤버인 열만 반환합니다. |
| SQL_SS_NAME_SCOPE_DEFAULT | SQL_SS_NAME_SCOPE_TABLE 같습니다. |
SS_TYPE_CATALOG_NAME 및 SS_TYPE_SCHEMA_NAME 각각 CatalogName 및 SchemaName 매개 변수와 함께 테이블 반환 매개 변수의 카탈로그 및 스키마를 식별하는 데 사용됩니다. 애플리케이션에서 테이블 반환 매개 변수에 대한 메타데이터 검색을 마쳤으면 SQL_SOPT_SS_NAME_SCOPE 기본값인 SQL_SS_NAME_SCOPE_TABLE 다시 설정해야 합니다.
SQL_SOPT_SS_NAME_SCOPE가 SQL_SS_NAME_SCOPE_TABLE로 설정되면 연결된 서버에 대한 쿼리가 실패합니다. 서버 구성 요소가 포함된 카탈로그를 사용하여 SQLColumns 또는 SQLPrimaryKeys에 대한 호출이 실패합니다.
SQL_SOPT_SS_NAME_SCOPE 잘못된 값으로 설정하려고 하면 SQL_ERROR 반환되고 SQLSTATE HY024 및 "잘못된 특성 값" 메시지와 함께 진단 레코드가 생성됩니다.
카탈로그 함수가 다른 경우 SQLTable, SQLColumns 또는 SQLPrimaryKeys는 SQL_SOPT_SS_NAME_SCOPE SQL_SS_NAME_SCOPE_TABLE 이외의 값이 있을 때 호출되고 SQL_ERROR 반환됩니다. SQLSTATE HY010 및 "함수 시퀀스 오류입니다(SQL_SOPT_SS_NAME_SCOPE가 SQL_SS_NAME_SCOPE_TABLE로 설정되지 않았습니다)" 메시지가 표시되고 진단 레코드가 생성됩니다.