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

CAPÍTULO 1 - Introdução

Definiçã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.

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

Objetivo

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.

Estrutura

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.

Procedures para implementação

afterAllSelectedRecords

Objetivo

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âmetros

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

Exemplo

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

contador = contador + 9

hTeste:BUFFER-VALUE = contador.

END.

queryHandle:GET-NEXT(NO-LOCK).

END.

afterPersistRecord

Objetivo

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âmetros

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

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.

Exemplo

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

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

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.

afterSelectedRecord

Objetivo

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âmetros

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

Exemplo

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.

hDSNome = getDatasetFieldHandle("nome").

IF VALID-HANDLE(hDSNome) THEN DO:

hDSNome:BUFFER-VALUE = "[CUSTOM] " + hDSNome:BUFFER-VALUE.

END.

beforePersistRecord

Objetivo

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âmetros

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

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.

Exemplo

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

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

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.

prepareQuery

Objetivo

Tem por objetivo disponibilizar um meio de customizar a query que será executada para realizar a busca de dados.

Parâmetros

Parâmetro	I/O	Tipo de Dado	Conteúdo
queryHandler	Input-Output	Handle	Handle da Query

Exemplo

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

Functions e Procedures auxiliaries

prepareDatasetFields

Tipo

PROCEDURE

Objetivo

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âmetros

Parâmetro	I/O	Tipo de Dado	Conteúdo
ttDataset	Input-Output	Handle	Handle da temp-table do dataset

Exemplo

Vide exemplos das procedures afterAllSelectedRecords, afterSelectedRecord e beforePersistRecord.

prepareRowObjectFields

Tipo

PROCEDURE

Objetivo

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âmetros

Parâmetro	I/O	Tipo de Dado	Conteúdo
RowObject	Input-Output	Handle	Handle da temp-table do RowObject

Exemplo

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.

Parâmetros

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

Exemplo

Vide exemplos das procedures afterAllSelectedRecords, afterSelectedRecord e beforePersistRecord.

getRowObjFieldHandle

Tipo

FUNCTION

Objetivo

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âmetros

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

Exemplo

Vide exemplo da procedure beforePersistRecord.

Pontos de UPC

Objetivo

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.

Pontos padrão

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

customHandler.rar

O Custom Handler é um programa PROGRESS que tem por objetivo disponibilizar para o usuário uma maneira para poder realizar customizações nas informações que são passadas para a o By You e também gerar os dados dos campos virtuais do Dataset.

Árvore de páginas

Manual de Customizações Dataset

CAPÍTULO 1 - Introdução

Definição

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

Objetivo

Estrutura

Procedures para implementação

afterAllSelectedRecords

Objetivo

Parâmetros

Exemplo

afterPersistRecord

Objetivo

Parâmetros

Exemplo

afterSelectedRecord

Objetivo

Parâmetros

Exemplo

beforePersistRecord

Objetivo

Parâmetros

Exemplo

prepareQuery

Objetivo

Parâmetros

Exemplo

Functions e Procedures auxiliaries

prepareDatasetFields

Tipo

Objetivo

Parâmetros

Exemplo

prepareRowObjectFields

Tipo

Objetivo

Parâmetros

Exemplo

getDatasetFieldHandle

Tipo

Objetivo

Parâmetros

Exemplo

getRowObjFieldHandle

Tipo

Objetivo

Parâmetros

Exemplo

Pontos de UPC

Objetivo

Pontos padrão