Função SQLColumnPrivileges

  • Artigo

Conformidade
Versão introduzida: Conformidade de padrões do ODBC 1.0: ODBC

Resumo
SQLColumnPrivileges retorna uma lista de colunas e privilégios associados para a tabela especificada. O driver retorna as informações como um conjunto de resultados no StatementHandle especificado.

Sintaxe

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

Argumentos

StatementHandle
[Entrada] Identificador de instrução.

Catalogname
[Entrada] Nome do catálogo. Se um driver der suporte a nomes para alguns catálogos, mas não para outros, como quando o driver recupera dados de DBMSs diferentes, uma cadeia de caracteres vazia ("") indica os catálogos que não têm nomes. CatalogName não pode conter um padrão de pesquisa de cadeia de caracteres.

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

NameLength1
[Entrada] Comprimento em caracteres de *CatalogName.

Schemaname
[Entrada] Nome do esquema. Se um driver der suporte a esquemas para algumas tabelas, mas não para outras, como quando o driver recupera dados de DBMSs diferentes, uma cadeia de caracteres vazia ("") indica essas tabelas que não têm esquemas. SchemaName não pode conter um padrão de pesquisa de cadeia de caracteres.

Se o atributo de instrução SQL_ATTR_METADATA_ID estiver definido como SQL_TRUE, SchemaName será tratado como um identificador. Se for SQL_FALSE, SchemaName será um argumento comum; é tratado literalmente, e seu caso é significativo.

NameLength2
[Entrada] Comprimento em caracteres de *SchemaName.

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

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

NameLength3
[Entrada] Comprimento em caracteres de *TableName.

ColumnName
[Entrada] Padrão de pesquisa de cadeia de caracteres para nomes de coluna.

Se o atributo de instrução SQL_ATTR_METADATA_ID estiver definido como SQL_TRUE, ColumnName será tratado como um identificador e seu caso não será significativo. Se for SQL_FALSE, ColumnName será um argumento de valor padrão; é tratado literalmente, e seu caso é significativo.

NameLength4
[Entrada] Comprimento em caracteres de *ColumnName.

Retornos

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_STILL_EXECUTING, SQL_ERROR ou SQL_INVALID_HANDLE.

Diagnósticos

Quando SQLColumnPrivileges 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 Identificador de StatementHandle. A tabela a seguir lista os valores SQLSTATE normalmente retornados por SQLColumnPrivileges 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 o contrário.

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 foi conectado falhou antes da função concluir o processamento.
24.000 Estado de cursor inválido Um cursor foi aberto no StatementHandle e SQLFetch ou SQLFetchScroll foram chamados. Esse erro será retornado pelo Gerenciador de Driver se SQLFetch ou SQLFetchScroll não tiver retornado SQL_NO_DATA e for retornado pelo driver se SQLFetch ou SQLFetchScroll tiver retornado SQL_NO_DATA.

Um cursor foi aberto no StatementHandle, mas SQLFetch ou SQLFetchScroll não foram chamados.
40001 Falha na 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 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.
HY008 Operação cancelada O processamento assíncrono foi habilitado para 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 O argumento TableName era um ponteiro nulo.

O atributo de instrução SQL_ATTR_METADATA_ID foi definido como SQL_TRUE, o argumento CatalogName era um ponteiro nulo e o SQL_CATALOG_NAME InfoType retorna que há suporte para nomes de catálogo.

(DM) O atributo de instrução SQL_ATTR_METADATA_ID foi definido como SQL_TRUE e o argumento SchemaName ou ColumnName era um ponteiro nulo.
HY010 Erro de sequência de funções (DM) Uma função em 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 essa função foi chamada.

(DM) SQLExecute, SQLExecDirect ou SQLMoreResults foi chamado para StatementHandle e retornado SQL_PARAM_DATA_AVAILABLE. Essa função foi 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) foi chamada para StatementHandle e ainda estava em execução quando essa função foi chamada.

(DM) SQLExecute, SQLExecDirect, SQLBulkOperations ou SQLSetPos foram chamados para StatementHandle e retornados 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.
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 Comprimento de buffer ou cadeia de caracteres inválida (DM) O valor de um dos argumentos de comprimento do nome era menor que 0, mas não igual a SQL_NTS.
O valor de um dos argumentos de comprimento do nome excedeu o valor de comprimento máximo para o nome correspondente. (Confira "Comentários".)
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 Função SQLEndTran.
HYC00 Recurso opcional não implementado Um nome de catálogo foi especificado e o driver ou fonte de dados não dá suporte a catálogos.

Um nome de esquema foi especificado e o driver ou fonte de dados não dá suporte a esquemas.

Um padrão de pesquisa de cadeia de caracteres foi especificado para o nome da coluna e a fonte de dados não dá suporte a padrões de pesquisa para esse argumento.

A combinação das configurações atuais dos atributos de instrução SQL_CONCURRENCY e SQL_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 esgotado O período de tempo limite da consulta expirou antes da fonte de dados retornar o conjunto de resultados. 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 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 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.

Comentários

SQLColumnPrivileges retorna os resultados como um conjunto de resultados padrão, ordenado por TABLE_CAT, TABLE_SCHEM, TABLE_NAME, COLUMN_NAME e PRIVILEGE.

Observação

SQLColumnPrivileges pode não retornar privilégios para todas as colunas. Por exemplo, um driver pode não retornar informações sobre privilégios para pseudo-colunas, como Oracle ROWID. Os aplicativos podem usar qualquer coluna válida, independentemente de ela ser retornada por SQLColumnPrivileges.

Os comprimentos das colunas VARCHAR não são mostrados na tabela; os comprimentos reais dependem da fonte de dados. Para determinar os comprimentos reais das colunas CATALOG_NAME, SCHEMA_NAME, TABLE_NAME e COLUMN_NAME, um aplicativo pode chamar 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.

Observação

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.

As colunas a seguir foram renomeada para ODBC 3. x. As alterações no nome da coluna não afetam a compatibilidade com versões anteriores porque os aplicativos são associados por número de coluna.

Coluna ODBC 2.0 ODBC 3. coluna x
TABLE_QUALIFIER TABLE_CAT
TABLE_OWNER TABLE_SCHEM

A tabela a seguir lista as colunas no conjunto de resultados. Colunas adicionais além da coluna 8 (IS_GRANTABLE) podem ser definidas pelo driver. Um aplicativo deve obter acesso 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 obter mais informações, consulte Dados retornados por funções de catálogo.

Nome da coluna Número da coluna Tipo de dados Comentários
TABLE_CAT (ODBC 1.0) 1 Varchar Identificador de catálogo; NULL se não for aplicável à fonte de dados. Se um driver der suporte a catálogos para algumas tabelas, mas não para outras, como quando o driver recupera dados de DBMSs diferentes, ele retorna uma cadeia de caracteres vazia ("") para as tabelas que não têm catálogos.
TABLE_SCHEM (ODBC 1.0) 2 Varchar Identificador de esquema; NULL se não for aplicável à fonte de dados. Se um driver der suporte a esquemas para algumas tabelas, mas não para outras, como quando o driver recupera dados de DBMSs diferentes, ele retorna uma cadeia de caracteres vazia ("") para as tabelas que não têm esquemas.
TABLE_NAME (ODBC 1.0) 3 Varchar não NULL Identificador de tabela.
COLUMN_NAME (ODBC 1.0) 4 Varchar não NULL Nome da coluna. O driver retorna uma cadeia de caracteres vazia para uma coluna que não tem um nome.
GRANTOR (ODBC 1.0) 5 Varchar Nome do usuário que concedeu o privilégio; NULL se não for aplicável à fonte de dados.

Para todas as linhas nas quais o valor na coluna GRANTEE é o proprietário do objeto , a coluna GRANTOR será "_SYSTEM".
GRANTEE (ODBC 1.0) 6 Varchar não NULL Nome do usuário ao qual o privilégio foi concedido.
PRIVILEGE (ODBC 1.0) 7 Varchar não NULL Identifica o privilégio da coluna. Pode ser um dos seguintes (ou outros compatíveis com a fonte de dados quando definido pela implementação):

SELECT: o usuário autorizado tem permissão para recuperar dados para a coluna.

INSERT: o usuário autorizado tem permissão para fornecer dados para a coluna em novas linhas que são inseridas na tabela associada.

UPDATE: o usuário autorizado tem permissão para atualizar dados na coluna.

REFERÊNCIAS: o usuário autorizado tem permissão para fazer referência à coluna dentro de uma restrição (por exemplo, uma restrição exclusiva, referencial ou de verificação de tabela).
IS_GRANTABLE (ODBC 1.0) 8 Varchar Indica se o usuário autorizado tem permissão para conceder o privilégio a outros usuários; "SIM", "NÃO" ou "NULL" se for desconhecido ou não aplicável à fonte de dados.

Um privilégio é concedido ou não é permitido, mas não ambos. O conjunto de resultados retornado por SQLColumnPrivileges nunca conterá duas linhas para as quais todas as colunas, exceto a coluna IS_GRANTABLE, contêm o mesmo valor.

Exemplo de código

Para obter um exemplo de código de uma função semelhante, consulte Função SQLColumns.

Para obter informações sobre Consulte
Associar um buffer a uma coluna em um conjunto de resultados Função SQLBindCol
Cancelando o processamento de instruções Função SQLCancel
Retornando as colunas em uma tabela ou tabelas Função SQLColumns
Buscar um bloco de dados ou rolar por um conjunto de resultados Função SQLFetchScroll
Buscar várias linhas de dados Função SQLFetch
Retornando privilégios para uma tabela ou tabela Função SQLTablePrivileges
Retornando uma lista de tabelas em uma fonte de dados Função SQLTables

Consulte Também

Referência de API do ODBC
Arquivos de cabeçalho ODBC