Função SQLPrimaryKeys

Conformidade
Versão Introduzida: Conformidade com as Normas ODBC 1.0: ODBC

Summary
SQLPrimaryKeys devolve os nomes das colunas que compõem a chave primária de uma tabela. O condutor devolve a informação como conjunto de resultados. Esta função não suporta o retorno de chaves primárias de múltiplas tabelas numa única chamada.

Syntax

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

Arguments

HandleStatement
[Entrada] Identificador do extrato.

Nome do Catálogo
[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 SGBD, uma string vazia ("") indica as tabelas que não têm catálogos. O CatalogName não pode conter um padrão de pesquisa em cadeia de caracteres.

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

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

Nome do esquema
[Entrada] Nome do esquema. Se um driver suportar esquemas para algumas tabelas mas não para outras, como quando o driver recupera dados de diferentes SGBD, uma cadeia vazia ("") denota as tabelas que não têm esquemas. O Nome do Esquema não pode conter um padrão de pesquisa de cadeias de caracteres.

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

NomeComprimento2
[Entrada] Comprimento em caracteres de *NomeEsquema.

TableName
[Entrada] Nome da mesa. Este argumento não pode ser um ponto nulo. O TableName não pode conter um padrão de pesquisa de strings.

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

NomeComprimento3
[Entrada] Comprimento em caracteres de *NomeTabela.

Devoluções

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_STILL_EXECUTING, SQL_ERROR ou SQL_INVALID_HANDLE.

Diagnósticos

Quando o SQLPrimaryKeys retorna SQL_ERROR ou SQL_SUCCESS_WITH_INFO, pode ser obtido um valor SQLSTATE associado ao chamar SQLGetDiagRec com um HandleType de SQL_HANDLE_STMT e um Handle de StatementHandle. A tabela seguinte lista os valores SQLSTATE normalmente devolvidos pelo SQLPrimaryKeys e explica cada um no contexto desta função; a notação "(DM)" precede as descrições dos SQLSTATEs devolvidas pelo Gestor de Drivers. O código de retorno associado a cada valor SQLSTATE é SQL_ERROR, salvo indicação em contrário.

SQLSTATE	Erro	Descrição
01000	Aviso geral	Mensagem informativa específica para o condutor. (Função devolve SQL_SUCCESS_WITH_INFO.)
08S01	Falha da ligação de comunicação	A ligação de comunicação entre o driver e a fonte de dados à qual o driver estava ligado falhou antes de a função concluir o processamento.
24000	Estado do cursor inválido	(DM) Um cursor estava aberto no HandleStatement, e SQLFetch ou SQLFetchScroll tinham sido chamados. Um cursor estava aberto no StatementHandle, mas SQLFetch ou SQLFetchScroll não tinham sido chamados.
40001	Falha de serialização	A transação foi revertida devido a um bloqueio de recursos com outra transação.
40003	Conclusão da afirmação desconhecida	A ligação associada falhou durante a execução desta função, e o estado da transação não pode ser determinado.
HY000	Erro geral	Ocorreu um erro para o qual não existia um SQLSTATE específico e para o qual não estava definido nenhum SQLSTATE específico da implementação. A mensagem de erro devolvida pelo SQLGetDiagRec no buffer MessageText* descreve o erro e a sua causa.
HY001	Erro de alocação de memória	O driver não conseguia alocar a memória necessária para suportar a execução ou conclusão da função.
HY008	Operação cancelada	O processamento assíncrono foi ativado para o StatementHandle. A função era chamada e, antes de terminar a execução, o SQLCancel ou SQLCancelHandle era chamado no StatementHandle. Depois, a função era chamada novamente no StatementHandle. A função era chamada e, antes de terminar a execução, o SQLCancel ou SQLCancelHandle era chamado no StatementHandle a partir de um thread diferente numa aplicação multithread.
HY009	Uso inválido do 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 o SQLGetInfo com o tipo de informação SQL_CATALOG_NAME devolve que os nomes de catálogo são suportados. (DM) O atributo da SQL_ATTR_METADATA_ID instrução foi definido para SQL_TRUE, e o argumento SchemaName era um ponteiro nulo.
HY010	Erro de sequência de funções	(DM) Uma função de execução assíncrona era chamada para o handle de ligação associado ao StatementHandle. Esta função assíncrona ainda estava a ser executada quando a função SQLPrimaryKeys foi chamada. (DM) SQLExecute, SQLExecDirect ou SQLMoreResults era chamado para o StatementHandle e devolvido SQL_PARAM_DATA_AVAILABLE. Esta função era chamada antes de os dados serem recuperados para todos os parâmetros transmitidos. (DM) Uma função de execução assíncrona (não esta) era chamada para o StatementHandle e continuava a ser executada quando esta função era chamada. (DM) SQLExecute, SQLExecDirect, SQLBulkOperations ou SQLSetPos era chamado para o StatementHandle e devolvido SQL_NEED_DATA. Esta função era chamada antes de os dados serem enviados para todos os parâmetros ou colunas de dados na execução.
HY013	Erro de gestão de memória	A chamada de função não podia ser processada porque os objetos de memória subjacentes não podiam ser acedidos, possivelmente devido a condições de baixa memória.
HY090	Comprimento inválido da corda ou do buffer	(DM) O valor de um dos argumentos do comprimento do nome era inferior a 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 do comprimento do nome excedia o valor máximo de comprimento do nome correspondente.
HY117	A ligação é suspensa devido ao estado desconhecido da transação. Apenas funções de desconexão e de leitura são permitidas.	(DM) Para mais informações sobre o estado suspenso, veja Função SQLEndTran.
HYC00	Funcionalidade opcional não implementada	Foi especificado um catálogo, e o driver ou fonte de dados não suporta catálogos. Foi especificado um esquema e o driver ou fonte de dados não suporta esquemas. A combinação das definições atuais dos atributos SQL_ATTR_CONCURRENCY e SQL_ATTR_CURSOR_TYPE da instrução não era suportada pelo driver ou pela fonte de dados. O atributo da instrução SQL_ATTR_USE_BOOKMARKS foi definido para SQL_UB_VARIABLE, e o atributo da instrução SQL_ATTR_CURSOR_TYPE foi definido para um tipo de cursor para o qual o driver não suporta favoritos.
HYT00	O tempo limite expirou	O período de tempo expirou antes de a fonte de dados devolver o conjunto de resultados solicitado. O período de tempo é definido através do SQLSetStmtAttr, SQL_ATTR_QUERY_TIMEOUT.
HYT01	Expirou o tempo limite de ligação	O período de timeout da ligação expirou antes de a fonte de dados responder ao pedido. O período de tempo de expiração da ligação é definido através do SQLSetConnectAttr, SQL_ATTR_CONNECTION_TIMEOUT.
IM001	O driver não suporta esta função	(DM) O driver associado ao StatementHandle não suporta a função.
IM017	A sondagem está desativada no modo de notificação assíncrona	Sempre que o modelo de notificação é utilizado, o sonding é desativado.
IM018	O SQLCompleteAsync não foi chamado para completar a operação assíncrona anterior neste handle.	Se a chamada de função anterior no handle devolver SQL_STILL_EXECUTING e se o modo de notificação estiver ativado, o SQLCompleteAsync deve ser chamado no handle para fazer o pós-processamento e completar a operação.

Comments

SQLPrimaryKeys devolve os resultados como um conjunto de resultados padrão, ordenado por TABLE_CAT, TABLE_SCHEM, TABLE_NAME e KEY_SEQ. Para informações sobre como esta informação pode ser utilizada, consulte Utilizações dos Dados de Catálogo.

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

Coluna ODBC 2.0	ODBC 3. Coluna X
TABLE_QUALIFIER	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 ao 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 mais informações sobre o uso geral, argumentos e dados devolvidos das funções de catálogo ODBC, consulte Funções de Catálogo.

A tabela seguinte lista as colunas do conjunto de resultados. Colunas adicionais para além da coluna 6 (PK_NAME) podem ser definidas pelo driver. Uma aplicação deve aceder a colunas específicas do driver contando a partir do final do conjunto de resultados, em vez de especificar uma posição ordinal explícita. Para mais informações, consulte Dados Devolvidos 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 for aplicável à fonte de dados. Se um driver suportar catálogos para algumas tabelas mas não para outras, como quando o driver recupera dados de diferentes SGBD, devolve uma string vazia ("") para as tabelas que não têm catálogos.
TABLE_SCHEM (ODBC 1.0)	2	Varchar	Nome do esquema da tabela de chaves primárias; NULL se não for aplicável à fonte de dados. Se um controlador suportar esquemas para algumas tabelas mas não para outras, como quando recupera dados de diferentes SGBD, devolve uma cadeia vazia ("") para as tabelas que não têm esquemas.
TABLE_NAME (ODBC 1.0)	3	Varchar não NULL	Nome principal da tabela de chaves.
COLUMN_NAME (ODBC 1.0)	4	Varchar não NULL	Nome da coluna chave principal. O driver devolve uma cadeia vazia para uma coluna que não tem nome.
KEY_SEQ (ODBC 1.0)	5	Smallint not NULL	Número de sequência da coluna em tonalidade (começando por 1).
PK_NAME (ODBC 2.0)	6	Varchar	Nome-chave principal. NULL se não for aplicável à fonte de dados.

Exemplo de código

Veja SQLForeignKeys.

Para obter informações sobre	Veja
Ligar um buffer a uma coluna num conjunto de resultados	Função SQLBindCol
Cancelamento do processamento de extratos	Função SQLCancel
Buscar um bloco de dados ou percorrer um conjunto de resultados	Função SQLFetchScroll
Obter uma única linha ou um bloco de dados numa direção apenas direta	Função SQLFetch
Devolvendo as colunas de chaves estrangeiras	Função SQLForeignKeys
Estatísticas e índices de tabela de retorno	Função SQLStatistics

Comentários

Esta página foi útil?

Last updated on 2026-08-24