int SQL OPENBASEDBEXTNAME(char datasource, char *hostname, int instancia)
Cria uma conexão com uma base. No caso da conexão já existir com o número da instância especificado, ela se torna a corrente.
O valor retornado pela função é igual a menos um (–1), em caso de erro, ou maior ou igual a zero (>=0) identificando o número da conexão.
Parâmetros de entrada:
datasource: Cadeia que especifica uma base como descrito no Apêndice 3.
hostname: Nome da máquina onde reside a base. Pode ser também especificado no parâmetro datasource. O parâmetro hostname tem prioridade.
instancia: Permite diferenciar duas ou mais conexões com a mesma base.
int SQL OPENBASEPREPARE(char *statement, int *sqlcode)
Prepara (compila) um comando SQL.
O valor retornado pela função é igual a menos um (–1), em caso de erro, ou igual a zero (0).
Parâmetro de entrada:
statement: Cadeia que contém o comando SQL. O parâmetro deve conter um dos comandos SQL listados abaixo:
comando_COMMIT |
comando_DELETE_selecionado |
comando_DELETE_posicionado |
comando_INSERT |
comando_ROLLBACK |
comando_SELECT_dinâmico |
comando_UPDATE_selecionado |
comando_UPDATE_posicionado |
comando_CREATE_TABLE |
comando_DROP_TABLE |
comando_CREATE_INDEX |
comando_DROP_INDEX
Parâmetro de saída:
sqlcode: Código de erro. Zero se sucesso.
int SQL OPENBASEDESCRIBE(struct SQLDA *sqlda, int *sqlcode)
Retorna informações sobre o comando SQL preparado.
O valor retornado pela função é igual a menos um (–1), em caso de erro, ou igual a zero (0).
Parâmetro de entrada:
sqlda: Estrutura que contem informações sobre o comando preparado. Se o número de valores associados ao comando (SQLD) for zero o comando não é um comando SELECT. A utilização da estrutura pela rotina SQL OPENBASEDESCRIBE é descrita a seguir:
struct SQLDA {
short SQLN;
short SQLD;
struct SQLVAR *SQLVAR;
}
struct SQLVAR {
char *SQLDATA;
long *SQLIND;
short SQLTYPE;
short SQLNULL;
short SQLLEN;
short SQLSCALE;
struct {
short SQLNAMEL;
char SQLNAMEC[18];
} SQLNAME;
}
O campo SQLN deve especificar o número de estruturas SQLVAR. O campo SQLD retorna zero se o comando preparado não for um comando SELECT .
Se o comando for um SELECT, SQLD indica o número de colunas da tabela por ele especificada. Se SQLD for maior que SQLN, não serão retornadas as informações sobre as colunas da tabela. Caso contrário serão retornadas nas primeiras estruturas SQLVAR a descrição das colunas correspondentes na tabela.
No campo SQLTYPE é retornado um valor numérico indicando o tipo da coluna segundo a tabela abaixo.
|
Tipo da Coluna |
Valor Numérico |
|
CHARACTER |
1 |
|
NUMERIC |
3 |
|
DECIMAL |
3 |
|
INTEGER |
4 |
|
SMALLINT |
5 |
|
FLOAT |
7 OU 8 |
|
REAL |
7 |
|
DOUBLE |
8 |
|
DATETIME |
9 |
|
VARCHAR |
12 |
No campo SQLNULL é retornado o valor 1 se a coluna puder ter valores nulos.
No campo SQLLEN é retornado o tamanho, em "bytes", da coluna, em função de seu tipo:
Em SQLSCALE é retornada a escala do tipo NUMERIC ou DECIMAL ou a precisão do tipo DATETIME. Esta é representada numericamente pelo valor numérico do campo inicial somado com o do final, se são diferentes. Os valores de cada campo são:
|
Ano |
64 |
|
Mês |
32 |
|
Dia |
16 |
|
Hora |
8 |
|
Minuto |
4 |
|
Segundo |
2 |
Em SQLNAMEC é retornado o nome da coluna. Se este tem menos de 18 caracteres, o nome é completado com caracteres brancos.
Em SQLNAMEL é retornado o tamanho do nome da coluna que será igual a 18, se a coluna tiver nome ou igual a 0, se a coluna não tiver nome.
A estrutura SQLDA encontra-se declarada no arquivo \usr\include\sqlda.h que pode ser incluído no programa de aplicação.
Parâmetro de saída:
sqlcode: Código de erro. Zero se sucesso.
int SQL OPENBASEEXECUTE(int *sqlcode)
Descrição
Executa o comando SQL preparado se o comando não é do tipo SELECT.
Parâmetro de saída:
sqlcode: Código de erro. Zero se sucesso.
Retorno:
0 : sucesso.
-1 : erro
int SQL OPENBASEIMMEDIATE(char *statement, int *sqlcode)
Descrição:
Prepara e executa um comando SQL. O comando não pode ser do tipo SELECT.
Parâmetro de entrada:
statement : cadeia que contém o comando SQL. Ver a descrição da chamada SQL OPENBASEPREPARE para os comandos permitidos.
Parâmetro de saída:
sqlcode: Código de erro. Zero se sucesso.
Retorno:
0 : sucesso.
-1 : erro
int SQL OPENBASEOPEN(int *sqlcode)
Descrição:
Executa o comando SELECT preparado e associa implicitamente o cursor ao conjunto resultado. O cursor é posicionado imediatamente antes do inicio da primeira linha. Diz-se que o cursor está no estado aberto. O nome do cursor não é relevante nesta interface considerando que êle é único.
Parâmetro de saída:
sqlcode: Código de erro. Zero se sucesso.
Retorno:
0 : sucesso. O cursor foi aberto.
-1 : erro
int SQL OPENBASEFETCH(struct SQLDA *sqlda, int *sqlcode)
Descrição:
Move o cursor para a próxima linha do conjunto resultado e recupera a linha colocando os valores das colunas na estrutura apontada por sqlda. A rotina SQL OPENBASEFETCH só pode ser chamada se o cursor estiver aberto.
Parâmetros de saída:
sqlcode: Código de erro. Zero se sucesso.
sqlda: Estrutura que contem os valores retornados.
struct SQLDA {
short SQLN;
short SQLD;
struct SQLVAR *SQLVAR;
}
struct SQLVAR {
char *SQLDATA;
long *SQLIND;
short SQLTYPE;
short SQLNULL;
short SQLLEN;
short SQLSCALE;
struct {
short SQLNAMEL;
char SQLNAMEC[18];
} SQLNAME;
}
O parâmetro corresponde ao campo SQLN e especifica o número de estruturas SQLVAR retornadas.
SQLD corresponde ao grau da tabela e deve ser menor ou igual a SQLN. As sucessivas estruturas SQLVAR conterão as descrições das variáveis no programa para as quais retornarão os valores das colunas.
O campo SQLTYPE deve conter um valor numérico indicando o tipo da coluna segundo a tabela abaixo.
|
Tipo da Coluna |
Valor Numérico |
|
CHARACTER |
1 |
|
NUMERIC |
2 |
|
DECIMAL |
3 |
|
INTEGER |
4 |
|
SMALLINT |
5 |
|
FLOAT |
6 |
|
REAL |
7 |
|
DOUBLE |
8 |
|
DATETIME |
9 |
|
VARCHAR |
12 |
O campo SQLNULL é igual a 1 se o valor retornado pode ser nulo. O campo SQLLEN é equivalente ao tamanho da variável. O campo SQLSCALE contém a escala do tipo numérico caso a variável seja desse tipo. O campo SQLNAME não é usado.
SQLDATA aponta para a área da memória para onde é retornado o valor da variável. SQLIND aponta para a área da memória onde é retornada o valor –1 se SQLNULL for igual a 1 e se a coluna correspondente tiver valor nulo; o tamanho do valor da coluna se este for uma cadeia de caracteres de tamanho maior que o tipo da variável ou nos demais casos, retorna 0.
SQLDATA aponta para a área da memória para onde é retornado o valor da variável. SQLIND aponta para a área da memória onde é retornada a variável INDICATOR, se SQLNULL é igual a 1.
Os tipos das variáveis devem corresponder aos tipos das colunas correspondentes na tabela. Se ocorrer um erro durante a atribuição de valores às variáveis, o parâmetro sqlcode retornará um valor negativo.
Se o tipo de uma variável é DATETIME de precisão diferente da precisão da coluna correspondente, os campos excedentes são truncados ou os campos adicionais são iniciados com o valor 1 para os campos mês e dia e com o valor 0 para os campos hora, minuto e segundo.
Caso a tabela associada ao cursor esteja vazia ou o cursor estiver na última linha, o cursor será posicionado após a última linha, o valor 100 será retornado no parâmetro sqlcode e não serão atribuídos valores às variáveis do programa de aplicação.
sqlcode :
< 0 se erro
= 100 se não há mais linhas a retornar
= 0 caso contrário
Retorno:
0 : se sqlcode >= 0
-1 : se sqlcode < 0
int SQL OPENBASECLOSE(int *sqlcode)
Descrição:
Fecha o cursor . A chamada SQL OPENBASEFETCH não pode mais ser executada até que um outro cursor seja aberto.
Parâmetro de saída:
sqlcode: Código de erro. Zero se sucesso.
Retorno:
0 : sucesso. O cursor foi fechado.
-1 : erro
int SQL OPENBASEKILL(int num)
Descrição:
Termina uma conexão.
Parâmetro de entrada:
num : número da conexão.
Retorno:
0 : sucesso
-1 : erro ao fechar a conexão
char *SQL OPENBASEERROR(char *endereco)
Descrição:
A rotina SQL OPENBASEERROR gera a mensagem de erro relativa á última chamada efetuada.
A mensagem é terminada com o caracter ‘\0’ e possui um tamanho máximo de 120 bytes.
Parâmetro de entrada :
endereco : endereço da mensagem. Se for passado com o valor (CHAR *) 0L, a mensagem é construída em uma área interna da rotina, que é alterada a cada nova chamada.
Retorno:
Endereço da mensagem
Veja também SQLCODE.