Manual de customizações

Dataset
Dezembro/2010
Copyright © 2009 TOTVS 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 TOTVS S.A., que reserva-se o
direito de efetuar alterações sem aviso prévio. A TOTVS S.A não assume
nenhuma responsabilidade pelas conseqüências de quaisquer erros ou
inexatidões que possam aparecer neste documento.
TOTVS S.A.
Av. Santos Dumont, 831, Joinville, SC, CEP 89.222-900
 i

Índice

Índice................................................................................................................. i

CAPÍTULO 1 Introdução...........................................................................1

CAPÍTULO 2 Customização dos dados do dataset...............................2

Procedures para implementação....................................................................3
afterAllSelectedRecords...........................................................................3
afterPersistRecord.....................................................................................4
afterSelectedRecord..................................................................................5
beforePersistRecord..................................................................................6
prepareQuery............................................................................................7
Functions e Procedures auxiliaries................................................................8
prepareDatasetFields.................................................................................8
prepareRowObjectFields...........................................................................8
getDatasetFieldHandle..............................................................................8
getRowObjFieldHandle............................................................................9
Pontos de UPC............................................................................................10
Definição

Customização dos dados do dataset 1

1

CAPÍTULO 1

Introdução

Dataset é a união dos dados físicos e lógicos em uma única estrutura com o
objetivo de prover uma representação mais próxima de uma determinada
funcionalidade / caso de uso, e também disponibilizando os chamados campos
virtuais, permitindo que o desenvolvedor consiga trafegar informações tanto
do Progress para o Flex como também permitir o contrário.
Estrutura
Objetivo

Customização dos dados do dataset 2

2

CAPÍTULO 2

Customização dos dados do dataset

Ensinar como realizar a customização dos dados que serão exibidos e também
armazenados no banco de dados através de uma camada intermediária, assim
sendo, podendo ajustar valores dos campos ou até mesmo passar valores que
não encontram-se na tabela física através dos chamados campos virtuais.

O programa destinado a realizar estas customizações é dividido em 4 (quatro)

procedures. São elas e seus pontos de execução:

 afterAllSelectedRecords: Esta procedure é executada após ter lido

todos os registros da página.

 afterPersistRecord: Esta procedure é executada após realizar

qualquer tipo de persistência (CREATE, DELETE, UPDATE).

 afterSelectedRecord: Esta procedure é executada para cada registro

que é encontrado na página.

 beforePersistRecord: Esta procedure é executada antes de realizar

qualquer tipo de persistência (CREATE, DELETE, UPDATE).

 prepareQuery: Esta procedure é executada antes de realizar a

pesquisa dos registros para que se possa customizar a query.
Exemplo
Parâmetros
Objetivo

Customização dos dados do dataset 3

Procedures para implementação

afterAllSelectedRecords

Tem por objetivo ser executada após todos os registros (apenas os registros da
página corrente) terem sido lidos para que o usuário possa realizar
customizações em registros específicos (navegar para um determinado
registro, alterar informação de um registro com base no valor de outro, etc)

Parâmetro I/O Tipo de Dado Conteúdo

tableName Input Character Nome da tabela em questão
ttDataset Input-Output Handle Handle da temp-table do dataset

O programa abaixo verifica o nome da tabela que está sendo lida para não
realizar o processo abaixo para as tabelas de referência. Também lê todos os
registros e altera a coluna “teste” com um contador que é incrementado de 9
em 9.

*******************************************************************/
DEFINE INPUT PARAMETER tableName AS HANDLE.
DEFINE INPUT-OUTPUT PARAMETER ttDataset AS HANDLE.

DEFINE VARIABLE queryHandle AS HANDLE NO-UNDO.

DEFINE VARIABLE bufferHandle AS HANDLE NO-UNDO.
DEFINE VARIABLE contador AS INTEGER NO-UNDO.
DEFINE VARIABLE hTeste AS HANDLE NO-UNDO.

IF tableName <> “banco.tabela” THEN DO:

return “ok”:u.
END.

CREATE QUERY queryHandle.

ASSIGN bufferHandle = ttDataset:DEFAULT-BUFFER-HANDLE.

queryHandle:SET-BUFFERS(bufferHandle).
queryHandle:QUERY-PREPARE("for each ttDataset").
queryHandle:QUERY-OPEN().
queryHandle:GET-FIRST(NO-LOCK).

DO WHILE(bufferHandle:AVAILABLE):

RUN prepareDatasetFields (INPUT-OUTPUT ttDataset).

ASSIGN hTeste = getDatasetFieldHandle("teste").

IF VALID-HANDLE(hTeste) THEN DO:
ASSIGN
 Parâmetros
Objetivo

contador = contador + 9
hTeste:BUFFER-VALUE = contador.
END.

queryHandle:GET-NEXT(NO-LOCK).
END.

afterPersistRecord

Tem por objetivo ser executada após ter realizado qualquer tipo de persistência
(CREATE, UPDATE e DELETE) para que possa ser realizado customizações
após a realização da persistência e/ou correções na RowErrors.

Parâmetro I/O Tipo de Dado Conteúdo

pType Input Character “CREATE”, “UPDATE” ou “DELETE”
ttDataset Input-Output Handle Handle da temp-table do dataset
RowObject Input-Output Handle Handle da temp-table do RowObject
hBoHandle Input Handle Handle da BO
RowErrors Input-Output Table Tabela RowErrors

Exemplo
O programa abaixo altera o valor da coluna “name” da tabela adicionando os
valores das colunas “teste” e “teste2” que eram do Dataset para a tabela física.

*******************************************************************/
DEFINE INPUT PARAMETER pType AS CHARACTER NO-UNDO.
DEFINE INPUT-OUTPUT PARAMETER ttDataset AS HANDLE.
DEFINE INPUT-OUTPUT PARAMETER RowObject AS HANDLE.
DEFINE INPUT PARAMETER hBoHandle AS HANDLE.
DEFINE INPUT-OUTPUT PARAMETER TABLE FOR RowErrors.

/* captura os campos do Dataset */

RUN prepareDatasetFields (INPUT-OUTPUT ttDataset).
RUN prepareRowObjectFields (INPUT-OUTPUT RowObject).

/*:T--- Utilize o parâmetro pType para identificar quais as

validações a serem executadas ---*/
/*:T--- Os valores possíveis para o parâmetro são: Create,
Delete e Update ---*/
DEFINE VARIABLE hROName AS HANDLE NO-UNDO.
DEFINE VARIABLE hDatasetNome AS HANDLE NO-UNDO.
DEFINE VARIABLE hDatasetTeste AS HANDLE NO-UNDO.
DEFINE VARIABLE hDatasetTeste2 AS HANDLE NO-UNDO.
IF pType = "CREATE":U THEN DO:
hROName = getRowObjFieldHandle("nome").
hDatasetNome = getDatasetFieldHandle("nome").
hDatasetTeste = getDatasetFieldHandle("teste").
hDatasetTeste2 = getDatasetFieldHandle("teste2").
Exemplo
Parâmetros
Objetivo

Customização dos dados do dataset 5

IF VALID-HANDLE(hROName) THEN DO:

ASSIGN hROName:BUFFER-VALUE = hROName:BUFFER-VALUE + " -
" + pType.
IF VALID-HANDLE(hDatasetTeste) THEN
ASSIGN hROName:BUFFER-VALUE = hROName:BUFFER-VALUE +
" - DATASET " + hDatasetTeste:BUFFER-VALUE.
IF VALID-HANDLE(hDatasetTeste2) THEN
ASSIGN hROName:BUFFER-VALUE = hROName:BUFFER-VALUE +
" - DATASET " + hDatasetTeste2:BUFFER-VALUE.
END.
END.

afterSelectedRecord

Tem por objetivo ser executada após cada registro ter sido lido para que o
usuário possa realizar customizações no registro (gerar informação de um
campo virtual baseado nos valores do registro, validar a informação de uma
coluna da tabela, etc)

Parâmetro I/O Tipo de Dado Conteúdo

tableName Input Character Nome da tabela em questão
ttDataset Input-Output Handle Handle da temp-table do dataset

O programa abaixo verifica o nome da tabela que está sendo lida para não
realizar o processo abaixo para as tabelas de referência. E também altera o
valor da coluna “teste2” para o valor 15 e também adiciona na coluna “nome”
o prefixo “[CUSTOM]”.

*******************************************************************/
DEFINE INPUT PARAMETER tableName AS CHARACTER.
DEFINE INPUT-OUTPUT PARAMETER ttDataset AS HANDLE.

DEFINE VARIABLE hDSTeste2 AS HANDLE NO-UNDO.

DEFINE VARIABLE hDSNome AS HANDLE NO-UNDO.

IF tableName <> “banco.tabela” THEN DO:

return “ok”:u.
END.

RUN prepareDatasetFields (INPUT-OUTPUT ttDataset).

hDSTeste2 = getDatasetFieldHandle("teste2").
IF VALID-HANDLE(hDSTeste2) THEN DO:
hDSTeste2:BUFFER-VALUE = 15.
END.
 Parâmetros
Objetivo

hDSNome = getDatasetFieldHandle("nome").
IF VALID-HANDLE(hDSNome) THEN DO:
hDSNome:BUFFER-VALUE = "[CUSTOM] " + hDSNome:BUFFER-VALUE.
END.

beforePersistRecord

Tem por objetivo ser executada antes de realizar qualquer tipo de persistência
(CREATE, UPDATE e DELETE) para que possa ser realizado a conversão
dos valores virtuais para colunas físicas.

Parâmetro I/O Tipo de Dado Conteúdo

pType Input Character “CREATE”, “UPDATE” ou “DELETE”
ttDataset Input-Output Handle Handle da temp-table do dataset
RowObject Input-Output Handle Handle da temp-table do RowObject
hBoHandle Input Handle Handle da BO

Exemplo
O programa abaixo altera o valor da coluna “name” da tabela adicionando os
valores das colunas “teste” e “teste2” que eram do Dataset para a tabela física.

*******************************************************************/
DEFINE INPUT PARAMETER pType AS CHARACTER NO-UNDO.
DEFINE INPUT-OUTPUT PARAMETER ttDataset AS HANDLE.
DEFINE INPUT-OUTPUT PARAMETER RowObject AS HANDLE.
DEFINE INPUT PARAMETER hBoHandle AS HANDLE.

/* captura os campos do Dataset */

RUN prepareDatasetFields (INPUT-OUTPUT ttDataset).
RUN prepareRowObjectFields (INPUT-OUTPUT RowObject).

/*:T--- Utilize o parâmetro pType para identificar quais as

validações a serem executadas ---*/
/*:T--- Os valores possíveis para o parâmetro são: Create,
Delete e Update ---*/
DEFINE VARIABLE hROName AS HANDLE NO-UNDO.
DEFINE VARIABLE hDatasetNome AS HANDLE NO-UNDO.
DEFINE VARIABLE hDatasetTeste AS HANDLE NO-UNDO.
DEFINE VARIABLE hDatasetTeste2 AS HANDLE NO-UNDO.
IF pType = "CREATE":U THEN DO:
hROName = getRowObjFieldHandle("nome").
hDatasetNome = getDatasetFieldHandle("nome").
hDatasetTeste = getDatasetFieldHandle("teste").
hDatasetTeste2 = getDatasetFieldHandle("teste2").
IF VALID-HANDLE(hROName) THEN DO:
ASSIGN hROName:BUFFER-VALUE = hROName:BUFFER-VALUE + " -
" + pType.
IF VALID-HANDLE(hDatasetTeste) THEN
Exemplo
Parâmetros
Objetivo

Customização dos dados do dataset 7

ASSIGN hROName:BUFFER-VALUE = hROName:BUFFER-VALUE +

" - DATASET " + hDatasetTeste:BUFFER-VALUE.
IF VALID-HANDLE(hDatasetTeste2) THEN
ASSIGN hROName:BUFFER-VALUE = hROName:BUFFER-VALUE +
" - DATASET " + hDatasetTeste2:BUFFER-VALUE.
END.
END.
prepareQuery

Tem por objetivo disponibilizar um meio de customizar a query que será

executada para realizar a busca de dados.

Parâmetro I/O Tipo de Dado Conteúdo

queryHandler Input-Output Handle Handle da Query

O programa abaixo altera a query para adicionar a na cláusula a empresa

corrente do usuário.

*******************************************************************/

DEFINE INPUT-OUTPUT PARAMETER queryHandle AS HANDLE NO-UNDO.

DEFINE VARIABLE cTemp AS CHARACTER NO-UNDO.

DEFINE VARIABLE queryString AS CHARACTER NO-UNDO.
DEFINE NEW GLOBAL SHARED VARIABLE v_cod_empres_usuar AS
CHARACTER FORMAT "x(3)":U LABEL "Empresa"
COLUMN-LABEL "Empresa" NO-UNDO.

queryString = queryHandle:PREPARE-STRING.

ASSIGN cTemp = " WHERE ".

IF INDEX(queryString, "WHERE") > 0 THEN

ASSIGN cTemp = "AND".

queryString = queryString + cTemp +

" tabela.cod_empresa = '" + v_cod_empres_usuar + "'".

queryHandle:QUERY-PREPARE(queryString).
Exemplo
Parâmetros
Objetivo

Functions e Procedures auxiliaries

prepareDatasetFields

Tipo PROCEDURE

Esta PROCEDURE realiza o mapeamento de todos os campos que vieram no

Dataset para que possa facilitar a forma de trabalhar com estas handles. Deve
ser utilizada junto com a FUNCTION getDatasetFieldHandle.

Parâmetro I/O Tipo de Dado Conteúdo

ttDataset Input-Output Handle Handle da temp-table do dataset

Vide exemplos das procedures afterAllSelectedRecords, afterSelectedRecord e

beforePersistRecord.
prepareRowObjectFields

Tipo PROCEDURE

Esta PROCEDURE realiza o mapeamento de todos os campos que vieram do

RowObject para que possa facilitar a forma de trabalhar com estas handles.
Deve ser utilizada junto com a FUNCTION getRowObjFieldHandle.

Parâmetro I/O Tipo de Dado Conteúdo

RowObject Input-Output Handle Handle da temp-table do RowObject

Vide exemplo da procedure beforePersistRecord.

getDatasetFieldHandle

Tipo FUNCTION

Objetivo Esta FUNCTION tem por objetivo retornar a handle de um determinado

campo do dataset. Sua utilização está vinculada ao uso correto da procedure
prepareDatasetFields.
Exemplo
Parâmetros
Objetivo

Customização dos dados do dataset 9

Parâmetro I/O Tipo de Dado Conteúdo

pName Input Character Nome do campo que deseja buscar
retorno Return Handle Handle do campo desejado

Vide exemplos das procedures afterAllSelectedRecords, afterSelectedRecord e

beforePersistRecord.

getRowObjFieldHandle

Tipo FUNCTION

Esta FUNCTION tem por objetivo retornar a handle de um determinado

campo da RowObject. Sua utilização está vinculada ao uso correto da
procedure prepareRowObjectFields.

Parâmetro I/O Tipo de Dado Conteúdo

pName Input Character Nome do campo que deseja buscar
retorno Return Handle Handle do campo desejado

Vide exemplo da procedure beforePersistRecord.

Pontos padrão
Objetivo

Pontos de UPC

Por padrão, foram selecionadas algumas procedures desta fachada para terem
por padrão pontos de UPC nativamente, isso não quer dizer que o
desenvolvedor desta camada não pode criar outros pontos que venha a ser
necessário para ele e para a solução que este está desenvolvendo.
Para instruções de como criar uma UPC e como registra-la consulte a
documentação referente a UPC.

Por padrão, são disponibilizados pontos de UPC para as procedures

“afterPersistRecord” e “beforePersistRecord”. Para cada uma destas
procedures é disponibilizado dois eventos “before” e “after”, que conforme o
próprio nome sugere são respectivamente antes de executar a procedure e após
ter executado a procedure.
Para um melhor detalhamento, abaixo encontram-se os nomes dos eventos.

 before-afterPersistRecord: É executada ANTES da procedure

“afterPersistRecord”
 after-afterPersistRecord: É executada APÓS da procedure
“afterPersistRecord”
 before-beforePersistRecord: É executada ANTES da procedure
“beforePersistRecord”
 after-beforePersistRecord: É executada APÓS da procedure
“beforePersistRecord”