API de Integração entre Progress e Microsoft Word (001)

Nome Físico: utp/utapi002.p

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

Versão de Integração: 002

Objetivo: 

Criação de arquivos, baseados em formulários, para o Microsoft Word.

Pré-requisitos: 

É necessário ter o MS-WORD com uma versão compatível com o produto. Para mais detalhes consulte a documentação localizada em: https://tdn.totvs.com/pages/releaseview.action?pageId=195301010


IMPORTANTE:

Para novos programas que venham a utilizar esta API, é recomendado que seja utilizado o programa utp/utapi012 ao invés deste.


Considerações Gerais

  • A API recebe como parâmetros valores, que serão utilizados para o preenchimento de campos de formulário existentes no documento. Caso não seja possível criar o arquivo, será retornado uma Temp-Table com os, possíveis, erros;
  • A include {utp/utapi002.i} contém as definições das Temp-Table´s que devem ser passadas como parâmetros à API utp/utapi002.p. Sendo que a chamada desta include, como a inclusão de valores, deve ser feita antes da chamada da API utp/utapi002.p;
  • A criação do arquivo é feita através da execução da API utp/utapi002.p.


Parâmetros de Entrada 


Temp-table tt-configuracao: possui as definições, gerais, do arquivo a ser criado.

TEMP-TABLE tt-configuracao

Atributo

Tipo

Formato

Valor Inicial

versao-integracao

integer

>>9


arquivo

character

x(255)

c:\tmp\utapi002.doc

modelo

character

x(255)


senha-modelo

character



exibir-construcao

logical


No

abrir-word-termino

logical


No





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

Atributo

Descrição

versao-integracao

Versão de Integração da API

arquivo

Nome do arquivo a ser criado

modelo

Nome do modelo a ser utilizado para criação do arquivo

senha-modelo

Senha para desproteger o modelo a ser utilizado

exibir-construcao

Exibir construção do arquivo durante o processo

abrir-word-termino

Abrir Microsoft Word após término do processo




Temp-Table tt-dados: possui as definições, gerais, sobre cada um dos campos a serem preenchidos no documento.

TEMP-TABLE tt-dados

Atributo

Tipo

Formato

Valor Inicial

campo-nome

character



campo-tipo

integer

9


campo-valor

character



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

* ver Referência sobre Tipo Campo

Atributo

Descrição

campo-nome

Nome do campo de formulário

campo-tipo

Tipo do campo

campo-valor

Valor a ser inserido no campo




Execução

O programa utp/utapi002.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 através da verificação da versão de integração passada como parâmetro. Caso a versão esteja incompatível, a API abortará 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 através da verificação dos dados passados como parâmetros. Caso os dados sejam inconsistentes ou insuficientes, a API abortará a execução retornando o código de erro 8646.


Cabe ao programa de origem, verificar os registros que estão com erro.

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




Parâmetros de Saída

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


NOK: 

Criação do arquivo sem sucesso pois os dados passados como parâmetros, através das Temp-Tables, são inconsistentes ou foram insuficientes;

OK: 

Criação do arquivo com sucesso.





Outras Informações

Abaixo encontram-se as principais validações a serem executadas em cada uma das Temp-Table´s de entrada utilizadas pela API utp/utapi002.p.


Principais Validações da Temp-Table tt-configuracao :

  • Existência de dados na Temp-Table tt-configuracao;
  • Inexistência do arquivo a ser criado, sendo passado como parâmetro através do campo tt-configuracao.arquivo;
  • Existência do modelo a ser utilizado, sendo passado como parâmetro através do campo tt-configuracao.modelo;
  • Integridade dos dados.


Principais Validações da Temp-Table tt-dados :

  • Existência de dados na Temp-Table tt-dados;
  • Compatibilidade entre os valores dos campos e seus respectivos tipos de campos;
  • Integridade dos dados.


A seguir se encontram referências sobre os valores que alguns campos podem assumir:


Referência Tipo Campo

01 -  Check-Box

02 -  Drop-Down

03 -  Text-Input

Exemplo

Abaixo programa exemplo de utilização da API.

Instruções:

  • Crie um formulário no Word com três campos texto, os campos precisam ter os nomes (nome, endereço, telefone) e grave como um modelo do Word no diretório c:\tmp com o nome de  a.dot.
  • Execute o programa abaixo:


{utp/utapi002.i}     
os-delete value("c:\tmp\a.doc").

create tt-configuracao.  
assign tt-configuracao.versao-integracao = 2
       tt-configuracao.arquivo = "c:\tmp\a.doc"
       tt-configuracao.modelo  = "c:\tmp\a.dot"
       tt-configuracao.senha-modelo = ""
       tt-configuracao.exibir-construcao = yes
       tt-configuracao.abrir-word-termino = yes.

create tt-dados.
assign tt-dados.campo-nome = "Nome"
       tt-dados.campo-tipo = 3
       tt-dados.campo-valor = "Datasul - Tecnologia".        

create tt-dados.
assign tt-dados.campo-nome = "Endereco"
       tt-dados.campo-tipo = 3
       tt-dados.campo-valor = "Santos Dummond, 831".       

create tt-dados.
assign tt-dados.campo-nome = "telefone"
       tt-dados.campo-tipo = 3
       tt-dados.campo-valor = "(47) 441-7000". 

run utp/utapi002.p
                 (input-output table tt-configuracao,
                  input-output table tt-dados,
                  input-output table tt-erros).

if return-value = "nok" then do:
    for each tt-erros:
        disp tt-erros with 1 col width 500.
    end.
end.