Técnicas de Uso de DBOshttps://เนื้อเพลง.com/PDF/Totvs-Datasul... · 2015. 7....
Transcript of Técnicas de Uso de DBOshttps://เนื้อเพลง.com/PDF/Totvs-Datasul... · 2015. 7....
1
Técnicas de Uso de DBOs
Tecnologia
2
Como Utilizar DBOs
Métodos Básicos
Considerações Gerais
Agenda
3
Como Utilizar DBOs
Como Utilizar DBOs
4
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.
Como Utilizar DBOs
5
Definir temp-table de Comunicação
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.
{xxbo/boxx001.i ttCustomer}
Como Utilizar DBOs
6
Como Utilizar DBOs
Definir temp-table de Erro
O DBO normalmente devolve os erros na temp-tableRowErrors. Para tanto a mesma deve estar definida no programa.Usa-se o include method/dbotterr.i no início do programa.
{method/dbotterr.i}
7
Como Utilizar DBOs
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 e guardando um ponteiro para esta instância (HANDLE).
DEFINE VARIABLE hBOXX001 AS HANDLE NO-UNDO.RUN xxbo/boxx001.p PERSISTENT SET hBOXX001.
8
Como Utilizar DBOs
Executar Métodos
Para executar os métodos do DBO basta utilizar o HANDLE já inicializado do DBO.
IF VALID-HANDLE(hBOXX001) THENRUN openQueryStatic IN hBOXX001 (INPUT "CustNum":U).
9
Como Utilizar DBOs
Eliminar a Instância do DBO
A eliminação da instância do DBO é feita através do método destroy.
IF VALID-HANDLE(hBOXX001) THENRUN destroy IN hBOXX001.
10
Como Utilizar DBOs
Para o ambiente state-awere normalmente a instância do DBO é eliminada quando o programa chamador é eliminado da memória.
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.
11
Métodos Básicos
Métodos Básicos
12
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.
Métodos Básicos
13
Métodos Básicos
Sintaxe:
RUN bringCurrent IN <handle DBO>.
Outras informações:
Para retornar o registro corrente, pode-se utilizar o método getRecord.
14
Métodos Básicos
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.
15
Métodos Básicos
Sintaxe:
RUN getFirst IN <handle DBO>.
Outras informações:
Para retornar o registro corrente, pode-se utilizar o método getRecord.
16
Métodos Básicos
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.
17
Métodos Básicos
Sintaxe:
RUN getLast IN <handle DBO>.
Outras informações:
Para retornar o registro corrente, pode-se utilizar o método getRecord.
18
Métodos Básicos
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.
19
Métodos Básicos
Sintaxe:
RUN getNext IN <handle DBO>.
Outras informações:
Para retornar o registro corrente, pode-se utilizar o método getRecord.
20
Métodos Básicos
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.
21
Métodos Básicos
Sintaxe:
RUN getPrev IN <handle DBO>.
Outras informações:
Para retornar o registro corrente, pode-se utilizar o método getRecord.
22
Métodos Básicos
repositionRecord
Este método reposiciona a query através de um rowidpassado 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.
23
Métodos Básicos
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.
24
Métodos Básicos
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.
25
Métodos Básicos
Sintaxe:
RUN createRecord IN <handle DBO>.
Outras informações:
Para setar a temp-table RowObject, pode-se utilizar o método setRecord.
26
Métodos Básicos
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.
27
Métodos Básicos
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.
28
Métodos Básicos
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.
29
Métodos Básicos
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.
30
Métodos Básicos
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.
31
Métodos Básicos
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.
32
Métodos Básicos
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.
33
Métodos Básicos
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>.
34
Métodos Básicos
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>.
35
Métodos Básicos
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>.
36
Métodos Básicos
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>.
37
Métodos Básicos
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.
38
Métodos Básicos
Sintaxe:
RUN getBatchRecords IN <handle DBO> ( INPUT <pRowid ROWID>,INPUT <pNext LOGICAL>,INPUT <pRowsToReturned INTEGER>,OUTPUT <pRowsReturned INTEGER>,OUTPUT TABLE <pTable RowObject>).
39
Métodos Básicos
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;
40
Métodos Básicos
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.
41
Métodos Básicos
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.
42
Métodos Básicos
Sintaxe:
RUN getBatchRecordsPrev IN <handle DBO> ( INPUT <pRowid ROWID>,INPUT <pPrev LOGICAL>,INPUT <pRowsToReturned INTEGER>,OUTPUT <pRowsReturned INTEGER>,OUTPUT TABLE <pTable RowObject>).
43
Métodos Básicos
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;
44
Métodos Básicos
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.
45
Métodos Básicos
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).
46
Métodos Básicos
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.
47
Métodos Básicos
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).
48
Métodos Básicos
Sintaxe:
RUN getRawRecord IN <handle DBO> (OUTPUT <pRaw RAW>).
Parâmetro:
pRaw: parâmetro de saída, que contém a variável Raw.
49
Métodos Básicos
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.
50
Métodos Básicos
Sintaxe:
RUN getRecord IN <handle DBO> OUTPUT TABLE <pTable RowObject>).
Parâmetro:
pTable: parâmetro de saída, temp-table na qual devem ser retornados os registros.
51
Métodos Básicos
Outras informações:
Geralmente ele é utilizado em conjunto com os métodos: getFirst, getLast, getNext, getPrev ou repositionRecord.
52
Métodos Básicos
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>).
53
Métodos Básicos
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.
54
Métodos Básicos
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).
55
Métodos Básicos
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.
56
Métodos Básicos
insertError
Este método insere um novo registro na temp-tableRowErrors. Este é um método interno e não deve ser utilizado pelo desenvolvedor.
57
insertErrorManual
Este método insere um novo registro na temp-tableRowErrors 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.
Métodos Básicos
58
Métodos Básicos
openQueryStatic
Este método verifica qual método de abertura de querydeve ser executado, através do parâmetro passado. E ainda, retorna status do processo através de RETURN-VALUE (OK/NOK).
59
Métodos Básicos
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.
60
Métodos Básicos
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).
61
Métodos Básicos
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.
62
Métodos Básicos
setRecord
Este método transfere os dados a temp-tableRowObject do Client para a temp-table RowObject do DBO. 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.
63
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.
Métodos Básicos
64
Métodos Básicos
Outras informações:
Geralmente, ele é utilizado em conjunto com os métodos: createRecord ou updateRecord.
65
Métodos Básicos
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.
66
Métodos Básicos
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>.
67
Métodos Básicos
Outras informações:
Este método não deve ser utilizado para abrir a querydiretamente. Para realizar a abertura da query deve-se utilizar o método: openQueryStatic.
68
Métodos Básicos
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 ?>, ...).
69
Métodos Básicos
Parâmetro:
pConstraint: parâmetros de entrada, que contém os valores das restrições que podem ser utilizadas posteriormente pelo método openQueryStatic.
70
Métodos Básicos
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>).
71
Métodos Básicos
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.
72
Métodos Básicos
linkTo<Description>
Este método recebe o handle de outro DBO e executa o método getKey com o handle recebido a fim de setaruma restrição relacionada ao outro DBO. E ainda, retorna status do processo através de RETURN-VALUE (OK/NOK).
73
Métodos Básicos
Sintaxe:
RUN linkTo<Description> IN <handle DBO> (INPUT <pHandle HANDLE>).
Parâmetro:
pHandle: parâmetro de entrada, que contém o handlede outro DBO.
74
Métodos Básicos
Outras informações:
Geralmente, ele é utilizado quando faz-se necessária a integração entre DBOs.
75
Métodos Básicos
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).
76
Métodos Básicos
Sintaxe:
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}.
77
Métodos Básicos
Outras informações:
Geralmente, ele é utilizado quando faz-se necessária a integração entre DBOs.
78
Métodos Básicos
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.
79
Métodos Básicos
Sintaxe:
RUN goToKey IN <handle DBO> (INPUT <pKey ?>, ...).
Parâmetro:
pKeys: parâmetros de entrada, que contém os valores dos campos do índice único da tabela {&TableName}.
80
Métodos Básicos
Outras informações:
Para retornar o registro corrente, pode-se utilizar o método getRecord.
81
Métodos Básicos
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).
82
Métodos Básicos
Sintaxe:
RUN get<Field-Data-Type> IN <handle DBO> (INPUT <pFieldName CHARACTER>,OUTPUT <pFieldValue Field-Data-Type).
Parâmetro:
pFieldName: parâmetros de entrada, que contém o nome do campo a ser retornado;
pFieldValue: parâmetros de saída, que terá o valor do campo solicitado.
83
Métodos Básicos
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.
84
Métodos Básicos
Sintaxe:
RUN setQueryWhere IN <handle DBO> (INPUT <pWhereClause CHARACTER>).
Parâmetro:
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.
85
Métodos Básicos
setQueryBy
Este método permite determinar a ordenação dos registros retornados pelo método openQueryDynamic.
86
Métodos Básicos
Sintaxe:
RUN setQueryBy IN <handle DBO>
(INPUT <pByClause CHARACTER>).
Parâmetro:
pByClause: Clausula do BY com a palavra BY e separado por vírgula e novamente a palavra BY se mais de um campo for usado para ordenação.
O nome da tabela pode ser informado como &1garantindo com isso independência em relação ao nome físico da tabela.
87
Métodos Básicos
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.
88
Métodos Básicos
Sintaxe:
RUN setQueryFieldList IN <handle DBO> (INPUT <pFieldList CHARACTER>).
Parâmetro:
pFieldList: Lista dos campos sem o nome da tabela e separados por espaço em branco.
89
Métodos Básicos
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.
90
Sintaxe:
RUN openQueryDynamic IN <handle DBO>.
Métodos Básicos
91
Métodos Básicos
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.
92
Métodos Básicos
Sintaxe:
RUN resetQueryParameters IN <handle DBO>.
93
Considerações Gerais
Considerações Gerais
94
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.
RUN xxbo/boxx001.p PERSISTENT SET hBOXX001.
Considerações Gerais
95
Considerações Gerais
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.
96
Este material é de propriedade da DATASUL S.A., sendo proibida a sua reprodução em qualquer meio, total ou parcial, sem aprovação por escrito. Todos os direitos estão reservados. A informação contida aqui é confidencial
e não pode ser utilizada fora da empresa ou das franquias que fazem parte da nossa rede, não podendo ser divulgada para clientes, parceiros ou outra empresa ou indivíduo sem o prévio consentimento de um diretor da
DATASUL S.A. As opiniões expressas aqui estão sujeitas a modificação sem aviso prévio.
http://universidade.datasul.com.br
http://universidade.datasul.com.br
Obrigada!
Obrigada