Post on 11-Feb-2019
Manual de Técnicas de Uso
DBOs 2.0
Novembro/2001
Copyright © 1998 DATASUL S.A. Todos os direitos reservados.
Nenhuma parte deste documento pode ser copiada, reproduzida, traduzida ou
transmitida por qualquer meio eletrônico ou mecânico, na sua totalidade ou em
parte, sem a prévia autorização escrita da DATASUL S.A., que se reserva o
direito de efetuar alterações sem aviso prévio. A DATASUL S.A não assume
nenhuma responsabilidade pelas conseqüências de quaisquer erros ou
inexatidões que possam aparecer neste documento.
DATASUL S.A.
Av. Santos Dumont, 831, Joinville, SC, CEP 89.222-900
i
Índice
CAPÍTULO 1 Como utilizar os DBOs ................................................. 3
Utilização dos DBOs no UIB/ADM1 ............................................................ 6 Métodos Básicos ............................................................................................ 7 DBO XML Receiver .................................................................................... 22 Virtual DBO................................................................................................. 28 Considerações Gerais ................................................................................... 45
3
CAPÍTULO 1
Como utilizar os DBOs
Este capítulo é destinado ao desenvolvedor que vai utilizar DBOs já existentes.
Para utilizar um DBO devem ser seguidos os seguintes passos:
definir temp-table de comunicação;
definir temp-table de erro;
criar instância do DBO;
executar métodos;
eliminar instância do DBO, quando utilizado em ambiente state-less.
A seguir são detalhados estes passos.
Definir temp-table de comunicação
Normalmente, o DBO utiliza uma temp-table para troca de dados. A temp-
table geralmente é definida como a tabela principal do DBO (LIKE
<TableName>) e o seu nome são definidos pelo desenvolvedor.
Esta temp-table é utilizada para enviar e receber dados aos métodos do DBO.
Deve-se verificar quais métodos do DBO utilizam a temp-table como
parâmetro.
A definição é feita utilizando-se o include com mesmo nome do DBO.
Exemplo: Definição da temp-table de comunicação do DBO xxbo/boxx001.p,
associado a tabela customer.
/* Temp-table Definitions --- */
Descrição
Características
4
{xxbo/boxx001.i ttCustomer}
Definir temp-table de erro
O DBO normalmente devolve os erros na temp-table RowErrors. Para tanto a
mesma deve estar definida no programa.
Use o include method/dbotterr.i no início do programa.
Exemplo: Definição da temp-table RowErrors.
/* Temp-table Definitions --- */
{method/dbotterr.i}
Criar instância do DBO
O DBO é um programa persistente, ou seja, precisa ser carregado em memória
para que se possa acessar seus métodos. Isto é feito criando a instância do
DBO que se deseja usar (usando o comando RUN PERSISTENT) e guardando
um ponteiro para esta instância (HANDLE).
Exemplo: Criar instância para o DBO xxbo/boxx001.p, associado a tabela
customer.
/* Temp-table Definitions --- */
{method/dbotterr.i}
{xxbo/boxx001.i ttCustomer}
/* Variable Definitions --- */
DEFINE VARIABLE hBOXX001 AS HANDLE NO-UNDO.
/* DBO Instance --- */
RUN xxbo/boxx001.p PERSISTENT SET hBOXX001.
Executar métodos
Para executar os métodos do DBO basta utilizar o HANDLE já inicializado do
DBO.
Exemplo: Executar o método openQueryStatic do DBO xxbo/boxx001.p,
associado a tabela customer.
/* Temp-table Definitions --- */
{method/dbotterr.i}
{xxbo/boxx001.i ttCustomer}
CAPÍTULO 1 Como utilizar os DBOs 5
/* Variable Definitions --- */
DEFINE VARIABLE hBOXX001 AS HANDLE NO-UNDO.
/* DBO Instance --- */
RUN xxbo/boxx001.p PERSISTENT SET hBOXX001.
/* Main Block --- */
IF VALID-HANDLE(hBOXX001) THEN
RUN openQueryStatic IN hBOXX001 (INPUT "CustNum":U).
Eliminar instância do DBO
A eliminação da instância do DBO é feita através do método destroy.
Exemplo: Eliminar instância do DBO xxbo/boxx001.p, associado a tabela
customer.
/* Temp-table Definitions --- */
{method/dbotterr.i}
{xxbo/boxx001.i ttCustomer}
/* Variable Definitions --- */
DEFINE VARIABLE hBOXX001 AS HANDLE NO-UNDO.
/* DBO Instance --- */
RUN xxbo/boxx001.p PERSISTENT SET hBOXX001.
/* Destroy --- */
IF VALID-HANDLE(hBOXX001) THEN
RUN destroy IN hBOXX001.
Para o ambiente state-awhere normalmente a instância do DBO é eliminada
quando o programa chamador é eliminado da memória.
Porém quando utiliza-se o ambiente state-less é obrigatória a eliminação da
instância do DBO após a execução dos métodos desejados. Isto faz-se
necessário devido as seguintes características:
se não for eliminada a instância, quando o DBO for utilizado em ambiente
state-less, o DBO vai ficar “preso” na memória, causando alocação
incorreta da mesma;
possibilitando, no desenvolvimento WEB, a eliminação da instância do
DBO é essencial para o correto funcionamento do servidor WEB. Se for
esquecido de eliminar o DBO o Progress não vai liberar a memória
alocada causando perda de performance e em alguns casos o travamento
do serviço WEBSPEED;
6
outro problema que pode ocorrer é o bloqueio de registros, pois, uma vez
que a instância não é eliminada, o buffer do registro também pode ficar
ativo causando problemas de bloqueio. Isto deve ser analisado com
cuidado, pois isto é problema em potencial. Se houver problemas de
bloqueio deve-se analisar outros aspectos também, como a lógica do DBO
e do programa chamador.
Utilização dos DBOs no UIB/ADM1
A fim de reutilizar a regra de negócio que está dentro do DBO nos programas
desenvolvidos no UIB/ADM1 (caso dos produtos EMS2 e HR), temos
algumas restrições, pois nem todos os métodos podem ser reutilizados por
causa da arquitetura do ADM1.
Atualmente, a estratégia é reutilizar o que for possível, e o que não for possível
deve ficar temporariamente duplicado pois estão sendo construídos templates
GUI para o DBO. A arquitetura do DBO é diferente da arquitetura do ADM1 e
portanto é difícil sua integração.
A recomendação principal é que o DBO é um programa Progress normal,
sujeito as restrições e comportamentos do Progress. A diferença é que é um
programa persistente e o desenvolvedor deve cuidar para criação e eliminação
da instância do mesmo conforme explicado em “Como utilizar os DBOs” neste
manual.
A seguir algumas linhas gerais de como fazer isto:
o método validateRecord é provavelmente um dos que podem ser usados,
haja visto que ele faz a validação na temp-table de campos (RowObject) e
insere os erros em outra temp-table (RowErrors). No programa deve ser
feita a chamada deste método e então, é mostrada mensagem padrão em
caso de erro;
os métodos createRecord, updateRecord e deleteRecord ficam
complicados de usar na arquitetura do ADM1, pois o ADM1 já cuida da
criação, modificação e eliminação do registro. No momento, a estratégia
adotada é não usar este métodos do DBO no ADM1;
os métodos de navegação do DBO também não devem ser usados com
ADM1 pois eles também são fornecidos neste;
os métodos de negócio do DBO devem ser utilizados pois o objetivo é
reutilizar estas regras de negócio, como cálculos e processamentos;
CAPÍTULO 1 Como utilizar os DBOs 7
Métodos Básicos
Um DBO contém uma série de métodos padrão, denominados básicos. Estes
possuem o comportamento básico de qualquer DBO.
A seguir, especificamos o que cada método deve fazer:
bringCurrent
Este método posiciona a query no registro corrente. E ainda, retorna status do
processo através de RETURN-VALUE (OK/NOK).
Caso ocorra algum erro na execução do método, os erros estão gravados na
temp-table RowErrors.
Sintaxe:
RUN bringCurrent IN <handle DBO>.
Outras informações:
Para retornar o registro corrente, pode-se utilizar o método getRecord.
getFirst
Este método posiciona a query no primeiro registro. E ainda, retorna status do
processo através de RETURN-VALUE (OK/NOK).
Caso ocorra algum erro na execução do método, os erros estão gravados na
temp-table RowErrors.
Sintaxe:
RUN getFirst IN <handle DBO>.
Outras informações:
Para retornar o registro corrente, pode-se utilizar o método getRecord.
getLast
Este método posiciona a query no último registro. E ainda, retorna status do
processo através de RETURN-VALUE (OK/NOK).
Caso ocorra algum erro na execução do método, os erros estão gravados na
temp-table RowErrors.
8
Sintaxe:
RUN getLast IN <handle DBO>.
Outras informações:
Para retornar o registro corrente, pode-se utilizar o método getRecord.
getNext
Este método posiciona a query no próximo registro. E ainda, retorna status do
processo através de RETURN-VALUE (OK/NOK).
Caso ocorra algum erro na execução do método, os erros estão gravados na
temp-table RowErrors.
Sintaxe:
RUN getNext IN <handle DBO>.
Outras informações:
Para retornar o registro corrente, pode-se utilizar o método getRecord.
getPrev
Este método posiciona a query no registro anterior. E ainda, retorna status do
processo através de RETURN-VALUE (OK/NOK).
Caso ocorra algum erro na execução do método, os erros estão gravados na
temp-table RowErrors.
Sintaxe:
RUN getPrev IN <handle DBO>.
Outras informações:
Para retornar o registro corrente, pode-se utilizar o método getRecord.
repositionRecord
Este método reposiciona a query através de um rowid passado como
parâmetro. E ainda, retorna status do processo através de RETURN-VALUE
(OK/NOK).
Caso ocorra algum erro na execução do método, os erros estão gravados na
temp-table RowErrors.
CAPÍTULO 1 Como utilizar os DBOs 9
Sintaxe:
RUN repositionRecord IN <handle DBO>
(INPUT <pRowid ROWID>).
Parâmetros:
pRowid: parâmetro de entrada, que contém o rowid a ser reposicionado.
Outras informações:
Para retornar o registro corrente, pode-se utilizar o método getRecord.
createRecord
Este método cria um novo registro para a tabela {&TableName}. E ainda,
retorna status do processo através de RETURN-VALUE (OK/NOK).
Caso ocorra algum erro na execução do método, os erros estão gravados na
temp-table RowErrors.
Sintaxe:
RUN createRecord IN <handle DBO>.
Outras informações:
Para setar a temp-table RowObject, pode-se utilizar o método setRecord.
deleteRecord
Este método elimina o registro corrente da tabela {&TableName}. E ainda,
retorna status do processo através de RETURN-VALUE (OK/NOK).
Caso ocorra algum erro na execução do método, os erros estão gravados na
temp-table RowErrors.
Sintaxe:
RUN deleteRecord IN <handle DBO>.
Outras informações:
Para setar o registro a ser eliminado, pode-se utilizar os métodos: getFirst,
getLast, getNext, getPrev ou repositionRecord.
10
newRecord
Este método limpa e cria um novo registro para a temp-table RowObject. E
ainda, retorna status do processo através de RETURN-VALUE (OK/NOK).
Caso ocorra algum erro na execução do método, os erros estão gravados na
temp-table RowErrors.
Sintaxe:
RUN newRecord IN <handle DBO>.
Outras informações:
Geralmente, ele é utilizado quando deseja-se retornar os valores iniciais do
registro.
Para retornar a temp-table, pode-se utilizar o método getRecord.
updateRecord
Este método altera o registro corrente da tabela {&TableName}. E ainda,
retorna status do processo através de RETURN-VALUE (OK/NOK).
Caso ocorra algum erro na execução do método, os erros estão gravados na
temp-table RowErrors.
Sintaxe:
RUN updateRecord IN <handle DBO>.
Outras informações:
Para setar a temp-table RowObject, pode-se utilizar o método setRecord.
E para setar o registro a ser alterado, pode-se utilizar os métodos: getFirst,
getLast, getNext, getPrev ou repositionRecord.
_copyTT2Buffer
Este método atualiza o registro corrente da query com base na temp-table
RowObject. Este é um método interno e não deve ser utilizado pelo
desenvolvedor.
CAPÍTULO 1 Como utilizar os DBOs 11
destroy
Este método destrói o DBO. E ainda, retorna status do processo através de
RETURN-VALUE (OK/NOK).
Sintaxe:
RUN destroy IN <handle DBO>.
emptyRowErrors
Este método esvazia a temp-table RowErrors. E ainda, retorna status do
processo através de RETURN-VALUE (OK/NOK).
Sintaxe:
RUN emptyRowErrors IN <handle DBO>.
emptyRowObject
Este método esvazia a temp-table RowObject. E ainda, retorna status do
processo através de RETURN-VALUE (OK/NOK).
Sintaxe:
RUN emptyRowObject IN <handle DBO>.
emptyRowObjectAux
Este método esvazia a temp-table RowObjectAux. E ainda, retorna status do
processo através de RETURN-VALUE (OK/NOK).
Sintaxe:
RUN emptyRowObjectAux IN <handle DBO>.
getBatchRecords
Este método retorna uma faixa de registro da query na temp-table
RowObject, fazendo a leitura de query em sentido ascendente. E ainda,
retorna status do processo através de RETURN-VALUE (OK/NOK) e o
número de registros retornados.
Sintaxe:
RUN getBatchRecords IN <handle DBO>
( INPUT <pRowid ROWID>,
12
INPUT <pNext LOGICAL>,
INPUT <pRowsToReturned INTEGER>,
OUTPUT <pRowsReturned INTEGER>,
OUTPUT TABLE <pTable RowObject>).
Parâmetros:
pRowid: parâmetro de entrada, que indica o rowid a ser reposicionado para o
início da leitura;
pNext: parâmetro de entrada, que indica se a leitura deve ser feita a partir do
próximo registro;
pRowsToReturned: parâmetro de entrada, que indica o número de registros
a serem retornados;
pRowsReturned: parâmetro de saída, que indica o número de registros
retornados;
pTable: parâmetro de saída, temp-table na qual devem ser retornados os
registros.
getBatchRecordsPrev
Este método retorna uma faixa de registro da query na temp-table
RowObject, fazendo a leitura de query em sentido descendente. E ainda,
retorna status do processo através de RETURN-VALUE (OK/NOK) e o
número de registros retornados.
Sintaxe:
RUN getBatchRecordsPrev IN <handle DBO>
( INPUT <pRowid ROWID>,
INPUT <pPrev LOGICAL>,
INPUT <pRowsToReturned INTEGER>,
OUTPUT <pRowsReturned INTEGER>,
OUTPUT TABLE <pTable RowObject>).
Parâmetros:
pRowid: parâmetro de entrada, que indica o rowid a ser reposicionado para o
início da leitura;
pPrev: parâmetro de entrada, que indica se a leitura deve ser feita a partir do
registro anterior;
CAPÍTULO 1 Como utilizar os DBOs 13
pRowsToReturned: parâmetro de entrada, que indica o número de registros
a serem retornados;
pRowsReturned: parâmetro de saída, que indica o número de registros
retornados;
pTable: parâmetro de saída, temp-table na qual devem ser retornados os
registros.
getProtocol
Este método retorna a versão do protocolo do DBO. E ainda, retorna status do
processo através de RETURN-VALUE (OK/NOK).
Sintaxe:
RUN getProtocol IN <handle DBO>
(OUTPUT <pProtocol CHARACTER>).
Parâmetro:
pProtocol: parâmetro de saída, que contém a versão do protocolo do DBO.
getRawRecord
Este método retorna o registro corrente da query em uma variável RAW. E
ainda, retorna status do processo através de RETURN-VALUE (OK/NOK).
Sintaxe:
RUN getRawRecord IN <handle DBO>
(OUTPUT <pRaw RAW>).
Parâmetro:
pRaw: parâmetro de saída, que contém a variável Raw.
getRecord
Este método retorna a temp-table RowObject. E ainda, retorna status do
processo através de RETURN-VALUE (OK/NOK).
Caso ocorra algum erro na execução do método, os erros estão gravados na
temp-table RowErrors.
Sintaxe:
RUN getRecord IN <handle DBO>
14
(OUTPUT TABLE <pTable RowObject>).
Parâmetro:
pTable: parâmetro de saída, temp-table na qual devem ser retornados os
registros.
Outras informações:
Geralmente ele é utilizado em conjunto com os métodos: getFirst,
getLast, getNext, getPrev ou repositionRecord.
getRowErrors
Este método retorna a temp-table RowErrors. E ainda, retorna status do
processo através de RETURN-VALUE (OK/NOK).
Sintaxe:
RUN getRowErrors IN <handle DBO>
(OUTPUT TABLE <pTable RowErrors>).
Outras informações:
Geralmente ele é utilizado em conjunto com métodos que retornam um flag
que indica se o método foi executa com sucesso. Pois, caso algum método
retorne este flag com o valor NOK, a temp-table RowErrors contém
informações sobre os erros ocorridos internamente na execução dos métodos.
getRowid
Este método retorna o rowid do registro corrente da query. E ainda, retorna
status do processo através de RETURN-VALUE (OK/NOK).
Sintaxe:
RUN getRowid IN <handle DBO>
(OUTPUT <pRowid ROWID>).
Parâmetro:
pRowid: parâmetro de saída, que contém o rowid do registro corrente da
query.
CAPÍTULO 1 Como utilizar os DBOs 15
_insertError
Este método insere um novo registro na temp-table RowErrors. Este é um
método interno e não deve ser utilizado pelo desenvolvedor.
_insertErrorManual
Este método insere um novo registro na temp-table RowErrors porém todos
os campos são informados pelos desenvolvedor, exceto o campo seqüência.
Este é um método interno e não deve ser utilizado pelo desenvolvedor.
openQueryStatic
Este método verifica qual método de abertura de query deve ser executado,
através do parâmetro passado. E ainda, retorna status do processo através de
RETURN-VALUE (OK/NOK).
Sintaxe:
RUN openQueryStatic IN <handle DBO>
(INPUT <pQuery CHARACTER>).
Parâmetro:
pQuery: parâmetro de entrada, que indica qual o tipo de query a ser aberta.
selfInfo
Este método retorna informações sobre o DBO. Este é um método interno e
não deve ser utilizado pelo desenvolvedor. E ainda, retorna status do processo
através de RETURN-VALUE (OK/NOK).
Sintaxe:
RUN selfInfo IN <handle DBO> (OUTPUT TABLE <pTable RowInfo>).
Parâmetro:
pTable: parâmetro de saída, temp-table que contém informações sobre o
DBO.
setRecord
Este método transfere os dados a temp-table RowObject do Client para a
temp-table RowObject do DBO. E ainda, retorna status do processo através
de RETURN-VALUE (OK/NOK).
16
Caso ocorra algum erro na execução do método, os erros estão gravados na
temp-table RowErrors.
Sintaxe:
RUN setRecord IN <handle DBO>
(INPUT TABLE <pTable RowObject>).
Parâmetro:
pTable: parâmetro de entrada, temp-table que será transferida para o DBO.
Outras informações:
Geralmente, ele é utilizado em conjunto com os métodos: createRecord
ou updateRecord.
_copyBuffer2TT
Este método atualiza a temp-table RowObject com base no registro corrente
da query. Este é um método interno e não deve ser utilizado pelo
desenvolvedor.
openQuery<Description>
Este método abre a query. E ainda, retorna status do processo através de
RETURN-VALUE (OK/NOK).
Sintaxe:
RUN openQuery<Description> IN <handle DBO>.
Outras informações:
Este método não deve ser utilizado para abrir a query diretamente. Para
realizar a abertura da query deve-se utilizar o método: openQueryStatic.
setConstraint<Description>
Este método seta restrições que podem ser utilizadas posteriormente pelo
método openQueryStatic.
Sintaxe: RUN setConstraint<Description> IN <handle DBO>
(INPUT <pConstraint ?>, ...).
CAPÍTULO 1 Como utilizar os DBOs 17
Parâmetro:
pConstraint: parâmetros de entrada, que contém os valores das restrições
que podem ser utilizadas posteriormente pelo método openQueryStatic.
validateRecord
Este método executa todas as validações pertinentes ao DBO. E ainda, retorna
status do processo através de RETURN-VALUE (OK/NOK).
Sintaxe:
RUN validateRecord IN <handle DBO>
(INPUT <pType CHARACTER>).
Parâmetro:
pType: parâmetro de entrada, que indica o tipo de validação a ser executada.
Pode possuir os valores: Create, Delete e Update.
linkTo<Description>
Este método recebe o handle de outro DBO e executa o método getKey com
o handle recebido a fim de setar uma restrição relacionada ao outro DBO. E
ainda, retorna status do processo através de RETURN-VALUE (OK/NOK).
Sintaxe:
RUN linkTo<Description> IN <handle DBO>
(INPUT <pHandle HANDLE>).
Parâmetro:
pHandle: parâmetro de entrada, que contém o handle de outro DBO.
Outras informações:
Geralmente, ele é utilizado quando faz-se necessária a integração entre DBOs.
getKey
Este método retorna os valores dos campos do índice único da tabela
{&TableName}. E ainda, retorna status do processo através de RETURN-VALUE (OK/NOK).
Sintaxe:
18
RUN getKey IN <handle DBO>
(OUTPUT <pKey ?>, ...).
Parâmetro:
pKey: parâmetros de saída, que contém os valores dos campos do índice único
da tabela {&TableName}.
Outras informações:
Geralmente, ele é utilizado quando faz-se necessária a integração entre DBOs.
goToKey
Este método reposiciona a query através dos valores dos campos do índice
único da tabela {&TableName}. E ainda, retorna status do processo através
de RETURN-VALUE (OK/NOK).
Caso ocorra algum erro na execução do método, os erros estão gravados na
temp-table RowErrors.
Sintaxe:
RUN goToKey IN <handle DBO>
(INPUT <pKey ?>, ...). Parâmetros:
pKeys: parâmetros de entrada, que contém os valores dos campos do índice
único da tabela {&TableName}.
Outras informações:
Para retornar o registro corrente, pode-se utilizar o método getRecord.
get<Char/Int/Dec/Date/Recid/Rowid/Raw>Field
Estes métodos retornam os valores dos campos da tabela {&TableName},
conforme o tipo do campo. E ainda, retorna status do processo através de RETURN-VALUE (OK/NOK).
Sintaxe:
RUN get<Field-Data-Type> IN <handle DBO>
( INPUT <pFieldName CHARACTER>,
OUTPUT <pFieldValue Field-Data-Type).
Parâmetro:
CAPÍTULO 1 Como utilizar os DBOs 19
pFieldName: parâmetros de saída, que contém o nome do campo a ser
retornado;
pFieldValue: parâmetros de saída, que terá o valor do campo solicitado.
setQueryWhere
Este método permite determinar o conteúdo da clausula WHERE que será
utilizada pelo método openQueryDynamic. Geralmente este método é utilizado
para definir uma faixa de registros a serem retornados pela Query.
Sintaxe:
RUN setQueryWhere IN <handle DBO>
( INPUT <pWhereClause CHARACTER>).
Parâmetros:
pWhereClause: Clausula do WHERE do Progress (sem a palavra
WHERE). O nome da tabela pode ser informado como &1 garantindo com
isso independência em relação ao nome físico da tabela, que pode
eventualmente ser alterado;
Nota: Além do conteúdo informado através do método setQueryWhere, a
clausula WHERE efetivamente usada pela Query dinâmica terá também
restrições de segurança que são definidas pelo próprio DBO e não podem ser
sobrepostas pelo usuário do DBO.
setQueryBy
Este método permite determinar a ordenação dos registros retornados pelo
método openQueryDynamic.
Sintaxe:
RUN setQueryBy IN <handle DBO>
( INPUT <pByClause CHARACTER>).
Parâmetros:
pByClause: Clausula do BY com a palavra BY e separado por virgula e
novamente a palavra BY se mais de um campo for usado para ordenação. O
nome da tabela pode ser informado como &1 garantindo com isso
20
independência em relação ao nome físico da tabela, que pode eventualmente
ser alterado;
setQueryFieldList
Este método permite determinar os campos que devem ser lidos pela Query no
método openQueryDynamic. Geralmente este método visa melhorar a
performance de execução da query, evitando que campos não utilizados sejam
lidos por ela.
Sintaxe:
RUN setQueryFieldList IN <handle DBO>
( INPUT <pFieldList CHARACTER>).
Parâmetros:
pFieldList: Lista dos campos sem o nome da tabela e separados por
espaço em branco.
openQueryDynamic
Este método abre uma query baseada nos parâmetros informados nos métodos
setQueryWhere, setQueryBy e setQueryFieldList. Após a execução deste
método todos os métodos de navegação e atualização de registro ficam
disponíveis para uso, da mesma forma que acontece com o método
openQueryStatic..
Sintaxe:
RUN openQueryDynamic IN <handle DBO>.
Atenção: A consistência das informações passadas em setQueryWhere,
setQueryBy e setQueryFieldList é feita no método openQueryDynamic.
Portanto se alguma informa inconsistente foi passada neles, será retorno
“NOK” através do RETURN-VALUE e os erros estarão disponíveis através do
método getRowErrors.
CAPÍTULO 1 Como utilizar os DBOs 21
Nota: Na versão atual do DBO não é possível utilizar JOIN (EACH, EACH) de
tabelas na Query Dinâmica. Quando necessário, os JOINs devem ser providos
por Queries Estáticas utilizadas através do método OpenQueryStatic.
resetQueryParameters
Em um único método limpa o conteúdo dos métodos setQueryWhere,
setQueryBy e setQueryFieldList. Deve ser usado antes da reabertura de uma
query dinâmica, caso se deseje ler todos os registros da tabela.
Sintaxe:
RUN resetQueryParameters IN <handle DBO>.
22
DBO XML Receiver
Nota: Todos os métodos listados em DBO XML Receiver só estarão
disponíveis nos DBOs que sejam XMLReceivers, ou seja, que tenham o pré-
processador XMLReceiver definido na sua construção.
getRowErrorsXML
Retorna o conteúdo da RowErros em formato XML.
Sintaxe:
RUN getRowErrorsXML IN <handle DBO>
(INPUT-OUTPUT pErrorsMessage X-DOCUMENT | X-NODEREF).
Parâmetros:
pErrorsMessage: Se for passado o handle de um objeto X-DOCUMENT,
a tag <ERRORS> será a tag root deste documento. Se for passado o handle de
um objeto X-NODEREF, a tag <ERRORS> será filha deste objeto. Se não for
passado um handle válido, o método vai criar um novo documento e dará o
mesmo tratamento de X-DOCUMENT. contendo os erros.
Categoria:
Método de Busca de Dados.
Formato do registro de Erro em XML:
<ERRORS>
<ERROR>
<ErrorSequence>
<ErrorNumber>
<ErrorDescription>
<ErrorParameters>
<ErrorType>
<ErrorHelp>
<ErrorSubType>
</ERROR>
</ERRORS>
CAPÍTULO 1 Como utilizar os DBOs 23
receiveMessage
Recebe uma mensagem XML e executa a ação estabelecida na tag
<ACTION>.
Sintaxe:
RUN receiveMessage IN <handle DBO>
(INPUT pReceiveMessage X-DOCUMENT,
OUTPUT pReturnMessage X-DOCUMENT).
Parâmetros:
pErrorsMessage: Se for passado o handle de um objeto X-DOCUMENT,
a tag <ERRORS> será a tag root deste documento. Se for passado o handle de
um objeto X-NODEREF, a tag <ERRORS> será filha deste objeto. Se não for
passado um handle válido, o método vai criar um novo documento e dará o
mesmo tratamento de X-DOCUMENT. contendo os erros.
Categoria:
Genérico.
Formato da mensagem XML de pReceiveMessage:
<DATASUL-MESSAGE>
<ACTION>
<BODY>
<TABELA>
<CAMPO1>
<CAMPO2>
<CAMPOn>
</TABELA>
</BODY>
</DATASUL-MESSAGE>
Parâmetros da mensagem XML de pReceiveMessage:
<ACTION>: ADD, UPDATE, DELETE, LIST (ver mais detalhes sobre
mensagem com action = LIST adiante no documento).
Formato da mensagem XML de pReceiveMessage (ACTION = LIST):
<DATASUL-MESSAGE>
<ACTION>LIST</ACTION>
24
<BODY>
<CONSTRAINT>
<CAMPO1>
<CAMPO2>
<CAMPOn>
</CONSTRAINT>
<ORDER-BY>
<CAMPO1>A/D</CAMPO1>
</CAMPOn>
</ORDER-BY>
<FIELD-LIST>
<CAMPO1>
<CAMPO2>
<CAMPOn>
</FIELD-LIST>
</BODY>
</DATASUL-MESSAGE>
Parâmetros da mensagem XML de pReceiveMessage (ACTION = LIST):
<ACTION>: LIST
<CONSTRAINT>: Indica as restrições (filtro) que devem ser aplicadas para
determinar os registros a serem retornados
<CAMPO1...n>: Campos para os quais deve ser feito o filtro. Se após a tag
do campo for informado um valor, a restrição será do tipo igualdade.
CAMPO1 = valor1. Se informadas as tags <FROM> ou <TO> a restrição será
do tipo faixa: <FROM> >= ; <TO> <=. Se um mesmo campo for
repetido várias vezes em tags adjacentes, as restrições serão unidas por OR,
sendo retornados os registros que atenderem a pelo menos uma das restrições
daquele campo. Os campos diferentes serão agrupados com AND, e com isso
os registros retornados deverão atender às restrições de todos os diferentes
campos informados. Se duas restrições de um mesmo campo forem
intercaladas por um segundo campo, eles serão considerados campos
diferentes e unidos por AND. Se um campo inexistente for informado como
restrição, ele será ignorado e nenhum erro será mostrado.
<ORDER-BY>: Indica a ordenação que os registros devem ser devolvidos
CAPÍTULO 1 Como utilizar os DBOs 25
<CAMPO1...n>: Campos utilizados na ordenação. A seqüência informada
dos campos será a mesma da ordenação. Para cada campo, opcionalmente
pode ser informado o valor A ou D, respectivamente para Ascendente e
Descendente. Se não informado, será usado Ascendente por padrão. Se um
campo inexistente for informado, será retornado um erro Progress indicando
que não foi possível entender o campo especificado.
<FIELD-LIST>: Indica os campos que devem fazer parte do documento de
retorno. Se esta tag não for informada, serão retornados todos os campos do
DBO. Independente da lista de campos informada, os campos da chave são
sempre retornados.
<CAMPO1...n>: Campos que devem fazer parte do documento de retorno.
Se um campo inexistente for informado, será retornado um erro Progress
indicando que não foi possível entender o campo especificado.
<MAX-ROWS>: Indica o número máximo de registros que devem ser
retornados. No caso da restrição resultar em uma quantidade muito grande de
registros, este parâmetro evita que a mensagem de retorno seja muito grande.
<FIRST-ROWID>: Determina o rowid , tag <r-ROWID>, do primeiro
registro que deve fazer parte da mensagem de retorno. Geralmente utilizado na
leitura subseqüente ao uso de MAX-ROWS para trazer o próximo bloco de
registros.
<AFTER-ROWID>: Determina o rowid , tag <r-ROWID>, do registro anterior
ao primeiro registro que deve fazer parte da mensagem de retorno. Geralmente
utilizado na leitura subseqüente ao uso de MAX-ROWS para trazer o próximo
bloco de registros.
Formato da mensagem XML de pReturnMessage quando ocorre ERRO:
<DATASUL-MESSAGE>
<BODY>
<ERRORS>
<ERROR>
<ErrorSequence>
<ErrorNumber>
<ErrorDescription>
<ErrorParameters>
<ErrorType>
<ErrorHelp>
26
<ErrorSubType>
</ERROR>
</ERRORS>
</BODY>
</DATASUL-MESSAGE>
Formato da mensagem XML de pReturnMessage quando o processamento é OK (ACTION: ADD, UPDATE, DELETE):
<DATASUL-MESSAGE> <BODY />
</DATASUL-MESSAGE>
Formato da mensagem XML de pReturnMessage quando o processamento é OK (ACTION: LIST):
<DATASUL-MESSAGE>
<TOPIC>
<ACTION>SHOW</ACTION>
<BODY>
<TABELAS>
<TABELA>
<CAMPO1>
<CAMPO2>
<CAMPOn>
<r-Rowid>
</TABELA>
</TABELAS> </BODY>
</DATASUL-MESSAGE>
Nota: Se não houver registros a serem retornados, a mensagem terá a tag
<BODY> vazia.
findRecordOFRowObject
Localiza um registro na tabela baseado no conteúdo de RowObject que é
temp-table do DBO. Este método executado após o método setRecord, permite
CAPÍTULO 1 Como utilizar os DBOs 27
localizar o registro na tabela sem saber o seu rowid ou usar o método
goToKey.
Sintaxe:
RUN findRecordOFRowObject IN <handle DBO>.
28
Virtual DBO
Tem como objetivo manter um conjunto de registros de uma tabela temporária
(temp-table) entre várias chamadas stateless (ex. WebSpeed).
Este conjunto de registros pode ser um result-set utilizado para pesquisa ou
registros que devem ser criados de uma única vez em tabela física do Banco de
Dados, mas que estão disponíveis somente naquela sessão, ou seja, não estarão
disponíveis no Banco de Dados caso o usuário tenha efetuado outro login.
O Virtual DBO possuí os seguintes métodos:
setToken
Este mecanismo poderá ser utilizado tanto pela WEB, como por GUI Stateless,
portanto o Token, que é o identificador da sessão do usuário, nem sempre será
o Cookie da WEB. Por este motivo, deve haver uma função que receba este
valor, ficando a cargo da interface gerá-lo. O valor do Token (não o Token da
sessão WEB) é único por instância do “Virtual DBO” e armazenado em uma
variável local.
Sintaxe:
RUN setToken IN <handle VDBO>
(INPUT <cToken CHARACTER>).
Parâmetros:
cToken: parâmetro de entrada, que contém o Token a ser armazenado.
Categoria:
Método de Configuração e Controle.
Obrigatoriedade:
A execução deste método é necessária.
Outras informações:
Caso o método tenha sido executado com sucesso, será retornado, via return-
value, OK. Caso tenha ocorrido algum erro na execução do método, será
retornado NOK e os erros serão gravados na temp-table RowErrors.
CAPÍTULO 1 Como utilizar os DBOs 29
createToken
Se a interface não desejar gerar um valor de Token, este pode ser gerado
através deste método.
Sintaxe:
RUN createToken IN <handle VDBO>
(OUTPUT <cToken CHARACTER>).
Parâmetros:
cToken: parâmetro de saída, que contém o Token gerado.
Categoria:
Método de Configuração e Controle.
Obrigatoriedade:
A execução deste método não é necessária.
Outras informações:
Caso o método tenha sido executado com sucesso, será retornado, via return-
value, OK. Caso tenha ocorrido algum erro na execução do método, será
retornado NOK e os erros serão gravados na temp-table RowErrors.
getToken
Devolve para interface o Token atual.
Sintaxe:
RUN getToken IN <handle VDBO>
(OUTPUT <cToken CHARACTER>).
Parâmetros:
cToken: parâmetro de saída, que contém o Token que está sendo utilizado
naquela momento.
Categoria:
Método de Configuração e Controle.
Obrigatoriedade:
A execução deste método não é necessária.
Outras informações:
30
Caso o método tenha sido executado com sucesso, será retornado, via return-
value, OK. Caso tenha ocorrido algum erro na execução do método, será
retornado NOK e os erros serão gravados na temp-table RowErrors.
setTableName
Define o nome da tabela (temp-table) que vai identificar de forma única o
conjunto de registros para cada instância do VDBO de um mesmo token.
Sintaxe:
RUN setTableName IN <handle VDBO>
(INPUT <cTabela CHARACTER>).
Parâmetros:
cTabela: parâmetro de entrada, que contém o nome da tabela a ser utilizada.
Categoria:
Método de Configuração e Controle.
Obrigatoriedade:
A execução deste método é necessária.
Outras informações:
Caso o método tenha sido executado com sucesso, será retornado, via return-
value, OK. Caso tenha ocorrido algum erro na execução do método, será
retornado NOK e os erros serão gravados na temp-table RowErrors.
setTableHandle
Define o handle da tabela (temp-table) a ser utilizada pelo Virtual DBO.
Sintaxe:
RUN setTableHandle IN <handle VDBO>
(INPUT (BUFFER <cTabela CHARACTER>:HANDLE)).
Parâmetros:
cTabela: parâmetro de entrada, que contém o nome da tabela a ser utilizada.
Categoria:
Método de Configuração e Controle.
Obrigatoriedade:
CAPÍTULO 1 Como utilizar os DBOs 31
A execução deste método é necessária.
Outras informações:
Caso o método tenha sido executado com sucesso, será retornado, via return-
value, OK. Caso tenha ocorrido algum erro na execução do método, será
retornado NOK e os erros serão gravados na temp-table RowErrors.
getTable
Permite consultar o nome da tabela (temp-table) que está sendo utilizada
naquele momento.
Sintaxe:
RUN getTableName IN <handle VDBO>
(OUTPUT <cTabela CHARACTER>).
Parâmetros:
cTabela: parâmetro de saída, que contém o nome da tabela utilizada.
Categoria:
Método de Configuração e Controle.
Obrigatoriedade:
A execução deste método não é necessária.
Outras informações:
Caso o método tenha sido executado com sucesso, será retornado, via return-
value, OK. Caso tenha ocorrido algum erro na execução do método, será
retornado NOK e os erros serão gravados na temp-table RowErrors.
SetIndexType
Define a forma de calcular o valor que vai no campo índice, ou seja, com base
no conteúdo deste campo, serão lidos os registros.
Valor Tipo Descrição
0 Sequencial A leitura dos registro será feita na mesma ordem na qual foram
criados
1 Nome do campo Criará um índice com base nos conteúdos dos campos passados como
parâmetro.
2 PI Callback Cria´ra um índice com base no conteúdo retornado por uma procedure
do desenvolvedor.
32
Sintaxe:
RUN setIndexType IN <handle VDBO>
(INPUT <iTipo INTEGER>,
INPUT <cComplemento CHARACTER>,
INPUT <hComplemento HANDLE>).
Parâmetros:
iTipo: parâmetro de entrada, que contém o tipo de índice a ser utilizado.
cComplemento: parâmetro de entrada, que contém o complemento para o
índice que será utilizado.
hComplemento: parâmetro de entrada, que contém o handle do programa
que contêm a PI CallBack.
Valor Complemento Complemento2
0 Nenhum Nenhum
1 Lista de campos separados por virgula Nenhum
2 Nome da procedure de CallBack Handle da PI de CallBack
Categoria:
Método de Configuração e Controle.
Obrigatoriedade:
A execução deste método não é necessária.
Outras informações:
Caso o método tenha sido executado com sucesso, será retornado, via return-
value, OK. Caso tenha ocorrido algum erro na execução do método, será
retornado NOK e os erros serão gravados na temp-table RowErrors.
A Utilização do tipo 2 (Índice da Temp-Table) não tratará índices
Descendentes.
A PI de Callback recebe o buffer da temp-table já posicionada e retorna uma
string.
CAPÍTULO 1 Como utilizar os DBOs 33
setQuerySort
Define se os registros serão lidos ascendente (default) ou descendente no valor
calculado através do método setIndexType.
Sintaxe:
RUN setQuerySort IN <handle VDBO>
(INPUT <iTipo INTEGER>).
Parâmetros:
iTipo: parâmetro de entrada, que contém o tipo de ordenação a ser utilizada.
Valor Tipo
1 Ascendente (default)
2 Descendente
Categoria:
Método de Configuração e Controle.
Obrigatoriedade:
A execução deste método não é necessária.
Outras informações:
Caso o método tenha sido executado com sucesso, será retornado, via return-
value, OK. Caso tenha ocorrido algum erro na execução do método, será
retornado NOK e os erros serão gravados na temp-table RowErrors.
Caso este método não seja executado, será assumido o seu valor padrão, que é
Ascendente.
getFirst
Reposiciona no primeiro registro.
Sintaxe:
RUN getFirst IN <handle VDBO>.
Categoria:
Método de Navegação.
Outras informações:
34
Caso o método tenha sido executado com sucesso, será retornado, via return-
value, OK. Caso tenha ocorrido algum erro na execução do método, será
retornado NOK e os erros serão gravados na temp-table RowErrors.
getLast
Reposiciona no último registro.
Sintaxe:
RUN getLast IN <handle VDBO>.
Categoria:
Método de Navegação.
Outras informações:
Caso o método tenha sido executado com sucesso, será retornado, via return-
value, OK. Caso tenha ocorrido algum erro na execução do método, será
retornado NOK e os erros serão gravados na temp-table RowErrors.
getNext
Reposiciona no próximo registro.
Sintaxe:
RUN getNext IN <handle VDBO>.
Categoria:
Método de Navegação.
Outras informações:
Caso o método tenha sido executado com sucesso, será retornado, via return-
value, OK. Caso tenha ocorrido algum erro na execução do método, será
retornado NOK e os erros serão gravados na temp-table RowErrors.
getPrev
Reposiciona no registro anterior.
Sintaxe:
RUN getPrev IN <handle VDBO>.
CAPÍTULO 1 Como utilizar os DBOs 35
Categoria:
Método de Navegação.
Outras informações:
Caso o método tenha sido executado com sucesso, será retornado, via return-
value, OK. Caso tenha ocorrido algum erro na execução do método, será
retornado NOK e os erros serão gravados na temp-table RowErrors.
repositionRecord
Reposiciona o registro pelo seu ROWID. Deve ser sempre utilizado o ROWID
gerado automaticamente pelo VDBO (r-rowid).
Sintaxe:
RUN repositionRecord IN <handle VDBO>
(INPUT <rRowid ROWID>).
Parâmetros:
rRowid: parâmetro de entrada, que contém o ROWID do registro a ser
posicionado.
Categoria:
Método de Navegação.
Outras informações:
Caso o método tenha sido executado com sucesso, será retornado, via return-
value, OK. Caso tenha ocorrido algum erro na execução do método, será
retornado NOK e os erros serão gravados na temp-table RowErrors.
getBatchRecords
Retorna um conjunto de registros com base nos parâmetros passados.
Sintaxe:
RUN getBatchRecords IN <handle VDBO>
(INPUT <rRowidIni ROWID>,
INPUT <lProx LOGICAL>,
INPUT <iQtd INTEGER>,
OUTPUT <iRet INTEGER>,
INPUT <htt HANDLE>).
36
Parâmetros:
rRowidIni: parâmetro de entrada, que contém o ROWID inicial para a
busca.
lProx: parâmetro de entrada, que define se a leitura será feita a partir do
registro corrente (definido pelo rRowidIni) ou pelo seguinte.
iQtd parâmetro de entrada, que define o número de registros a serem
retornados pelo método.
iRet: parâmetro de saída, que contém o número de registros retornados pelo
método.
htt: parâmetro de entrada, que contém o handle da temp-table onde serão
retornados os registros.
Categoria:
Método de Busca de Dados.
Outras informações:
Caso o método tenha sido executado com sucesso, será retornado, via return-
value, OK. Caso tenha ocorrido algum erro na execução do método, será
retornado NOK e os erros serão gravados na temp-table RowErrors.
getCurrent
Retorna o registro atual na temp-table.
Sintaxe:
RUN getCurrent IN <handle VDBO>
(INPUT <htt HANDLE>).
Parâmetros:
htt: parâmetro de entrada, que contém o handle da temp-table onde será
retornado o registro.
Categoria:
Método de Busca de Dados.
Outras informações:
CAPÍTULO 1 Como utilizar os DBOs 37
Caso o método tenha sido executado com sucesso, será retornado, via return-
value, OK. Caso tenha ocorrido algum erro na execução do método, será
retornado NOK e os erros serão gravados na temp-table RowErrors.
getFieldValue
Retorna o valor do campo do registro corrente passado como parâmetro.
Sintaxe:
RUN getFieldValue IN <handle VDBO>
(INPUT <cFieldname CHARACTER>,
OUPTUT <cFieldValue CHARACTER>).
Parâmetros:
cFieldName: parâmetro de entrada, contendo o nome do campo a ser
retornado o seu valor.
cFieldValue: parâmetro de saída, contendo o valor do campo pesquisado.
Categoria:
Método de Busca de Dados.
Outras informações:
Caso o método tenha sido executado com sucesso, será retornado, via return-
value, OK. Caso tenha ocorrido algum erro na execução do método, será
retornado NOK e os erros serão gravados na temp-table RowErrors.
getCharField
Retorna o valor do campo do registro corrente - CHARACTER.
Sintaxe:
RUN getCharField IN <handle VDBO>
(INPUT <cFieldname CHARACTER>,
OUPTUT <cFieldValue CHARACTER>).
Parâmetros:
cFieldName: parâmetro de entrada, contendo o nome do campo a ser
retornado o seu valor.
cFieldValue: parâmetro de saída, contendo o valor do campo pesquisado.
38
Categoria:
Método de Busca de Dados.
Outras informações:
Caso o método tenha sido executado com sucesso, será retornado, via return-
value, OK. Caso tenha ocorrido algum erro na execução do método, será
retornado NOK e os erros serão gravados na temp-table RowErrors.
getIntField
Retorna o valor do campo do registro corrente – INTEGER.
Sintaxe:
RUN getIntField IN <handle VDBO>
(INPUT <cFieldname CHARACTER>,
OUPTUT <cFieldValue INTEGER>).
Parâmetros:
cFieldName: parâmetro de entrada, contendo o nome do campo a ser
retornado o seu valor.
cFieldValue: parâmetro de saída, contendo o valor do campo pesquisado.
Categoria:
Método de Busca de Dados.
Outras informações:
Caso o método tenha sido executado com sucesso, será retornado, via return-
value, OK. Caso tenha ocorrido algum erro na execução do método, será
retornado NOK e os erros serão gravados na temp-table RowErrors.
getDecField
Retorna o valor do campo do registro corrente - DECIMAL.
Sintaxe:
RUN getDecField IN <handle VDBO>
(INPUT <cFieldname CHARACTER>,
OUPTUT <cFieldValue DECIMAL>).
Parâmetros:
CAPÍTULO 1 Como utilizar os DBOs 39
cFieldName: parâmetro de entrada, contendo o nome do campo a ser
retornado o seu valor.
cFieldValue: parâmetro de saída, contendo o valor do campo pesquisado.
Categoria:
Método de Busca de Dados.
Outras informações:
Caso o método tenha sido executado com sucesso, será retornado, via return-
value, OK. Caso tenha ocorrido algum erro na execução do método, será
retornado NOK e os erros serão gravados na temp-table RowErrors.
getDateField
Retorna o valor do campo do registro corrente - DATE.
Sintaxe:
RUN getDateField IN <handle VDBO>
(INPUT <cFieldname CHARACTER>,
OUPTUT <cFieldValue DATE>).
Parâmetros:
cFieldName: parâmetro de entrada, contendo o nome do campo a ser
retornado o seu valor.
cFieldValue: parâmetro de saída, contendo o valor do campo pesquisado.
Categoria:
Método de Busca de Dados.
Outras informações:
Caso o método tenha sido executado com sucesso, será retornado, via return-
value, OK. Caso tenha ocorrido algum erro na execução do método, será
retornado NOK e os erros serão gravados na temp-table RowErrors.
getRowidField
Retorna o valor do campo do registro corrente - ROWID.
Sintaxe:
RUN getRowidField IN <handle VDBO>
40
(INPUT <cFieldname CHARACTER>,
OUPTUT <cFieldValue ROWID>).
Parâmetros:
cFieldName: parâmetro de entrada, contendo o nome do campo a ser
retornado o seu valor.
cFieldValue: parâmetro de saída, contendo o valor do campo pesquisado.
Categoria:
Método de Busca de Dados.
Outras informações:
Caso o método tenha sido executado com sucesso, será retornado, via return-
value, OK. Caso tenha ocorrido algum erro na execução do método, será
retornado NOK e os erros serão gravados na temp-table RowErrors.
getLogField
Retorna o valor do campo do registro corrente - LOGICAL.
Sintaxe:
RUN getLogField IN <handle VDBO>
(INPUT <cFieldname CHARACTER>,
OUPTUT <cFieldValue LOGICAL>).
Parâmetros:
cFieldName: parâmetro de entrada, contendo o nome do campo a ser
retornado o seu valor.
cFieldValue: parâmetro de saída, contendo o valor do campo pesquisado.
Categoria:
Método de Busca de Dados.
Outras informações:
Caso o método tenha sido executado com sucesso, será retornado, via return-
value, OK. Caso tenha ocorrido algum erro na execução do método, será
retornado NOK e os erros serão gravados na temp-table RowErrors.
CAPÍTULO 1 Como utilizar os DBOs 41
getRowid
Retorna o ROWID do registro atual gerado pelo VDBO (r-rowid).
Sintaxe:
RUN getRowid IN <handle VDBO>
(OUPTUT <rRowid ROWID>).
Parâmetros:
rRowid: parâmetro de saída, contendo o ROWID do registro atual.
Categoria:
Método de Busca de Dados.
Outras informações:
Caso o método tenha sido executado com sucesso, será retornado, via return-
value, OK. Caso tenha ocorrido algum erro na execução do método, será
retornado NOK e os erros serão gravados na temp-table RowErrors.
getRowErrors
Retorna uma temp-table com os erros que ocorreram durante o processamento
de algum método.
Sintaxe:
RUN getCharField IN <handle VDBO>
(OUPTUT TABLE [<Rowerrors TEMP-TABLE>]
[<tt-bo-erro TEMP-TABLE>]).
Parâmetros:
RowErros: parâmetro de saída, temp-table contendo os erros.
Categoria:
Método de Busca de Dados.
Outras informações:
Caso o método tenha sido executado com sucesso, será retornado, via return-
value, OK. Caso tenha ocorrido algum erro na execução do método, será
retornado NOK.
42
createRecord
Cria o registro na base de dados. Mesma funcionalidade dos DBO’s normais,
porém ao invés de ser passada a temp-table, é passado o seu handle.
Sintaxe:
RUN createRecord IN <handle VDBO>
(INPUT <htt HANDLE>).
Parâmetros:
htt: parâmetro de entrada, contendo o handle da temp-table.
Categoria:
Método de Manutenção de Registros.
Outras informações:
Caso o método tenha sido executado com sucesso, será retornado, via return-
value, OK. Caso tenha ocorrido algum erro na execução do método, será
retornado NOK e os erros serão gravados na temp-table RowErrors.
deleteRecord
Elimina o registro atual da base de dados. Deve-se sempre estar com o registro
a ser eliminado já posicionado, tanto na virtual dbo quanto na interface. Para
posicionar o registro basta rodar o RepositionRecord na virtual dbo e em
seguida o GetCurrent para trazer o mesmo para interface e posicioná-lo.
Ex:
RUN repositionRecord IN <handle DBO>
(INPUT <pRowid ROWID>).
RUN getCurrent IN <handle VDBO>
(INPUT <htt HANDLE>).
Sintaxe:
RUN deleteRecord IN <handle VDBO>.
Categoria:
Método de Manutenção de Registros.
Outras informações:
CAPÍTULO 1 Como utilizar os DBOs 43
Caso o método tenha sido executado com sucesso, será retornado, via return-
value, OK. Caso tenha ocorrido algum erro na execução do método, será
retornado NOK e os erros serão gravados na temp-table RowErrors.
updateRecord
Atualiza o registro na base de dados.
Sintaxe:
RUN updateRecord IN <handle VDBO>
(INPUT <htt HANDLE>).
Parâmetros:
htt: parâmetro de entrada, contendo o handle da temp-table.
Categoria:
Método de Manutenção de Registros.
Outras informações:
Caso o método tenha sido executado com sucesso, será retornado, via return-
value, OK. Caso tenha ocorrido algum erro na execução do método, será
retornado NOK e os erros serão gravados na temp-table RowErrors.
deleteAllRecords
Elimina todos os registros com o TokenID e TableName definidos pelos
métodos setToken e setTableName. Deve ser chamado sempre ao final da
transação ou no seu início para não se trabalhar com dados desatualizados.
Sintaxe:
RUN deleteAllRecords IN <handle VDBO>.
Categoria:
Método de Manutenção de Registros.
Outras informações:
Caso o método tenha sido executado com sucesso, será retornado, via return-
value, OK. Caso tenha ocorrido algum erro na execução do método, será
retornado NOK e os erros serão gravados na temp-table RowErrors.
44
insertAllRecords
Insere todos os registros da temp-table recebida como parâmetro na base de
dados.
Sintaxe:
RUN insertAllRecords IN <handle VDBO>
(INPUT <htt HANDLE>).
Parâmetros:
htt: parâmetro de entrada, contendo o handle da temp-table.
Categoria:
Método de Manutenção de Registros.
Outras informações:
Caso o método tenha sido executado com sucesso, será retornado, via return-
value, OK. Caso tenha ocorrido algum erro na execução do método, será
retornado NOK e os erros serão gravados na temp-table RowErrors.
clearTempTable
Elimina todos os registros da temp-table passada como parâmetro.
Sintaxe:
RUN clearTempTable IN <handle VDBO>
(INPUT <htt HANDLE>).
Parâmetros:
htt: parâmetro de entrada, contendo o handle da temp-table.
Categoria:
Método de Manutenção de Registros.
Outras informações:
Caso o método tenha sido executado com sucesso, será retornado, via return-
value, OK. Caso tenha ocorrido algum erro na execução do método, será
retornado NOK e os erros serão gravados na temp-table RowErrors.
CAPÍTULO 1 Como utilizar os DBOs 45
Considerações Gerais
Algumas recomendações para uso dos DBOs.
Chamada aos DBOs
Ao executar um DBO através do comando RUN usar somente letras
minúsculas no nome do programa e diretórios e usar a barra normal ("/"). Isto
evita problemas no ambiente UNIX.
Exemplo: Instância do DBO xxbo/boxx001.p, associado a tabela customer.
/* Temp-table Definitions --- */
{method/dbotterr.i}
{xxbo/boxx001.i ttCustomer}
/* Variable Definitions --- */
DEFINE VARIABLE hBOXX001 AS HANDLE NO-UNDO.
/* DBO Instance --- */
RUN xxbo/boxx001.p PERSISTENT SET hBOXX001.
Chamada aos DBOs através do recurso de RPC
Quando houver a necessidade de executar um DBO através do recurso de
RPC, deve-se utilizar a técnica de execução RPC do produto EMS/HR.
Exemplo de utilização do Virtual DBO
/* Definição da Temp-table onde serão retornados os erros */
DEFINE TEMP-TABLE RowErrors NO-UNDO
FIELD ErrorSequence AS INTEGER
FIELD ErrorNumber AS INTEGER
FIELD ErrorDescription AS CHARACTER
FIELD ErrorParameters AS CHARACTER
FIELD ErrorType AS CHARACTER
FIELD ErrorHelp AS CHARACTER
FIELD ErrorSubType AS CHARACTER.
/* Definição da temp-table que será utilizada pelo VDBO */
define temp-table tt-customer like customer
field r-Rowid as rowid.
def var h-prog as handle no-undo.
def var c-token as char no-undo.
/* Criação dos registros na temp-table */
46
for each customer where customer.state = "Uusimaa":
create tt-customer.
buffer-copy customer to tt-customer.
end.
/* Rodando o VDBO persistente */
run utp/ut-vdbo.p persistent set h-prog.
/* Criando um token a ser utilizado pelo VDBO */
/* Este método já define o token do VDBO */
run createToken in h-prog (output c-token).
/* Definição da temp-table que será utilizada pelo VDBO */
run setTableName in h-prog (input "tt-customer").
run setTableHandle in h-prog (input (buffer tt-customer:handle)).
/* Definindo que a query será ordenada pelo campo nome */
run setIndexType in h-prog (input 2,
input "name",
input ?).
/* A ordem de leitura dos registros será descendente */
run setQuerySort in h-prog (input 2).
/* Inserindo todos os registros no VDBO */
run insertAllRecords in h-prog.
/* Elimiando todos os registros da temp-table */
for each tt-customer:
delete tt-customer.
end.
/* Buscando o primeiro registro no VDBO */
run getFirst in h-prog.
/* Retornando o registro corrente, neste caso o primeiro, para o VDBO */
run getCurrent in h-prog (input (buffer tt-customer:handle)).
/* Vai eliminar os registros do VDBO */
run deleteAllRecords in h-prog.