Função SQLProcedureColumns
Conformidade
Versão introduzida: ODBC 1.0 Standards Compliance: ODBC
Resumo
SQLProcedureColumns retorna a lista de parâmetros de entrada e saída, bem como as colunas que compõem o conjunto de resultados para os procedimentos especificados. O driver retorna as informações como um conjunto de resultados na instrução especificada.
Sintaxe
SQLRETURN SQLProcedureColumns(
SQLHSTMT StatementHandle,
SQLCHAR * CatalogName,
SQLSMALLINT NameLength1,
SQLCHAR * SchemaName,
SQLSMALLINT NameLength2,
SQLCHAR * ProcName,
SQLSMALLINT NameLength3,
SQLCHAR * ColumnName,
SQLSMALLINT NameLength4);
Argumentos
StatementHandle
[Entrada] Identificador de instrução.
Catalogname
[Entrada] Nome do catálogo de procedimentos. Se um driver der suporte a catálogos para alguns procedimentos, mas não para outros, como quando o driver recupera dados de DBMSs diferentes, uma cadeia de caracteres vazia ("") indica os procedimentos que não têm catálogos. 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] Padrão de pesquisa de cadeia de caracteres para nomes de esquema de procedimento. Se um driver der suporte a esquemas para alguns procedimentos, mas não para outros, como quando o driver recupera dados de DBMSs diferentes, uma cadeia de caracteres vazia ("") indica os procedimentos que não têm esquemas.
Se o atributo de instrução SQL_ATTR_METADATA_ID estiver definido como SQL_TRUE, SchemaName será tratado como um identificador e seu caso não será significativo. Se for SQL_FALSE, SchemaName será um argumento de valor padrão; é tratado literalmente, e seu caso é significativo.
NameLength2
[Entrada] Comprimento em caracteres de *SchemaName.
Procname
[Entrada] Padrão de pesquisa de cadeia de caracteres para nomes de procedimento.
Se o atributo de instrução SQL_ATTR_METADATA_ID estiver definido como SQL_TRUE, ProcName será tratado como um identificador e seu caso não será significativo. Se for SQL_FALSE, ProcName será um argumento de valor padrão; é tratado literalmente, e seu caso é significativo.
NameLength3
[Entrada] Comprimento em caracteres de *ProcName.
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 SQLProcedureColumns 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 SQLProcedureColumns 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.) |
| 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. |
| 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 | Falha na conexão associada 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 SQLError 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 | 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, ProcName ou ColumnName era um ponteiro nulo. |
| HY010 | Erro de sequência de funções | (DM) Uma função de execução assíncrona foi chamada para o identificador de conexão associado ao StatementHandle. Essa função aynschronous ainda estava em execução quando a função SQLProcedureColumns foi chamada. (DM) SQLExecute, SQLExecDirect ou SQLMoreResults foi chamado para o StatementHandle e retornou 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 o StatementHandle e ainda estava em execução quando essa função foi chamada. (DM) SQLExecute, SQLExecDirect, SQLBulkOperations ou SQLSetPos foram chamados para o StatementHandle e retornaram 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. |
| 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 catálogo, esquema, procedimento ou nome da coluna correspondente. |
| 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 catálogo de procedimentos foi especificado e o driver ou fonte de dados não dá suporte a catálogos. Um esquema de procedimento 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 esquema de procedimento, o nome do procedimento ou o nome da coluna, e a fonte de dados não dá suporte a padrões de pesquisa para um ou mais desses argumentos. 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 esgotado | O período de tempo limite 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
Normalmente, essa função é usada antes da execução da instrução para recuperar informações sobre parâmetros de procedimento e as colunas que compõem o conjunto de resultados ou conjuntos retornados pelo procedimento, se houver. Para obter mais informações, consulte Procedimentos.
Observação
SQLProcedureColumns pode não retornar todas as colunas usadas por um procedimento. Por exemplo, um driver pode retornar apenas informações sobre os parâmetros usados por um procedimento e não as colunas em um conjunto de resultados gerado por ele.
Os argumentos SchemaName, ProcName e ColumnName aceitam padrões de pesquisa. Para obter mais informações sobre padrões de pesquisa válidos, consulte Argumentos de valor padrão.
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.
SQLProcedureColumns retorna os resultados como um conjunto de resultados padrão, ordenado por PROCEDURE_CAT, PROCEDURE_SCHEM, PROCEDURE_NAME e COLUMN_TYPE. Os nomes de coluna são retornados para cada procedimento na seguinte ordem: o nome do valor retornado, os nomes de cada parâmetro na invocação do procedimento (em ordem de chamada) e, em seguida, os nomes de cada coluna no conjunto de resultados retornado pelo procedimento (em ordem de coluna).
Os aplicativos devem associar colunas específicas do driver em relação ao final do conjunto de resultados. Para obter mais informações, consulte Dados retornados por funções de catálogo.
Para determinar os comprimentos reais das colunas PROCEDURE_CAT, PROCEDURE_SCHEM, PROCEDURE_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_PROCEDURE_NAME_LEN e SQL_MAX_COLUMN_NAME_LEN.
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 |
|---|---|
| PROCEDURE_QUALIFIER | PROCEDURE_CAT |
| PROCEDIMENTO _OWNER | PROCEDURE_SCHEM |
| PRECISION | COLUMN_SIZE |
| LENGTH | BUFFER_LENGTH |
| SCALE | DECIMAL_DIGITS |
| RADIX | NUM_PREC_RADIX |
As colunas a seguir foram adicionadas ao conjunto de resultados retornado por SQLProcedureColumns para ODBC 3. x:
COLUMN_DEF
DATETIME_CODE
CHAR_OCTET_LENGTH
ORDINAL_POSITION
IS_NULLABLE
A tabela a seguir lista as colunas no conjunto de resultados. Colunas adicionais além da coluna 19 (IS_NULLABLE) 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 |
|---|---|---|---|
| PROCEDURE_CAT (ODBC 2.0) | 1 | Varchar | Nome do catálogo de procedimentos; NULL se não for aplicável à fonte de dados. Se um driver der suporte a catálogos para alguns procedimentos, mas não para outros, como quando o driver recupera dados de DBMSs diferentes, ele retorna uma cadeia de caracteres vazia ("") para os procedimentos que não têm catálogos. |
| PROCEDURE_SCHEM (ODBC 2.0) | 2 | Varchar | Nome do esquema de procedimento; NULL se não for aplicável à fonte de dados. Se um driver der suporte a esquemas para alguns procedimentos, mas não para outros, como quando o driver recupera dados de DBMSs diferentes, ele retorna uma cadeia de caracteres vazia ("") para os procedimentos que não têm esquemas. |
| PROCEDURE_NAME (ODBC 2.0) | 3 | Varchar não NULL | Nome do procedimento. Uma cadeia de caracteres vazia é retornada para um procedimento que não tem um nome. |
| COLUMN_NAME (ODBC 2.0) | 4 | Varchar não NULL | Nome da coluna do procedimento. O driver retorna uma cadeia de caracteres vazia para uma coluna de procedimento que não tem um nome. |
| COLUMN_TYPE (ODBC 2.0) | 5 | Smallint não NULL | Define a coluna de procedimento como um parâmetro ou uma coluna de conjunto de resultados: SQL_PARAM_TYPE_UNKNOWN: a coluna de procedimento é um parâmetro cujo tipo é desconhecido. (ODBC 1.0) SQL_PARAM_INPUT: a coluna de procedimento é um parâmetro de entrada. (ODBC 1.0) SQL_PARAM_INPUT_OUTPUT: a coluna de procedimento é um parâmetro de entrada/saída. (ODBC 1.0) SQL_PARAM_OUTPUT: a coluna de procedimento é um parâmetro de saída. (ODBC 2.0) SQL_RETURN_VALUE: a coluna de procedimento é o valor retornado do procedimento. (ODBC 2.0) SQL_RESULT_COL: a coluna de procedimento é uma coluna de conjunto de resultados. (ODBC 1.0) |
| DATA_TYPE (ODBC 2.0) | 6 | Smallint não NULL | Tipo de dados SQL. Pode ser um tipo de dados SQL ODBC ou um tipo de dados SQL específico do driver. Para tipos de dados datetime e interval, essa coluna retorna os tipos de dados concisos (por exemplo, SQL_TYPE_TIME ou SQL_INTERVAL_YEAR_TO_MONTH). Para obter uma lista de tipos de dados SQL ODBC válidos, consulte Tipos de dados SQL no Apêndice D: Tipos de dados. Para informações sobre tipos de dados SQL específicos do driver, confira a documentação do driver. |
| TYPE_NAME (ODBC 2.0) | 7 | Varchar não NULL | Nome do tipo de dados dependente da fonte de dados; por exemplo, "CHAR", "VARCHAR", "MONEY", "LONG VARBINARY" ou "CHAR ( ) FOR BIT DATA". |
| COLUMN_SIZE (ODBC 2.0) | 8 | Inteiro | O tamanho da coluna de procedimento na fonte de dados. NULL é retornado para tipos de dados em que o tamanho da coluna não é aplicável. Para obter mais informações sobre precisão, consulte Tamanho da Coluna, Dígitos Decimais, Tamanho do Octeto de Transferência e Tamanho de Exibição no Apêndice D: Tipos de Dados. |
| BUFFER_LENGTH (ODBC 2.0) | 9 | Inteiro | O comprimento em bytes de dados transferidos em uma operação SQLGetData ou SQLFetch se SQL_C_DEFAULT for especificado. Para dados numéricos, esse tamanho pode ser diferente do tamanho dos dados armazenados na fonte de dados. Para obter mais informações, consulte Tamanho da Coluna, Dígitos Decimais, Tamanho do Octeto de Transferência e Tamanho de Exibição, no Apêndice D: Tipos de Dados. |
| DECIMAL_DIGITS (ODBC 2.0) | 10 | Smallint | Os dígitos decimais da coluna de procedimento na fonte de dados. NULL é retornado para tipos de dados em que dígitos decimais não são aplicáveis. Para obter mais informações sobre dígitos decimais, consulte Tamanho da Coluna, Dígitos Decimais, Tamanho do Octeto de Transferência e Tamanho de Exibição, no Apêndice D: Tipos de Dados. |
| NUM_PREC_RADIX (ODBC 2.0) | 11 | Smallint | Para tipos de dados numéricos, 10 ou 2. Se 10, os valores em COLUMN_SIZE e DECIMAL_DIGITS fornecerão o número de dígitos decimais permitidos para a coluna. Por exemplo, uma coluna DECIMAL(12,5) retornaria um NUM_PREC_RADIX de 10, um COLUMN_SIZE de 12 e um DECIMAL_DIGITS de 5; uma coluna FLOAT pode retornar um NUM_PREC_RADIX de 10, um COLUMN_SIZE de 15 e um DECIMAL_DIGITS de NULL. Se 2, os valores em COLUMN_SIZE e DECIMAL_DIGITS fornecer o número de bits permitidos na coluna. Por exemplo, uma coluna FLOAT pode retornar um NUM_PREC_RADIX de 2, um COLUMN_SIZE de 53 e um DECIMAL_DIGITS de NULL. NULL é retornado para tipos de dados em que NUM_PREC_RADIX não é aplicável. |
| NULLABLE (ODBC 2.0) | 12 | Smallint não NULL | Se a coluna de procedimento aceita um valor NULL: SQL_NO_NULLS: a coluna de procedimento não aceita valores NULL. SQL_NULLABLE: a coluna de procedimento aceita valores NULL. SQL_NULLABLE_UNKNOWN: não se sabe se a coluna de procedimento aceita valores NULL. |
| COMENTÁRIOS (ODBC 2.0) | 13 | Varchar | Uma descrição da coluna de procedimento. |
| COLUMN_DEF (ODBC 3.0) | 14 | Varchar | O valor padrão da coluna. Se NULL tiver sido especificado como o valor padrão, essa coluna será a palavra NULL, não entre aspas. Se o valor padrão não puder ser representado sem truncamento, esta coluna conterá TRUNCATED, sem aspas simples. Se nenhum valor padrão tiver sido especificado, essa coluna será NULL. O valor de COLUMN_DEF pode ser usado na geração de uma nova definição de coluna, exceto quando ela contém o valor TRUNCATED. |
| SQL_DATA_TYPE (ODBC 3.0) | 15 | Smallint não NULL | O valor do tipo de dados SQL como ele aparece no campo SQL_DESC_TYPE do descritor. Essa coluna é igual à coluna DATA_TYPE, exceto para tipos de dados datetime e interval. Para tipos de dados datetime e interval, o campo SQL_DATA_TYPE no conjunto de resultados retornará SQL_INTERVAL ou SQL_DATETIME e o campo SQL_DATETIME_SUB retornará o subcódigo para o tipo de dados de intervalo ou datetime específico. (Consulte Apêndice D: Tipos de dados.) |
| SQL_DATETIME_SUB (ODBC 3.0) | 16 | Smallint | O código de subtipo para tipos de dados datetime e interval. Para outros tipos de dados, essa coluna retorna um NULL. |
| CHAR_OCTET_LENGTH (ODBC 3.0) | 17 | Inteiro | O comprimento máximo em bytes de uma coluna de tipo de dados binário ou caractere. Para todos os outros tipos de dados, essa coluna retorna um NULL. |
| ORDINAL_POSITION (ODBC 3.0) | 18 | Integer não NULL | Para parâmetros de entrada e saída, a posição ordinal do parâmetro na definição do procedimento (em ordem de parâmetro crescente, começando em 1). Para um valor retornado (se houver), 0 é retornado. Para colunas de conjunto de resultados, a posição ordinal da coluna no conjunto de resultados, com a primeira coluna no conjunto de resultados sendo o número 1. Se houver vários conjuntos de resultados, as posições ordinais de coluna serão retornadas de maneira específica do driver. |
| IS_NULLABLE (ODBC 3.0) | 19 | Varchar | "NÃO" se a coluna não incluir NULLs. "SIM" se a coluna puder incluir NULLs. Esta coluna retorna uma cadeia de caracteres de comprimento zero se a possibilidade de nulidade for desconhecida. As regras ISO são seguidas para determinar a possibilidade de nulidade. Um DBMS em conformidade com ISO SQL não pode retornar uma cadeia de caracteres vazia. O valor retornado para esta coluna é diferente do valor retornado para a coluna NULLABLE. (Consulte a descrição da coluna NULLABLE.) |
Exemplo de código
Consulte Chamadas de procedimento.
Funções relacionadas
| Para obter informações sobre | Consulte |
|---|---|
| Associar um buffer a uma coluna em um conjunto de resultados | Função SQLBindCol |
| Cancelando o processamento da instrução | Função SQLCancel |
| Buscando uma única linha ou um bloco de dados em uma direção somente de avanço | Função SQLFetch |
| Buscando um bloco de dados ou rolando por um conjunto de resultados | Função SQLFetchScroll |
| Retornando uma lista de procedimentos em uma fonte de dados | Função SQLProcedures |