API de Window para Geração de Gráficos (003)

Nome Físico: utp/wutapi011.w

Nome do Include com Parâmetros: utp/utapi011.i

Versão de Integração: 003

Objetivo: 

Criação de gráficos.

Pré-requisitos: 

Homologado para Windows 7 e inferiores.





Considerações Gerais

  • Esse programa utiliza o OCX ChartFx para geração dos gráficos, para o seu correto funcionamento é necessário instalar o OCX utilizando um dos arquivos .bat existentes no diretório interfac/chartfx do produto;
  • O programa pode ser executado a partir da API utapi011 ou pode ser executado diretamente por outro programa;
  • A include {utp/utapi011.i} contém as definições das Temp-Table´s que podem ser passadas como parâmetro para a geração dos gráficos;
  • Só podem ser construídos no máximo 2 gráficos na mesma aplicação, vide exemplo;
  • Maiores informações em relação aos valores e descrições dos atributos podem ser encontradas no HELP do Chart FX(chartfx_com_win_api.chm) que encontra-se no diretório interfac/chartfx da instalação do produto;
  • Para visualizar o conteúdo do arquivo chartfx_com_win_api.chm é necessário copiá-lo para um diretório local ou realizar os procedimentos descritos no endereço http://support.microsoft.com/kb/896358;
  • Para obter informações sobre as temp-tables que podem ser passadas como parâmetro, deve-se consultar o arquivo docapi/utapi011.doc que encontra-se no diretório de instalação do produto;
  • Todos os parâmetros que referem-se a cor devem utilizar os valores gerados ou pela função Progress RGB-VALUE ou pela função interna da API fnc_convColor que faz a conversão das cores disponíveis na utapi011 para o valor RGB adequado;
  • Sempre que o desenvolvedor optar por construir gráficos sem utilizar as temp-tables, a responsabilidade de validar os dados informados não é da API;
  • Todas as procedures da API retornam, através do RETURN-VALUE, “OK” quando a procedure foi executada com sucesso e “NOK” no caso de algum erro.
  • Existe uma limitação do componente ChartFx em relação a impressão de gráficos com o tipo “Pizza”. Os tipos de gráficos (campo GraphType) 1 e 2 não devem ser utilizados como opção inicial de impressão, deve ser utilizado outro tipo de gráfico. Caso haja a necessidade que o gráfico seja do tipo pizza, deve ser setado no desenvolvimento do programa outro tipo de gráfico e após a geração pode ser mudado o gráfico para o tipo pizza, utilizando a opção “Gallery” na guia de controle do componente.


Procedures


PI-CARREGADADOS:

Procedure responsável por varrer as temp-tables e criar os pontos nos gráficos. Essa procedure não deve ser executada pelo desenvolvedor, ela será executada por uma outra procedure quando for necessário.


PI-CLEAR-DATA:

Procedure que executa o método ClearData do componente ChartFx. Dependendo do valor informado para a flag serão eliminados diferentes valores iniciais. Na seção Constantes existe a tabela de valores para ClearDataFlag, maiores informações sobre cada uma das opções pode ser consultado no manual do ChartFX. Essa procedure recebe dois parâmetros, o primeiro é o COM-HANDLE do gráfico e o segundo é um inteiro que representa a flag desejada.

Parâmetros:  

  DEFINE INPUT PARAMETER hGrafico AS COM-HANDLE NO-UNDO.
  DEFINE INPUT PARAMETER iFlag AS INTEGER NO-UNDO.

Sintaxe:    

RUN pi-clear-data (INPUT chGrafico, INPUT 4).


PI-CLOSEDATA:

Procedure que executa o método CloseData do componente ChartFx. Dependendo do valor informado para o código será encerrada a criação de determinados tipos de valores. Na seção Constantes existe a tabela de valores para COD, maiores informações sobre cada uma das opções pode ser consultado no manual do ChartFX. Essa procedure recebe dois parâmetros, o primeiro é o COM-HANDLE do gráfico e o segundo é um inteiro que representa o código  desejado. Antes de ser executada é necessário que seja executada a procedure pi-openData com o mesmo código.

Parâmetros:

 DEFINE INPUT PARAMETER hGrafico AS COM-HANDLE NO-UNDO.
 DEFINE INPUT PARAMETER iCod AS INTEGER NO-UNDO.

Sintaxe:

RUN pi-closedata (INPUT chGrafico, INPUT 1).


PI-CRIA-BTEXIT:

Procedure responsável por criar o botão de exit para cada um dos gráficos. Essa procedure não deve ser executada pelo desenvolvedor, ela será executada sempre que o programa for inicializado.


PI-CRIA-ERRO:


Procedure responsável por criar os registros de erro na temp-table tt-erros. Essa procedure não deve ser executada pelo desenvolvedor, ela será executada sempre que o gráfico gerado for baseado nas temp-tables.


PI-CRIA-INIVALUE:


Procedure que executa o método IniValue do componente ChartFx. Determina valores iniciais para os pontos do gráfico. Recebe como parâmetros o COM-HANDLE do gráfico, um inteiro que representa o número do set, um inteiro que representa o número do ponto e um decimal que é o valor inicial.

Parâmetros:

 DEFINE INPUT PARAMETER hGrafico AS COM-HANDLE NO-UNDO.
 DEFINE INPUT PARAMETER iNumSet AS INTEGER NO-UNDO.
 DEFINE INPUT PARAMETER iNumPoint AS INTEGER NO-UNDO.
 DEFINE INPUT PARAMETER dValor AS DECIMAL NO-UNDO.

    Sintaxe:

RUN pi-cria-inivalue (INPUT chGrafico, INPUT 0, INPUT 0, INPUT 100.85).

  


PI-CRIA-LINHALIMITE:


Procedure que cria linhas constantes no gráfico, são as ConstantLines do componente ChartFX. Recebe como parâmetros o COM-HANDLE do gráfico, um char que é o label da linha, um inteiro que é o valor onde será criada a linha, um inteiro que é a cor da linha, um inteiro que é o eixo onde será criada a linha, X(2) ou Y(0), e um inteiro que é o estilo da linha. Na seção Constantes existe uma tabela com os possíveis valores para o estilo da linha.

Parâmetros:

DEFINE INPUT PARAMETER hGrafico AS COM-HANDLE NO-UNDO.
    DEFINE INPUT PARAMETER cLabel AS CHAR NO-UNDO.
    DEFINE INPUT PARAMETER iValue AS INTEGER NO-UNDO.
    DEFINE INPUT PARAMETER iTextColor AS INTEGER NO-UNDO.
    DEFINE INPUT PARAMETER iAxis AS INTEGER NO-UNDO.
    DEFINE INPUT PARAMETER iLineStyle AS INTEGER NO-UNDO.

    Sintaxe:

RUN pi-cria-linhalimite(INPUT hGrafico,
 INPUT “Limite 01”,
 INPUT 250,
 INPUT RGB-VALUE(11,7,102),
 INPUT 0, 
 INPUT 1).


PI-CRIA-LINHASLIMITE:


Procedure que cria linhas constantes no gráfico, são as ConstantLines do componente ChartFX. Essa procedure não deve ser utilizada pelo desenvolvedor, o desenvolvedor deve utilizar a procedure PI-CRIA-LINHALIMITE para criar suas próprias linhas constantes.



PI-CRIA-LINHASSTAT:


Procedure que cria linhas estatísticas no gráfico. Para que o desenvolvedor possa executar essa procedure é necessário que o gráfico tenha sido criado utilizando as temp-tables de comunicação. Recebe como parâmetros o COM-HANDLE do gráfico, e um inteiro que é o número do gráfico que deseja-se criar as linhas.

Parâmetros:

DEFINE INPUT PARAMETER hGrafico AS COM-HANDLE NO-UNDO.
DEFINE INPUT PARAMETER iNumGraph AS INTEGER NO-UNDO.

Sintaxe:

RUN pi-cria-linhasStat(INPUT hGrafico, INPUT 1).


PI-CRIA-PONTO:


Procedure que cria a legenda dos pontos do gráfico. Recebe como parâmetros o COM-HANDLE do gráfico, um inteiro que é o número do ponto(para cada ponto deve-se utilizar um número diferente), e um char que é o label do ponto informado.

Parâmetros:

DEFINE INPUT PARAMETER hGrafico AS COM-HANDLE NO-UNDO.
DEFINE INPUT PARAMETER iNumPoint AS INTEGER NO-UNDO.
DEFINE INPUT PARAMETER cLabel AS CHARACTER NO-UNDO.

Sintaxe:

 RUN pi-cria-ponto (INPUT chGrafico, INPUT 0, INPUT “Ponto 01”).


PI-CRIA-SET:


Procedure que cria os sets dos gráficos. Recebe como parâmetros o COM-HANDLE do gráfico, um inteiro que é o número do set (para cada set deve-se utilizar um número diferente), um char que é a legenda do set, um inteiro que é a cor do set, um inteiro que determina se serão exibidos os labels dos pontos, se for maior que 0 indica que os labels devem ser exibidos, e um inteiro que é a cor dos labels dos pontos.

Parâmetros:   

 DEFINE INPUT PARAMETER hGrafico AS COM-HANDLE NO-UNDO.
 DEFINE INPUT PARAMETER iNumSet AS INTEGER NO-UNDO.
 DEFINE INPUT PARAMETER cLegend AS CHARACTER NO-UNDO.
 DEFINE INPUT PARAMETER iColor AS INTEGER NO-UNDO.
 DEFINE INPUT PARAMETER iDataLabels AS INTEGER NO-UNDO.
 DEFINE INPUT PARAMETER iDataLabelsColor AS INTEGER NO-UNDO.

Sintaxe:   

 RUN pi-cria-set (INPUT hGrafico,
     INPUT hGrafico:Chart:Series:COUNT,
     INPUT "Serie " + hGrafico:Chart:Series:COUNT,
     INPUT RGB-VALUE(0,0,0),
     INPUT "",
     INPUT RGB-VALUE(0,0,0)).


PI-CRIA-STRIP:


Procedure que cria os strips dos gráficos. No ChartFX o strip é uma região destacada do gráfico, para maiores informações deve-se consultar o manual do ChartFX. Recebe como parâmetros o COM-HANDLE do gráfico, um inteiro que é o número do strip (para cada strip deve-se utilizar um número diferente), um inteiro que é o valor mínimo, um inteiro que é o valor máximo, um inteiro que é a cor do strip, e um inteiro que é o eixo onde será criada a linha, X(2) ou Y(0).

Parâmetros:   

DEFINE INPUT PARAMETER hGrafico AS COM-HANDLE NO-UNDO.
DEFINE INPUT PARAMETER iStrip AS INTEGER NO-UNDO.
DEFINE INPUT PARAMETER iValueMin AS INTEGER NO-UNDO.
DEFINE INPUT PARAMETER iValueMax AS INTEGER NO-UNDO.
DEFINE INPUT PARAMETER iTextColor AS INTEGER NO-UNDO.
DEFINE INPUT PARAMETER iAxis AS INTEGER NO-UNDO.

Sintaxe:   

 RUN pi-cria-strip (INPUT hGrafico,
                   INPUT 0,
                   INPUT 10,
                   INPUT 100,
                   INPUT RGB-VALUE(255,0,0),
                   INPUT 0).


PI-CRIA-TITULO:

Procedure que cria títulos nos gráficos. Recebe como parâmetros o COM-HANDLE do gráfico, um inteiro que é número do título(para cada título deve-se utilizar um número diferente), um char que é o texto do título, um char que é o nome da fonte desejada, um inteiro que é o tamanho da fonte, um inteiro que é a cor do título, um inteiro que é o alinhamento( na seção Constantes existe a tabela de valores para StringAlignment), um inteiro que é a região do gráfico onde será exibido o título( na seção Constantes existe a tabela de valores para DockArea), um lógico que determina se o título deve ser em itálico, um lógico que determina se o título deve ser em negrito, e um lógico que determina se o título deve ser sublinhado.

Parâmetros:

    DEFINE INPUT PARAMETER hGrafico AS COM-HANDLE NO-UNDO.    DEFINE INPUT PARAMETER iText AS INTEGER NO-UNDO.    DEFINE INPUT PARAMETER cText AS CHAR NO-UNDO.    DEFINE INPUT PARAMETER cFontName AS CHAR NO-UNDO.    DEFINE INPUT PARAMETER iFontSize AS INTEGER NO-UNDO.    DEFINE INPUT PARAMETER iTextColor AS INTEGER NO-UNDO.    DEFINE INPUT PARAMETER iAlignment AS INTEGER NO-UNDO.    DEFINE INPUT PARAMETER iDockArea AS INTEGER NO-UNDO.    DEFINE INPUT PARAMETER lItalic AS LOGICAL NO-UNDO.    DEFINE INPUT PARAMETER lBold AS LOGICAL NO-UNDO.    DEFINE INPUT PARAMETER lUnderline AS LOGICAL NO-UNDO.

Sintaxe:

RUN pi-cria-titulo (INPUT chGrafico,                              INPUT 0,                              INPUT “Título”,                              INPUT “Arial”,                              INPUT 10,                              INPUT RGB-VALUE(0,0,0),                              INPUT 1,                              INPUT 1,                              INPUT False,                              INPUT True,                              INPUT False).









   



            


PI-CRIA-VALUE:


Procedure que executa o método Value do componente ChartFx. Determina os valores dos pontos do gráfico. Recebe como parâmetros o COM-HANDLE do gráfico, um inteiro que representa o número do set, um inteiro que representa o número do ponto e um decimal que é o valor.


Parâmetros:


    DEFINE INPUT PARAMETER hGrafico AS COM-HANDLE NO-UNDO.

    DEFINE INPUT PARAMETER iNumSet AS INTEGER NO-UNDO.

    DEFINE INPUT PARAMETER iNumPoint AS INTEGER NO-UNDO.

    DEFINE INPUT PARAMETER dValor AS DECIMAL NO-UNDO.


Sintaxe:


    RUN pi-cria-value (INPUT chGrafico, INPUT 0, INPUT 0, INPUT 128).


PI-FORMAT-LEGEND:


Procedure que formata as legendas do gráfico. Recebe como parâmetros o COM-HANDLE da legenda, um char que é o nome da fonte, um inteiro que é o tamanho da fonte, um inteiro que é a cor, um lógico que determina se a legenda deve ser em itálico, um lógico que determina se a legenda deve ser em negrito, e um lógico que determina se a legenda deve ser sublinhada.


Parâmetros:


    DEFINE INPUT PARAMETER hLegend AS COM-HANDLE NO-UNDO.

    DEFINE INPUT PARAMETER cFontName AS CHAR NO-UNDO.

    DEFINE INPUT PARAMETER iFontSize AS INTEGER NO-UNDO.

    DEFINE INPUT PARAMETER iTextColor AS INTEGER NO-UNDO.

    DEFINE INPUT PARAMETER lItalic AS LOGICAL NO-UNDO.

    DEFINE INPUT PARAMETER lBold AS LOGICAL NO-UNDO.

    DEFINE INPUT PARAMETER lUnderline AS LOGICAL NO-UNDO.


Sintaxe:


    RUN pi-format-legend (INPUT chGrafico:Chart:AxisX,

                                          INPUT “Arial”,

                                          INPUT 10,

                                          INPUT RGB-VALUE(0,255,0),

                                          INPUT True,

                                          INPUT False,

                                          INPUT False).


PI-FORMAT-SERIES:


Procedure que formata as séries do gráfico. Recebe como parâmetros o COM-HANDLE da série, um inteiro que se for maior que 0 informa que devem ser exibidos os labels dos pontos, e um inteiro que é a cor.


Parâmetros:


    DEFINE INPUT PARAMETER chSeries AS COM-HANDLE NO-UNDO.

    DEFINE INPUT PARAMETER iDataLabels AS INTEGER NO-UNDO.

    DEFINE INPUT PARAMETER iDataLabelsColor AS INTEGER NO-UNDO.


Sintaxe:


    RUN pi-format-series (INPUT hGrafico:Chart:Series(0),

               INPUT 1,

               INPUT RGB-VALUE(0,0,255)).


PI-GET-CHARTHANDLE:


Procedure que retorna o handle do gráfico desejado. Com essa funcionalidade o desenvolvedor possui toda liberdade para utilizar os recursos do componente mesmo que não sejam disponibilizados via API. Recebe como parâmetro um valor inteiro que indica o handle do gráfico que será retornado. Se for informado 1 será retornado o handle do gráfico 1 e se for diferente de 1 será retornado o handle do gráfico 2. Essa procedure tem um parâmetro de OUTPUT que é do tipo COM-HANDLE, e contém o handle do gráfico desejado.


Parâmetros:


    DEFINE INPUT  PARAMETER iChart AS INTEGER NO-UNDO.

    DEFINE OUTPUT PARAMETER hGrafico AS COM-HANDLE NO-UNDO.


Sintaxe:


    RUN pi-get-chartHandle (INPUT 1,

     OUTPUT hGrafico).


PI-GET-TT-ATRIBUTOS:


Procedure que retorna a temp-table tt-atributos.


Parâmetros:


    DEFINE OUTPUT PARAMETER TABLE FOR tt-atributos.


Sintaxe:


    RUN pi-get-tt-atributos (OUTPUT TABLE tt-atributos).


PI-GET-TT-DADOS:


Procedure que retorna a temp-table tt-dados.


Parâmetros:


    DEFINE OUTPUT PARAMETER TABLE FOR tt-dados.


Sintaxe:


    RUN pi-get-tt-dados (OUTPUT TABLE tt-dados).


PI-GET-TT-ERROS:


Procedure que retorna a temp-table tt-erros.


Parâmetros:


    DEFINE OUTPUT PARAMETER TABLE FOR tt-erros.


Sintaxe:


    RUN pi-get-tt-erros (OUTPUT TABLE tt-erros).


PI-GET-TT-POINTS-2:


Procedure que retorna a temp-table tt-points-2.


Parâmetros:


    DEFINE OUTPUT PARAMETER TABLE FOR tt-points-2.


Sintaxe:


    RUN pi-get-tt-points-2 (OUTPUT TABLE tt-points-2).


PI-GET-TT-SETS:


Procedure que retorna a temp-table tt-sets.


Parâmetros:


    DEFINE OUTPUT PARAMETER TABLE FOR tt-sets.


Sintaxe:


    RUN pi-get-tt-sets (OUTPUT TABLE tt-sets).


PI-INICIALIZAR:


Procedure que faz a criação dos gráficos quando os dados são inseridos através das temp-tables que são utilizadas na utapi011. Quando essa procedure é executada a mesma realiza o processo de validação dos dados, assim como é feito na utapi011. Se existir alguma falha será retornado “NOK” e a temp-table tt-erros conterá os registros dos erros. Essa procedure só deve ser executada pelo desenvolvedor no momento em que desejar exibir os dados e não for mais necessário alterar nenhum informação. Não recebe nem retorna nenhum tipo de parâmetro.


PI-OPENDATA:


Procedure que permite ao desenvolvedor iniciar a criação dos pontos no gráfico. Após executar essa procedure e não deseja-se criar mais pontos é necessário executar a procedure pi-closeData com o mesmo código informado nessa procedure. Na seção Constantes existe a tabela de valores para COD, maiores informações sobre cada uma das opções pode ser consultado no manual do ChartFX. Recebe como parâmetro o COM-HANDLE do gráfico, um inteiro que representa o código do tipo de dados que deseja-se criar, um inteiro que determina o número de séries do gráfico, e um inteiro que determina o número de pontos de cada série. É importante esclarecer que no componente ChartFX todas as séries devem possuir o mesmo número de pontos.


Parâmetros:


    DEFINE INPUT PARAMETER hGrafico AS COM-HANDLE NO-UNDO.

    DEFINE INPUT PARAMETER iCod AS INTEGER NO-UNDO.

    DEFINE INPUT PARAMETER iSerie AS INTEGER NO-UNDO.

    DEFINE INPUT PARAMETER iPoints AS INTEGER NO-UNDO.


Sintaxe:


    RUN pi-openData(INPUT hGrafico,

                     INPUT 1,

                                  INPUT 2,

                                  INPUT 5).


PI-REG-COMPONENTS:


Procedure que registra os OCXs necessários para execução do DataGraph. Essa procedure não deve ser executada pelo desenvolvedor.

 

PI-SET-CHART-3D:


Procedure que define se o gráfico é exibido em modo 3D ou não. Recebe como parâmetro o COM-HANDLE do gráfico, e um valor lógico que se for verdadeiro define o gráfico como 3D senão define o gráfico como 2D.


Parâmetros:


    DEFINE INPUT PARAMETER hGrafico AS COM-HANDLE NO-UNDO.

    DEFINE INPUT PARAMETER l3d AS LOGICAL NO-UNDO.


Sintaxe:


    RUN pi-set-chart-3d (INPUT hGrafico,

                          INPUT TRUE).


PI-SET-CHART-OPTIONS:


Procedure que define algumas características gerais do gráfico. Recebe como parâmetro o COM-HANDLE do gráfico, um char que  determina a fonte do gráfico, um inteiro que define o tamanho da fonte, um inteiro que se for maior que 0 determina que as linhas do gráfico serão espessas, um lógico que determina que os textos devem ser em itálico, um lógico que determina que os textos devem ser em negrito, e um lógico que determina que os textos devem ser sublinhados.


Parâmetros:


    DEFINE INPUT PARAMETER hGrafico AS COM-HANDLE NO-UNDO.

    DEFINE INPUT PARAMETER cFontName AS CHAR NO-UNDO.

    DEFINE INPUT PARAMETER iFontSize AS INTEGER NO-UNDO.

    DEFINE INPUT PARAMETER iThickLines AS INTEGER NO-UNDO.

    DEFINE INPUT PARAMETER lItalic AS LOGICAL NO-UNDO.

    DEFINE INPUT PARAMETER lBold AS LOGICAL NO-UNDO.

    DEFINE INPUT PARAMETER lUnderline AS LOGICAL NO-UNDO.


Sintaxe:


    RUN pi-set-chart-options (INPUT chGrafico,

                                              INPUT “Arial”,

                                              INPUT 10,

                                              INPUT 1,

                                              INPUT False,

                                              INPUT False,

                                              INPUT True). 


PI-SET-CHART-STYLE:


Procedure que determina o estilo do gráfico baseado nas informações das temp-tables. Essa procedure não deve ser executada pelo desenvolvedor.


PI-SET-CHART-TYPE:


Procedure que determina o tipo do gráfico. Recebe como parâmetro o COM-HANDLE do gráfico, e um inteiro que é o tipo do gráfico. Na seção Constantes existe a tabela de valores para Gallery, maiores informações sobre cada uma das opções pode ser consultado no manual do ChartFX.


Parâmetros:


    DEFINE INPUT PARAMETER hGrafico AS COM-HANDLE NO-UNDO.

    DEFINE INPUT PARAMETER iGraphType AS INTEGER NO-UNDO.

   

Sintaxe:


    RUN pi-set-chart-type (INPUT chGrafico,

                                          INPUT 2). 


PI-SET-CHARTBORDER:


Procedure que determina o tipo de borda do gráfico. Recebe como parâmetro o COM-HANDLE do gráfico, e um inteiro que é o tipo da borda do gráfico. Na seção Constantes existe a tabela de valores para BorderType, maiores informações sobre cada uma das opções pode ser consultado no manual do ChartFX.


Parâmetros:


    DEFINE INPUT PARAMETER hGrafico AS COM-HANDLE NO-UNDO.

    DEFINE INPUT PARAMETER iGridStyle AS INTEGER NO-UNDO.

   

Sintaxe:


    RUN pi-set-chartBorder ( INPUT chGrafico,

                                             INPUT 21).


PI-SET-GRID:


Procedure que determina o grid do gráfico. Recebe como parâmetro o COM-HANDLE do gráfico, um inteiro que é o estilo do grid( 1 para grid horizontal, 2 para grid vertical e 3 para ambos), e um inteiro que é o estilo da linha do grid. Na seção Constantes existe a tabela de valores para DashStyle, maiores informações sobre cada uma das opções pode ser consultado no manual do ChartFX.


Parâmetros:


    DEFINE INPUT PARAMETER hGrafico AS COM-HANDLE NO-UNDO.

    DEFINE INPUT PARAMETER iGridStyle AS INTEGER NO-UNDO.

    DEFINE INPUT PARAMETER iGridLineStyle AS INTEGER NO-UNDO.

   

Sintaxe:


    RUN pi-set-grid (INPUT chGrafico,

                               INPUT 3,

     INPUT 3).


PI-SET-GRID-AXIS:


Procedure que cria o grid para um determinado eixo do gráfico. Recebe como parâmetro o COM-HANDLE do axis desejado, e um inteiro que é o estilo da linha do grid. Na seção Constantes existe a tabela de valores para DashStyle, maiores informações sobre cada uma das opções pode ser consultado no manual do ChartFX.


Parâmetros:


    DEFINE INPUT PARAMETER hAxis AS COM-HANDLE NO-UNDO.

    DEFINE INPUT PARAMETER iGridLineStyle AS INTEGER NO-UNDO.

   

Sintaxe:


    RUN pi-set-grid-axis (INPUT hGrafico:Chart:AxisX,

                                       INPUT 2).


PI-SET-LOGBASE:


Procedure que determina se um determinado eixo do gráfico está com base logarítmica. Recebe como parâmetro o COM-HANDLE do gráfico, um inteiro que é o eixo que deve estar na base logarítmica( 1 – apenas o eixo Y, 2 – apenas o eixo X e 3 – para ambos), e um inteiro que é o valor da base logarítmica.


Parâmetros:


    DEFINE INPUT PARAMETER hGrafico AS COM-HANDLE NO-UNDO.

    DEFINE INPUT PARAMETER iAxis AS INTEGER NO-UNDO.

    DEFINE INPUT PARAMETER iLogBase AS INTEGER NO-UNDO.

   

Sintaxe:


    RUN pi-set-logbase(INPUT chGrafico,

                                     INPUT 1,

                                     INPUT 10).


PI-SET-PIELINESTYLE:


Procedure que determina os estilos de linha para os gráficos do tipo pizza. Essa procedure não deve ser utilizada por desenvolvedores.


PI-SET-TT-ATRIBUTOS:


Procedure que passa a temp-table tt-atributos para a API.


Parâmetros:


    DEFINE INPUT PARAMETER TABLE FOR tt-atributos.


Sintaxe:


    RUN pi-set-tt-atributos (INPUT TABLE tt-atributos).


PI-SET-TT-DADOS:


Procedure que passa a temp-table tt-dados para a API.


Parâmetros:


    DEFINE INTPUT PARAMETER TABLE FOR tt-dados.


Sintaxe:


    RUN pi-set-tt-dados (INPUT TABLE tt-dados).


PI-SET-TT-POINTS-2:


Procedure que passa a temp-table tt-points-2 para a API.


Parâmetros:


    DEFINE INPUT PARAMETER TABLE FOR tt-points-2.


Sintaxe:


    RUN pi-set-tt-points-2 (INPUT TABLE tt-points-2).


PI-SET-TT-SETS:


Procedure que passa a temp-table tt-sets para a API.


Parâmetros:


    DEFINE INPUT PARAMETER TABLE FOR tt-sets.


Sintaxe:


    RUN pi-set-tt-sets (INPUT TABLE tt-sets).


PI-SET-VISIBLE:


Procedure que passa exibe ou esconde os gráficos. Recebe como parâmetro um inteiro e de acordo com o seu valor os gráficos serão exibidos ou escondidos. Para um valor menor ou igual a 0 os dois gráficos serão escondidos, para o valor 1 apenas o gráfico 1 será exibido, para o valor 2 apenas o gráfico 2 será exibido e para um valor maior ou igual a 3 os dois gráficos serão exibidos.


Parâmetros:


    DEFINE INPUT PARAMETER iGrafico AS INTEGER NO-UNDO.

Sintaxe:


    RUN pi-set-visible (INPUT 3).


PI-SETA-ESTILO-LEGENDBOX:


Procedure que determina o estilo da legendbox. Recebe como parâmetro o COM-HANDLE do gráfico, um char que é o nome da fonte desejada, um inteiro com o tamanho da fonte, um inteiro com a posição da legenda(ver na seção Referências a tabela de posição da legenda), um lógico que determina que os textos devem ser em itálico, um lógico que determina que os textos devem ser em negrito, e um lógico que determina que os textos devem ser sublinhados.


Parâmetros:


    DEFINE INPUT PARAMETER hGrafico         AS COM-HANDLE NO-UNDO.

    DEFINE INPUT PARAMETER cLegendFontName  AS CHAR NO-UNDO.

    DEFINE INPUT PARAMETER iLegendFontSize  AS INTEGER NO-UNDO.

    DEFINE INPUT PARAMETER iLegendPos       AS INTEGER NO-UNDO.

    DEFINE INPUT PARAMETER lItalic AS LOGICAL NO-UNDO.

    DEFINE INPUT PARAMETER lBold AS LOGICAL NO-UNDO.

    DEFINE INPUT PARAMETER lUnderline AS LOGICAL NO-UNDO.


Sintaxe:


    RUN pi-seta-estilo-legendBox (INPUT chGrafico,

                                                      INPUT “Arial”,

                            INPUT 10,

                            INPUT 1,

                                                      INPUT True,

                                                 INPUT True,

                                                 INPUT False).   


PI-SHOWTIPS:


Procedure que determina se os tips dos pontos serão exibidos no gráfico. Recebe como parâmetro o COM-HANDLE do gráfico, e um lógico que determina se serão ou não exibidos os tips.


Parâmetros:


    DEFINE INPUT PARAMETER hGrafico AS COM-HANDLE NO-UNDO.

    DEFINE INPUT PARAMETER lShowTips AS LOGICAL NO-UNDO.


Sintaxe:


    RUN pi-showTips (INPUT chGrafico,

                                   INPUT True).   


PI-TRANSFORM:


Procedure que altera as dimensões da janela para ocupar a tela inteira. Essa procedure é executada na inicialização da API e por isso não deve ser executada pelo desenvolvedor.


PI-VALIDA:


Procedure que realiza as validações dos dados das temp-tables. Essa procedure não deve ser executada pelo desenvolvedor pois é executada automaticamente quando os dados são enviados através de temp-tables para a API. Se for encontrado algum erro a temp-table tt-erros conterá os registros com os erros ocorridos.


Funções:

 

FNC_CHECKEXTRASERIE:


Função que verifica se é necessário a criação de séries adicionais. Essa função não deve ser utilizada pelo desenvolvedor.


FNC_CONVCOLOR:


Função que converte o valor inteiro, da tabela de cores da utapi011 para o valor RGB correspondente. Retorna um valor do tipo inteiro.


Parâmetros:


INPUT iColor AS INTEGER


Sintaxe:


fnc_convColor(5)


FNC_CONVGRAPHSTYLE:


Função que converte o valor inteiro, da tabela de estilos da utapi011, para o valor utilizado pelo componente ChartFX. Essa função não deve ser utilizada pelo desenvolvedor.


FNC_CONVGRAPHTYPE:


Função que converte o valor inteiro, da tabela de tipos de gráfico da utapi011, para o valor inteiro utilizado pelo ChartFX. Retorna um valor do tipo inteiro.


Parâmetros:


INPUT iGraphType AS INTEGER


Sintaxe:


fnc_convGraphType(6)


FNC_CONVLEGENDPOSALIGN:


Função que converte o valor inteiro, da tabela de alinhamento das legendas da utapi011, para o valor inteiro utilizado pelo ChartFX. Retorna um valor do tipo inteiro.


Parâmetros:


INPUT iAlignPos AS INTEGER


Sintaxe:


fnc_convLegendPosAlign(3)


FNC_CONVLEGENDPOSDOCK:


Função que converte o valor inteiro, da tabela de alinhamento das legendas da utapi011, para o valor inteiro utilizado pelo ChartFX. Retorna um valor do tipo inteiro.


Parâmetros:


INPUT iDockPos AS INTEGER


Sintaxe:


fnc_convLegendPosDock(3)


FNC_CONVSTYLE:


Função que converte o valor inteiro, da tabela de tipos de fontes da utapi011, para true ou false dependendo do valor informado e do tipo de fonte. Recebe como parâmetro um valor inteiro que é o código da tabela do tipo de fontes, e um valor do tipo char que representa que estilo estamos analisando(pode ser igual a: “Italic”, “Bold” ou “Underline”). Retorna um valor do tipo lógico.


Parâmetros:


    INPUT iStyle AS INTEGER

    INPUT cType AS CHARACTER


Sintaxe:

 

fnc_convStyle(3, “Italic”)


















TEMP-TABLE tt-reuniao

Atributo

Tipo

Formato

Valor Inicial

i-versao-integracao

integer

">>9"


c-assunto

Char



c-corpo

Char



c-local

Char



c-categoria

Char



dt-dataini

Date

“99/99/9999”


dt-horaini

Char



l-lembrete

Logical


No

l-diatodo

Logical


No

i-duracao

Integer

“9999”


i-horaaviso

Integer



i-tipohorario

integer



c-convidadosreq

Char



c-convidadosopc

Char



c-convidadosrec

Char



i-importancia

Integer



i-tipo

Integer



l-periodico

Logical


No

i-tipoperiodo

Integer



i-intervalo

Integer



i-diassemana

Integer



i-mesdoano

Integer



i-diadomes

Integer



dt-fimperiodico

date



i-inicioocorrencia

integer



i-ocorrencias

integer



* ver Principais Validações da Temp-Table tt-reuniao


Atributo

Descrição

i-versao-integracao

Campo usado para verificar compatibilidade entre programa e api

c-assunto

Campo referente ao assunto do compromisso

c-corpo

Texto que seguira junto com o compromisso, é o corpo da mensagem

c-local

Local do compromisso

c-categoria

Categorias que o compromisso pertence separadas por “;”

dt-dataini

Data inicial do compromisso em formato mm/dd/yyyy

c-horaini

Hora de início do compromisso em formato hh:mm:ss

i-lembrete

Define se deve ser habilitado o lembrete para aviso prévio do compromisso

i-diatodo

Define se o compromisso ocupa todo o dia (hora de início deve ser informada)

i-duracao

Duração, em minutos, do compromisso.

i-horaaviso

Define o tempo, em minutos, para aviso prévio antes do compromisso (a função lembrete deverá estar ativada)

i-tipohorario

Define como deve ser mostrado o horário 0-Disponível 1-Provisório 2- Ocupado 3-Fora do escritório

c-convidadosreq

Convidados requeridos separados por “;”, podendo ser usado o nome do catálogo de endereços ou endereço de e-mail. *

c-convidadosopc

Convidados opcionais separados por “;”, podendo ser usado o nome do catálogo de endereços ou endereço de e-mail.*

c-convidadosrec

Convidados do tipo recurso separados por “;”, podendo ser usado o nome do catálogo de endereços ou endereço de e-mail. *

i-importancia

Importância da reunião 0-baixa 1-normal 2-alta

i-tipo

Tipo do compromisso 0-normal 1-pessoal 2-privado 3-confidencial.

i-periodico

Define se o compromisso é do tipo periódico, ou seja, se o mesmo tem várias ocorrências. **

i-tipoperiodo

Define o tipo de período a ser usado no compromisso.**

i-intervalo

Define o intervalo entre as ocorrências, como 2 meses 3 dias dependendo do tipo da mesma. **

i-diassemana

Máscara que define o(s) dias(s) de semana a serem usados para o compromisso. **

i-mesdoano

Define o mês de 1 a 12 para o compromisso. **

i-diadomes

Define o dia do mês para o compromisso. **

dt-fimperiodico

Data do fim das ocorrências de um compromisso periódico, sobrescreve o valor da variável i-ocorrências. **

i-inicioocorrencia

Define o dia de início de ocorrência para certos tipos de períodos como terceira (segunda) de cada mês. **

i-ocorrencias

Número de ocorrências de um compromisso periódico. **

*O contato deverá existir no catálogo de endereços

** Verificar tópico referente a compromissos periódicos em “Outras informações”.



Temp-Table tt-erros: possui todos os erros encontrados pela API.

TEMP-TABLE tt-erros

Atributo

Tipo

Formato

Valor Inicial

cod-erro

Integer



desc-erro

Character

x(256)


* ver Definição Temp-Table tt-erros

Atributo

Descrição

cod-erro

Número do erro

desc-erro

Descrição do erro ocorrido da ut-msgs


Execução

O programa utp/utapi028.p irá executar 2 validações básicas:




1º Validação:

Versão de Integração

O programa irá verificar se o programa chamador está íntegro com a API, e isto ocorre ao realizar a verificação da versão de integração passada como parâmetro. Caso a versão seja incompatível, a API finalizará a execução retornando o código de erro 3941.


2ª Validação:

Inconsistência ou Insuficiência dos Dados

O programa irá verificar a inconsistência e/ou insuficiência dos dados, e isto ocorre ao realizar a verificação dos dados passados como parâmetros. Caso os dados sejam inconsistentes ou insuficientes, a API finalizará a execução retornando o código de erro 8646.


O programa também executará outras validações referentes a erros específicos que serão abordados na seção “Possíveis erros” deste documento.

Cabe ao programa de origem, verificar a consistência do registro que está sendo enviado.

* ver descrições da Temp-Table tt-reuniao




Parâmetros de Saída

No retorno da execução do utp/utapi028.p, será retornado um dos valores via RETURN-VALUE:


NOK: 

Envio do compromisso interrompido, os dados passados como parâmetros, através das Temp-Tables, são inconsistentes ou foram insuficientes;

OK: 

Criação do compromisso com sucesso.


No caso do retorno ser NOK, todos os erros encontrados serão retornados através da Temp-Table tt-erros.




Outras Informações

Compromissos periódicos: 

            Os compromissos periódicos podem ser dos seguintes tipos:

Diário (0):

  • Os compromissos do tipo diário são executados em todas as semanas do ano, podendo ser de n em n dias conforme definição do usuário para a variável i-intervalo.

    Exemplo da definição de um compromisso diário:

    assign i-tipoperiodo = 0    /*define o tipo do período como diário */
       i-intervalo   = 2.  /* define o intervalo entre as ocorrências */

      Desta forma será agendado um compromisso do tipo diário que acontece de 2 em 2 dias.


Semanal (1):

  • Os compromissos do tipo semanal são executados de n em n semanas conforme a variável i-intervalo em determinados dias da semana conforme a variável i-diassemana.

    Exemplo da definição de um compromisso semanal:

    assign i-tipoperiodo = 1 /* define o tipo do período como semanal */
       i-intervalo   = 2
       i-diassemana  = 3.

      Desta forma será agendado um compromisso do tipo semanal que acontece de 2 em 2 semanas no domingo e na segunda.


Mensal (2):

  • Os compromissos do tipo mensal são executados de n em n meses conforme a variável i-intervalo no dia x conforme a variável i-diadomes.

    Exemplo da definição de um compromisso mensal:

    assign i-tipoperiodo = 2 /* define o tipo do período como mensal */
       i-intervalo   = 5
       i-diadomes    = 14.

    Desta forma será agendado um compromisso do tipo mensal que acontece de 5 em 5 meses no dia 14.


Mensal com início de ocorrência (3):

  • Os compromissos do tipo mensal com início de ocorrência são executados de n em n meses conforme a variável i-intervalo no primeiro, segundo, terceiro, quarto ou ultimo dia da ocorrência do dia definido na variável i-diassemana conforme a variável i-inicioocorrencia.

    Exemplo da definição de um compromisso mensal com início de ocorrência:

    assign i-tipoperiodo = 3 /* define o tipo do período como mensal com início de ocorrência */
       i-intervalo   = 4
       i-diassemana  = 1
       i-inicioocorrencia = 2.

              Desta forma será agendado um compromisso do tipo mensal com início de ocorrência que acontece de 4 em 4 meses no segundo domingo do mês.

                No caso particular de compromissos com início de ocorrência, deve se levar em consideração que a variável i-diassemana deverá conter o valor de apenas um dia da semana ou então o valor 127 para o primeiro dia, o valor 65 para o primeiro dia de fim de semana ou 62 para o primeiro dia útil. Note que 127 é a soma de todos os dias da semana, 65 é a soma de sábado e domingo e 62 e a soma de segunda a sexta, estes são os únicos valores somados permitidos para esse tipo de ocorrência exclusivamente.


Anual (5):

  • Os compromissos do tipo anual ocorrem 1 vez por ano no mês n definido pela variável i-mesdoano no dia n definido pela variável i-diadomes.

    Exemplo da definição de um compromisso anual:

    assign i-tipoperiodo = 5  /* define o tipo do período como anual */
       i-diadomes    = 30
       i-mesdoano    = 4. /* define o mês do ano */

    Desta forma será agendado um compromisso do tipo anual que acontece uma vez pôr ano no dia 30 do mês 4.


Anual com início de ocorrência (6):

  • Os compromissos do tipo anual com início de ocorrência ocorrem 1 vez por ano no mês n conforme a variável i-mesdoano, no primeiro, segundo, terceiro, quarto ou ultimo dia da ocorrência do dia definido na variável i-diassemana conforme a variável i-inicioocorrencia.

    Exemplo da definição de um compromisso anual com início de ocorrência:

    assign i-tipoperiodo = 6 /* define o tipo do período como anual */
       i-mesdoano = 5
       i-diassemana = 16
       i-inicioocorrencia = 2.

    Desta forma será agendado um compromisso do tipo anual com início de ocorrência que acontece no mês 5 na segunda quinta-feira. Os valores da variável i-diassemana são os mesmos do tipo de período 3.


Variável i-diassemana:

  • A variável i-diassemana é usada em vários tipos de compromisso, e ela consiste na soma dos valores para definir os dias:

1  -Domingo

2  -Segunda-feira

4  -Terça-feira

8  -Quarta-feira

16-Quinta-feira

32-Sexta-feira

64-Sabado

Exemplos:

assign diassemana = 3    /* 1+2 domingo + segunda  */
assign diassemana = 127  /* todos os dias */


Definições das Temp-Tables a serem utilizadas pela API utp/utapi028.p

Definição Temp-Table tt-reuniao:

DEFINE TEMP-TABLE tt-reuniao
    field i-versao-integracao AS INTEGER FORMAT ">>9" 
    field c-assunto           AS CHAR
    FIELD c-corpo             AS CHAR
    FIELD c-local             AS CHAR
    FIELD c-categoria         AS CHAR
    FIELD dt-dataini          AS DATE FORMAT "99/99/9999"
    FIELD c-horaini           AS CHAR
    FIELD l-lembrete          AS LOGICAL INIT NO
    FIELD l-diatodo           AS LOGICAL INIT NO
    FIELD i-duracao           AS INTEGER FORMAT "9999"
    FIELD i-horaaviso         AS INTEGER
    FIELD i-tipohorario       AS INTEGER
    FIELD c-convidadosreq     AS CHAR
    FIELD c-convidadosopc     AS CHAR
    FIELD c-convidadosrec     AS CHAR
    FIELD i-importancia       AS INTEGER
    FIELD i-tipo              AS INTEGER
    FIELD l-periodico         AS LOGICAL INIT NO
    FIELD i-tipoperiodo       AS INTEGER
    FIELD i-intervalo         AS INTEGER
    FIELD i-diassemana        AS INTEGER
    FIELD i-mesdoano          AS INTEGER
    FIELD i-diadomes          AS INTEGER
    FIELD dt-fimperiodico     AS DATE
    FIELD i-inicioocorrencia  AS INTEGER
    FIELD i-ocorrencias       AS INTEGER.


Definição Temp-Table tt-erros:

define temp-table tt-erros
    field cod-erro   as integer
    field desc-error as char format "x(256)"

Exemplo de Utilização

{utp/utapi028.i}
CREATE tt-reuniao.
ASSIGN c-assunto = "Assunto da mensagem"
       c-corpo = " Aqui vai um grande texto para o corpo da mensagem"
       c-local = " Local qualquer"
       dt-dataini = 12/23/2002
       l-lembrete = FALSE
       c-horaini = "00:00:00"
       l-diatodo = FALSE
       i-duracao = 800
       i-horaaviso = 50
       i-importancia = 0 
       i-tipohorario = 3 
       c-convidadosreq = "[email protected]"
       c-convidadosopc = "João da Silva"
       c-convidadosrec = "Luiz Cesar Medeiros Filho;Joao da Silva"
       i-tipo =2
       c-categoria = "Importante"
/* inicia periódico */
       l-periodico = TRUE
       i-tipoperiodo = 1
       i-diassemana = 127
       i-inicioocorrencia = 2
       i-intervalo = 2.

run utp/utapi028.p persistent set h-utapi028.
run pi-execute in h-utapi028 (input table tt-reuniao,output table tt-erros).
for each tt-erros:
        disp "Erro: " tt-erros.cod-erro skip
             "Descrição: " tt-erros.desc-erro format "x(50)".
end.

delete procedure h-utapi028.
                      
    


Possíveis erros

Erro 8646: Dados incorretos ou insuficientes

 

  • Este erro acontece quando há erros na passagem da tabela temporária como parâmetro, é ocasionado quando a api não pode achar o primeiro registro da tabela tt-reuniao, ou seja, o único por onde serão passados os parâmetros para a api.

  • Deve ser verificado se a tabela temporária está sendo preenchida antes de ser enviada como parâmetro para a api.


Erro 3941: Versão de integração incorreta!

 

  • Este erro acontece quando o programa que chama a api não passa como parâmetro a versão de integração correta da api, esta verificação é feita para verificar se o programa chamador está compatível com a API.

  • Deve ser verificado se o campo i-versao-integracao da tabela tt-reuniao é preenchido com a versão correta da api definida no arquivo utapi028.p.


Erro 4786: Hora informada não está correta!

  • Erro ocasionado quando o campo c-horaini não é preenchido corretamente, ou seja não contém uma hora no formato HH:MM:SS, ou seu tamanho não tem 8 caracteres, ou a hora informada é maior que 23, os minutos informados maiores que 59 ou os segundos informados também maiores que 59.

  • Deve ser também levado em consideração que uma hora do tipo 2:29:35 está errada pois seu formato é H:MM:SS e não corresponde ao formato solicitado pela api. O correto seria 02:29:35.



Erro 26815: Valor da variável &1 inválido!

  • Este erro é ocasionado quando o campo &1 da temp-table tt-reuniao é preenchido incorretamente, deve se consultar esta documentação para possíveis valores e deve se levar em consideração que se um valor necessário não for informado, essa mensagem ocorrerá. 


Erro 26816: Um ou mais convidados estão incorretos

  • Erro causado pelo fato de um dos convidados da reunião não existir no catálogo de endereço global, ou seja, do servidor.

  • Neste caso deve ser verificado se os campos c-convidadosreq, c-convidadosopc e

    c-convidadosrec foram preenchidos com nomes válidos no catálogo de endereços global e/ou  endereços de e-mail separados por “;”.