TED - CPM PROGRAMA DE CONTROLE PARA MICROTERMINAIS TED COLLETER

Transcrição

1 TED - CPM PROGRAMA DE CONTROLE PARA MICROTERMINAIS TED COLLETER xcpml Guia do Programador Versão.0 Outubro/0

2 Introdução Representado por um arquivo XML devidamente validado, um script de programação CPM cuida de toda a lógica operacional de coleta de dados do seu projeto de automação. Para livrá-lo de detalhes técnicos entediantes, definidos uma camada de abstração que lhe garante um ambiente de trabalho simples, ágil e muito confortável. Você poderá usar qualquer editor de texto sem formatação (notepad, gedit, etc) para programar seus scripts e, dentro em breve, também contará com um ambiente integrado de desenvolvimento (IDE) intuitivo e cheio de recursos. O CPM roda em qualquer sistema operacional que suporte uma Java Virtual Machine (JVM), isso inclui os principais sistemas operacionais: Windows, Linux, OS X e Solaris. Por ser desenvolvido em Java, necessita que o HOST que o executa, tenha uma versão do Java devidamente instalado e configurado, para tanto, caso não tenha muita experiência com esta linguagem, é um bom lugar para começar. Importante! Em alguns exemplos de código, você notará a presença do sinal de reticências (), esses sinais devem ser desconsiderados quando na digitação dos seus scripts, pois apenas indicam a presença de outros comandos que, no contexto do aprendizado, são completamente irrelevantes. As TAGs XML Definimos um conjunto de TAGs XML específicas para servirem de comandos para a programação dos scripts e, mesmo não sendo muitas, decidimos separá-las em dois grupos básicos: TAGs de projeto e TAGs de programação. As TAGs de programação são todas aquelas que devem aparecer contidas em um bloco <program>, as demais são consideradas, então, TAGs de projeto. Caso você não esteja familiarizado com a XML é bom lembrar que todas as TAGs devem ser digitadas em letras minúsculas. Novas TAGs surgirão e as atuais, poderão, com o tempo, serem alteradas ou removidas, mas, não se preocupe, o CPM sempre saberá executar seus scripts antigos sem que você tenha que alterá-los. Entidades XML pré-definidas Você deve ter notado que a XML define alguns caracteres especiais, portanto, para que não ocorram problemas no processo de análise do seu script, evite utilizá-los para outras finalidades que não as reservadas pela própria linguagem. A tabela abaixo poderá auxiliá-lo quando na necessidade de utilizar um desses caracteres: Ao necessitar de Utilize O Projeto Para representar < < Menor que > > Maior que & & E comercial ' &apos; Apóstrofe " Aspas A TAG <project> é container para todas as demais TAGs presentes em um script xcpml, possuindo como filhas diretas as seguintes TAGs de projeto:. fonte de dados (<datasource></datasource>). programas (<program>). terminais (<terminal></terminal>)

3 E das seguintes associações entre TAGs de projeto:. Programas com fontes de dados, e;. Terminais com programas; Note o fragmento de script xcpml abaixo: <?xml version=".0" encoding="utf-"?> <project name="prj"> <datasource name="dso" type="http"> <host> <error key="erro" retype="session" /> </datasource> <datasource name="dso" type="sapiens"> <host> <error retype="session" /> </datasource> <program name=prg" datasource="dso"> <session name="ses" hotkey="k_f"> <!-- TAGs de Programação --> <session name="ses" hotkey="k_f"> <!-- TAGs de Programação --> <program name="prg" datasource="dso" > <session name="ses" hotkey="k_f"> <!-- TAGs de Programação --> <session name="ses" hotkey="k_f"> <!-- TAGs de Programação --> <terminal name="trm" program="prg" ip="...00" /> <terminal name="trm" program="prg" ip="...0" />

4 Importante! Assim como as TAGs de programação devem estar contidas em um bloco <session>, as TAGs de projeto devem estar contidas em um bloco <project>. Executando seus scripts Para executar seus scripts, em uma janela de terminal (ou prompt de comandos, caso esteja utilizando o Windows), você deve digitar o seguinte comando: $ java -jar cpm-*.jar <script_do_projeto>.xml O asterisco(*) refere-se a versão do CPM sendo utilizada e, <script_do_projeto>, o nome que você atribuiu ao seu arquivo de projeto em disco. TAGs XML de projeto A seguir você encontra a lista válida de TAGs XML de projeto, acompanhadas de informações que apoiam seu uso. <project> Esta TAG declara o início de um sessão de projeto, sendo portanto, container de todas as outras. REQUERIDA:. OCORRÊNCIA: Uma por arquivo. FILHA DE: Ninguém (TAG ancestral de todas as outras). ATRIBUTO(S) SIGNIFICADO name Nome do projeto version Versão da linguagem (esquema) de definição do projeto. Valor(es) permitido(s) até o momento:.0 CONTEÚDO: Todas as demais TAGs.

5 <?xml version=".0" encoding="utf-"?> Importante! Todo script de programação, deve iniciar com a declaração XML exibida na linha. <datasource> Esta TAG define uma fonte de dados externa (servidor de dados). Esta fonte de dados será utilizada tanto para o envio de dados coletados, como também na validação de uma entrada (digitação). REQUERIDA:. FILHA DE: <project> ATRIBUTOS(S) SIGNIFICADO CONTEÚDO: name Nome da fonte de dados. type Tipo da fonte de dados. Valor(es) permitido(s) até o momento: http; <host> <?xml version=".0" encoding="utf-"?> <project name= TAG datasource > <datasource name="servidora" type="http"> </datasource>

6 <host> Esta TAG define o host utilizado na configuração de uma fonte de dados externa. REQUERIDA. OCORRÊNCIA Várias por arquivo. FILHA DE: <datasource> ATRIBUTO(S) SIGNIFICADO port Número da porta HTTP de conexão. username Nome do usuário para autenticação. password Senha do usuário para autenticação. params Define o formato dos parâmetros passados na URL de conexão. Valores permitidos: query (parâmetros passados no formato query params. :?par=var&par=var) rest (parâmetros passados em formato semântico. : /par/var/par/var) Quando esse parâmetro for omitido rest será assumido. CONTEÚDO: Identificação do host na rede, podendo ser o IP, nome do domínio e nome NetBIOS. <?xml version=".0" encoding="utf-"?> <datasource name="server" type="http"> <host port= 00 > </datasource>

7 <error> Esta TAG define uma condição de erro na digitação dos dados, disparando ação subsequente de redigitação. Lembrando que a ação será disparada quando no retorno (resposta) de uma requisição HTTP. REQUERIDA OCORRÊNCIA Várias por arquivo. FILHA DE: <datasource> ATRIBUTO(S) SIGNIFICADO key Define a chave JSON que representa uma condição de erro associada à resposta HTTP. Quando omitido, error será assumido. retype Define o ponto de retorno para a redigitação dos dados: Valores permitidos: last (para o último say..store); session (para o início da sessão corrente), ou; none (para a instrução/comando seguinte) Quando omitido last será assumido. CONTEÚDO: Nenhum. <terminal> Esta TAG define um terminal coletor de dados. REQUERIDA: FILHA DE: <project> ATRIBUTO(S) SIGNIFICADO name Nome de identificação do terminal ip IP único que identifica o terminal na rede program Programa associado ao terminal model Indica o modelo do equipamento controlado. Valor(es) permitido(s) até o momento: COLLETER_TC00 CONTEÚDO: TAG vazia

8 <?xml version=".0" encoding="utf-"?> <terminal ip="...00" name="term" program="prog" model="colleter_tc00" /> <program> Esta TAG define um programa, ou seja, um bloco contendo TAGs para a programação dos coletores de dados. REQUERIDA: FILHA DE: <project> ATRIBUTO(S) SIGNIFICADO name Nome único de identificação do programa. datasource Fonte de dados associado ao programa. session Define o nome da sessão de inicialização quando na execução do projeto. Se ausente, a primeira sessão definida, será a sessão executada. CONTEÚDO: Uma ou mais TAGs <session> <?xml version=".0" encoding="utf-"?> <program name="program" datasource="server" session="menu">

9 <session> Esta TAG define uma sessão de programa. No CPM um programa é composto por várias sessões. REQUERIDA: (Ao menos uma) FILHA DE: <program> ATRIBUTO(S) SIGNIFICADO name Nome único de identificação da sessão hotkey Tecla de função associada à execução da sessão. Valor(es) permitido(s) até o momento: K_F, K_F, K_F, K_F, K_F, K_F, K_F, K_F, K_F, K_F0, K_F e K_F CONTEÚDO: Uma ou mais TAGs de programação. REQUERIDA 0 <?xml version=".0" encoding="utf-"?> <program name= my program > <session name= main hotkey="k_f"> Importante! A execução de uma sessão de programação é cíclica, isso significa que, ao término da última instrução, o fluxo de execução retornará novamente ao início da sessão. Toda sessão deve ter, no mínimo, uma condição de solicitação de entrada de dados. Isso significa a presença de, ao menos, uma TAG <say> com o atributo store.

10 TAGs XML de programação A seguir você encontrará as TAGs XML específicas de programação. Note que todas são filhas da TAG <session> e, portanto, devem estar contidas nesta. <say> Esta TAG é a responsável pelo envio e captura de dados do equipamento controlado. REQUERIDA: FILHA DE: <session> ATRIBUTO(S) SIGNIFICADO beep Valor numérico que indica a quantidade de sinais sonoros que acompanha a informação enviada ao equipamento. wait Valor numérico que indica quantos segundos de espera será aguardado após envio da informação ao equipamento. get Recupera informação do DataList (vide sessão específica), processando-a e exibindo-a, concomitantemente, no display do equipamento. Este atributo suporta cálculos aritméticos básicos (somas, subtrações, multiplicações e divisões). store Aguarda informação do equipamento (digitação ou leitura), armazenando-a na variável definida por esse atributo. CONTEÚDO: Dado a ser exibido no display do equipamento. 0 <?xml version=".0" encoding="utf-"?> <program name= my program > <session name= sessao hotkey="k_f"> <say beep= store= ficha >Digite:</say> <say wait= get= ficha >Digitado:</say> <session name= sessao hotkey="k_f"> <say store= a >A:</say> <say store= b >B:</say> <say get= a+b >A+B:</say>

11 <store> Esta TAG é a responsável pelo armazenamento direto (sem prévio processamento) de valores no DataList. REQUERIDA: FILHA DE: <session> ATRIBUTOS(S) SIGNIFICADO name Nome da variável cujo valor será armazenado no DataList. CONTEÚDO: Dado a ser armazenado no DataList. <?xml version=".0" encoding="utf-"?> <program name= my program > <session name= main hotkey="k_f"> <store name="a"></store> <store name="b"></store>

12 <repeat> Esta TAG define o início de um bloco de TAGs cuja execução deve repetir. REQUERIDA: FILHA DE: <session> CONTEÚDO: TAGs componentes do laço de repetição. 0 <?xml version=".0" encoding="utf-"?> <program name= my program > <session name= main hotkey="k_f"> <repeat> <say store="a">a:</say> <if break="true">a eq 0</if> </repeat> As linhas de a 0 delimitam a região de repetição e, na linha, o atributo break="true" da TAG <if> define a expressão lógica cuja condição controla a saída do laço de repetição.

13 <clear> Esta TAG limpa o display do equipamento controlado. REQUERIDA: FILHA DE: <session> CONTEÚDO: TAG sem conteúdo. 0 <?xml version=".0" encoding="utf-"?> <program name= my program > <session name= calc hotkey="k_f"> <say store="a">a:</say> <say store="b">b:</say> <calc store="c">a+b</calc> <say wait="" get="c">a+b:</say> <clear /> Importante! Essa instrução é invocada no inicio da execução de cada sessão do programa.

14 <calc> Esta TAG armazena no DataList o resultado obtido após a execução de cálculos aritméticos básicos (somas, subtrações, multiplicações e divisões). REQUERIDA: FILHA DE: <session> ATRIBUTOS(S) SIGNIFICADO store Nome da variável que será atribuído o resultado. CONTEÚDO: Uma expressão aritmética válida. 0 <?xml version=".0" encoding="utf-"?> <program name= my program > <session name= calc hotkey="k_f"> <say store="a">a:</say> <say store="b">b:</say> <calc store="c">a+b</calc> <say get="c">a+b:</say> <jump> Esta TAG permite o desvio condicional no fluxo normal de execução do script para um ponto específico de entrada de dados. Este ponto (rótulo) é representado pelo valor do atributo store de uma TAG <say>. REQUERIDA: FILHA DE: <session> ATRIBUTOS(S) SIGNIFICADO to Nome de uma variável definida no atributo store de uma TAG <say> say Mensagem a ser exibida no display do equipamento. CONTEÚDO: Uma expressão lógica válida. O desvio ocorrerá se a expressão for avaliada como verdadeira.

15 0 <?xml version=".0" encoding="utf-"?> <program name= my program > <session name= jump hotkey="k_f"> <say store="a">a:</say> <say store="b">b:</say> <say store="c">c:</say> <say store="d">d:</say> <get ns="db" url= /web/service/ /> <jump to="a" say="a < 0">db.ret eq </jump> <jump to="b" say="b < 0">db.ret eq </jump> <jump to="c" say="c < 0">db.ret eq </jump> <jump to="d">db.ret eq </jump> Importante! Esta TAG é uma alternativa para a estratégia padrão de validação dos dados a cada entrada (digitação), permitindo ao programador, solicitar nova entrada de acordo com os dados retornados do servidor. Note que esta TAG também reduz o número de chamadas ao servidor <if> Esta TAG representa uma instrução de desvio no fluxo normal de execução do script de programação. REQUERIDA: FILHA DE: <session> ATRIBUTOS(S) SIGNIFICADO session Nome da sessão a ser executada, caso a expressão seja avaliada como verdadeira. break Abandona a laço <repeat> atual caso a expressão seja avaliada como verdadeira. error Mensagem de erro a ser exibida, caso a expressão seja avaliada como falsa. CONTEÚDO: Uma expressão lógica válida.

16 0 0 <?xml version=".0" encoding="utf-"?> <program name= my program > <session name= menu hotkey="k_f"> <say>-incluir -EXCLUIR</say> <say store="opcao">opcao:</say> <if session="incluir">opcao eq </if> <if session="excluir">opcao eq </if> <say wait="">opcao invalida!</say> <session name= incluir hotkey="k_f"> <say>f-menu F-EXCLUIR</say> <say store="opcao">opcao:</say> <session name= excluir hotkey="k_f"> <say>f-menu F-INCLUIR</say> <say store="opcao">opcao:</say> <get> Esta TAG é responsável pela recuperação de dados de uma fonte de dados externa (datasource), normalmente objetivando validação de uma entrada. Para maiores esclarecimentos, consulte a sessão Fonte de dados. REQUERIDA: FILHA DE: <session> ATRIBUTOS(S) SIGNIFICADO ns Namespace(prefixo) atribuído aos dados válidos recebidos do servidor. Útil para evitar conflito de nomes. url URL da fonte de dados no servidor. CONTEÚDO: TAG vazia.

17 0 <?xml version=".0" encoding="utf-"?> <program name= my program > <datasource name="server" type="http"> <host> </datasource> <session name= main hotkey="k_f"> <say store="vendedor">vendedor:</say> <if error="invalido!">vendedor gt 0</if> <get ns="db" url="/web/service/" /> <say get="db.nome">nome:</say> <put> Esta TAG é responsável pelo envio de dados a uma fonte de dados (datasource), objetivando a gravação efetiva dos mesmos. Para maiores esclarecimentos, consulte a sessão Fonte de dados. 0?xml version=".0" encoding="utf-"?> <program name= my program > <datasource name="server" type="http"> <host> </datasource> <session name="main" hotkey="k_f">... <put url="/web/service/" />...

18 O DataList O CPM define o DataList como uma área para armazenar as variáveis do script de programação. Os valores presentes no DataList são eliminados a cada início de sessão e atualizados nas seguintes situações: Através da TAG <say> via atributo store; Através da TAG <calc> via atributo store; Através da TAG <store>, e; Ao receber dados válidos através da TAG <get>. Importante! Numa requisição HTTP, todos os valores presentes no DataList são formatados e enviados ao servidor de dados (datasource) quando na execução das TAGs <get> e <put>. O DataList armazena seus dados em fila, portanto, o primeiro que entra é o primeiro que sai quando na montagem de uma requisição HTTP. Observe o trecho de programa abaixo: 0?xml version=".0" encoding="utf-"?> <program name= my program > <datasource name="server" type="http"> <host> </datasource> <session name= main hotkey="k_f"> <store name= n >0</store> <get url="/service/cep" ns= cep />... O exemplo de código acima, produzirá, automaticamente, a seguinte requisição HTTP quando na execução da TAG <get> presente na linha. Note que, service=cep (linha ), foi introduzido no DataList antes de n=0 (linha ), portanto - graças à organização em fila do DataList - sairá também antes, quando na formação da requisição.

19 Fonte de dados O diagrama abaixo define o protocolo utilizado pelo CPM quando na comunicação com um servidor WEB (HTTP/HTTPS). Neste formato, a comunicação se dá através da formatação e envio dos dados presentes no DataList. Em resposta, uma String JSON será recebida, avaliada e, caso uma condição de erro não seja encontrada, os dados recebidos serão prefixados e inseridos no DataList, ficando assim, disponíveis para uso como se digitado pelo operador eles fossem. O diagrama a seguir, esclarece o fluxo lógico PADRÃO para tratamento da mesma requisição, só que desta vez, do lado do servidor WEB.

20 Expressões aritméticas e lógicas O CPM suporta os seguintes operadores: Aritméticos SÍMBOLO SIGNIFICADO + Soma - Subtração * Multiplicação / Divisão Importante! Os parênteses são aceitos em expressões aritméticas para efeito de mudança na prioridade de avaliação dos operadores. Lógicos SÍMBOLO SIGNIFICADO ne eq lt gt le ge Diferente (not equal) Igual (equal) Menor que (less than) Maior que (great than) Menor ou igual (less or equal) Maior ou igual (great or equal)

21 Integração Senior ERP O CPM fornece integração com o sistema de gestão empresarial da Senior, uma das maiores empresas de desenvolvimento de sistemas de gestão do Brasil. Maiores informações você obtém em A seguir você encontra um script que demonstra os pontos que apoiam essa integração: 0 <?xml version=".0" encoding="utf-"?> <project name="integracao-sapiens"> <datasource name="datasource-sapiens" type="http"> <host params="query"> HA&NOMUSU=suporte&SENUSU=suporte& </host> <error key="erro" retype="last" /> </datasource> <program name="programa-exemplo datasource="datasource-sapiens"> <session name="session_responder" hotkey="k_f"> <say beep="" store="val">valor:</say> <get ns="ds" url="proxacao=sid.srv.regra&numreg=" /> <say wait="" get="ds.retorno" /> <terminal ip="..." name="terminal" program="test-program" model="colleter_tc00" /> As linhas de a são as únicas que apresentam particulares relevantes para a integração com o Sapiens ERP. Na linha definimos uma fonte de dados (datasource) de nome datasource-sapiens e tipo http. Na linha a definição desta fonte de dados é finalizada. Na linha definimos as particularidades do servidor (host) que iremos enviar e receber dados. Um host Senior necessita que os parâmetros da requisição HTTP sejam formatados ao estilo query string, para tanto, configuramos o atributo params da tag host com o valor query. Ainda na linha (estendendo-se pelas linhas e ) note a string de conexão ao host Senior: amp;nomusu=suporte&senusu=suporte& Para evitar erros em nosso arquivo XML alguns caracteres não podem ser livremente utilizados e, o & é um destes caracteres. Mas, como fazer se a string de conexão Senior utiliza o & como separador de parâmetros? Para resolver esta limitação, devemos representar esses caracteres através de suas entidades XML associadas. Para o caracter & & é sua entidade associada. Para outras entidades consulte a sessão

22 Entidades XML pré-definidas. Na linha, atributo url e tag get, você também pode notar a presença da entidade XML &. Conforme você deve saber a contra parte de uma requisição HTTP é uma resposta HTTP. Até agora, tudo que vimos, foi apenas para dar subsidios ao CPM para formatar, corretamente, uma requisição para o host de destino com o intuito de enviar os dados coletados. Muito bem, mas o CPM tenta também - quando no recebimento da resposta HTTP - identificar uma condição de erro lógico, para esclarecer o que vêm a ser um erro lógico, responda a seguinte questão: Os dados coletados e enviados ao servidor (que presumimos executou sua lógica interna de validação) podem ser considerados como um lote de entrada válido? Para responder a essa questão o CPM analisa os dados retornados em busca de uma chave que, por convenção, representa uma condição de erro na coleta realizada e, portanto, o ciclo de coleta atual deve ser refeita. Com base no que foi dito nos últimos parágrafos, a linha do script XML de exemplo pode ser traduzida pela seguinte frase: Uma condição de erro (tag erro) deve ser considerada quando, ao analisar os dados retornados do servidor, a chave erro (key = erro ) seja encontrada. Nesta caso, a última entrada de dados (retype= last ) deve ser novamente solicitada Lembrando que a linha representa a última entrada de dados realizada antes da solicitação ser disparada para o servidor pela instrução presente na linha. Usamos algumas vezes o termo lote de dados e, por achar que o termo merece esclarecimentos, vamos a ele: Para o CPM um lote de dados é todo o conjunto de dados obtidos através do atributo store de uma tag say, dentro da sessão (tag session) de programa (tag program) atualmente sendo executado. Note na linha que val e seu respectivo valor digitado, pertencerá ao lote de dados atual logo após o operador do coletor confirmar a entrada, normalmente, através do pressionamento da tecla ENTER. Integração Colleter Automação Fabricante de terminais e coletores de dados há anos, a Colleter possui mais de 000 unidades instaladas no Comércio e na Indústria, muitas delas em operação por mais de 0 anos. O CPM fornece integração especifica com os Microterminais Colleter ( modelos TC/TW-00. Através de driver Java especialmente desenvolvido o TED-CPM amplia o alcance operacional desses equipamentos para qualquer servidor (host) que possua uma implementação da JVM disponível. Isso inclui todos os sistemas operacionais modernos tais como o Windows, Linux, Solaris, OS X e até mesmo o Android. Projeto Calculadora Abaixo você encontrará um exemplo completo de script TED-CPM de projeto. Esse script faz uso das principais TAGs XML de projeto e programação para desenvolver uma calculadora simples de operações para duas entradas de dados: a e b.

23 <?xml version=".0" encoding="utf-"?> <project name="calculadora"> <program name="calculadora"> <session name="menu" hotkey="k_f"> <say store="opcao">(+)(-)(*)(/)opcao:</say> <if session="soma">opcao eq </if> <if session="subtracao">opcao eq </if> <if session="multiplicacao">opcao eq </if> <if session="divisao">opcao eq </if> <say wait="">opcao invalida!</say> <session name="soma"> <say>som(f-menu)</say> <say store="a">a:</say> <say store="b">b:</say> <calc store="r">a+b</calc> <say get="r">a+b=</say> <session name="subtracao"> <say>sub(f-menu)</say> <say store="a">a:</say> <say store="b">b:</say> <calc store="r">a-b</calc> <say get="r">a-b=</say> <session name="multiplicacao"> <say>mul(f-menu)</say> <say store="a">a:</say> <say store="b">b:</say> <calc store="r">a*b</calc> <say get="r">a*b=</say> <session name="divisao"> <say>div(f-menu)</say> <say store="a">a:</say> <say store="b">b:</say> <if error="div por zero!">b gt 0</if> <calc store="r">a/b</calc> <say get="r">a/b=</say> <terminal ip="...0" name="terminal" program="calculadora" type="colleter_tc00" /> ----