Desenvolvimento de Aplicativos: CLI (Call Level Interface)
|
|
|Palavra-chave de Configuração CLI/ODBC Trusted_Connection
|
|
|- Descrição da Palavra-chave
|- Permitir que seja feita uma conexão com o usuário autenticado atual.
|
|- Sintaxe:
|- Trusted_Connection=Yes
|
|
Nota:
|Esta palavra-chave não terá efeito se
|configurada no arquivo db2cli.ini. Ela deve, então, ser fornecida
|na cadeia de conexão com SQLDriverConnect().
|
|- Definição Padrão:
|- O DB2 CLI utiliza informações de ID do usuário e senha fornecidas na cadeia de conexão
|para SQLDriverConnect(), não o usuário autenticado atual.
|
|- Notas de Uso:
|-
|
Os aplicativos DB2 CLI que se conectam a um banco de dados geralmente conectam-se utilizando a função SQLDriverConnect(). Um dos argumentos de entrada para esta função
|é o valor DriverCompletion, que determina quando uma janela será
|aberta. A seguir estão os valores de DriverCompletion:
|
|- SQL_DRIVER_PROMPT: Um diálogo é sempre iniciado.
|- SQL_DRIVER_COMPLETE: Um diálogo será iniciado apenas se houver informações insuficientes
|na cadeia de conexão.
|- SQL_DRIVER_COMPLETE_REQUIRED: Um diálogo será iniciado apenas se houver informações insuficientes na cadeia de conexão. Apenas as informações mandatórias são
|solicitadas. São solicitadas do usuário apenas as informações requeridas.
|- SQL_DRIVER_NOPROMPT: Não é solicitada nenhuma informação do usuário. É feita uma tentativa de conexão com as informações contidas na cadeia de conexão.
|Se não houver informações suficientes, será retornado SQL_ERROR.
|
|Nota:
|Detalhes adicionais sobre DriverCompletion podem ser localizados
|na documentação para SQLDriverConnect().
|Alguns aplicativos, por exemplo,
|os que estão em um ambiente do Kerberos, podem requerer que um usuário possa conectar-se
|a um servidor DB2 UDB sem fornecer um ID do usuário ou senha.
|Se o aplicativo utilizar a opção SQL_DRIVER_NO_PROMPT na chamada SQLDriverConnect(),
|será feita uma tentativa de conexão sem autenticação do usuário. Esta palavra-chave não
|é requerida.
|No caso de um aplicativo de terceiros estar envolvido
|e o nível de prompt utilizado pelo aplicativo for algo diferente
|de SQL_DRIVER_NO_PROMPT, o DB2 CLI abrirá uma janela para solicitar as informações ausentes.
|Configurar Trusted_Connection como Yes, fornecendo-o para a cadeia de conexão de entrada
|para SQLDriverConnect() ("Trusted_Connection=Yes"), faz o DB2 CLI ignorar qualquer cadeia
|de ID do usuário ou senha (incluindo cadeias em branco) da cadeia de conexão
|e ignorar o nível de prompt da função de conexão. O DB2 CLI utiliza o usuário autenticado
|atual para tentar a conexão com o banco de dados.
|Se a tentativa de conexão falhar, serão solicitados do usuário o ID do usuário e a
|senha.
|Esta palavra-chave é utilizada apenas na cadeia de conexão para SQLDriverConnect();
|configurá-la no arquivo db2cli.ini não tem nenhum efeito.
|
|
Diagnóstico de Atualização da Tabela para Função SQLDescribeParam (CLI)
A função SQLDescribeParam() retorna a descrição de um marcador de
parâmetro associado a uma instrução SQL preparada.
A tabela de diagnósticos foi atualizada com SQLSTATE HYC00.
Diagnósticos
Tabela 24. SQLDescribeParam SQLSTATEs
SQLSTATE |
Descrição |
Explicação |
HYC00 |
Controlador não competente |
Os procedimentos armazenados da função de esquema não estão acessíveis no servidor.
Instale os procedimentos armazenados da função de esquema no servidor e certifique-se de que eles
estão acessíveis. |
Execução Assíncrona do Call Level Interface
O DB2 CLI (DB2 Call Level Interface) pode executar um subconjunto de funções assincronamente.
O driver DB2 CLI retorna controle para o aplicativo após chamar a função
mas antes de que a função tenha concluído a execução. A função retorna SQL_STILL_EXECUTING
toda vez que é chamada até que a execução esteja concluída, no momento em que ela retorna
um valor diferente (por exemplo, SQL_SUCCESS).
A execução assíncrona é benéfica apenas em sistemas operacionais com encadeamento
único. Aplicativos que são executáveis em sistemas operacionais multiencadeados devem
executar funções em encadeamentos separados. A execução assíncrona é possível para
as funções que normalmente enviam um pedido para o servidor e, então, esperam
por uma resposta. Ao invés de esperar, uma função em execução assincronamente
retorna controle ao aplicativo. O aplicativo pode, assim, desempenhar outras
tarefas, ou retornar controle para o sistema operacional, e utilizar um interruptor para
efetuar poll repetidamente para a função até que um código de retorno diferente de SQL_STILL_EXECUTING
seja retornado.
O suporte à execução assíncrona do CLI está incluído no DB2 UDB
(Universal Database), iniciando com a Versão 8.2 FixPak 1 (equivalente à Versão
8.1 FixPak 8). Para obter a documentação desse recurso, consulte o DB2 UDB Versão
7 Information Center em http://publib.boulder.ibm.com/infocenter/db2v7luw/index.jsp. Toda a informação contida na documentação da Versão 7 aplica-se à Versão
8.2 FixPak 1 (equivalente à Versão 8.1 FixPak 8) e mais recente. O DB2 Versão
8 Information Center não contém nenhuma documentação desse recurso.
Atributo de Conexão SQL_ATTR_PING_DB
SQL_ATTR_PING_DB (DB2 CLI v8.2)
O SQL_ATTR_PING_DB é um inteiro de 32 bits utilizado com a função SQLGetConnectAttr() para obter o tempo de resposta da rede de conexão existente
entre o cliente DB2 UDB e o servidor DB2 UDB. O tempo de resposta é relatado
em microssegundos.
Se uma conexão foi estabelecida anteriormente e foi derrubada pelo
banco de dados, um valor de 0 é relatado. Se a conexão foi fechada
pelo aplicativo, um SQLSTATE de 08003 é relatado. Esse atributo de
conexão pode ser retornado por SQLGetConnectAttr(), mas não pode
ser configurado por SQLSetConnectAttr(). Qualquer tentativa para configurar esse atributo
resultará em um SQLSTATE de HYC00 (Driver não competente).
Função SQLBindParameter (CLI)
Na documentação para a função SQLBindParameter, a descrição
na seção Parâmetro de entrada é incorreta. A descrição correta
é:
- Parâmetro de entrada
- Um 0 ColumnSize significa que o DB2 CLI utilizará
o comprimento máximo do tipo SQL fornecido conforme o tamanho dos parâmetros da
coluna ou do procedimento armazenado. O DB2 CLI desempenhará qualquer conversão necessária
utilizando esse tamanho.
Função SQLMoreResults (CLI)
Na documentação da função SQLMoreResults, o atributo de instrução SQL_ATTR_ROW_ARRAY_SIZE
é referenciado incorretamente. O atributo de instrução correto
é SQL_ATTR_PARAMSET_SIZE. A seção Uso deve ser lida da seguinte forma:
Essa função é utilizada para retornar conjunto de resultados múltiplos de uma maneira seqüencial
baseado na execução de:
- Uma consulta de parâmetros com uma matriz de valores de parâmetro de entrada especificados
com o atributo de instrução SQL_ATTR_PARAMSET_SIZE e SQLBindParameter()
Atributos de Ambiente Adicionais
Além de serem atributos de conexão CLI, os atributos a seguir também são suportados como atributos de ambiente CLI:
- SQL_ATTR_INFO_ACCTSTR
- SQL_ATTR_INFO_APPLNAME
- SQL_ATTR_INFO_USERID
- SQL_ATTR_INFO_WRKSTNNAME
Para obter informações sobre esses atributos, consulte a documentação dos atributos de conexão CLI no DB2 Information Center ou no CLI Guide and Reference Volume 2 .
Requisito de Cursores Roláveis Dinâmicos
Para executar atualizações e exclusões nas linhas em um conjunto de resultados do cursor rolável dinâmico, a instrução UPDATE ou DELETE deve incluir todas as colunas de, pelo menos, uma chave exclusiva na tabela de base. Essa pode ser a chave primária ou qualquer outra chave exclusiva.
Palavra-chave de Configuração CLI/ODBC RetCatalogAsCurrServer
- Descrição da Palavra-chave
- As funções de catálogo retornam o valor CURRENT SERVER ao invés do valor nulo
para as colunas de catálogo.
- Sintaxe da Palavra-chave db2cli.ini:
- RetCatalogAsCurrServer= 0 | 1
- Definição Padrão:
- Se o DBMS de destino retornar nulo para as colunas de catálogo, o valor CURRENT
SERVER não será substituído.
- Notas de Uso:
- Se as funções de catálogo do DBMS de destino retornarem um valor nulo para
as colunas de catálogo, a configuração RetCatalogAsCurrServer como 1 fará com que o DBMS
retorne o valor CURRENT SERVER no lugar.
- 0 = As funções de catálogo retornam o valor nulo para as colunas de catálogo (padrão).
- 1 = As funções de catálogo retornam o valor CURRENT SERVER ao invés do valor
nulo para as colunas de catálogo.
Por exemplo, assumir a função de catálogo SQLTables() retorna
um conjunto de resultados no qual os valores na coluna TABLE_CAT sejam valores nulos. A configuração
RetCatalogAsCurrServer como 1 fará com que o DBMS retorne o valor CURRENT SERVER
na coluna TABLE_CAT.
Nota:
Essa palavra-chave é suportada pelo DB2
UDB para Linux, UNIX(R) e Windows(R) Versão 8.2 FixPak 3 (equivalente
à Versão 8.1 FixPak 10) e mais recente.
Palavra-chave da Configuração de ReceiveTimeout CLI/ODBC
- Descrição da Palavra-chave
- Especifique o tempo, em segundos, para aguardar uma resposta do servidor em uma conexão estabelecida antes de finalizar a tentativa e gerar um erro de tempo limite de comunicação.
- Sintaxe da Palavra-chave db2cli.ini:
- ReceiveTimeout = 0 | 1 | 2 |
... | 32767
- Definição Padrão:
- O cliente aguarda indefinidamente por uma resposta do servidor sobre uma conexão estabelecida.
- Atributo de Conexão Equivalente:
- SQL_ATTR_RECEIVE_TIMEOUT
- Notas de Uso:
- O valor padrão 0 indica que o cliente aguarda indefinidamente por uma resposta. O tempo limite de recepção não tem efeito durante o estabelecimento da conexão; ele é suportado apenas para TCP/IP e é ignorado para qualquer outro protocolo.
Atributo de Conexão SQL_ATTR_RECEIVE_TIMEOUT
- SQL_ATTR_RECEIVE_TIMEOUT (DB2 CLI v8)
- Um valor inteiro de 32 bits, que é o número de segundos que o cliente aguarda por uma resposta de um servidor em uma conexão estabelecida antes de finalizar a tentativa e gerar um erro de tempo limite de comunicação. O valor padrão 0 indica que o cliente aguarda indefinidamente por uma resposta. O tempo limite de recepção não tem efeito durante o estabelecimento da conexão; ele é suportado apenas para TCP/IP e é ignorado para qualquer outro protocolo. Os valores suportados são inteiros de 0 a 32767.
Palavra-chave de Configuração Reopt CLI/ODBC
- Descrição da Palavra-chave
- Ativa a otimização de consultas ou reotimização de instruções SQL que possuem registros especiais ou marcadores de parâmetros.
- Sintaxe da Palavra-chave db2cli.ini:
- Reopt = 2 | 3 | 4
- Definição Padrão:
- Nenhuma otimização de consultas ocorre no tempo de execução da consulta. A estimativa padrão escolhida pelo compilador é utilizada para registros especiais ou marcadores de parâmetros.
- Atributo de Instrução e Conexão Equivalente:
- SQL_ATTR_REOPT
- Notas de Uso:
- A otimização ocorre utilizando os valores disponíveis no tempo de execução da consulta para registros especiais ou marcadores de parâmetros, em vez da estimativa padrão escolhida pelo compilador. Os valores válidos da palavra-chave são:
- 2 = SQL_REOPT_NONE. Este é o padrão.
Nenhuma otimização de consultas ocorre no tempo de execução da consulta. A estimativa padrão escolhida pelo compilador é utilizada para registros especiais ou marcadores de parâmetros. O conjunto de pacotes padrão "NULLID" é utilizado para executar as instruções SQL dinâmicas.
- 3 = SQL_REOPT_ONCE. A otimização de consultas ocorre uma vez no tempo de execução de consulta, quando a consulta é executada pela primeira vez. O conjunto de pacotes "NULLIDR1", ligado com a opção de ligação REOPT ONCE, é utilizado.
- 4 = SQL_REOPT_ALWAYS. A otimização da consulta ou a reotimização ocorre no tempo de execução da consulta sempre que a consulta é executada. O conjunto de pacotes "NULLIDRA", ligado com a opção de ligação REOPT ALWAYS, é utilizado.
O "NULLIDR1" e "NULLIDRA" são nomes de conjuntos de pacotes reservados e, quando utilizados, REOPT ONCE e REOPT ALWAYS são implicadas respectivamente.
Esses conjuntos de pacotes devem ser criados explicitamente com os seguintes comandos:
db2 bind db2clipk.bnd collection NULLIDR1
db2 bind db2clipk.bnd collection NULLIDRA
Se as palavras-chave Reopt e CurrentPackageSet forem especificadas, CurrentPackageSet tem precedência.
Atributo de Instrução e de Conexão SQL_ATTR_REOPT
- SQL_ATTR_REOPT (DB2 CLI v8)
- Um valor inteiro de 32 bits que permite a otimização de consultas para instruções SQL que contêm registros especiais ou marcadores de parâmetros. A otimização ocorre utilizando os valores disponíveis no tempo de execução da consulta para registros especiais ou marcadores de parâmetros, em vez da estimativa padrão escolhida pelo compilador. Os valores válidos do atributo são:
- 2 = SQL_REOPT_NONE. Este é o padrão.
Nenhuma otimização de consultas ocorre no tempo de execução da consulta. A estimativa padrão escolhida pelo compilador é utilizada para registros especiais ou marcadores de parâmetros. O conjunto de pacotes padrão "NULLID" é utilizado para executar as instruções SQL dinâmicas.
- 3 = SQL_REOPT_ONCE. A otimização de consultas ocorre uma vez no tempo de execução de consulta, quando a consulta é executada pela primeira vez. O conjunto de pacotes "NULLIDR1", ligado com a opção de ligação REOPT ONCE, é utilizado.
- 4 = SQL_REOPT_ALWAYS. A otimização da consulta ou a reotimização ocorre no tempo de execução da consulta sempre que a consulta é executada. O conjunto de pacotes "NULLIDRA", ligado com a opção de ligação REOPT ALWAYS, é utilizado.
O "NULLIDR1" e "NULLIDRA" são nomes de conjuntos de pacotes reservados e, quando utilizados, REOPT ONCE e REOPT ALWAYS são implicadas respectivamente.
Esses conjuntos de pacotes devem ser criados explicitamente com esses comandos:
db2 bind db2clipk.bnd collection NULLIDR1
db2 bind db2clipk.bnd collection NULLIDRA
SQL_ATTR_REOPT e SQL_ATTR_CURRENT_PACKAGE_SET
são mutuamente exclusivos, portanto, se um é definido, o outro não é permitido.
Palavra-chave da Configuração de CurrentPackageSet CLI/ODBC
- Descrição da Palavra-chave
- Emite a instrução SET CURRENT PACKAGESET após todas as conexões.
- Sintaxe da Palavra-chave db2cli.ini:
- CurrentPackageSet = schema name
- Definição Padrão:
- A cláusula não é anexada.
- Atributo de Conexão Equivalente:
- SQL_ATTR_CURRENT_PACKAGE_SET
- Notas de Uso:
-
Essa opção emite a instrução SET CURRENT PACKAGESET SQL com o valor CurrentPackageSet, após todas as conexões a um banco de dados. Por padrão, essa cláusula não é anexada.
A instrução SET CURRENT PACKAGESET SQL define o nome do esquema (identificador de coletas), utilizado para selecionar o pacote a ser utilizado para instruções SQL subseqüentes.
Aplicativos CLI/ODBC emitem instruções SQL dinâmicas. Utilizando essa opção, é possível controlar os privilégios utilizados para executar essas instruções:
- Escolha um esquema para utilizar ao executar as instruções SQL dos aplicativos CLI/ODBC.
- Assegure-se de que os objetos no esquema possuem os privilégios desejados e, em seguida, religue de acordo.
- Define a opção CurrentPackageSet para esse esquema.
As instruções SQL dos aplicativos CLI/ODBC serão executadas agora no esquema especificado e utilizarão os privilégios definidos.
Os seguintes nomes de conjuntos de pacotes são reservados: "NULLID ", "NULLIDR1", "NULLIDRA".
Se as palavras-chave Reopt e CurrentPackageSet forem especificadas, CurrentPackageSet tem precedência.
Atributo de Conexão SQL_ATTR_CURRENT_PACKAGE_SET
- SQL_ATTR_CURRENT_PACKAGE_SET (DB2 CLI v5)
- Uma cadeia de caracteres finalizada em nulo que indica o nome do esquema (identificador de coleta), utilizado para selecionar o pacote para instruções SQL subseqüentes.
A configuração desse atributo causa a emissão da instrução SET CURRENT PACKAGESET SQL. Se esse atributo for definido antes de uma conexão, a instrução SET CURRENT PACKAGESET
SQL será emitida no tempo de conexão.
Aplicativos CLI/ODBC emitem instruções SQL dinâmicas. Utilizando esse atributo de conexão, é possível controlar os privilégios utilizados para executar essas instruções:
- Escolha um esquema para utilizar ao executar as instruções SQL dos aplicativos CLI/ODBC.
- Assegure-se de que os objetos no esquema possuem os privilégios desejados e, em seguida, religue de acordo. Isso geralmente significa a ligação dos pacotes CLI (sqllib/bnd/db2cli.lst), utilizando a opção COLLECTION <id_da_coleta>. Consulte o comando BIND para obter detalhes adicionais.
- Defina a opção CURRENTPACKAGESET para esse esquema.
As instruções SQL dos aplicativos CLI/ODBC serão executadas agora no esquema especificado e utilizarão os privilégios definidos.
A configuração da palavra-chave de configuração de CLI/ODBC, CURRENTPACKAGESET, é um método alternativo de especificação do nome do esquema.
Os seguintes nomes de conjuntos de pacotes são reservados: "NULLID ", "NULLIDR1", "NULLIDRA".
SQL_ATTR_REOPT e SQL_ATTR_CURRENT_PACKAGE_SET
são mutuamente exclusivos, portanto, se um é definido, o outro não é permitido.
Palavra-chave de Configuração MapBigintCDefault de CLI/ODBC
- Descrição da Palavra-chave
- Especifique o tipo C padrão de colunas e marcadores de parâmetro BIGINT.
- Sintaxe da Palavra-chave db2cli.ini:
- MapBigintCDefault = 0 | 1 | 2
- Definição Padrão:
- A representação do tipo C padrão para dados BIGINT é SQL_C_BIGINT.
- Notas de Uso:
-
MapBigintCDefault controla o tipo C utilizado quando SQL_C_DEFAULT
é especificado para colunas e marcadores de parâmetros BIGINT. Esta palavra-chave deve ser
utilizada principalmente com aplicativos da Microsoft, como o Microsoft Access,
que não podem manipular inteiros de 8 bytes. Defina MapBigintCDefault da seguinte forma:
- 0 - para a representação do tipo C SQL_C_BIGINT padrão
- 1 - para uma representação de tipo C SQL_C_CHAR
- 2 - para uma representação de tipo C SQL_C_WCHAR
Esta palavra-chave afeta o comportamento de funções CLI nas quais SQL_C_DEFAULT
pode ser especificado como um tipo C, por exemplo, SQLBindParameter(), SQLBindCol()
e SQLGetData().
Palavra-chave de Configuração DescribeOutputLevel de CLI/ODBC
- Descrição da Palavra-chave
- Defina o nível de informações de descrição de colunas de saída que são solicitadas
pelo driver CLI durante pedidos de preparação ou de descrição.
- Sintaxe da Palavra-chave db2cli.ini:
- DescribeOutputLevel = 0 | 1 | 2 | 3
- Definição Padrão:
- Solicite as informações de descrição listadas no nível 2 da Tabela 25.
- Notas de Uso:
-
Esta palavra-chave controla a quantidade de informações solicitadas pelo driver CLI
em um pedido de preparação ou de descrição. Por padrão, quando o servidor recebe um pedido
de descrição, ele retorna as informações contidas no nível 2 da Tabela 25 para as colunas do conjunto de resultados. No entanto, um aplicativo talvez
não precise destas informações ou precise de informações adicionais.
A definição da
palavra-chave DescribeOutputLevel para um nível que atende as necessidades do aplicativo cliente
pode aprimorar o desempenho, porque os dados de descrição transferidos
entre o cliente e o servidor estão limitados à quantidade mínima requerida pelo aplicativo.
Se a definição de DescribeOutputLevel for muito baixa, poderá impactar
a funcionalidade do aplicativo (dependendo dos requisitos do aplicativo).
As funções CLI para recuperar as informações de descrição podem não falhar neste caso, mas
as informações retornadas podem estar incompletas.
As definições suportadas
para DescribeOutputLevel são:
- 0 - nenhuma informação de descrição é retornada ao aplicativo cliente
- 1 - as informações de descrição categorizadas no nível 1 (consulte a Tabela 25)
são retornadas ao aplicativo cliente
- 2 - (padrão) as informações de descrição categorizadas no nível 2 (consulte a Tabela 25)
são retornadas ao aplicativo cliente
- 3 - as informações de descrição categorizadas no nível 3 (consulte a Tabela 25)
são retornadas ao aplicativo cliente
A tabela a seguir lista os campos que formam as informações de descrição
retornadas pelo servidor quando ele recebe um pedido de preparação ou descrição. Estes campos
são agrupados em níveis e a palavra-chave de configuração DescribeOutputLevel de CLI/ODBC
controla quais níveis de informações de descrição são solicitados pelo driver CLI.
Nota:
Nem todos os níveis de informações de descrição são suportados por todos os servidores DB2.
Todos os níveis de informações de descrição são suportados nos servidores DB2 a seguir: DB2 UDB (Universal Database) para Linux , UNIX e Windows Versão 8 e posterior, DB2 UDB para z/OS Versão 8 e posterior e DB2 UDB para iSeries Versão 5 Release 3 e posterior. Todos os outros
servidores DB2 suportam apenas a definição 2 ou 0 para DescribeOutputLevel.
Tabela 25. Níveis de Informações de Descrição
Nível 1 |
Nível 2 |
Nível 3 |
SQL_DESC_COUNT
SQL_COLUMN_COUNT
SQL_DESC_TYPE
SQL_DESC_CONCISE_TYPE
SQL_COLUMN_LENGTH
SQL_DESC_OCTET_LENGTH
SQL_DESC_LENGTH
SQL_DESC_PRECISION
SQL_COLUMN_PRECISION
SQL_DESC_SCALE
SQL_COLUMN_SCALE
SQL_DESC_DISPLAY_SIZE
SQL_DESC_NULLABLE
SQL_COLUMN_NULLABLE
SQL_DESC_UNSIGNED
SQL_DESC_SEARCHABLE
SQL_DESC_LITERAL_SUFFIX
SQL_DESC_LITERAL_PREFIX
SQL_DESC_CASE_SENSITIVE
SQL_DESC_FIXED_PREC_SCALE |
todos os campos de nível
1 e:
SQL_DESC_NAME
SQL_DESC_LABEL
SQL_COLUMN_NAME
SQL_DESC_UNNAMED
SQL_DESC_TYPE_NAME
SQL_DESC_DISTINCT_TYPE
SQL_DESC_REFERENCE_TYPE
SQL_DESC_STRUCTURED_TYPE
SQL_DESC_USER_TYPE
SQL_DESC_LOCAL_TYPE_NAME
SQL_DESC_USER_DEFINED_
TYPE_CODE |
todos os campos de níveis
1 e 2 e:
SQL_DESC_BASE_COLUMN_NAME
SQL_DESC_UPDATABLE
SQL_DESC_AUTO_UNIQUE_VALUE
SQL_DESC_SCHEMA_NAME
SQL_DESC_CATALOG_NAME
SQL_DESC_TABLE_NAME
SQL_DESC_BASE_TABLE_NAME |
[ Início da Página |Página Anterior | Próxima Página | Índice ]