CONTEÚDO

01. Objetivos

A API utp/utapi033.p permite a geração de planilha eletrônica, sem a necessidade da instalação do MS Excel na máquina que está executando a geração.

02. Considerações gerais

A API gera um arquivo do tipo XML com as informações necessárias para a criação de uma planilha eletrônica no padrão MS Excel.
Programas que podem ser utilizados para a visualização do arquivo XML gerado:
- Apache OpenOffice homologado com ressalvas*;
- MS Excel homologado sem ressalvas;
- Libre Office homologado com ressalvas*.

* O Apache OpenOffice e o Libre Office abrem um arquivo maior que 1.1 MB, mas o tempo para a abertura do arquivo é alto comparado ao MS Excel.

Importante

Considerações para utilização desta API com LibreOffice:

O funcionamento para LibreOffice não possui diferenças, exceto para o caractere “;” que é utilizado como separador de dados exportados, portanto deve ser evitado.

03. Como utilizar

01 - Executar a API de forma persistente

DEFINE VARIABLE h-handle AS HANDLE NO-UNDO.    
RUN utp/utapi033.p PERSISTENT SET h-handle.

02 - Executar as procedures piColumn e piWorksheetColumn

Caso esteja usando mais de uma aba na planilha utilize piWorksheetColumn, caso contrário utilize piColumn.

Estas procedures são utilizadas para criar as colunas da planilha e possuem a seguinte assinatura:

Procedure piColumn:

PROCEDURE piColumn:

DEFINE INPUT PARAMETER pColumn   AS INTEGER   NO-UNDO.

DEFINE INPUT PARAMETER pDataType AS CHARACTER NO-UNDO.

DEFINE INPUT PARAMETER pLabel    AS CHARACTER NO-UNDO.

DEFINE INPUT PARAMETER pFormat   AS CHARACTER NO-UNDO.

DEFINE INPUT PARAMETER pWidth    AS CHARACTER NO-UNDO.

Parâmetro	I/O	Tipo de Dado	Conteúdo
pColumn	Input	Integer	Define o número da coluna na planilha.
pDataType	Input	Character	Define o tipo do conteúdo da coluna: char, date, decimal, int ou logical.
pLabel	Input	Character	Define o título da coluna.
pFormat	Input	Character	Define o formato da coluna. Os formatos são os mesmos formatos suportados pelo Progress e caso o tipo do conteúdo seja char, não é preciso informar o formato.
pWidth	Input	Character	Define a largura da coluna.

Procedure piWorksheetColumn

PROCEDURE piWorksheetColumn: 

DEFINE INPUT PARAMETER pWorksheet AS INTEGER   NO-UNDO.

DEFINE INPUT PARAMETER pColumn    AS INTEGER   NO-UNDO.

DEFINE INPUT PARAMETER pDataType  AS CHARACTER NO-UNDO.

DEFINE INPUT PARAMETER pLabel     AS CHARACTER NO-UNDO.

DEFINE INPUT PARAMETER pFormat    AS CHARACTER NO-UNDO.

DEFINE INPUT PARAMETER pWidth     AS CHARACTER NO-UNDO.

Parâmetro	I/O	Tipo de Dado	Conteúdo
pWorksheet	Input	Integer	Número da aba da planilha onde pretende definir a coluna.
pColumn	Input	Integer	Define o número da coluna na planilha.
pDataType	Input	Character	Define o tipo do conteúdo da coluna: char, date, decimal, int ou logical.
pLabel	Input	Character	Define o título da coluna.
pFormat	Input	Character	Define o formato da coluna. Os formatos são os mesmos formatos suportados pelo Progress e caso o tipo do conteúdo seja char, não é preciso informar o formato.
pWidth	Input	Character	Define a largura da coluna.

Ver Exemplos

RUN piColumn IN h-handle (INPUT 9,

RUN piColumn IN h-handle (INPUT 9,
                          INPUT "DECIMAL",

RUN piColumn IN h-handle (INPUT 9,
                          INPUT "DECIMAL",
                          INPUT "Qtd Líquida",

RUN piColumn IN h-handle (INPUT 9,
                          INPUT "DECIMAL",
                          INPUT "Qtd Líquida",
					      INPUT ">>,>>>,>>>,>>9.9999",

RUN piColumn IN h-handle (INPUT 9,
                          INPUT "DECIMAL",
                          INPUT "Qtd Líquida",
					      INPUT ">>,>>>,>>>,>>9.9999",
						  INPUT 105).

Mais alguns exemplos:

RUN piWorksheetColumn IN h-handle(INPUT 2, INPUT 1, INPUT "CHAR", INPUT "Teste", INPUT "", INPUT 85).

RUN piColumn IN h-handle(INPUT 1, INPUT "CHAR", INPUT "Item", INPUT "", INPUT 85).

RUN piColumn IN h-handle(INPUT 2, INPUT "CHAR", INPUT "Est", INPUT "", INPUT 33).

RUN piColumn IN h-handle(INPUT 3, INPUT "CHAR", INPUT "Dep", INPUT "", INPUT 30).

RUN piColumn IN h-handle(INPUT 4, INPUT "CHAR", INPUT "Localização", INPUT "", INPUT 63).

RUN piColumn IN h-handle(INPUT 5, INPUT "CHAR", INPUT "Lote", INPUT "", INPUT 227).

RUN piColumn IN h-handle(INPUT 6, INPUT "CHAR", INPUT "Refer.", INPUT "", INPUT 60).

RUN piColumn IN h-handle(INPUT 7, INPUT "DATE", INPUT "Validade",INPUT "99/99/9999", INPUT 60).

RUN piColumn IN h-handle(INPUT 8, INPUT "CHAR", INPUT "Un", INPUT "", INPUT 18).

RUN piColumn IN h-handle(INPUT 9, INPUT "DEC", INPUT "Qtd Liquida", INPUT ">>,>>9.9999", INPUT 105).

RUN piColumn IN h-handle(INPUT 10, INPUT "DEC", INPUT "Qtd Aloca Fatur", INPUT ">>,>>9.9999", INPUT 105).

03 - Executar a procedure piNewWorkSheet

Esta procedure cria uma nova aba, ela não é necessária caso tenha apenas uma aba na sua planilha.

RUN piNewWorksheet IN h-handle (INPUT "Nome da aba", INPUT "Titulo").

04 - Executar a procedure piNewWorksheetByTT

Caso queira adicionar uma aba associada a uma temp-table pode ser utilizada esta, ela preenche a aba da planilha com o conteúdo da temp-table.

Parâmetros:

Parâmetro	Tipo
Nome da aba.	Character
Título da aba.	Character
Handle da temp-table utilizada.	Handle
Lista de campos que serão usados na planilha, esta lista também serve para ordenar os campos, caso informe “?” todos os campos serão utilizados.	Character
Ordenação, a lista será ordenada pelos campos informados, informe “?” para utilizar a ordenação da temp-table.	Character

RUN piNewWorksheetByTT IN h-handle (INPUT "Nome", 
                                    INPUT "Titulo",
                                    INPUT BUFFER temp_table:HANDLE, 
                                    "cod,nome,ende", 
                                    "nome,cod").

05 - Executar a procedure piNewLine:

Esta procedure não possui parâmetros de entrada ou saída e deve ser executada toda vez que for necessário criar uma nova linha na planilha.

FOR EACH saldo-estoq NO-LOCK:
		RUN piNewLine IN h-handle.
END.

06 - Executar procedure piLine

Esta procedure tem por finalidade atribuir um valor ao conteúdo de uma célula.

PROCEDURE piLine:

      DEFINE INPUT PARAMETER pColumn   AS INTEGER   NO-UNDO.

      DEFINE INPUT PARAMETER pCell     AS CHARACTER NO-UNDO.

Parâmetro	I/O	Tipo de Dado	Conteúdo
pColumn	Input	Integer	Número da coluna
pCell	Input	Character	Conteúdo da célula

FOR EACH saldo-estoq NO-LOCK:
                
    ASSIGN de-qtde-liquida = saldo-estoq.qtidade-atu -
                            (saldo-estoq.qt-alocada +
                             saldo-estoq.qt-aloc-prod +
                             saldo-estoq.qt-aloc-ped).

   RUN piNewLine IN h-handle.
   RUN piLine IN h-handle (INPUT 1,  INPUT saldo-estoq.it-codigo).     
   RUN piLine IN h-handle (INPUT 2,  INPUT saldo-estoq.cod-estabel).      
   RUN piLine IN h-handle (INPUT 3,  INPUT saldo-estoq.cod-depos).     
   RUN piLine IN h-handle (INPUT 4,  INPUT saldo-estoq.cod-localiz).    
   RUN piLine IN h-handle (INPUT 5,  INPUT saldo-estoq.lote).     
   RUN piLine IN h-handle (INPUT 6,  INPUT saldo-estoq.cod-refer).
   RUN piLine IN h-handle (INPUT 7,  INPUT saldo-estoq.dt-vali-lote).       
   RUN piLine IN h-handle (INPUT 8,  INPUT c-unidade).              
   RUN piLine IN h-handle (INPUT 9,  INPUT de-qtde-liquida). 
   RUN piLine IN h-handle (INPUT 10, INPUT saldo-estoq.qt-alocada).
                     
END.

07 - Executar procedure show

Define se a procedure piProcessa (executada posteriormente) deve mostrar (true) ou não (false) o arquivo após o processamento.

Seu valor inicial é true, o que significa que caso não marque show como false o arquivo será mostrado. Caso o ambiente de execução for RPW ou batch, o arquivo não será mostrado independente de configuração.

RUN show IN h-handle (false).

08 - Executar procedure ConvertToXls

Define se a procedure piProcessa (executada posteriormente) converte para XLS ou XLSX (true) ou não (false) o arquivo após o processamento.

Seu valor inicial é true, o que significa que caso não marque ConvertToXls como false o arquivo será convertido.

RUN ConvertToXls IN h-handle (false).

09 - Executar procedure pi-ShowDocument

Mostra o documento informado como parâmetro.

É executado automaticamente pela procedure piProcessa (executada posteriormente) quando show = true.

RUN pi-ShowDocument IN h-handle (“c:\tmp\arquivo.xml”).

10 - Executar procedure piConvertXMLToXLS

Converte o arquivo do formato XML para XLS.

É executado automaticamente pela procedure piProcessa quando ConvertToXls = true.

RUN piConvertXMLToXLS IN h-handle (INPUT “c:\tmp\arquivoOrigem.xml”, OUTPUT varArqDestino).

11 - Executar procedure piProcessa

Esta procedure tem como finalidade gerar um arquivo XML com as configurações necessárias para a criação de uma planilha Excel e possui a seguinte assinatura:

PROCEDURE piProcessa:
	DEFINE INPUT-OUTPUT PARAMETER pFile     AS CHARACTER NO-UNDO.
    DEFINE INPUT        PARAMETER pProgram  AS CHARACTER NO-UNDO.
    DEFINE INPUT        PARAMETER pTitle    AS CHARACTER NO-UNDO.

Parâmetro	I/O	Tipo de Dado	Conteúdo
pFile	Input/Output	Character	Define o nome completo do arquivo de destino e retorna o nome completo do arquivo xml gerado
pProgram	Input	Character	Define o nome do programa
pTitle	Input	Character	Define o título da planilha

Observação: pProgram e pTitle não tem efeito quando é usada mais de uma aba, esses valores são informados ao se utilizar as procedures piNewWorksheet e piNewWorksheetByTT.

ASSIGN c-arquivo = "c:\temp\ce0919.xls".
RUN piProcessa IN h-handle (INPUT-OUTPUT c-arquivo,
                            INPUT "CE0919",
                            INPUT "Saldo Físico dos Itens – 16/07/2012").

12 - Executar procedure getRowErrors

Retorna mensagens de erro no processamento e/ou conversão do arquivo.

RUN piProcessa IN h-handle (INPUT-OUTPUT c-arquivo,
                            INPUT "CE0919",
                            INPUT "Saldo Físico dos Itens – 16/07/2012").

IF RETURN-VALUE <> "OK" THEN DO:
	RUN getRowErrors IN h-handle (output table RowErrors).
	FOR EACH RowErrors:
		MESSAGE 
			RowErrors.ErrorNumber      SKIP
    		RowErrors.ErrorDescription 
    	VIEW-AS ALERT-BOX INFO BUTTONS OK.   
	END.
END.

13 - Excluir o handle ao finalizar a criação da planilha

DELETE PROCEDURE h-handle.

04. Exemplos

Os programas também podem ser usados para testes de performance alterando o número de abas, linhas e colunas para a geração da planilha.

Exemplo 01 - Sem temp-table

Ver exemplo 01

DEF VAR nTab AS INT NO-UNDO INIT 3.
DEF VAR nCol AS INT NO-UNDO INIT 5.
DEF VAR nLine AS INT NO-UNDO INIT 11.
DEF VAR cFile AS CHAR INIT "c:\tmp\ttt.xml".
   
DEF VAR hApi AS HANDLE NO-UNDO.
DEF VAR iTab AS INT NO-UNDO.
DEF VAR iCol AS INT NO-UNDO.
DEF VAR iLine AS INT NO-UNDO.

RUN utp/utapi033.p PERSISTENT SET hApi.

DO iTab = 1 TO nTab:        
    DO iCol = 1 TO nCol:
        IF iCol = 4 THEN
            RUN piWorksheetColumn IN hApi( INPUT iTab,
                                           INPUT iCol,
                                           INPUT "int",
                                           INPUT "c" + STRING(iCol),
                                           INPUT "",
                                           INPUT ?).
        ELSE IF iCol = 5  THEN
            RUN piWorksheetColumn IN hApi( INPUT iTab,
                                           INPUT iCol,
                                           INPUT "date",
                                           INPUT "c" + STRING(iCol),
                                           INPUT "dd/mm/yyyy",
                                           INPUT 0).
        ELSE
            RUN piWorksheetColumn IN hApi( INPUT iTab,
                                           INPUT iCol,
                                           INPUT "char",
                                           INPUT "c" + STRING(iCol),
                                           INPUT "",
                                           INPUT 60).    
    END.

    RUN piNewWorksheet IN hApi ( INPUT "Tab" + STRING(itab), 
                                 INPUT "title" + STRING(itab)).

    DO iLine = 1 TO nLine:
        RUN piNewLine IN hApi.    
        DO iCol = 1 TO nCol:
            IF iCol = 4 THEN
                RUN piLine IN hApi ( INPUT iCol, 
                                     INPUT STRING(iTab + iLine + iCol)).
            ELSE IF iCol = 5  THEN
                RUN piLine IN hApi ( INPUT iCol, 
                                     INPUT STRING(TODAY + iTab + iLine)).
            ELSE
                RUN piLine IN hApi ( INPUT iCol, 
                                     INPUT STRING(iTab) + "x" + STRING(iLine) + "x" + STRING(iCol)).            
        END.
    END.
END.

RUN ConvertToXls IN hApi (NO).

RUN show IN hApi (NO).

RUN piProcessa IN hApi (INPUT-OUTPUT cFile, 
                        INPUT "", 
                        INPUT "").

IF RETURN-VALUE <> "OK" THEN 
    MESSAGE RETURN-VALUE VIEW-AS ALERT-BOX INFORMATION BUTTONS OK.

DELETE PROCEDURE hApi.

Exemplo 02 - Com temp-table

Ver exemplo 02

DEF VAR nLine AS INT NO-UNDO INIT 1000.
DEF VAR cFile AS CHAR INIT "c:\tmp\ttt.xml".
DEF VAR hApi AS HANDLE NO-UNDO.
DEF VAR iL AS INT NO-UNDO.

DEFINE TEMP-TABLE teste SERIALIZE-NAME "Meu Teste"
    FIELD a AS CHAR FORMAT "X(40)" COLUMN-LABEL "Char"
    FIELD b AS DECI FORMAT ">>>>>>9.99"  COLUMN-LABEL "Deci"
    FIELD c AS DATE FORMAT "99/99/99" COLUMN-LABEL "Date"
    FIELD d AS INT EXTENT 3 FORMAT "999"
    FIELD e AS DECI FORMAT ">,>>>,>>9.99999"
    FIELD f AS LOGICAL  FORMAT "Sim/Não".
    
RUN utp/utapi033.p PERSISTENT SET hApi.

DO iL = 1 TO nLine:
    CREATE teste.
    ASSIGN 
        teste.a = FILL( CHR(64 + (il MOD 30)) , iL MOD 60 )        
        teste.b = (il MOD 100) / 3
        teste.c = TODAY + il
        teste.d[1] = il
        teste.d[2] = nLine - il
        teste.d[3] = RANDOM(0,99)
        teste.e = (il MOD 200) / 2
        teste.f = (il MOD 3) = 0.

END.

RUN piWorksheetColumn IN hApi(INPUT 1,
                              INPUT 1,
                              INPUT "char",
                              INPUT "Minha coluna custom",
                              INPUT "",
                              INPUT 250).

RUN piNewWorksheetbyTT IN hApi (INPUT "tst1", INPUT "tit1",
                                INPUT BUFFER teste:HANDLE, 
                                ?, 
                                ?). 

RUN piNewWorksheetbyTT IN hApi (INPUT "tst2", INPUT "tit2",
                                INPUT BUFFER teste:HANDLE, 
                                "b,a", 
                                "a"). 

//customização de coluna 
RUN piWorksheetColumn IN hApi(INPUT 3, //terceira planilha
                              INPUT 5, //quarta coluna
                              INPUT "int",
                              INPUT "Minha coluna custom",
                              INPUT ">>>9",
                              INPUT 250).

RUN piNewWorksheetbyTT IN hApi (INPUT "tst3", INPUT "tit3",
                                INPUT BUFFER teste:HANDLE, 
                                "b,f,a,d[1],d[2]", 
                                "b Descending"). 

RUN ConvertToXls IN hApi (NO).

RUN show IN hApi (NO).

RUN piProcessa IN hApi (INPUT-OUTPUT cFile, 
                        INPUT "", 
                        INPUT "").

IF RETURN-VALUE <> "OK" THEN 
    MESSAGE RETURN-VALUE VIEW-AS ALERT-BOX INFORMATION BUTTONS OK.

DELETE PROCEDURE hApi.

05. Mais opções

01 - Como mostrar os parâmetros utilizados na geração dos dados mostrados na planilha

Expandir

Declarar a definição da tabela temporária tt-param contida na include {utp/utapi033.i};
Criar os registros na tabela temporária tt-param conforme o exemplo abaixo:

CREATE TEMP-TABLE tt-param.
ASSIGN tt-param.descricao = “descrição do parâmetro”
       tt-param.valor     = “valor do parâmetro”.

Passar a tabela temporária com os parâmetros para a API conforme o exemplo abaixo:

RUN setTTParam IN h-api (INPUT TABLE tt-param).

(Opcional) Os parâmetros serão mostrados em uma nova aba (worksheet) sendo dispostos em duas colunas com largura padrão iguais a 100. A primeira coluna mostrará a descrição do parâmetro e a segunda coluna mostrará o valor do parâmetro. Para alterar a largura da primeira e/ou da segunda coluna, proceda conforme o exemplo abaixo:

DEFINE VARIABLE iParamColumnWidth AS INTEGER EXTENT 2 NO-UNDO.

ASSIGN iParamColumnWidth[1] = 150
       iParamColumnWidth[2] = 200.

RUN setParamColumnWidth IN h-api (INPUT iParamColumnWidth).

02 - Como mostrar os valores digitados utilizados na geração dos dados mostrados na planilha

Expandir

Declarar a definição da tabela temporária tt-digita contida na include {utp/utapi033.i};
Criar os registros na tabela temporária tt-digita conforme o exemplo abaixo:

CREATE TEMP-TABLE tt-digita.
ASSIGN tt-digita.descricao = “descrição do valor digitado”
       tt-digita.valor     = “valor digitado”.

Passar a tabela temporária com os valores digitados para a APIconforme o exemplo abaixo:

RUN setTTDigita IN h-api (INPUT TABLE tt-digita).

(Opcional) Os valores digitados serão mostrados em uma nova aba (worksheet) sendo dispostos em duas colunas com largura padrão iguais a 100. A primeira coluna mostrará a descrição do valor digitado e a segunda coluna mostrará o valor digitado. Para alterar a largura da primeira e/ou da segunda coluna, proceda conforme o exemplo abaixo:

DEFINE VARIABLE iDigitColumnWidth AS INTEGER EXTENT 2 NO-UNDO.

ASSIGN iDigitColumnWidth[1] = 150
       iDigitColumnWidth[2] = 200.

RUN setDigitColumnWidth IN h-api (INPUT iDigitColumnWidth).

03 - Técnica de exportação de dados

Expandir

Incluída na release 12.1.23, esta técnica visa facilitar as simulações dos problemas sem a necessidade de efetuar parametrizações de negócio (ou dados de negócio).

Para gerar os dados necessários para a simulação é preciso que a API tenha a técnica implementada e esteja com o extrato de versão ativo.

Seguindo isto, serão gerados no diretório temporário da sessão, alguns arquivos com extensão .json e nomeados de acordo com as temp-tables recebidas como parâmetro para gerar o relatório.

Estando com estes arquivos gerados (ex..: “tt-temp-table.json”), para simular o problema, basta efetuar a execução da API lendo estes registros e os passando como parâmetro.

04 - Técnica de importação de dados

Expandir

Simulação com os arquivos .json oriundos da técnica acima, abaixo um exemplo de código para a utapi033 efetuando um input desses registros:

DEFINE VARIABLE h-handle AS HANDLE NO-UNDO.
DEFINE VARIABLE c-arquivo AS CHARACTER   NO-UNDO.
DEFINE VARIABLE varArqDestino AS CHARACTER   NO-UNDO.
DEFINE VARIABLE iColumn AS INTEGER     NO-UNDO.

{utp/utapi033.i}

RUN utp/utapi033.p PERSISTENT SET h-handle.

TEMP-TABLE tt-column:READ-JSON("file", "C:\tmp\tt-column.json", "empty").
TEMP-TABLE tt-line:READ-JSON("file", "C:\tmp\tt-line.json", "empty").
//TEMP-TABLE tt-param:READ-JSON("file", "C:\tmp\tt-param.json", "empty").
//TEMP-TABLE tt-digita:READ-JSON("file", "C:\tmp\tt-digita.json", "empty").


FOR EACH tt-column NO-LOCK:
    IF icolumn < tt-column.iColumn  THEN DO:
RUN piColumn IN h-handle (INPUT tt-column.iColumn,
                          INPUT tt-column.cDataType,
                          INPUT tt-column.cLabel,
                          INPUT tt-column.cFormat,
                          INPUT tt-column.cWidth).
END.
ELSE
    LEAVE.

ASSIGN iColumn = iColumn + 1.
END.


FOR EACH tt-line NO-LOCK:
IF tt-line.lNewLine = TRUE THEN
RUN piNewLine IN h-handle.
ELSE
RUN piLine IN h-handle (INPUT tt-line.iColumn,
       INPUT tt-line.cCell).
END.

RUN show IN h-handle (TRUE).

ASSIGN c-arquivo = "c:\tmp\ArqSimulaçãoUtapi033.xml".

RUN piProcessa IN h-handle (INPUT-OUTPUT c-arquivo,
  INPUT "Simulação",
                   INPUT "Input dados Utapi033").

DELETE PROCEDURE h-handle.

05 - Importação com arquivo XML

Expandir

{utp/utapi033.i}

DEFINE VARIABLE cArquivo   AS CHARACTER.
DEFINE VARIABLE h-utapi033 AS HANDLE NO-UNDO.

IF NOT VALID-HANDLE(h-utapi033) THEN
       RUN utp/utapi033.p PERSISTENT SET h-utapi033.


RUN piConvertXMLToXLS IN h-utapi033 (INPUT "C:\Users\"usuario"\Desktop\DFWKAPI-3195\AMA_GG416453626.xml",
                            OUTPUT cArquivo).
MESSAGE cArquivo
  VIEW-AS ALERT-BOX INFO BUTTONS OK.


IF VALID-HANDLE(h-utapi033) THEN
	DELETE OBJECT h-utapi033.

Árvore de páginas

utapi033 - API de Geração de Planilha Eletrônica

CONTEÚDO

01. Objetivos

02. Considerações gerais

03. Como utilizar

04. Exemplos

05. Mais opções

01 - Como mostrar os parâmetros utilizados na geração dos dados mostrados na planilha

02 - Como mostrar os valores digitados utilizados na geração dos dados mostrados na planilha

03 - Técnica de exportação de dados

04 - Técnica de importação de dados

05 - Importação com arquivo XML