Função SQLSetDescField
Conformidade
Versão introduzida: ODBC 3.0 Standards Compliance: ISO 92
Resumo
SQLSetDescField define o valor de um único campo de um registro de descritor.
Sintaxe
SQLRETURN SQLSetDescField(
SQLHDESC DescriptorHandle,
SQLSMALLINT RecNumber,
SQLSMALLINT FieldIdentifier,
SQLPOINTER ValuePtr,
SQLINTEGER BufferLength);
Argumentos
DescriptorHandle
[Entrada] Identificador de descritor.
RecNumber
[Entrada] Indica o registro do descritor que contém o campo que o aplicativo busca definir. Os registros do descritor são numerados de 0, com o número de registro 0 sendo o registro de indicador. O argumento RecNumber é ignorado para campos de cabeçalho.
FieldIdentifier
[Entrada] Indica o campo do descritor cujo valor deve ser definido. Para obter mais informações, consulte "Argumento FieldIdentifier " na seção "Comentários".
ValuePtr
[Entrada] Ponteiro para um buffer que contém as informações do descritor ou um valor inteiro. O tipo de dados depende do valor de FieldIdentifier. Se ValuePtr for um valor inteiro, ele poderá ser considerado como 8 bytes (SQLLEN), 4 bytes (SQLINTEGER) ou 2 bytes (SQLSMALLINT), dependendo do valor do argumento FieldIdentifier .
BufferLength
[Entrada] Se FieldIdentifier for um campo definido por ODBC e ValuePtr apontar para uma cadeia de caracteres ou um buffer binário, esse argumento deverá ter o comprimento de *ValuePtr. Para dados de cadeia de caracteres, esse argumento deve conter o número de bytes na cadeia de caracteres.
Se FieldIdentifier for um campo definido por ODBC e ValuePtr for um inteiro, BufferLength será ignorado.
Se FieldIdentifier for um campo definido pelo driver, o aplicativo indicará a natureza do campo para o Gerenciador de Driver definindo o argumento BufferLength . BufferLength pode ter os seguintes valores:
Se ValuePtr for um ponteiro para uma cadeia de caracteres, BufferLength será o comprimento da cadeia de caracteres ou SQL_NTS.
Se ValuePtr for um ponteiro para um buffer binário, o aplicativo colocará o resultado da macro SQL_LEN_BINARY_ATTR(length) em BufferLength. Isso coloca um valor negativo em BufferLength.
Se ValuePtr for um ponteiro para um valor diferente de uma cadeia de caracteres ou uma cadeia de caracteres binária, BufferLength deverá ter o valor SQL_IS_POINTER.
Se ValuePtr contiver um valor de comprimento fixo, BufferLength será SQL_IS_INTEGER, SQL_IS_UINTEGER, SQL_IS_SMALLINT ou SQL_IS_USMALLINT, conforme apropriado.
Retornos
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR ou SQL_INVALID_HANDLE.
Diagnósticos
Quando SQLSetDescField retorna SQL_ERROR ou SQL_SUCCESS_WITH_INFO, um valor SQLSTATE associado pode ser obtido chamando SQLGetDiagRec com um HandleType de SQL_HANDLE_DESC e um Identificador de DescriptorHandle. A tabela a seguir lista os valores SQLSTATE normalmente retornados por SQLSetDescField e explica cada um deles no contexto dessa função; a notação "(DM)" precede as descrições de SQLSTATEs retornadas pelo Gerenciador de Driver. O código de retorno associado a cada valor SQLSTATE é SQL_ERROR, a menos que indicado de outra forma.
| SQLSTATE | Erro | Descrição |
|---|---|---|
| 01000 | Aviso geral | Mensagem informativa específica do driver. (A função retorna SQL_SUCCESS_WITH_INFO.) |
| 01S02 | Valor da opção alterado | O driver não deu suporte ao valor especificado em *ValuePtr (se ValuePtr era um ponteiro) ou o valor em ValuePtr (se ValuePtr era um valor inteiro) ou *ValuePtr era inválido devido a condições de trabalho de implementação, portanto, o driver substituiu um valor semelhante. (A função retorna SQL_SUCCESS_WITH_INFO.) |
| 07009 | Índice de descritor inválido | O argumento FieldIdentifier era um campo de registro, o argumento RecNumber era 0 e o argumento DescriptorHandle se referia a um identificador IPD. O argumento RecNumber era menor que 0 e o argumento DescriptorHandle se referia a um ARD ou a um APD. O argumento RecNumber era maior que o número máximo de colunas ou parâmetros que a fonte de dados pode dar suporte e o argumento DescriptorHandle se referia a um APD ou ARD. (DM) O argumento FieldIdentifier foi SQL_DESC_COUNT e o argumento *ValuePtr foi menor que 0. O argumento RecNumber era igual a 0 e o argumento DescriptorHandle se referia a uma APD alocada implicitamente. (Esse erro não ocorre com um descritor de aplicativo alocado explicitamente, pois não se sabe se um descritor de aplicativo alocado explicitamente é um APD ou ARD até o tempo de execução.) |
| 08S01 | Falha no link de comunicação | O link de comunicação entre o driver e a fonte de dados à qual o driver foi conectado falhou antes da conclusão do processamento da função. |
| 22001 | Dados de cadeia de caracteres, truncados à direita | O argumento FieldIdentifier foi SQL_DESC_NAME e o argumento BufferLength era um valor maior que SQL_MAX_IDENTIFIER_LEN. |
| HY000 | Erro geral | Ocorreu um erro para o qual não havia nenhum SQLSTATE específico e para o qual nenhum SQLSTATE específico da implementação foi definido. A mensagem de erro retornada por SQLGetDiagRec no buffer *MessageText descreve o erro e sua causa. |
| HY001 | Erro de alocação de memória | O driver não pôde alocar a memória necessária para dar suporte à execução ou à conclusão da função. |
| HY010 | Erro de sequência de funções | (DM) O DescriptorHandle foi associado a um StatementHandle para o qual uma função de execução assíncrona (não esta) foi chamada e ainda estava em execução quando essa função foi chamada. (DM) SQLExecute, SQLExecDirect, SQLBulkOperations ou SQLSetPos foi chamado para o StatementHandle ao qual o DescriptorHandle foi associado e retornado SQL_NEED_DATA. Essa função foi chamada antes de os dados serem enviados para todos os parâmetros ou colunas de dados em execução. (DM) Uma função de execução assíncrona foi chamada para o identificador de conexão associado ao DescriptorHandle. Essa função assíncrona ainda estava em execução quando a função SQLSetDescField foi chamada. (DM) SQLExecute, SQLExecDirect ou SQLMoreResults foi chamado para um dos identificadores de instrução associados ao DescriptorHandle e retornados SQL_PARAM_DATA_AVAILABLE. Essa função foi chamada antes de os dados serem recuperados para todos os parâmetros transmitidos. |
| HY013 | Erro de gerenciamento de memória | A chamada de função não pôde ser processada porque os objetos de memória subjacentes não puderam ser acessados, possivelmente devido a condições de memória baixa. |
| HY016 | Não é possível modificar um descritor de linha de implementação | O argumento DescriptorHandle foi associado a um IRD e o argumento FieldIdentifier não foi SQL_DESC_ARRAY_STATUS_PTR ou SQL_DESC_ROWS_PROCESSED_PTR. |
| HY021 | Informações inconsistentes do descritor | Os campos SQL_DESC_TYPE e SQL_DESC_DATETIME_INTERVAL_CODE não formam um tipo SQL ODBC válido ou um tipo SQL específico do driver válido (para IPDs) ou um tipo C ODBC válido (para APDs ou ARDs). As informações do descritor verificadas durante uma verificação de consistência não eram consistentes. (Consulte "Verificação de consistência" em SQLSetDescRec.) |
| HY090 | Comprimento de buffer ou cadeia de caracteres inválida | (DM) *ValuePtr é uma cadeia de caracteres e BufferLength era menor que zero, mas não era igual a SQL_NTS. (DM) O driver era um driver ODBC 2*.x*, o descritor era um ARD, o argumento ColumnNumber foi definido como 0 e o valor especificado para o argumento BufferLength não era igual a 4. |
| HY091 | Identificador de campo de descritor inválido | O valor especificado para o argumento FieldIdentifier não era um campo definido por ODBC e não era um valor definido pela implementação. O argumento FieldIdentifier era inválido para o argumento DescriptorHandle . O argumento FieldIdentifier era um campo somente leitura definido por ODBC. |
| HY092 | Identificador de atributo/opção inválido | O valor em *ValuePtr não era válido para o argumento FieldIdentifier . O argumento FieldIdentifier foi SQL_DESC_UNNAMED e ValuePtr foi SQL_NAMED. |
| HY105 | Tipo de parâmetro inválido | (DM) O valor especificado para o campo SQL_DESC_PARAMETER_TYPE era inválido. (Para obter mais informações, consulte a seção "Argumento InputOutputType " em SQLBindParameter.) |
| HY117 | A conexão é suspensa devido ao estado de transação desconhecido. Somente funções de desconexão e somente leitura são permitidas. | (DM) Para obter mais informações sobre o estado suspenso, consulte Novidades no ODBC 3.8. |
| HYT01 | O tempo limite da conexão expirou | O período de tempo limite da conexão expirou antes da fonte de dados responder à solicitação. O período de tempo limite da conexão é definido por meio de SQLSetConnectAttr, SQL_ATTR_CONNECTION_TIMEOUT. |
| IM001 | O driver não dá suporte a essa função | (DM) O driver associado ao DescriptorHandle não dá suporte à função. |
Comentários
Um aplicativo pode chamar SQLSetDescField para definir qualquer campo de descritor um de cada vez. Uma chamada para SQLSetDescField define um único campo em um único descritor. Essa função pode ser chamada para definir qualquer campo em qualquer tipo de descritor, desde que o campo possa ser definido. (Consulte a tabela mais adiante nesta seção.)
Observação
Se uma chamada para SQLSetDescField falhar, o conteúdo do registro do descritor identificado pelo argumento RecNumber será indefinido.
Outras funções podem ser chamadas para definir vários campos de descritor com uma única chamada da função. A função SQLSetDescRec define uma variedade de campos que afetam o tipo de dados e o buffer associados a uma coluna ou parâmetro (os campos SQL_DESC_TYPE, SQL_DESC_DATETIME_INTERVAL_CODE, SQL_DESC_OCTET_LENGTH, SQL_DESC_PRECISION, SQL_DESC_SCALE, SQL_DESC_DATA_PTR, SQL_DESC_OCTET_LENGTH_PTR e SQL_DESC_INDICATOR_PTR). SQLBindCol ou SQLBindParameter podem ser usados para criar uma especificação completa para a associação de uma coluna ou parâmetro. Essas funções definem um grupo específico de campos de descritor com uma chamada de função.
SQLSetDescField pode ser chamado para alterar os buffers de associação adicionando um deslocamento aos ponteiros de associação (SQL_DESC_DATA_PTR, SQL_DESC_INDICATOR_PTR ou SQL_DESC_OCTET_LENGTH_PTR). Isso altera os buffers de associação sem chamar SQLBindCol ou SQLBindParameter, o que permite que um aplicativo altere SQL_DESC_DATA_PTR sem alterar outros campos, como SQL_DESC_DATA_TYPE.
Se um aplicativo chamar SQLSetDescField para definir qualquer campo diferente de SQL_DESC_COUNT ou os campos adiados SQL_DESC_DATA_PTR, SQL_DESC_OCTET_LENGTH_PTR ou SQL_DESC_INDICATOR_PTR, o registro ficará desvinculado.
Os campos de cabeçalho do descritor são definidos chamando SQLSetDescField com o FieldIdentifier apropriado. Muitos campos de cabeçalho também são atributos de instrução, portanto, eles também podem ser definidos por uma chamada para SQLSetStmtAttr. Isso permite que os aplicativos definam um campo de descritor sem primeiro obter um identificador de descritor. Quando SQLSetDescField é chamado para definir um campo de cabeçalho, o argumento RecNumber é ignorado.
Um RecNumber de 0 é usado para definir campos de indicador.
Observação
O atributo de instrução SQL_ATTR_USE_BOOKMARKS deve ser sempre definido antes de chamar SQLSetDescField para definir campos de indicador. Embora isso não seja obrigatório, é altamente recomendável.
Sequência de configuração de campos do descritor
Ao definir campos de descritor chamando SQLSetDescField, o aplicativo deve seguir uma sequência específica:
O aplicativo deve primeiro definir o campo SQL_DESC_TYPE, SQL_DESC_CONCISE_TYPE ou SQL_DESC_DATETIME_INTERVAL_CODE.
Depois que um desses campos for definido, o aplicativo poderá definir um atributo de um tipo de dados e o driver definirá campos de atributo de tipo de dados para os valores padrão apropriados para o tipo de dados. O padrão automático dos campos de atributo de tipo garante que o descritor esteja sempre pronto para uso depois que o aplicativo tiver especificado um tipo de dados. Se o aplicativo definir explicitamente um atributo de tipo de dados, ele substituirá o atributo padrão.
Depois que um dos campos listados na etapa 1 tiver sido definido e os atributos de tipo de dados tiverem sido definidos, o aplicativo poderá definir SQL_DESC_DATA_PTR. Isso solicita uma verificação de consistência dos campos do descritor. Se o aplicativo alterar o tipo de dados ou os atributos depois de definir o campo SQL_DESC_DATA_PTR, o driver definirá SQL_DESC_DATA_PTR como um ponteiro nulo, desvincando o registro. Isso força o aplicativo a concluir as etapas adequadas na sequência, antes que o registro do descritor seja utilizável.
Inicialização de campos de descritor
Quando um descritor é alocado, os campos no descritor podem ser inicializados para um valor padrão, ser inicializados sem um valor padrão ou ser indefinidos para o tipo de descritor. As tabelas a seguir indicam a inicialização de cada campo para cada tipo de descritor, com "D" indicando que o campo é inicializado com um padrão e "ND" indicando que o campo é inicializado sem um padrão. Se um número for mostrado, o valor padrão do campo será esse número. As tabelas também indicam se um campo é R/W (leitura/gravação) ou somente leitura (R).
Os campos de um IRD têm um valor padrão somente depois que a instrução tiver sido preparada ou executada e o IRD tiver sido preenchido, não quando o identificador de instrução ou descritor tiver sido alocado. Até que o IRD tenha sido preenchido, qualquer tentativa de obter acesso a um campo de um IRD retornará um erro.
Alguns campos de descritor são definidos para um ou mais, mas não todos, dos tipos de descritor (ARDs e IRDs e APDs e IPDs). Quando um campo é indefinido para um tipo de descritor, ele não é necessário para nenhuma das funções que usam esse descritor.
Os campos que podem ser acessados por SQLGetDescField não podem necessariamente ser definidos por SQLSetDescField. Os campos que podem ser definidos por SQLSetDescField são listados nas tabelas a seguir.
A inicialização de campos de cabeçalho é descrita na tabela a seguir.
| Nome do campo de cabeçalho | Type | R/W | Padrão |
|---|---|---|---|
| SQL_DESC_ALLOC_TYPE | SQLSMALLINT | ARD: R APD: R IRD: R IPD: R | ARD: SQL_DESC_ALLOC_AUTO para implícito ou SQL_DESC_ALLOC_USER para explícito APD: SQL_DESC_ALLOC_AUTO para implícito ou SQL_DESC_ALLOC_USER para explícito IRD: SQL_DESC_ALLOC_AUTO IPD: SQL_DESC_ALLOC_AUTO |
| SQL_DESC_ARRAY_SIZE | SQLULEN | ARD: R/W APD: R/W IRD: IPD não utilizado: não utilizado | ARD:[1] APD:[1] IRD: IPD não utilizado: não utilizado |
| SQL_DESC_ARRAY_STATUS_PTR | SQLUSMALLINT* | ARD: R/W APD: R/W IRD: R/W IPD: R/W | ARD: NUll ptr APD: Null ptr IRD: NUll ptr IPD: null ptr |
| SQL_DESC_BIND_OFFSET_PTR | SQLLEN* | ARD: R/W APD: R/W IRD: IPD não utilizado: não utilizado | ARD: APD de ptr nulo: Null ptr IRD: IPD não utilizado: não utilizado |
| SQL_DESC_BIND_TYPE | SQLINTEGER | ARD: R/W APD: R/W IRD: IPD não utilizado: não utilizado | ARD: SQL_BIND_BY_COLUMN APD: SQL_BIND_BY_COLUMN IRD: não utilizado IPD: não utilizado |
| SQL_DESC_COUNT | SQLSMALLINT | ARD: R/W APD: R/W IRD: R IPD: R/W | ARD: 0 APD: 0 IRD: D IPD: 0 |
| SQL_DESC_ROWS_PROCESSED_PTR | SQLULEN* | ARD: APD não utilizado: IRD não utilizado: IPD R/W: R/W | ARD: APD não utilizado: IRD não utilizado: IPD ptr nulo: ptr nulo |
[1] Esses campos são definidos somente quando o IPD é preenchido automaticamente pelo driver. Caso contrário, eles são indefinidos. Se um aplicativo tentar definir esses campos, SQLSTATE HY091 (identificador de campo de descritor inválido) será retornado.
A inicialização dos campos de registro é conforme mostrado na tabela a seguir.
| Nome do campo de registro | Type | R/W | Padrão |
|---|---|---|---|
| SQL_DESC_AUTO_UNIQUE_VALUE | SQLINTEGER | ARD: APD não utilizado: IRD não utilizado: IPD R: não utilizado | ARD: APD não utilizado: IRD não utilizado: D IPD: não utilizado |
| SQL_DESC_BASE_COLUMN_NAME | SQLCHAR* | ARD: APD não utilizado: IRD não utilizado: IPD R: não utilizado | ARD: APD não utilizado: IRD não utilizado: D IPD: não utilizado |
| SQL_DESC_BASE_TABLE_NAME | SQLCHAR* | ARD: APD não utilizado: IRD não utilizado: IPD R: não utilizado | ARD: APD não utilizado: IRD não utilizado: D IPD: não utilizado |
| SQL_DESC_CASE_SENSITIVE | SQLINTEGER | ARD: APD não utilizado: IRD não utilizado: IPD R: R | ARD: APD não utilizado: IRD não utilizado: D IPD: D[1] |
| SQL_DESC_CATALOG_NAME | SQLCHAR* | ARD: APD não utilizado: IRD não utilizado: IPD R: não utilizado | ARD: APD não utilizado: IRD não utilizado: D IPD: não utilizado |
| SQL_DESC_CONCISE_TYPE | SQLSMALLINT | ARD: R/W APD: R/W IRD: R IPD: R/W | ARD: SQL_C_ APD PADRÃO: SQL_C_ IRD PADRÃO: D IPD: ND |
| SQL_DESC_DATA_PTR | SQLPOINTER | ARD: R/W APD: R/W IRD: IPD não utilizado: não utilizado | ARD: APD de ptr nulo: Null ptr IRD: IPD não utilizado: não utilizado[2] |
| SQL_DESC_DATETIME_INTERVAL_CODE | SQLSMALLINT | ARD: R/W APD: R/W IRD: R IPD: R/W | ARD: ND APD: ND IRD: D IPD: ND |
| SQL_DESC_DATETIME_INTERVAL_PRECISION | SQLINTEGER | ARD: R/W APD: R/W IRD: R IPD: R/W | ARD: ND APD: ND IRD: D IPD: ND |
| SQL_DESC_DISPLAY_SIZE | SQLLEN | ARD: APD não utilizado: IRD não utilizado: IPD R: não utilizado | ARD: APD não utilizado: IRD não utilizado: D IPD: não utilizado |
| SQL_DESC_FIXED_PREC_SCALE | SQLSMALLINT | ARD: APD não utilizado: IRD não utilizado: IPD R: R | ARD: APD não utilizado: IRD não utilizado: D IPD: D[1] |
| SQL_DESC_INDICATOR_PTR | SQLLEN * | ARD: R/W APD: R/W IRD: IPD não utilizado: não utilizado | ARD: APD de ptr nulo: Null ptr IRD: IPD não utilizado: não utilizado |
| SQL_DESC_LABEL | SQLCHAR* | ARD: APD não utilizado: IRD não utilizado: IPD R: não utilizado | ARD: APD não utilizado: IRD não utilizado: D IPD: não utilizado |
| SQL_DESC_LENGTH | SQLULEN | ARD: R/W APD: R/W IRD: R IPD: R/W | ARD: ND APD: ND IRD: D IPD: ND |
| SQL_DESC_LITERAL_PREFIX | SQLCHAR* | ARD: APD não utilizado: IRD não utilizado: IPD R: não utilizado | ARD: APD não utilizado: IRD não utilizado: D IPD: não utilizado |
| SQL_DESC_LITERAL_SUFFIX | SQLCHAR* | ARD: APD não utilizado: IRD não utilizado: IPD R: não utilizado | ARD: APD não utilizado: IRD não utilizado: D IPD: não utilizado |
| SQL_DESC_LOCAL_TYPE_NAME | SQLCHAR* | ARD: APD não utilizado: IRD não utilizado: IPD R: R | ARD: APD não utilizado: IRD não utilizado: D IPD: D[1] |
| SQL_DESC_NAME | SQLCHAR* | ARD: APD não utilizado: IRD não utilizado: R IPD: R/W | ARD: ND APD: ND IRD: D IPD: ND |
| SQL_DESC_NULLABLE | SQLSMALLINT | ARD: APD não utilizado: IRD não utilizado: IPD R: R | ARD: ND APD: ND IRD: D IPD: ND |
| SQL_DESC_NUM_PREC_RADIX | SQLINTEGER | ARD: R/W APD: R/W IRD: R IPD: R/W | ARD: ND APD: ND IRD: D IPD: ND |
| SQL_DESC_OCTET_LENGTH | SQLLEN | ARD: R/W APD: R/W IRD: R IPD: R/W | ARD: ND APD: ND IRD: D IPD: ND |
| SQL_DESC_OCTET_LENGTH_PTR | SQLLEN * | ARD: R/W APD: R/W IRD: IPD não utilizado: não utilizado | ARD: APD de ptr nulo: Null ptr IRD: IPD não utilizado: não utilizado |
| SQL_DESC_PARAMETER_TYPE | SQLSMALLINT | ARD: APD não utilizado: IRD não utilizado: IPD não utilizado: R/W | ARD: APD não utilizado: IRD não utilizado: IPD não utilizado: D=SQL_PARAM_INPUT |
| SQL_DESC_PRECISION | SQLSMALLINT | ARD: R/W APD: R/W IRD: R IPD: R/W | ARD: ND APD: ND IRD: D IPD: ND |
| SQL_DESC_ROWVER | SQLSMALLINT | ARD: Não utilizado APD: não utilizado IRD: R IPD: R |
ARD: Não utilizado APD: não utilizado IRD: ND IPD: ND |
| SQL_DESC_SCALE | SQLSMALLINT | ARD: R/W APD: R/W IRD: R IPD: R/W | ARD: ND APD: ND IRD: D IPD: ND |
| SQL_DESC_SCHEMA_NAME | SQLCHAR* | ARD: APD não utilizado: IRD não utilizado: R IPD: não utilizado | ARD: APD não utilizado: IRD não utilizado: D IPD: não utilizado |
| SQL_DESC_SEARCHABLE | SQLSMALLINT | ARD: APD não utilizado: IRD não utilizado: R IPD: não utilizado | ARD: APD não utilizado: IRD não utilizado: D IPD: não utilizado |
| SQL_DESC_TABLE_NAME | SQLCHAR* | ARD: APD não utilizado: IRD não utilizado: R IPD: não utilizado | ARD: APD não utilizado: IRD não utilizado: D IPD: não utilizado |
| SQL_DESC_TYPE | SQLSMALLINT | ARD: R/W APD: R/W IRD: R IPD: R/W | ARD: SQL_C_DEFAULT APD: SQL_C_DEFAULT IRD: D IPD: ND |
| SQL_DESC_TYPE_NAME | SQLCHAR* | ARD: APD não utilizado: IRD não utilizado: R IPD: R | ARD: APD não utilizado: IRD não utilizado: D IPD: D[1] |
| SQL_DESC_UNNAMED | SQLSMALLINT | ARD: APD não utilizado: IRD não utilizado: R IPD: R/W | ARD: ND APD: ND IRD: D IPD: ND |
| SQL_DESC_UNSIGNED | SQLSMALLINT | ARD: APD não utilizado: IRD não utilizado: R IPD: R | ARD: APD não utilizado: IRD não utilizado: D IPD: D[1] |
| SQL_DESC_UPDATABLE | SQLSMALLINT | ARD: APD não utilizado: IRD não utilizado: R IPD: não utilizado | ARD: APD não utilizado: IRD não utilizado: D IPD: não utilizado |
[1] Esses campos são definidos somente quando o IPD é preenchido automaticamente pelo driver. Caso contrário, eles são indefinidos. Se um aplicativo tentar definir esses campos, SQLSTATE HY091 (identificador de campo de descritor inválido) será retornado.
[2] O campo SQL_DESC_DATA_PTR no IPD pode ser definido para forçar uma verificação de consistência. Em uma chamada subsequente para SQLGetDescField ou SQLGetDescRec, o driver não é necessário para retornar o valor para o qual SQL_DESC_DATA_PTR foi definido.
Argumento FieldIdentifier
O argumento FieldIdentifier indica o campo descritor a ser definido. Um descritor contém o cabeçalho do descritor, que consiste nos campos de cabeçalho descritos na próxima seção, "Campos de Cabeçalho" e zero ou mais registros de descritor, que consistem nos campos de registro descritos na seção após a seção "Campos de Cabeçalho".
Campos de cabeçalho
Cada descritor tem um cabeçalho que consiste nos seguintes campos:
SQL_DESC_ALLOC_TYPE [Todos]
Esse campo de cabeçalho SQLSMALLINT somente leitura especifica se o descritor foi alocado automaticamente pelo driver ou explicitamente pelo aplicativo. O aplicativo pode obter, mas não modificar, esse campo. O campo será definido como SQL_DESC_ALLOC_AUTO pelo driver se o descritor tiver sido alocado automaticamente pelo driver. Ele será definido como SQL_DESC_ALLOC_USER pelo driver se o descritor tiver sido explicitamente alocado pelo aplicativo.
SQL_DESC_ARRAY_SIZE [Descritores de aplicativo]
Em ARDs, esse campo de cabeçalho SQLULEN especifica o número de linhas no conjunto de linhas. Esse é o número de linhas a serem retornadas por uma chamada para SQLFetch ou SQLFetchScroll ou para serem operadas por uma chamada para SQLBulkOperations ou SQLSetPos.
Em APDs, esse campo de cabeçalho SQLULEN especifica o número de valores para cada parâmetro.
O valor padrão desse campo é 1. Se SQL_DESC_ARRAY_SIZE for maior que 1, SQL_DESC_DATA_PTR, SQL_DESC_INDICATOR_PTR e SQL_DESC_OCTET_LENGTH_PTR do APD ou ARD apontarão para matrizes. A cardinalidade de cada matriz é igual ao valor desse campo.
Esse campo no ARD também pode ser definido chamando SQLSetStmtAttr com o atributo SQL_ATTR_ROW_ARRAY_SIZE. Esse campo no APD também pode ser definido chamando SQLSetStmtAttr com o atributo SQL_ATTR_PARAMSET_SIZE.
SQL_DESC_ARRAY_STATUS_PTR [Todos]
Para cada tipo de descritor, esse campo de cabeçalho SQLUSMALLINT * aponta para uma matriz de valores SQLUSMALLINT. Essas matrizes são nomeadas da seguinte maneira: IRD (matriz de status de linha), IPD (matriz de status do parâmetro), ARD (matriz de operação de linha) e APD (matriz de operação de parâmetro).
No IRD, esse campo de cabeçalho aponta para uma matriz de status de linha que contém valores de status após uma chamada para SQLBulkOperations, SQLFetch, SQLFetchScroll ou SQLSetPos. A matriz tem tantos elementos quanto há linhas no conjunto de linhas. O aplicativo deve alocar uma matriz de SQLUSMALLINTs e definir esse campo para apontar para a matriz. O campo é definido como um ponteiro nulo por padrão. O driver preencherá a matriz , a menos que o campo SQL_DESC_ARRAY_STATUS_PTR seja definido como um ponteiro nulo; nesse caso, nenhum valor de status será gerado e a matriz não será preenchida.
Cuidado
O comportamento do driver será indefinido se o aplicativo definir os elementos da matriz de status da linha apontada pelo campo SQL_DESC_ARRAY_STATUS_PTR do IRD.
A matriz é inicialmente preenchida por uma chamada para SQLBulkOperations, SQLFetch, SQLFetchScroll ou SQLSetPos. Se a chamada não retornar SQL_SUCCESS ou SQL_SUCCESS_WITH_INFO, o conteúdo da matriz apontada por esse campo será indefinido. Os elementos na matriz podem conter os seguintes valores:
SQL_ROW_SUCCESS: a linha foi buscada com êxito e não foi alterada desde a última busca.
SQL_ROW_SUCCESS_WITH_INFO: a linha foi buscada com êxito e não foi alterada desde a última busca. No entanto, um aviso foi retornado sobre a linha.
SQL_ROW_ERROR: ocorreu um erro ao buscar a linha.
SQL_ROW_UPDATED: a linha foi buscada com êxito e foi atualizada desde a última busca. Se a linha for buscada novamente, seu status será SQL_ROW_SUCCESS.
SQL_ROW_DELETED: a linha foi excluída desde a última busca.
SQL_ROW_ADDED: a linha foi inserida por SQLBulkOperations. Se a linha for buscada novamente, seu status será SQL_ROW_SUCCESS.
SQL_ROW_NOROW: o conjunto de linhas sobrepôs o final do conjunto de resultados e nenhuma linha foi retornada que correspondia a esse elemento da matriz de status da linha.
Esse campo no IRD também pode ser definido chamando SQLSetStmtAttr com o atributo SQL_ATTR_ROW_STATUS_PTR.
O campo SQL_DESC_ARRAY_STATUS_PTR do IRD é válido somente depois que SQL_SUCCESS ou SQL_SUCCESS_WITH_INFO tiver sido retornado. Se o código de retorno não for um desses, o local apontado por SQL_DESC_ROWS_PROCESSED_PTR será indefinido.
No IPD, esse campo de cabeçalho aponta para uma matriz de status de parâmetro que contém informações de status para cada conjunto de valores de parâmetro após uma chamada para SQLExecute ou SQLExecDirect. Se a chamada para SQLExecute ou SQLExecDirect não retornar SQL_SUCCESS ou SQL_SUCCESS_WITH_INFO, o conteúdo da matriz apontada por esse campo será indefinido. O aplicativo deve alocar uma matriz de SQLUSMALLINTs e definir esse campo para apontar para a matriz. O driver preencherá a matriz , a menos que o campo SQL_DESC_ARRAY_STATUS_PTR seja definido como um ponteiro nulo; nesse caso, nenhum valor de status será gerado e a matriz não será preenchida. Os elementos na matriz podem conter os seguintes valores:
SQL_PARAM_SUCCESS: a instrução SQL foi executada com êxito para esse conjunto de parâmetros.
SQL_PARAM_SUCCESS_WITH_INFO: a instrução SQL foi executada com êxito para esse conjunto de parâmetros; no entanto, as informações de aviso estão disponíveis na estrutura de dados de diagnóstico.
SQL_PARAM_ERROR: ocorreu um erro ao processar esse conjunto de parâmetros. Informações adicionais de erro estão disponíveis na estrutura de dados de diagnóstico.
SQL_PARAM_UNUSED: esse conjunto de parâmetros não foi utilizado, possivelmente devido ao fato de que algum conjunto de parâmetros anterior causou um erro que anulou o processamento adicional ou porque SQL_PARAM_IGNORE foi definido para esse conjunto de parâmetros na matriz especificada pelo campo SQL_DESC_ARRAY_STATUS_PTR da APD.
SQL_PARAM_DIAG_UNAVAILABLE: as informações de diagnóstico não estão disponíveis. Um exemplo disso é quando o driver trata matrizes de parâmetros como uma unidade monolítica e, portanto, não gera esse nível de informações de erro.
Esse campo no IPD também pode ser definido chamando SQLSetStmtAttr com o atributo SQL_ATTR_PARAM_STATUS_PTR.
No ARD, esse campo de cabeçalho aponta para uma matriz de operações de linha de valores que podem ser definidos pelo aplicativo para indicar se essa linha deve ser ignorada para operações SQLSetPos . Os elementos na matriz podem conter os seguintes valores:
SQL_ROW_PROCEED: a linha está incluída na operação em massa usando SQLSetPos. (Essa configuração não garante que a operação ocorrerá na linha. Se a linha tiver o status SQL_ROW_ERROR na matriz de status da linha IRD, o driver poderá não ser capaz de executar a operação na linha.)
SQL_ROW_IGNORE: a linha é excluída da operação em massa usando SQLSetPos.
Se nenhum elemento da matriz for definido, todas as linhas serão incluídas na operação em massa. Se o valor no campo SQL_DESC_ARRAY_STATUS_PTR do ARD for um ponteiro nulo, todas as linhas serão incluídas na operação em massa; a interpretação é a mesma que se o ponteiro apontasse para uma matriz válida e todos os elementos da matriz fossem SQL_ROW_PROCEED. Se um elemento na matriz for definido como SQL_ROW_IGNORE, o valor na matriz de status da linha para a linha ignorada não será alterado.
Esse campo no ARD também pode ser definido chamando SQLSetStmtAttr com o atributo SQL_ATTR_ROW_OPERATION_PTR.
No APD, esse campo de cabeçalho aponta para uma matriz de valores de operação de parâmetro que pode ser definida pelo aplicativo para indicar se esse conjunto de parâmetros deve ser ignorado quando SQLExecute ou SQLExecDirect é chamado. Os elementos na matriz podem conter os seguintes valores:
SQL_PARAM_PROCEED: o conjunto de parâmetros está incluído na chamada SQLExecute ou SQLExecDirect .
SQL_PARAM_IGNORE: o conjunto de parâmetros é excluído da chamada SQLExecute ou SQLExecDirect .
Se nenhum elemento da matriz for definido, todos os conjuntos de parâmetros na matriz serão usados nas chamadas SQLExecute ou SQLExecDirect . Se o valor no campo SQL_DESC_ARRAY_STATUS_PTR do APD for um ponteiro nulo, todos os conjuntos de parâmetros serão usados; a interpretação é a mesma que se o ponteiro apontasse para uma matriz válida e todos os elementos da matriz fossem SQL_PARAM_PROCEED.
Esse campo no APD também pode ser definido chamando SQLSetStmtAttr com o atributo SQL_ATTR_PARAM_OPERATION_PTR.
SQL_DESC_BIND_OFFSET_PTR [Descritores de aplicativo]
Esse campo de cabeçalho SQLLEN * aponta para o deslocamento de associação. Ele é definido como um ponteiro nulo por padrão. Se esse campo não for um ponteiro nulo, o driver desreferencia o ponteiro e adiciona o valor desreferenciado a cada um dos campos adiados que tem um valor não nulo no registro do descritor (SQL_DESC_DATA_PTR, SQL_DESC_INDICATOR_PTR e SQL_DESC_OCTET_LENGTH_PTR) no momento da busca e usa os novos valores de ponteiro ao associar.
O deslocamento de associação sempre é adicionado diretamente aos valores nos campos SQL_DESC_DATA_PTR, SQL_DESC_INDICATOR_PTR e SQL_DESC_OCTET_LENGTH_PTR. Se o deslocamento for alterado para um valor diferente, o novo valor ainda será adicionado diretamente ao valor em cada campo descritor. O novo deslocamento não é adicionado ao valor do campo mais qualquer deslocamento anterior.
Esse campo é um campo adiado: ele não é usado no momento em que está definido, mas é usado posteriormente pelo driver quando precisa determinar endereços para buffers de dados.
Esse campo no ARD também pode ser definido chamando SQLSetStmtAttr com o atributo SQL_ATTR_ROW_BIND_OFFSET_PTR. Esse campo no ARD também pode ser definido chamando SQLSetStmtAttr com o atributo SQL_ATTR_PARAM_BIND_OFFSET_PTR.
Para obter mais informações, consulte a descrição da associação em linha em SQLFetchScroll e SQLBindParameter.
SQL_DESC_BIND_TYPE [Descritores de aplicativo]
Esse campo de cabeçalho SQLUINTEGER define a orientação de associação a ser usada para associar colunas ou parâmetros.
Em ARDs, esse campo especifica a orientação de associação quando SQLFetchScroll ou SQLFetch é chamado no identificador de instrução associado.
Para selecionar a associação em termos de coluna para colunas, esse campo é definido como SQL_BIND_BY_COLUMN (o padrão).
Esse campo no ARD também pode ser definido chamando SQLSetStmtAttr com o atributo SQL_ATTR_ROW_BIND_TYPE.
Em APDs, esse campo especifica a orientação de associação a ser usada para parâmetros dinâmicos.
Para selecionar a associação em termos de coluna para parâmetros, esse campo é definido como SQL_BIND_BY_COLUMN (o padrão).
Esse campo no APD também pode ser definido chamando SQLSetStmtAttr com o atributo SQL_ATTR_PARAM_BIND_TYPE.
SQL_DESC_COUNT [Todos]
Esse campo de cabeçalho SQLSMALLINT especifica o índice baseado em 1 do registro numerado mais alto que contém dados. Quando o driver define a estrutura de dados para o descritor, ele também deve definir o campo SQL_DESC_COUNT para mostrar quantos registros são significativos. Quando um aplicativo aloca uma instância dessa estrutura de dados, ele não precisa especificar quantos registros reservar espaço. Como o aplicativo especifica o conteúdo dos registros, o driver executa qualquer ação necessária para garantir que o identificador do descritor se refira a uma estrutura de dados do tamanho adequado.
SQL_DESC_COUNT não é uma contagem de todas as colunas de dados associadas (se o campo estiver em um ARD) ou de todos os parâmetros associados (se o campo estiver em uma APD), mas o número do registro numerado mais alto. Se a coluna ou parâmetro numerado mais alto não for associado, SQL_DESC_COUNT será alterado para o número da próxima coluna ou parâmetro com maior número. Se uma coluna ou um parâmetro com um número menor que o número da coluna com número mais alto não for associado (chamando SQLBindCol com o argumento TargetValuePtr definido como um ponteiro nulo ou SQLBindParameter com o argumento ParameterValuePtr definido como um ponteiro nulo), SQL_DESC_COUNT não será alterado. Se colunas ou parâmetros adicionais estiverem associados a números maiores que o registro numerado mais alto que contém dados, o driver aumentará automaticamente o valor no campo SQL_DESC_COUNT. Se todas as colunas não estiverem associadas chamando SQLFreeStmt com a opção SQL_UNBIND, os campos SQL_DESC_COUNT no ARD e no IRD serão definidos como 0. Se SQLFreeStmt for chamado com a opção SQL_RESET_PARAMS, os campos SQL_DESC_COUNT no APD e no IPD serão definidos como 0.
O valor em SQL_DESC_COUNT pode ser definido explicitamente por um aplicativo chamando SQLSetDescField. Se o valor em SQL_DESC_COUNT for explicitamente reduzido, todos os registros com números maiores que o novo valor em SQL_DESC_COUNT serão efetivamente removidos. Se o valor em SQL_DESC_COUNT for definido explicitamente como 0 e o campo estiver em um ARD, todos os buffers de dados, exceto uma coluna de indicador associado, serão liberados.
A contagem de registros nesse campo de um ARD não inclui uma coluna de indicador associado. A única maneira de desassociar uma coluna de indicador é definir o campo SQL_DESC_DATA_PTR como um ponteiro nulo.
SQL_DESC_ROWS_PROCESSED_PTR [Descritores de implementação]
Em um IRD, esse campo de cabeçalho SQLULEN * aponta para um buffer que contém o número de linhas buscadas após uma chamada para SQLFetch ou SQLFetchScroll ou o número de linhas afetadas em uma operação em massa executada por uma chamada para SQLBulkOperations ou SQLSetPos, incluindo linhas de erro.
Em um IPD, esse campo de cabeçalho SQLUINTEGER * aponta para um buffer que contém o número de conjuntos de parâmetros que foram processados, incluindo conjuntos de erros. Nenhum número será retornado se este for um ponteiro nulo.
SQL_DESC_ROWS_PROCESSED_PTR é válido somente depois que SQL_SUCCESS ou SQL_SUCCESS_WITH_INFO tiver sido retornado após uma chamada para SQLFetch ou SQLFetchScroll (para um campo IRD) ou SQLExecute, SQLExecDirect ou SQLParamData (para um campo IPD). Se a chamada que preenche o buffer apontado por esse campo não retornar SQL_SUCCESS ou SQL_SUCCESS_WITH_INFO, o conteúdo do buffer será indefinido, a menos que retorne SQL_NO_DATA, nesse caso, o valor no buffer será definido como 0.
Esse campo no ARD também pode ser definido chamando SQLSetStmtAttr com o atributo SQL_ATTR_ROWS_FETCHED_PTR. Esse campo no APD também pode ser definido chamando SQLSetStmtAttr com o atributo SQL_ATTR_PARAMS_PROCESSED_PTR.
O buffer apontado por esse campo é alocado pelo aplicativo. É um buffer de saída adiado definido pelo driver. Ele é definido como um ponteiro nulo por padrão.
Campos de registro
Cada descritor contém um ou mais registros que consistem em campos que definem dados de coluna ou parâmetros dinâmicos, dependendo do tipo de descritor. Cada registro é uma definição completa de uma única coluna ou parâmetro.
SQL_DESC_AUTO_UNIQUE_VALUE [IRDs]
Esse campo de registro SQLINTEGER somente leitura contém SQL_TRUE se a coluna for uma coluna de incremento automático ou SQL_FALSE se a coluna não for uma coluna de incremento automático. Esse campo é somente leitura, mas a coluna de incremento automático subjacente não é necessariamente somente leitura.
SQL_DESC_BASE_COLUMN_NAME [IRDs]
Este campo de registro SQLCHAR * somente leitura contém o nome da coluna base para a coluna do conjunto de resultados. Se um nome de coluna base não existir (como no caso de colunas que são expressões), essa variável conterá uma cadeia de caracteres vazia.
SQL_DESC_BASE_TABLE_NAME [IRDs]
Este campo de registro SQLCHAR * somente leitura contém o nome da tabela base para a coluna do conjunto de resultados. Se um nome de tabela base não puder ser definido ou não for aplicável, essa variável conterá uma cadeia de caracteres vazia.
SQL_DESC_CASE_SENSITIVE [Descritores de implementação]
Esse campo de registro SQLINTEGER somente leitura contém SQL_TRUE se a coluna ou parâmetro for tratado como diferenciador de maiúsculas e minúsculas para ordenações e comparações ou SQL_FALSE se a coluna não for tratada como diferenciar maiúsculas de minúsculas para ordenações e comparações ou se for uma coluna não caractere.
SQL_DESC_CATALOG_NAME [IRDs]
Este campo de registro SQLCHAR * somente leitura contém o catálogo da tabela base que contém a coluna. O valor retornado dependerá do driver se a coluna for uma expressão ou se a coluna fizer parte de uma exibição. Se a fonte de dados não der suporte a catálogos ou se o catálogo não puder ser determinado, essa variável conterá uma cadeia de caracteres vazia.
SQL_DESC_CONCISE_TYPE [Todos]
Esse campo de cabeçalho SQLSMALLINT especifica o tipo de dados conciso para todos os tipos de dados, incluindo os tipos de dados datetime e interval.
Os valores nos campos SQL_DESC_CONCISE_TYPE, SQL_DESC_TYPE e SQL_DESC_DATETIME_INTERVAL_CODE são interdependentes. Cada vez que um dos campos é definido, o outro também deve ser definido. SQL_DESC_CONCISE_TYPE pode ser definido por uma chamada para SQLBindCol ou SQLBindParameter ou SQLSetDescField. SQL_DESC_TYPE pode ser definido por uma chamada para SQLSetDescField ou SQLSetDescRec.
Se SQL_DESC_CONCISE_TYPE for definido como um tipo de dados conciso diferente de um tipo de dados interval ou datetime, o campo SQL_DESC_TYPE será definido com o mesmo valor e o campo SQL_DESC_DATETIME_INTERVAL_CODE será definido como 0.
Se SQL_DESC_CONCISE_TYPE for definido como o tipo de dados datetime ou interval conciso, o campo SQL_DESC_TYPE será definido como o tipo detalhado correspondente (SQL_DATETIME ou SQL_INTERVAL) e o campo SQL_DESC_DATETIME_INTERVAL_CODE será definido como o subcódigo apropriado.
SQL_DESC_DATA_PTR [IPDs e descritores de aplicativo]
Esse campo de registro SQLPOINTER aponta para uma variável que conterá o valor do parâmetro (para APDs) ou o valor da coluna (para ARDs). Este campo é um campo adiado. Ele não é usado no momento em que está definido, mas é usado posteriormente pelo driver para recuperar dados.
A coluna especificada pelo campo SQL_DESC_DATA_PTR do ARD será desassociada se o argumento TargetValuePtr em uma chamada para SQLBindCol for um ponteiro nulo ou se o campo SQL_DESC_DATA_PTR no ARD for definido por uma chamada para SQLSetDescField ou SQLSetDescRec para um ponteiro nulo. Outros campos não serão afetados se o campo SQL_DESC_DATA_PTR estiver definido como um ponteiro nulo.
Se a chamada para SQLFetch ou SQLFetchScroll que preenche o buffer apontado por esse campo não retornar SQL_SUCCESS ou SQL_SUCCESS_WITH_INFO, o conteúdo do buffer será indefinido.
Sempre que o campo SQL_DESC_DATA_PTR de um APD, ARD ou IPD estiver definido, o driver verificará se o valor no campo SQL_DESC_TYPE contém um dos tipos de dados ODBC C válidos ou um tipo de dados específico do driver e se todos os outros campos que afetam os tipos de dados são consistentes. Solicitar uma verificação de consistência é o único uso do campo SQL_DESC_DATA_PTR de um IPD. Especificamente, se um aplicativo define o campo SQL_DESC_DATA_PTR de um IPD e, posteriormente, chama SQLGetDescField nesse campo, ele não é necessariamente retornado o valor que havia definido. Para obter mais informações, confira "Verificações de consistência" em SQLSetDescRec.
SQL_DESC_DATETIME_INTERVAL_CODE [Todos]
Esse campo de registro SQLSMALLINT contém o subcódigo para o tipo de dados datetime ou interval específico quando o campo SQL_DESC_TYPE é SQL_DATETIME ou SQL_INTERVAL. Isso é verdadeiro para os tipos de dados SQL e C. O código consiste no nome do tipo de dados com "CODE" substituído por "TYPE" ou "C_TYPE" (para tipos datetime) ou "CODE" substituído por "INTERVAL" ou "C_INTERVAL" (para tipos de intervalo).
Se SQL_DESC_TYPE e SQL_DESC_CONCISE_TYPE em um descritor de aplicativo forem definidos como SQL_C_DEFAULT e o descritor não estiver associado a um identificador de instrução, o conteúdo de SQL_DESC_DATETIME_INTERVAL_CODE será indefinido.
Esse campo pode ser definido para os tipos de dados datetime listados na tabela a seguir.
| Tipos de datetime | DATETIME_INTERVAL_CODE |
|---|---|
| SQL_TYPE_DATE/SQL_C_TYPE_DATE | SQL_CODE_DATE |
| SQL_TYPE_TIME/SQL_C_TYPE_TIME | SQL_CODE_TIME |
| SQL_TYPE_TIMESTAMP/SQL_C_TYPE_TIMESTAMP | SQL_CODE_TIMESTAMP |
Esse campo pode ser definido para os tipos de dados de intervalo listados na tabela a seguir.
| Tipo de intervalo | DATETIME_INTERVAL_CODE |
|---|---|
| SQL_INTERVAL_DAY/SQL_C_INTERVAL_DAY | SQL_CODE_DAY |
| SQL_INTERVAL_DAY_TO_HOUR/SQL_C_INTERVAL_DAY_TO_HOUR | SQL_CODE_DAY_TO_HOUR |
| SQL_INTERVAL_DAY_TO_MINUTE/SQL_C_INTERVAL_DAY_TO_MINUTE | SQL_CODE_DAY_TO_MINUTE |
| SQL_INTERVAL_DAY_TO_SECOND/SQL_C_INTERVAL_DAY_TO_SECOND | SQL_CODE_DAY_TO_SECOND |
| SQL_INTERVAL_HOUR/SQL_C_INTERVAL_HOUR | SQL_CODE_HOUR |
| SQL_INTERVAL_HOUR_TO_MINUTE/SQL_C_INTERVAL_HOUR_TO_MINUTE | SQL_CODE_HOUR_TO_MINUTE |
| SQL_INTERVAL_HOUR_TO_SECOND/SQL_C_INTERVAL_HOUR_TO_SECOND | SQL_CODE_HOUR_TO_SECOND |
| SQL_INTERVAL_MINUTE/SQL_C_INTERVAL_MINUTE | SQL_CODE_MINUTE |
| SQL_INTERVAL_MINUTE_TO_SECOND/SQL_C_INTERVAL_MINUTE_TO_SECOND | SQL_CODE_MINUTE_TO_SECOND |
| SQL_INTERVAL_MONTH/SQL_C_INTERVAL_MONTH | SQL_CODE_MONTH |
| SQL_INTERVAL_SECOND/SQL_C_INTERVAL_SECOND | SQL_CODE_SECOND |
| SQL_INTERVAL_YEAR/SQL_C_INTERVAL_YEAR | SQL_CODE_YEAR |
| SQL_INTERVAL_YEAR_TO_MONTH/SQL_C_INTERVAL_YEAR_TO_MONTH | SQL_CODE_YEAR_TO_MONTH |
Para obter mais informações sobre os intervalos de dados e esse campo, consulte Identificadores de tipo de dados e descritores.
SQL_DESC_DATETIME_INTERVAL_PRECISION [Todos]
Esse campo de registro SQLINTEGER conterá a precisão à esquerda do intervalo se o campo SQL_DESC_TYPE for SQL_INTERVAL. Quando o campo SQL_DESC_DATETIME_INTERVAL_CODE é definido como um tipo de dados de intervalo, esse campo é definido como o intervalo padrão de precisão à esquerda.
SQL_DESC_DISPLAY_SIZE [IRDs]
Este campo de registro SQLINTEGER somente leitura contém o número máximo de caracteres necessários para exibir os dados da coluna.
SQL_DESC_FIXED_PREC_SCALE [Descritores de implementação]
Esse campo de registro SQLSMALLINT somente leitura será definido como SQL_TRUE se a coluna for uma coluna numérica exata e tiver uma precisão fixa e uma escala diferente de zero ou para SQL_FALSE se a coluna não for uma coluna numérica exata com precisão e escala fixas.
SQL_DESC_INDICATOR_PTR [Descritores de aplicativo]
Em ARDs, esse campo de registro SQLLEN * aponta para a variável de indicador. Essa variável conterá SQL_NULL_DATA se o valor da coluna for NULL. Para APDs, a variável de indicador é definida como SQL_NULL_DATA para especificar argumentos dinâmicos NULL. Caso contrário, a variável será zero (a menos que os valores em SQL_DESC_INDICATOR_PTR e SQL_DESC_OCTET_LENGTH_PTR sejam o mesmo ponteiro).
Se o campo SQL_DESC_INDICATOR_PTR em um ARD for um ponteiro nulo, o driver será impedido de retornar informações sobre se a coluna é NULL ou não. Se a coluna for NULL e SQL_DESC_INDICATOR_PTR for um ponteiro nulo, SQLSTATE 22002 (variável indicator necessária, mas não fornecida) será retornado quando o driver tentar preencher o buffer após uma chamada para SQLFetch ou SQLFetchScroll. Se a chamada para SQLFetch ou SQLFetchScroll não retornar SQL_SUCCESS ou SQL_SUCCESS_WITH_INFO, o conteúdo do buffer será indefinido.
O campo SQL_DESC_INDICATOR_PTR determina se o campo apontado por SQL_DESC_OCTET_LENGTH_PTR está definido. Se o valor de dados de uma coluna for NULL, o driver definirá a variável de indicador como SQL_NULL_DATA. O campo apontado por SQL_DESC_OCTET_LENGTH_PTR não é definido. Se um valor NULL não for encontrado durante a busca, o buffer apontado por SQL_DESC_INDICATOR_PTR será definido como zero e o buffer apontado por SQL_DESC_OCTET_LENGTH_PTR será definido com o comprimento dos dados.
Se o campo SQL_DESC_INDICATOR_PTR em um APD for um ponteiro nulo, o aplicativo não poderá usar esse registro descritor para especificar argumentos NULL.
Esse campo é um campo adiado: ele não é usado no momento em que está definido, mas é usado posteriormente pelo driver para indicar nulidade (para ARDs) ou para determinar a nulidade (para APDs).
SQL_DESC_LABEL [IRDs]
Este campo de registro SQLCHAR * somente leitura contém o rótulo ou o título da coluna. Se a coluna não tiver um rótulo, essa variável conterá o nome da coluna. Se a coluna não tiver nome e não estiver rotulada, essa variável conterá uma cadeia de caracteres vazia.
SQL_DESC_LENGTH [Todos]
Esse campo de registro SQLULEN é o comprimento máximo ou real de uma cadeia de caracteres em caracteres ou um tipo de dados binário em bytes. É o comprimento máximo para um tipo de dados de comprimento fixo ou o comprimento real para um tipo de dados de comprimento variável. Seu valor sempre exclui o caractere de terminação nula que termina a cadeia de caracteres. Para valores cujo tipo é SQL_TYPE_DATE, SQL_TYPE_TIME, SQL_TYPE_TIMESTAMP ou um dos tipos de dados de intervalo SQL, esse campo tem o comprimento em caracteres da representação de cadeia de caracteres do valor datetime ou interval.
O valor nesse campo pode ser diferente do valor de "length", conforme definido em ODBC 2*.x*. Para obter mais informações, consulte Apêndice D: Tipos de dados.
SQL_DESC_LITERAL_PREFIX [IRDs]
Esse campo de registro SQLCHAR * somente leitura contém o caractere ou caracteres que o driver reconhece como um prefixo para um literal desse tipo de dados. Essa variável contém uma cadeia de caracteres vazia para um tipo de dados para o qual um prefixo literal não é aplicável.
SQL_DESC_LITERAL_SUFFIX [IRDs]
Esse campo de registro SQLCHAR * somente leitura contém o caractere ou caracteres que o driver reconhece como um sufixo para um literal desse tipo de dados. Essa variável contém uma cadeia de caracteres vazia para um tipo de dados para o qual um sufixo literal não é aplicável.
SQL_DESC_LOCAL_TYPE_NAME [Descritores de implementação]
Este campo de registro SQLCHAR * somente leitura contém qualquer nome localizado (idioma nativo) para o tipo de dados que pode ser diferente do nome regular do tipo de dados. Se não houver nenhum nome localizado, uma cadeia de caracteres vazia será retornada. Esse campo é apenas para fins de exibição.
SQL_DESC_NAME [Descritores de implementação]
Esse campo de registro SQLCHAR * em um descritor de linha contém o alias de coluna, se ele se aplicar. Se o alias da coluna não se aplicar, o nome da coluna será retornado. Em ambos os casos, o driver define o campo SQL_DESC_UNNAMED como SQL_NAMED quando define o campo SQL_DESC_NAME. Se não houver nenhum nome de coluna ou um alias de coluna, o driver retornará uma cadeia de caracteres vazia no campo SQL_DESC_NAME e definirá o campo SQL_DESC_UNNAMED como SQL_UNNAMED.
Um aplicativo pode definir o campo SQL_DESC_NAME de um IPD como um nome de parâmetro ou alias para especificar parâmetros de procedimento armazenado por nome. (Para obter mais informações, consulte Parâmetros de associação por nome (parâmetros nomeados).) O campo SQL_DESC_NAME de um IRD é um campo somente leitura; SQLSTATE HY091 (identificador de campo do descritor inválido) será retornado se um aplicativo tentar defini-lo.
Em IPDs, esse campo será indefinido se o driver não oferecer suporte a parâmetros nomeados. Se o driver der suporte a parâmetros nomeados e for capaz de descrever parâmetros, o nome do parâmetro será retornado nesse campo.
SQL_DESC_NULLABLE [Descritores de implementação]
Em IRDs, esse campo de registro SQLSMALLINT somente leitura será SQL_NULLABLE se a coluna puder ter valores NULL, SQL_NO_NULLS se a coluna não tiver valores NULL ou SQL_NULLABLE_UNKNOWN se não se sabe se a coluna aceita valores NULL. Esse campo pertence à coluna do conjunto de resultados, não à coluna base.
Em IPDs, esse campo é sempre definido como SQL_NULLABLE porque os parâmetros dinâmicos são sempre anuláveis e não podem ser definidos por um aplicativo.
SQL_DESC_NUM_PREC_RADIX [Todos]
Esse campo SQLINTEGER contém um valor de 2 se o tipo de dados no campo SQL_DESC_TYPE for um tipo de dados numérico aproximado, pois o campo SQL_DESC_PRECISION contém o número de bits. Esse campo contém um valor de 10 se o tipo de dados no campo SQL_DESC_TYPE for um tipo de dados numérico exato, pois o campo SQL_DESC_PRECISION contém o número de dígitos decimais. Esse campo é definido como 0 para todos os tipos de dados não numéricos.
SQL_DESC_OCTET_LENGTH [Todos]
Esse campo de registro SQLLEN contém o comprimento, em bytes, de uma cadeia de caracteres ou um tipo de dados binário. Para tipos binários ou caracteres de comprimento fixo, esse é o comprimento real em bytes. Para tipos binários ou caracteres de comprimento variável, esse é o comprimento máximo em bytes. Esse valor sempre exclui o espaço para o caractere de terminação nula para descritores de implementação e sempre inclui espaço para o caractere de terminação nula para descritores de aplicativo. Para dados do aplicativo, esse campo contém o tamanho do buffer. Para APDs, esse campo é definido apenas para parâmetros de saída ou entrada/saída.
SQL_DESC_OCTET_LENGTH_PTR [Descritores de aplicativo]
Este campo de registro SQLLEN * aponta para uma variável que conterá o comprimento total em bytes de um argumento dinâmico (para descritores de parâmetro) ou de um valor de coluna associada (para descritores de linha).
Para uma APD, esse valor é ignorado para todos os argumentos, exceto cadeia de caracteres e binário; se esse campo apontar para SQL_NTS, o argumento dinâmico deverá ser encerrado em nulo. Para indicar que um parâmetro associado será um parâmetro de dados em execução, um aplicativo define esse campo no registro apropriado do APD como uma variável que, em tempo de execução, conterá o valor SQL_DATA_AT_EXEC ou o resultado da macro SQL_LEN_DATA_AT_EXEC. Se houver mais de um desses campos, SQL_DESC_DATA_PTR poderá ser definido como um valor que identifique exclusivamente o parâmetro para ajudar o aplicativo a determinar qual parâmetro está sendo solicitado.
Se o campo OCTET_LENGTH_PTR de um ARD for um ponteiro nulo, o driver não retornará informações de comprimento para a coluna. Se o campo SQL_DESC_OCTET_LENGTH_PTR de um APD for um ponteiro nulo, o driver pressupõe que as cadeias de caracteres e os valores binários sejam encerrados em nulo. (Os valores binários não devem ser encerrados em nulo, mas devem ter um comprimento para evitar truncamento.)
Se a chamada para SQLFetch ou SQLFetchScroll que preenche o buffer apontado por esse campo não retornar SQL_SUCCESS ou SQL_SUCCESS_WITH_INFO, o conteúdo do buffer será indefinido. Esse campo é um campo adiado. Ele não é usado no momento em que está definido, mas é usado posteriormente pelo driver para determinar ou indicar o comprimento do octeto dos dados.
SQL_DESC_PARAMETER_TYPE [IPDs]
Esse campo de registro SQLSMALLINT é definido como SQL_PARAM_INPUT para um parâmetro de entrada, SQL_PARAM_INPUT_OUTPUT para um parâmetro de entrada/saída, SQL_PARAM_OUTPUT para um parâmetro de saída, SQL_PARAM_INPUT_OUTPUT_STREAM para um parâmetro transmitido de entrada/saída ou SQL_PARAM_OUTPUT_STREAM para um parâmetro transmitido de saída. Ele é definido como SQL_PARAM_INPUT por padrão.
Para um IPD, o campo será definido como SQL_PARAM_INPUT por padrão se o IPD não for preenchido automaticamente pelo driver (o atributo de instrução SQL_ATTR_ENABLE_AUTO_IPD é SQL_FALSE). Um aplicativo deve definir esse campo no IPD para parâmetros que não são parâmetros de entrada.
SQL_DESC_PRECISION [Todos]
Esse campo de registro SQLSMALLINT contém o número de dígitos para um tipo numérico exato, o número de bits na mantissa (precisão binária) para um tipo numérico aproximado ou o número de dígitos no componente de segundos fracionários do tipo de dados SQL_TYPE_TIME, SQL_TYPE_TIMESTAMP ou SQL_INTERVAL_SECOND. Esse campo é indefinido para todos os outros tipos de dados.
O valor nesse campo pode ser diferente do valor de "precisão", conforme definido em ODBC 2*.x*. Para obter mais informações, consulte Apêndice D: Tipos de dados.
SQL_DESC_ROWVER [Descritores de implementação]
Esse campo SQLSMALLINTrecord indica se uma coluna é modificada automaticamente pelo DBMS quando uma linha é atualizada (por exemplo, uma coluna do tipo "carimbo de data/hora" em SQL Server). O valor desse campo de registro é definido como SQL_TRUE se a coluna for uma coluna de controle de versão de linha e para SQL_FALSE caso contrário. Esse atributo de coluna é semelhante a chamar SQLSpecialColumns com IdentifierType de SQL_ROWVER para determinar se uma coluna é atualizada automaticamente.
SQL_DESC_SCALE [Todos]
Esse campo de registro SQLSMALLINT contém a escala definida para tipos de dados decimal e numéricos. O campo é indefinido para todos os outros tipos de dados.
O valor nesse campo pode ser diferente do valor de "scale", conforme definido em ODBC 2*.x*. Para obter mais informações, consulte Apêndice D: Tipos de dados.
SQL_DESC_SCHEMA_NAME [IRDs]
Este campo de registro SQLCHAR * somente leitura contém o nome do esquema da tabela base que contém a coluna. O valor retornado dependerá do driver se a coluna for uma expressão ou se a coluna fizer parte de uma exibição. Se a fonte de dados não der suporte a esquemas ou o nome do esquema não puder ser determinado, essa variável conterá uma cadeia de caracteres vazia.
SQL_DESC_SEARCHABLE [IRDs]
Este campo de registro SQLSMALLINT somente leitura é definido como um dos seguintes valores:
SQL_PRED_NONE se a coluna não puder ser usada em uma cláusula WHERE . (Isso é o mesmo que o valor SQL_UNSEARCHABLE no ODBC 2*.x*.)
SQL_PRED_CHAR se a coluna puder ser usada em uma cláusula WHERE , mas somente com o predicado LIKE . (Isso é o mesmo que o valor SQL_LIKE_ONLY no ODBC 2*.x*.)
SQL_PRED_BASIC se a coluna puder ser usada em uma cláusula WHERE com todos os operadores de comparação, exceto LIKE. (Isso é o mesmo que o valor SQL_EXCEPT_LIKE no ODBC 2*.x*.)
SQL_PRED_SEARCHABLE se a coluna puder ser usada em uma cláusula WHERE com qualquer operador de comparação.
SQL_DESC_TABLE_NAME [IRDs]
Este campo de registro SQLCHAR * somente leitura contém o nome da tabela base que contém esta coluna. O valor retornado dependerá do driver se a coluna for uma expressão ou se a coluna fizer parte de uma exibição.
SQL_DESC_TYPE [Todos]
Esse campo de registro SQLSMALLINT especifica o tipo de dados SQL ou C conciso para todos os tipos de dados, exceto os tipos de dados datetime e interval. Para os tipos de dados datetime e interval, esse campo especifica o tipo de dados detalhado, que é SQL_DATETIME ou SQL_INTERVAL.
Sempre que esse campo contiver SQL_DATETIME ou SQL_INTERVAL, o campo SQL_DESC_DATETIME_INTERVAL_CODE deverá conter o subcódigo apropriado para o tipo conciso. Para tipos de dados datetime, SQL_DESC_TYPE contém SQL_DATETIME e o campo SQL_DESC_DATETIME_INTERVAL_CODE contém um subcódigo para o tipo de dados datetime específico. Para tipos de dados de intervalo, SQL_DESC_TYPE contém SQL_INTERVAL e o campo SQL_DESC_DATETIME_INTERVAL_CODE contém um subcódigo para o tipo de dados de intervalo específico.
Os valores nos campos SQL_DESC_TYPE e SQL_DESC_CONCISE_TYPE são interdependentes. Cada vez que um dos campos é definido, o outro também deve ser definido. SQL_DESC_TYPE pode ser definido por uma chamada para SQLSetDescField ou SQLSetDescRec. SQL_DESC_CONCISE_TYPE pode ser definido por uma chamada para SQLBindCol ou SQLBindParameter ou SQLSetDescField.
Se SQL_DESC_TYPE for definido como um tipo de dados conciso diferente de um tipo de dados interval ou datetime, o campo SQL_DESC_CONCISE_TYPE será definido como o mesmo valor e o campo SQL_DESC_DATETIME_INTERVAL_CODE será definido como 0.
Se SQL_DESC_TYPE for definido como o tipo de dados datetime ou interval detalhado (SQL_DATETIME ou SQL_INTERVAL) e o campo SQL_DESC_DATETIME_INTERVAL_CODE for definido como o subcódigo apropriado, o campo TYPE SQL_DESC_CONCISE será definido como o tipo conciso correspondente. Tentar definir SQL_DESC_TYPE como um dos tipos concisos de datetime ou intervalo retornará SQLSTATE HY021 (informações de descritor inconsistentes).
Quando o campo SQL_DESC_TYPE é definido por uma chamada para SQLBindCol, SQLBindParameter ou SQLSetDescField, os campos a seguir são definidos com os seguintes valores padrão, conforme mostrado na tabela abaixo. Os valores dos campos restantes do mesmo registro são indefinidos.
| Valor de SQL_DESC_TYPE | Outros campos definidos implicitamente |
|---|---|
| SQL_CHAR, SQL_VARCHAR, SQL_C_CHAR, SQL_C_VARCHAR | SQL_DESC_LENGTH está definido como 1. SQL_DESC_PRECISION está definido como 0. |
| SQL_DATETIME | Quando SQL_DESC_DATETIME_INTERVAL_CODE é definido como SQL_CODE_DATE ou SQL_CODE_TIME, SQL_DESC_PRECISION é definido como 0. Quando é definido como SQL_DESC_TIMESTAMP, SQL_DESC_PRECISION é definido como 6. |
| SQL_DECIMAL, SQL_NUMERIC, SQL_C_NUMERIC | SQL_DESC_SCALE está definido como 0. SQL_DESC_PRECISION é definido como a precisão definida pela implementação para o respectivo tipo de dados. Consulte SQL to C: Numérico para obter informações sobre como associar manualmente um valor de SQL_C_NUMERIC. |
| SQL_FLOAT, SQL_C_FLOAT | SQL_DESC_PRECISION é definido como a precisão padrão definida pela implementação para SQL_FLOAT. |
| SQL_INTERVAL | Quando SQL_DESC_DATETIME_INTERVAL_CODE é definido como um tipo de dados de intervalo, SQL_DESC_DATETIME_INTERVAL_PRECISION é definido como 2 (a precisão à esquerda do intervalo padrão). Quando o intervalo tem um componente de segundos, SQL_DESC_PRECISION é definido como 6 (a precisão de segundos de intervalo padrão). |
Quando um aplicativo chama SQLSetDescField para definir campos de um descritor em vez de chamar SQLSetDescRec, o aplicativo deve primeiro declarar o tipo de dados. Quando isso acontece, os outros campos indicados na tabela anterior são definidos implicitamente. Se qualquer um dos valores definidos implicitamente for inaceitável, o aplicativo poderá chamar SQLSetDescField ou SQLSetDescRec para definir o valor inaceitável explicitamente.
SQL_DESC_TYPE_NAME [Descritores de implementação]
Esse campo de registro SQLCHAR * somente leitura contém o nome do tipo dependente da fonte de dados (por exemplo, "CHAR", "VARCHAR" e assim por diante). Se o nome do tipo de dados for desconhecido, essa variável conterá uma cadeia de caracteres vazia.
SQL_DESC_UNNAMED [Descritores de implementação]
Esse campo de registro SQLSMALLINT em um descritor de linha é definido pelo driver como SQL_NAMED ou SQL_UNNAMED quando define o campo SQL_DESC_NAME. Se o campo SQL_DESC_NAME contiver um alias de coluna ou se o alias da coluna não se aplicar, o driver definirá o campo SQL_DESC_UNNAMED como SQL_NAMED. Se um aplicativo definir o campo SQL_DESC_NAME de um IPD como um nome de parâmetro ou alias, o driver definirá o campo SQL_DESC_UNNAMED do IPD como SQL_NAMED. Se não houver um nome de coluna ou um alias de coluna, o driver definirá o campo SQL_DESC_UNNAMED como SQL_UNNAMED.
Um aplicativo pode definir o campo SQL_DESC_UNNAMED de um IPD como SQL_UNNAMED. Um driver retornará SQLSTATE HY091 (identificador de campo de descritor inválido) se um aplicativo tentar definir o campo SQL_DESC_UNNAMED de um IPD como SQL_NAMED. O campo SQL_DESC_UNNAMED de um IRD é somente leitura; SQLSTATE HY091 (identificador de campo de descritor inválido) será retornado se um aplicativo tentar defini-lo.
SQL_DESC_UNSIGNED [Descritores de implementação]
Esse campo de registro SQLSMALLINT somente leitura será definido como SQL_TRUE se o tipo de coluna não for assinado ou não numérico ou SQL_FALSE se o tipo de coluna estiver assinado.
SQL_DESC_UPDATABLE [IRDs]
Esse campo de registro SQLSMALLINT somente leitura é definido como um dos seguintes valores:
SQL_ATTR_READ_ONLY se a coluna do conjunto de resultados for somente leitura.
SQL_ATTR_WRITE se a coluna do conjunto de resultados for leitura/gravação.
SQL_ATTR_READWRITE_UNKNOWN se não se sabe se a coluna do conjunto de resultados é atualizável ou não.
SQL_DESC_UPDATABLE descreve a atualização da coluna no conjunto de resultados, não a coluna na tabela base. A updatability da coluna na tabela base na qual essa coluna do conjunto de resultados se baseia pode ser diferente do valor nesse campo. Se uma coluna é atualizável pode ser baseada no tipo de dados, privilégios de usuário e na definição do próprio conjunto de resultados. Se não estiver claro se uma coluna é atualizável, SQL_ATTR_READWRITE_UNKNOWN deve ser retornado.
Verificações de consistência
Uma verificação de consistência é executada pelo driver automaticamente sempre que um aplicativo passa um valor para o campo SQL_DESC_DATA_PTR do ARD, APD ou IPD. Se qualquer um dos campos for inconsistente com outros campos, SQLSetDescField retornará SQLSTATE HY021 (informações inconsistentes do descritor). Para obter mais informações, confira "Verificação de consistência" em SQLSetDescRec.
Funções relacionadas
| Para obter informações sobre | Consulte |
|---|---|
| Associando uma coluna | Função SQLBindCol |
| Associando um parâmetro | Função SQLBindParameter |
| Obtendo um campo de descritor | Função SQLGetDescField |
| Obtendo vários campos de descritor | Função SQLGetDescRec |
| Definindo vários campos de descritor | Função SQLSetDescRec |
Consulte Também
Comentários
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulte https://aka.ms/ContentUserFeedback.
Enviar e exibir comentários de