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.

universidade@datasul.com.br

http://universidade.datasul.com.br

universidade@datasul.com.br

http://universidade.datasul.com.br

Obrigada!

Obrigada