manual de técnicas de uso - sanderlei.com.br · esquecido de eliminar o dbo o progress não vai...

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.


{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.


{method/dbotterr.i}


/* 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.


{method/dbotterr.i}


CAPÍTULO 1 Como utilizar os DBOs 5





/* 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.


{method/dbotterr.i}






/* 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;


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




Sintaxe:

RUN getFirst IN <handle DBO>.



getLast

Este método posiciona a query no último registro. E ainda, retorna status do




8

Sintaxe:

RUN getLast IN <handle DBO>.



getNext

Este método posiciona a query no próximo registro. E ainda, retorna status do




Sintaxe:

RUN getNext IN <handle DBO>.



getPrev

Este método posiciona a query no registro anterior. E ainda, retorna status do




Sintaxe:

RUN getPrev IN <handle DBO>.



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).




Sintaxe:

RUN repositionRecord IN <handle DBO>

(INPUT <pRowid ROWID>).

Parâmetros:

pRowid: parâmetro de entrada, que contém o rowid a ser reposicionado.



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).



Sintaxe:

RUN createRecord IN <handle DBO>.


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,




Sintaxe:

RUN deleteRecord IN <handle DBO>.


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).



Sintaxe:

RUN newRecord IN <handle DBO>.


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,




Sintaxe:

RUN updateRecord IN <handle DBO>.


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,


_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.


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


Sintaxe:

RUN emptyRowErrors IN <handle DBO>.

emptyRowObject

Este método esvazia a temp-table RowObject. E ainda, retorna status do


Sintaxe:

RUN emptyRowObject IN <handle DBO>.

emptyRowObjectAux

Este método esvazia a temp-table RowObjectAux. E ainda, retorna status do


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;


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;


registros.

getProtocol

Este método retorna a versão do protocolo do DBO. E ainda, retorna status do


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


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




Sintaxe:

RUN getRecord IN <handle DBO>

14

(OUTPUT TABLE <pTable RowObject>).

Parâmetro:


registros.


Geralmente ele é utilizado em conjunto com os métodos: getFirst,


getRowErrors

Este método retorna a temp-table RowErrors. E ainda, retorna status do


Sintaxe:

RUN getRowErrors IN <handle DBO>

(OUTPUT TABLE <pTable RowErrors>).


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.


_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


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



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.


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


Sintaxe:

RUN openQuery<Description> IN <handle DBO>.


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 ?>, ...).


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


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.


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}.


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).



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}.



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:


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.


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>


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


<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


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.


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.


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:


Obrigatoriedade:

A execução deste método não é necessária.





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:


Obrigatoriedade:



30




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:


Obrigatoriedade:






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:


Obrigatoriedade:







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:


Obrigatoriedade:






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:


Obrigatoriedade:






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.


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:


Obrigatoriedade:






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.


34




getLast

Reposiciona no último registro.

Sintaxe:

RUN getLast IN <handle VDBO>.

Categoria:






getNext

Reposiciona no próximo registro.

Sintaxe:

RUN getNext IN <handle VDBO>.

Categoria:






getPrev

Reposiciona no registro anterior.

Sintaxe:

RUN getPrev IN <handle VDBO>.


Categoria:






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:






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:






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:







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:






getCharField

Retorna o valor do campo do registro corrente - CHARACTER.

Sintaxe:

RUN getCharField IN <handle VDBO>


OUPTUT <cFieldValue CHARACTER>).

Parâmetros:




38

Categoria:






getIntField

Retorna o valor do campo do registro corrente – INTEGER.

Sintaxe:

RUN getIntField IN <handle VDBO>


OUPTUT <cFieldValue INTEGER>).

Parâmetros:




Categoria:






getDecField

Retorna o valor do campo do registro corrente - DECIMAL.

Sintaxe:

RUN getDecField IN <handle VDBO>


OUPTUT <cFieldValue DECIMAL>).

Parâmetros:





Categoria:






getDateField

Retorna o valor do campo do registro corrente - DATE.

Sintaxe:

RUN getDateField IN <handle VDBO>


OUPTUT <cFieldValue DATE>).

Parâmetros:




Categoria:






getRowidField

Retorna o valor do campo do registro corrente - ROWID.

Sintaxe:

RUN getRowidField IN <handle VDBO>

40


OUPTUT <cFieldValue ROWID>).

Parâmetros:




Categoria:






getLogField

Retorna o valor do campo do registro corrente - LOGICAL.

Sintaxe:

RUN getLogField IN <handle VDBO>


OUPTUT <cFieldValue LOGICAL>).

Parâmetros:




Categoria:







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:






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:





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>


Parâmetros:

htt: parâmetro de entrada, contendo o handle da temp-table.

Categoria:

Método de Manutenção de Registros.





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>


Sintaxe:

RUN deleteRecord IN <handle VDBO>.

Categoria:







updateRecord

Atualiza o registro na base de dados.

Sintaxe:

RUN updateRecord IN <handle VDBO>


Parâmetros:


Categoria:






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:






44

insertAllRecords

Insere todos os registros da temp-table recebida como parâmetro na base de

dados.

Sintaxe:

RUN insertAllRecords IN <handle VDBO>


Parâmetros:


Categoria:






clearTempTable

Elimina todos os registros da temp-table passada como parâmetro.

Sintaxe:

RUN clearTempTable IN <handle VDBO>


Parâmetros:


Categoria:







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.


{method/dbotterr.i}






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.

manual de técnicas de uso - sanderlei.com.br · esquecido de eliminar o dbo o progress não vai...

Documents