Função SQLPrimaryKeys

Conformidade
Versão Introduzida: Conformidade com os Padrões ODBC 1.0: ODBC

Summary
SQLPrimaryKeys retorna os nomes das colunas que compõem a chave primária de uma tabela. O driver retorna as informações como um conjunto de resultados. Essa função não suporta o retorno de chaves primárias de múltiplas tabelas em uma única chamada.

Sintaxe

  
SQLRETURN SQLPrimaryKeys(  
     SQLHSTMT       StatementHandle,  
     SQLCHAR *      CatalogName,  
     SQLSMALLINT    NameLength1,  
     SQLCHAR *      SchemaName,  
     SQLSMALLINT    NameLength2,  
     SQLCHAR *      TableName,  
     SQLSMALLINT    NameLength3);

Argumentos

Identificador de declaração
[Entrada] Identificador de instrução.

Catalogname
[Entrada] Nome do catálogo. Se um driver suporta catálogos para algumas tabelas, mas não para outras, como quando o driver recupera dados de diferentes DBMSs, uma string vazia ("") denota aquelas tabelas que não possuem catálogos. CatalogName não pode conter um padrão de busca em string.

Se o atributo da instrução SQL_ATTR_METADATA_ID for definido como SQL_TRUE, CatalogName é tratado como um identificador e seu caso não é significativo. Se for SQL_FALSE, Nome do Catálogo é um argumento comum; É tratado literalmente, e seu caso é significativo. Para obter mais informações, confira Argumentos em funções de catálogo.

NameLength1
[Entrada] Comprimento em caracteres de *NomeDeCatálogo.

Nome do esquema
[Entrada] Nome do esquema. Se um driver suporta esquemas para algumas tabelas, mas não para outras, como quando o driver recupera dados de diferentes SGBDs, uma string vazia ("") denota aquelas tabelas que não possuem esquemas. O NomeSchema não pode conter um padrão de busca em string.

Se o atributo da instrução SQL_ATTR_METADATA_ID for definido como SQL_TRUE, SchemaName é tratado como um identificador e seu caso não é significativo. Se for SQL_FALSE, NomeEsquema é um argumento comum; É tratado literalmente, e seu caso não é significativo.

NameLength2
[Entrada] Comprimento em caracteres de *NomeEsquema.

TableName
[Entrada] Nome da tabela. Esse argumento não pode ser um ponto nulo. TableName não pode conter um padrão de busca em cadeia de caracteres.

Se o atributo da instrução SQL_ATTR_METADATA_ID for definido como SQL_TRUE, TableName é tratado como um identificador e seu caso não é significativo. Se for SQL_FALSE, Nome da Tabela é um argumento comum; É tratado literalmente, e seu caso não é significativo.

NameLength3
[Entrada] Comprimento em caracteres de *NomeTaula.

Returns

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_STILL_EXECUTING, SQL_ERROR ou SQL_INVALID_HANDLE.

Diagnostics

Quando SQLPrimaryKeys retorna SQL_ERROR ou SQL_SUCCESS_WITH_INFO, um valor SQLSTATE associado pode ser obtido chamando SQLGetDiagRec com um HandleType de SQL_HANDLE_STMT e um Handle de StatementHandle. A tabela a seguir lista os valores SQLSTATE comumente retornados pelo SQLPrimaryKeys e explica cada um no contexto dessa função; a notação "(DM)" precede as descrições dos SQLSTATEs retornadas pelo Gerenciador de Drivers. 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.)
08S01	Falha no link de comunicação	O link de comunicação entre o driver e a fonte de dados à qual o driver estava conectado falhou antes que a função concluísse o processamento.
24000	Estado de cursor inválido	(DM) Um cursor estava aberto no StatementHandle e SQLFetch ou SQLFetchScroll havia sido chamado. Um cursor estava aberto no StatementHandle, mas SQLFetch ou SQLFetchScroll não haviam sido chamados.
40001	Falha de serialização	A transação foi revertida devido a um deadlock de recursos com outra transação.
40003	Conclusão da instrução desconhecida	A conexão associada falhou durante a execução dessa função e o estado da transação não pode ser determinado.
HY000	Erro geral	Ocorreu um erro para o qual não havia 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.
HY008	Operação cancelada	O processamento assíncrono foi habilitado para o StatementHandle. A função foi chamada e, antes de concluir a execução, SQLCancel ou SQLCancelHandle foi chamado no StatementHandle. Em seguida, a função foi chamada novamente no StatementHandle. A função foi chamada e, antes de concluir a execução, SQLCancel ou SQLCancelHandle foi chamado no StatementHandle de um thread diferente em um aplicativo multithread.
HY009	Uso inválido de ponteiro nulo	(DM) O argumento TableName era um ponteiro nulo. O atributo da instrução SQL_ATTR_METADATA_ID era definido como SQL_TRUE, o argumento CatalogName era um ponteiro nulo, e SQLGetInfo , com o tipo de informação SQL_CATALOG_NAME, retorna que nomes de catálogo são suportados. (DM) O atributo da instrução SQL_ATTR_METADATA_ID foi definido como SQL_TRUE, e o argumento SchemaName era um ponteiro nulo.
HY010	Erro de sequência de função	(DM) Uma função de execução assíncrona foi chamada para o identificador de conexão associado ao StatementHandle. Essa função assíncrona ainda estava em execução quando a função SQLPrimaryKeys foi chamada. (DM) SQLExecute, SQLExecDirect ou SQLMoreResults foi chamado para o StatementHandle e retornado SQL_PARAM_DATA_AVAILABLE. Essa função foi chamada antes que os dados fossem recuperados para todos os parâmetros transmitidos. (DM) Uma função de execução assíncrona (não esta) foi chamada para o StatementHandle e ainda estava em execução quando essa função foi chamada. (DM) SQLExecute, SQLExecDirect, SQLBulkOperations ou SQLSetPos foi chamado para o StatementHandle e retornado SQL_NEED_DATA. Essa função foi chamada antes que os dados fossem enviados para todos os parâmetros ou colunas de dados em execução.
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.
HY090	Cadeia de caracteres ou comprimento de buffer inválido	(DM) O valor de um dos argumentos do comprimento do nome era menor que 0, mas não igual a SQL_NTS, e o argumento associado ao nome não é um ponteiro nulo. O valor de um dos argumentos de comprimento do nome excedeu o valor máximo de comprimento para o nome correspondente.
HY117	A conexão está suspensa devido ao estado desconhecido da transação. Somente funções de desconexão e somente leitura são permitidas.	(DM) Para obter mais informações sobre o estado suspenso, consulte Função SQLEndTran.
HYC00	Recurso opcional não implementado	Um catálogo foi especificado, e o driver ou fonte de dados não suporta catálogos. Um esquema foi especificado e o driver ou fonte de dados não suporta esquemas. A combinação das configurações atuais dos atributos de instrução SQL_ATTR_CONCURRENCY e SQL_ATTR_CURSOR_TYPE não era compatível com o driver ou a fonte de dados. O atributo de instrução SQL_ATTR_USE_BOOKMARKS foi definido como SQL_UB_VARIABLE e o atributo de instrução SQL_ATTR_CURSOR_TYPE foi definido como um tipo de cursor para o qual o driver não dá suporte a indicadores.
HYT00	Tempo limite expirado	O período de tempo expirou antes que a fonte de dados retornasse o conjunto de resultados solicitado. O período de tempo limite é definido por meio de SQLSetStmtAttr, SQL_ATTR_QUERY_TIMEOUT.
HYT01	O tempo limite da conexão expirou	O período de tempo limite da conexão expirou antes que a fonte de dados respondesse à 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 suporta esta função	(DM) O driver associado ao StatementHandle não dá suporte à função.
IM017	A sondagem está desabilitada no modo de notificação assíncrona	Sempre que o modelo de notificação é usado, a sondagem é desabilitada.
IM018	SQLCompleteAsync não foi chamado para concluir a operação assíncrona anterior nesse identificador.	Se a chamada de função anterior no identificador retornar SQL_STILL_EXECUTING e se o modo de notificação estiver habilitado, SQLCompleteAsync deverá ser chamado no identificador para fazer o pós-processamento e concluir a operação.

Comments

SQLPrimaryKeys retorna os resultados como um conjunto padrão de resultados, ordenado por TABLE_CAT, TABLE_SCHEM, TABLE_NAME e KEY_SEQ. Para obter informações sobre como essas informações podem ser usadas, consulte Usos de dados de catálogo.

As colunas a seguir foram renomeadas para ODBC 3.x. As mudanças no nome das colunas não afetam a compatibilidade retroativa porque as aplicações são vinculadas por número de coluna.

Coluna ODBC 2.0	ODBC 3.coluna x
QUALIFICADOR_DE_TABELA	TABLE_CAT
PROPRIETÁRIO_DA_TABELA	TABLE_SCHEM

Para determinar os comprimentos reais das colunas TABLE_CAT, TABLE_SCHEM, TABLE_NAME e COLUMN_NAME, ligue para o SQLGetInfo com as opções SQL_MAX_CATALOG_NAME_LEN, SQL_MAX_SCHEMA_NAME_LEN, SQL_MAX_TABLE_NAME_LEN e SQL_MAX_COLUMN_NAME_LEN.

Note

Para obter mais informações sobre o uso geral, argumentos e dados retornados de funções de catálogo ODBC, consulte Funções de Catálogo.

A tabela a seguir lista as colunas no conjunto de resultados. Colunas adicionais além da coluna 6 (PK_NAME) podem ser definidas pelo driver. Uma aplicação deve obter acesso a colunas específicas do driver contando regressivamente a partir do final do conjunto de resultados, em vez de especificar uma posição ordinal explícita. Para obter mais informações, consulte Dados Retornados por Funções de Catálogo.

Nome da Coluna	Número da coluna	Tipo de dados	Comments
TABLE_CAT (ODBC 1.0)	1	Varchar	Nome do catálogo da tabela de chaves primárias; NULL se não aplicável à fonte de dados. Se um driver suporta catálogos para algumas tabelas, mas não para outras, como quando o driver recupera dados de diferentes DBMSs, ele retorna uma string vazia ("") para aquelas tabelas que não possuem catálogos.
TABLE_SCHEM (ODBC 1.0)	2	Varchar	Nome do esquema da tabela de chaves primárias; NULL se não aplicável à fonte de dados. Se um driver suporta esquemas para algumas tabelas, mas não para outras, como quando o driver recupera dados de diferentes DBMSs, ele retorna uma string vazia ("") para aquelas tabelas que não possuem esquemas.
TABLE_NAME (ODBC 1.0)	3	Varchar não é NULL	Nome da tabela de chave primária.
COLUMN_NAME (ODBC 1.0)	4	Varchar não é NULL	Nome da coluna principal. O driver retorna uma string vazia para uma coluna que não tem nome.
KEY_SEQ (ODBC 1.0)	5	Smallint não NULL	Número da sequência da coluna em chave (começando com 1).
PK_NAME (ODBC 2.0)	6	Varchar	Nome chave primário. NULL se não aplicável à fonte de dados.

Exemplo de código

Veja SQLForeignKeys.

Para obter informações sobre	Veja
Associando um buffer a uma coluna em um conjunto de resultados	Função SQLBindCol
Cancelando o processamento de instruções	Função SQLCancel
Buscando um bloco de dados ou rolando por um conjunto de resultados	Função SQLFetchScroll
Buscar uma única linha ou um bloco de dados em direção apenas direta	Função SQLFetch
Retornando as colunas de chaves estrangeiras	Função SQLForeignKeys
Retornando estatísticas e índices de tabelas	Função SQLStatistics

Comentários

Esta página foi útil?

Last updated on 2026-08-24