Programa Retorno Externo

Objetivo	Permitir o auxílio na construção de métodos do programa de retorno externo.
Programa	SOEXP001
Pré-Requisito	É pré-requisito para a execução dessa função: Função Propriedades dos Objetos (SO701)
Visão Geral	Por intermédio dessa função é possível criar métodos de retorno externo com base no valor do objeto selecionado e com base também nos valores dos outros objetos da tela.

Descrição

Programa de Retorno Externo

O programa de retorno externo é utilizado para especificar uma validação ou verificação conforme a necessidade do usuário.

Atualmente é possível utilizar retorno externo para as seguintes propriedades:

Condição: onde deve retornar YES para indicar que um botão deve ficar desabilitado/escondido.
Lista de Valores: onde deve retornar NO para indicar que o usuário não pode incluir, modificar, eliminar, etc.
Valor Inicial: onde deve retornar o valor para inicialização do objeto correspondente (caracter).

O programa de retorno externo é composto de um ou mais métodos construídos pelo usuário administrador, com o objetivo de verificar uma condição ou uma validação específica de um objeto.

Segue abaixo o protótipo de definição de um Programa de Retorno Externo:

/********************************************************************************
** Copyright DATASUL S.A. (1997)
** Todos os Direitos Reservados.
**
** Este fonte e de propriedade exclusiva da DATASUL, sua reproducao
** parcial ou total por qualquer meio, so podera ser feita mediante
** autorizacao expressa.
*******************************************************************************/
/*******************************************************************************
**   Programa..: sop/soexp001.P
**   Objetivo..: Retorno Externo para propriedades Condicao/Lista Valores SOP
********************************************************************************/
 
/* +++ definicao da biblioteca de funcoes +++ */
{sop\solib001.i}
 
/* +++ definicao de variaveis +++ */
 
PROCEDURE <metodo>:
.
.
.
END PROCEDURE.

Programa Métodos do Programa de Retorno Externo

A validação, verificação de uma condição ou inicialização de um objeto deve ser efetuada por intermédio de métodos do programa.

Prototipação para Lista de Valores e Condição:

PROCEDURE <metodo>:
    DEF OUTPUT PARAM pLogReturn  AS LOGICAL   NO-UNDO.
    DEF OUTPUT PARAM pDesMessage AS CHARACTER NO-UNDO.
  
    /*** lógica especifica ***/
    ...
    ...
    ...
   RETURN.
END PROCEDURE.

Prototipação para Valor Inicial de um objeto:

PROCEDURE <metodo>:
    DEF OUTPUT PARAM pLogReturn  AS LOGICAL   NO-UNDO.
    DEF OUTPUT PARAM pDesMessage AS CHARACTER NO-UNDO.
  
    /*** lógica especifica ***/
    ...
    ...
    ...
   RETURN.
END PROCEDURE.

Importante:

É de extrema importância que a definição dos parâmetros seja efetuada de acordo com a estrutura acima, inclusive os tipos de dados (logical e character) por extenso. A definição dos parâmetros é reconhecida pelo zoom de lista de valores e condição para validar se o método criado está correto ou não.

Definição dos Parâmetros

PROPRIEDADE	PARÂMETROS	VALOR	Descrição
Condição	pLogReturn	YES	Indica que o botão correspondente deverá ficar desabilitado/escondido.
Condição	pLogReturn	NO	Indica que o botão correspondente deverá permanecer no seu estado atual.
Condição	PDesMessage	-	Não é utilizada.
Lista de Valor	pLogReturn	YES	Indica que a validação do objeto ocorreu com sucesso.
Lista de Valor	pLogReturn	NO	Indica que a validação do objeto não foi bem sucedida. Será apresentada uma mensagem de erro ao usuário.
Lista de Valor	PDesMessage	-	Descrição da mensagem de erro ao usuário, quando pLogReturn = NO.
Valor Inicial	PDesValue	-	Valor para inicialização do objeto (caracter).

Importante:

Caso exista a necessidade de utilizar métodos parecidos para Condição e lista de valores (exemplo: validar apenas se o usuário possui permissão para o estabelecimento), pode ser utilizado uma regra para condição diferente (<>) do retorno externo, no zoom de condições do objeto. Dessa forma, para ambas as propriedades podem ser utilizadas um único método.

Definição Funções para uso nos Métodos

Para auxiliar na construção dos métodos dos programas de retorno externo, foi disponibilizada uma biblioteca de funções, por intermédio de uma include (sop/solib001.i), onde é possível acessar propriedades dos objetos da tela por meio de um apelido pré-definido pelo usuário.

Segue abaixo uma breve descrição das funções disponibilizadas nessa versão inicial da Biblioteca de Funções:

FUNCTION: getObjectHandle

RETORNO: handle

PARÂMETROS: INPUT Apelido (CHAR)

DESCRIÇÃO: Retorna o Handle do objeto, conforme o Apelido informado.

Caso o objeto não esteja disponível ou o apelido não referencie nenhum objeto, o retorno será "?".

FUNCTION: getObjectName

RETORNO: character

PARÂMETROS: INPUT Apelido (CHAR)

DESCRIÇÃO: Retorna o valor atual do objeto, conforme o Apelido informado.

Caso o objeto não esteja disponível, não possua a propriedade valor ou o apelido não referencie nenhum objeto, o retorno será “?”.

Observação: é importante lembrar que o retorno sempre é caracter. Para os casos de objetos do tipo data, inteiro, decimal e lógico, é necessário utilizar as funções DATE, INT, DEC, etc.

FUNCTION: getObjectValue

RETORNO: character

PARÂMETROS: INPUT Apelido (CHAR)

DESCRIÇÃO: Retorna o valor atual do objeto, conforme o Apelido informado.

Caso o objeto não esteja disponível, não possua a propriedade valor ou o apelido não referencie nenhum objeto, o retorno será “?”.

Observação: é importante lembrar que o retorno sempre é caracter. Para os casos de objetos do tipo data, inteiro, decimal e lógico, é necessário utilizar as funções DATE, INT, DEC, etc.

FUNCTION: getCurrentObjectHandle

RETORNO: handle

PARÂMETROS: Não possui parâmetros

DESCRIÇÃO: Retorna o Handle do objeto corrente.

Para a propriedade “Lista de Valor”, o objeto corrente é o objeto que possui a propriedade “Lista de Valor”.

Para a propriedade “Condição”, o objeto corrente é o objeto selecionado na regra de retorno externo no zoom de condição.

Caso o objeto não esteja disponível o retorno será “?”.

FUNCTION: getCurrentObjectName

RETORNO: character

PARÂMETROS: Não possui parâmetros

DESCRIÇÃO: Retorna o nome do objeto corrente.

Para a propriedade “Lista de Valor”, o objeto corrente é o objeto que possui a propriedade “Lista de Valor”.

Para a propriedade “Condição”, o objeto corrente é o objeto selecionado na regra de retorno externo no zoom de condição.

Caso o objeto não esteja disponível o retorno será “?”.

FUNCTION: getCurrentObjectValue

RETORNO: character

PARÂMETROS: Não possui parâmetros

DESCRIÇÃO: Retorna o valor atual do objeto corrente.

Para a propriedade “Lista de Valor”, o objeto corrente é o objeto que possui a propriedade “Lista de Valor”.

Para a propriedade “Condição”, o objeto corrente é o objeto selecionado na regra de retorno externo no zoom de condição.

Caso o objeto não esteja disponível ou não possua a propriedade valor o retorno será “?”.

Observação: é importante lembrar que o retorno sempre é caracter. Para os casos de objetos do tipo data, inteiro, decimal e lógico, é necessário utilizar as funções DATE, INT, DEC, etc.

Exemplo de Programa de Retorno Externo

Segue abaixo um exemplo de um programa externo com alguns métodos de exemplo para validação de objetos em tela.

/********************************************************************************
** Copyright DATASUL S.A. (1997)
** Todos os Direitos Reservados.
**
** Este fonte e de propriedade exclusiva da DATASUL, sua reproducao
** parcial ou total por qualquer meio, so podera ser feita mediante
** autorizacao expressa.
*******************************************************************************/
/*******************************************************************************
**   Programa..: soexp001.P
**   Objetivo..: Retorno Externo para propriedades Condicao/Lista Valores SOP
**   Data......: 01/10/2002
**   Notas.....: Programa de exemplo de retorno externo.
**               Contém o protótipo necessário para definicao de programas de
**               retorno externo e definição dos métodos
**               É possível adicionar novos métodos, conforme necessidade           
********************************************************************************/
 
/* +++ definicao da biblioteca de funcoes +++ */
{sop\solib001.i}
 
/* +++    prototipacao dos metodos existentes - apenas para consulta   +++ */
/* +++ FUNCTION getObjectHandle        RETURNS HANDLE (vAlias AS CHAR) +++ */
/* +++ FUNCTION getObjectName          RETURNS CHAR   (vAlias AS CHAR) +++ */
/* +++ FUNCTION getObjectValue         RETURNS CHAR   (vAlias AS CHAR) +++ */
/* +++ FUNCTION getCurrentObjectHandle RETURNS HANDLE (              ) +++ */
/* +++ FUNCTION getCurrentObjectName   RETURNS CHAR   (              ) +++ */
/* +++ FUNCTION getCurrentObjectValue  RETURNS CHAR   (              ) +++ */
 
/* +++ definicao de variaveis +++ */
DEF NEW GLOBAL SHARED VAR v_cod_usuar_corren AS CHAR NO-UNDO.
 
/*******************************************************************************
Procedure exampleMethod01
Objetivo: Exemplo de validacao do usuario corrente
*******************************************************************************/
PROCEDURE exampleMethod01:
    DEF OUTPUT PARAM pLogReturn  AS LOGICAL   NO-UNDO.
    DEF OUTPUT PARAM pDesMessage AS CHARACTER NO-UNDO.
 
    MESSAGE getCurrentObjectHandle() SKIP
            getCurrentObjectName  () SKIP
            getCurrentObjectValue () SKIP
        VIEW-AS ALERT-BOX INFO BUTTONS OK.
 
    IF v_cod_usuar_corren <> getCurrentObjectValue() THEN
        ASSIGN pLogReturn  = NO
               pDesMessage = "Usuário inválido. O usuário corrente deve ser "
                           + v_cod_usuar_corren.
    ELSE
        ASSIGN pLogReturn  = YES.  
    RETURN.
END PROCEDURE.
 
/*******************************************************************************
Procedure exampleMethod02
Objetivo: Exemplo de condicao para botao conforme usuario / data
*******************************************************************************/
PROCEDURE exampleMethod02:
    DEF OUTPUT PARAM pLogReturn  AS LOGICAL   NO-UNDO.
    DEF OUTPUT PARAM pDesMessage AS CHARACTER NO-UNDO.
 
    MESSAGE getCurrentObjectHandle() SKIP getObjectHandle("data-atual") SKIP
            getCurrentObjectName  () SKIP getObjectName  ("data-atual") SKIP
            getCurrentObjectValue () SKIP getObjectValue ("data-atual") SKIP
        VIEW-AS ALERT-BOX INFO BUTTONS OK.
 
    /* +++ condicao para desabilitar/esconder botao +++ */
    IF v_cod_usuar_corren <> getCurrentObjectValue()
        OR DATE(getObjectValue("data-atual")) <> TODAY THEN
        /* +++ desabilita o botao +++ */
        ASSIGN pLogReturn  = YES.
    ELSE
        /* +++ botao permanece no seu estado atual +++ */
        ASSIGN pLogReturn  = NO.   
    RETURN.
END PROCEDURE.
 
/*******************************************************************************
Procedure exampleMethod03
Objetivo: Exemplo de Valor Inicial para um objeto
*******************************************************************************/
PROCEDURE exampleMethod03:
    DEF OUTPUT PARAM pDesReturn  AS CHARACTER NO-UNDO.
 
    MESSAGE getCurrentObjectHandle() SKIP
            getCurrentObjectName  () SKIP
            getCurrentObjectValue () SKIP
        VIEW-AS ALERT-BOX INFO BUTTONS OK.
 
    /* +++ verifica qual o usuario +++ */
    IF v_cod_usuar_corren <> getCurrentObjectValue() THEN
        ASSIGN pDesReturn  = "12345".
    ELSE
        ASSIGN pDesReturn  = "55555".
   
    RETURN.
END PROCEDURE.

Importante 1:

Dica - Para verificar os valores dos objetos da tela, é possível mostrar uma mensagem na tela dos resultados obtidos pelas funções para verificação.

MESSAGE getCurrentObjectHandle() SKIP getObjectHandle("<Apelido>") SKIP
            getCurrentObjectName  () SKIP getObjectName  ("<Apelido>") SKIP
            getCurrentObjectValue () SKIP getObjectValue ("<Apelido>") SKIP
        VIEW-AS ALERT-BOX INFO BUTTONS OK.

Importante 2:

Dica - Para métodos utilizados na lista de valores, é possível retornar uma mensagem ao usuário caso ocorra erros de validação.

Assign pDesMessage = "Data inválida. A data de ser maior que "
                       + string(getObjectValue ("data-atual")).

Importante 3:

Dica - Eventualmente pode ser construído um método de retorno externo para lista de valores e para condição que tenham o mesmo objetivo ou a mesma codificação. Mas como a lista de valores deve retornar YES para OK e a propriedade condição tem que retornar YES para desabilitar, no zoom de condição pode ser criada uma regra utilizando o mesmo método de validação, apenas com o tipo diferente (<>). Dessa forma, se o retorno externo for NO, o objeto é desabilitado ou escondido.

Importante 4:

Dica - Existe um programa já definido que pode servir de exemplo para utilização da construção do programa de retorno externo. O mesmo encontra-se no diretório FONTES/SOP/SOEXP001.ZIP. Aconselha-se ao usuário administrador abrir esse programa e efetuar a opção “Salvar Como” para criar um programa de retorno externo, conforme nomenclatura desejada pelo usuário administrador.

Árvore de páginas

SOEXP001 - Programa Retorno Externo

Programa Retorno Externo

Descrição

Programa de Retorno Externo

Programa Métodos do Programa de Retorno Externo

Definição dos Parâmetros

Definição Funções para uso nos Métodos

Exemplo de Programa de Retorno Externo