C.P.M. PROGRAMA DE CONTROLE PARA MICRO TERMINAL xcpml Guia do Programador Versão.0. Agosto/0
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 o Windows, Linux, OS X Solaris, etc. 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, http://www.java.com/pt_br/download/help/download_options.xml é 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 da explicação, são completamente irrelevantes. As TAGs XML Definimos um conjunto de TAGs XML específicas para servir de comandos para a programação dos scripts e, mesmo não sendo muitas TAGs ( até o momento), 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. A maioria das TAGs XML definidas possuem um elemento de abertura e outro de fechamento e devem ser digitadas em caixa baixa (letra minúscula). Essas TAGs são containers de outras, pois você poderá introduzir outras TAGs no interior do bloco que as define. Todas as TAGs nesta condição respeitam o seguinte formato <x>...</x>, onde o x representa um nome de uma TAG válida, por exemplo: datasource, project, program, etc. Outras TAGs (a minoria), por não serem containers para outras, não necessitam de elemento de fechamento (são resolvidas em uma única linha), neste caso, seu formato geral se resume a: <x />. São exemplos destas TAGs: terminal, get, put e clear. Novas TAGs surgirão e as atuais, com o tempo, alteradas ou excluídas, mas, não se preocupe, o CPM sempre saberá executar seus scripts antigos sem que você tenha que alterá-los.
O Projeto Um arquivo XML deve conter todo o seu projeto de automação, este, por sua vez, é composto das seguintes TAGs XML de projeto:. fonte de dados (<datasource></datasource>). programas (<program>). terminais (<terminal></terminal>) E das seguintes associações entre TAGs de projeto:. Programas com fontes de dados, e;. Terminais com programas; Importante! Assim como as TAGs de programação devem estar contidas em um bloco <program>, todas as outras TAGs 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. <?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 name Nome da fonte de dados. type Tipo da fonte de dados. Valor(es) permitido(s) até o momento: http, e; sapiens (integração com ERP Sapiens/Senior) CONTEÚDO: <host>
<?xml version=".0" encoding="utf-"?> <project name= TAG datasource > <datasource name="servidora" type="http"> </datasource> <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. 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 >www.meudominio.com</host> </datasource>
<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 <?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"> <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-"?> <session name= main hotkey="k_f"> Importante! A execução de uma sessão de programação é ciclica, 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. 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-"?> <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> <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-"?> <session name= main hotkey="k_f"> <store name="a"></store> <store name="b"></store> <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-"?> <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.
<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-"?> <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. <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-"?> <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.
0 <?xml version=".0" encoding="utf-"?> <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 prefix="db" url= /web/service/ /> <jump to="a" say="a < 0">db.ret eq </calc> <jump to="b" say="b < 0">db.ret eq </calc> <jump to="c" say="c < 0">db.ret eq </calc> <jump to="d">db.ret eq </calc> 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. 0 0 <?xml version=".0" encoding="utf-"?> <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. 0 <?xml version=".0" encoding="utf-"?> <datasource name="server" type="http"> <host>http://meudominio.com</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-"?> <datasource name="server" type="http"> <host>http://meudominio.com</host> </datasource> <session name="main" hotkey="k_f">... <put url="/web/service/" />...
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-"?> <datasource name="server" type="http"> <host>http://meudominio.com</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. http://meudominio.com/service/cep/n/0
Note que, service=cep (linha ), foi introduzido no DataList antes de n=0 (linha 0), portanto - graças à organização em fila do DataList - sairá também antes, quando na formação da requisição. 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 para tratamento da mesma requisição, só que desta vez, do lado do servidor WEB. Expressões aritmética 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 ne eq lt gt le ge SIGNIFICADO 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) Projeto Calculadora Abaixo você encontrará um exemplo completo de script 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. 0 0 <?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>
0 0 0 <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" /> ----