C.P.M.

PROGRAMA DE CONTROLE PARA MICRO TERMINAL

xCPML

Guia do Programador

Versão 1.0.7

Julho/2014
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 (14 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></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.
Entidades XML pré-definidas
Você deve ter notado que a XML define alguns caracteres especiais, por exemplo, os sinais <
(menor que) e > (maior que) são exemplos. Para que não ocorram problemas no processo
de análise do seu script, você deve evitar utilizá-los para outras finalidades que não as
reservadas pela própria linguagem, portanto, deve recorrer a tabela de entidades pré-
definidas apresentada a seguir:

Ao necessitar de Utilize Para representar

< &lt; Menor que
> &gt; Maior que
& &amp; E comercial
' &apos; Apóstrofe
“ &quot; Aspas

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:

1. fonte de dados (<datasource></datasource>)

2. programas (<program></program>)
3. terminais (<terminal></terminal>)

E das seguintes associações entre TAGs de projeto:

1. Programas com fontes de dados, e;

2. Terminais com programas;

Importante!

• Assim como as TAGs de programação devem estar contidas em um bloco

<program></program>, todas as outras TAGs devem estar contidas em um bloco
<project></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: Sim.
OCORRÊNCIA: Uma por arquivo.
FILHA DE: Ninguém (TAG ancestral de todas as outras).
ATRIBUTO(S) SIGNIFICADO REQUERIDO
name Nome do projeto Sim
version Versão da linguagem (esquema) de definição do projeto. Não
Valor(es) permitido(s) até o momento:
• 1.0
CONTEÚDO: Todas as demais TAGs.

Exemplo

1 <?xml version="1.0" encoding="UTF-8"?>

2 <project name=”my project”>
3 …
4 </project>

Importante!

• Todo script de programação, deve iniciar com a declaração XML exibida na linha 1.

<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: Não.
OCORRÊNCIA: Várias por arquivo.
FILHA DE: <project>
ATRIBUTOS(S) SIGNIFICADO REQUERIDO
name Nome da fonte de dados. Sim
type Tipo da fonte de dados. Sim
Valor(es) permitido(s) até o momento:
• http, e;
• sapiens (integração com ERP Sapiens)
CONTEÚDO: <host>
Exemplo

1 <?xml version="1.0" encoding="UTF-8"?>

2 <project name=”Exemplo TAG datasource”>
3 …
4 <datasource name="servidorA" type="http">
5 …
6 </datasource>
7 …
8 </project>

<host>

Esta TAG define o host utilizado na configuração de uma fonte de dados

externa.

REQUERIDA Sim.
OCORRÊNCIA Várias por arquivo.
FILHA DE: <datasource>
ATRIBUTO(S) SIGNIFICADO REQUERIDO
port Número da porta HTTP de conexão. Não
username Nome do usuário para autenticação. Não
password Senha do usuário para autenticação. Não
params Define o formato dos parâmetros passados na URL de Não
conexão.
Valores permitidos:
 • query (parâmetros passados no formato query
params. Exemplo: ?par1=var1&par2=var2)
• rest (parâmetros passados em formato
semântico. Exemplo: /par1/var1/par2/var2)
Quando esse parâmetro for omitido o formato rest será
assumido.
CONTEÚDO: Identificação do host na rede, podendo ser o IP, nome
do domínio e nome NetBIOS.

Exemplo

1 <?xml version="1.0" encoding="UTF-8"?>

2 <project name=”my project”>
3 …
4 <datasource name="server" type="http">
5 <host port=”8080”>www.meudominio.com</host>
6 </datasource>
7 …
8 </project>

<terminal>

Esta TAG define um terminal coletor de dados.

REQUERIDA: Não
OCORRÊNCIA: Várias por arquivo.
FILHA DE: <project>
ATRIBUTO(S) SIGNIFICADO REQUERIDO
name Nome de identificação do terminal Sim
ip IP único que identifica o terminal na rede Sim
program Programa associado ao terminal Sim
model Indica o modelo do equipamento controlado. Sim
Valor(es) permitido(s) até o momento:
• COLLETER_TC100
CONTEÚDO: TAG vazia
Exemplo

1 <?xml version="1.0" encoding="UTF-8"?>

2 <project name=”my project”>
3 …
4 <terminal ip="192.168.1.100" name="term1" program="prog1"
5 model="COLLETER_TC100" />
6 …
7 </project>

<program>

Esta TAG define um programa, ou seja, um bloco contendo TAGs para a

programação dos coletores de dados.

REQUERIDA: Não
OCORRÊNCIA: Várias por arquivo.
FILHA DE: <project>
ATRIBUTO(S) SIGNIFICADO REQUERIDO
name Nome único de identificação do programa. Sim
datasource Fonte de dados associado ao programa. Não
session Define o nome da sessão de inicialização quando na Não
execução do projeto. Se ausente, a primeira sessão
definida, será a sessão executada.
CONTEÚDO: Uma ou mais TAGs <session>

Exemplo

1 <?xml version="1.0" encoding="UTF-8"?>

2 <project name=”my project”>
3 …
4 <program name="program" datasource="server" session="menu">
5 …
6 </program>
7 …
8 </project>
 <session>

Esta TAG define uma sessão de programa. No CPM um programa é

composto por várias sessões.

REQUERIDA: Sim (Ao menos uma)

OCORRÊNCIA: Várias por arquivo.
FILHA DE: <program>
ATRIBUTO(S) SIGNIFICADO REQUERIDA
name Nome único de identificação da sessão Sim
hotkey Tecla de função associada à execução da sessão. Não
Valor(es) permitido(s) até o momento:
K_F1, K_F2, K_F3, K_F4, K_F5, K_F6, K_F7,
K_F8, K_F9, K_F10, K_F11 e K_F12
CONTEÚDO: Uma ou mais TAGs de programação.

Exemplo

1 <?xml version="1.0" encoding="UTF-8"?>

2 <project name=”my project”>
3 …
4 <program name=”my program”>
5 …
6 <session name=”main” hotkey="K_F1">
7 …
8 </session>
9 …
10 </program>
11 …
12 </project>

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: Não
OCORRÊNCIA: Várias por arquivo.
FILHA DE: <session>
ATRIBUTO(S) SIGNIFICADO REQUERIDO
beep Valor numérico que indica a quantidade de sinais Não
sonoros que acompanha a informação enviada ao
equipamento.
wait Valor numérico que indica quantos segundos de espera Não
será aguardado após envio da informação ao
equipamento.
get Recupera informação do DataList (vide sessão Nã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 Não
leitura), armazenando-a na variável definida por esse
atributo.
CONTEÚDO: Dado a ser exibido no display do equipamento.

Exemplo

1 <?xml version="1.0" encoding="UTF-8"?>

2 <project name=”my project”>
3 <program name=”my program”>
4 <session name=”sessao1” hotkey="K_F1">
5 <say beep=”1” store=”ficha”>Digite:</say>
6 <say wait=”1” get=”ficha”>Digitado:</say>
7 </session>
 8 <session name=”sessao2” hotkey="K_F2">
9 <say store=”a”>A:</say>
10 <say store=”b”>B:</say>
11 <say get=”a+b”>A+B:</say>
12 </session>
13 </program>
14 </project>

<store>

Esta TAG é a responsável pelo armazenamento direto (sem prévio

processamento) de valores no DataList.

REQUERIDA: Não
OCORRÊNCIA: Várias por arquivo.
FILHA DE: <session>
ATRIBUTOS(S) SIGNIFICADO REQUERIDO
name Nome da variável cujo valor será armazenado no Sim
DataList.
CONTEÚDO: Dado a ser armazenado no DataList.

Exemplo

1 <?xml version="1.0" encoding="UTF-8"?>

2 <project name=”my project”>
3 <program name=”my program”>
4 <session name=”main” hotkey="K_F1">
5 <store name="a">1</store>
6 <store name="b">2</store>
7 </session>
8 </program>
9 </project>
 <repeat>

Esta TAG define o início de um bloco de TAGs cuja execução deve repetir.

REQUERIDA: Não
OCORRÊNCIA: Várias por arquivo.
FILHA DE: <session>
CONTEÚDO: TAGs componentes do laço de repetição.

Exemplo

1 <?xml version="1.0" encoding="UTF-8"?>

2 <project name=”my project”>
3 <program name=”my program”>
4 <session name=”main” hotkey="K_F1">
5 <repeat>
6 …
7 <say store="a">A:</say>
8 <if break="true">a eq 0</if>
9 …
10 </repeat>
11 </session>
12 </program>
13 </project>

As linhas de 5 a 10 delimitam a região de repetição e, na linha 8, 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: Não
OCORRÊNCIA: Várias por arquivo.
FILHA DE: <session>
 CONTEÚDO: TAG sem conteúdo.

Exemplo

1 <?xml version="1.0" encoding="UTF-8"?>

2 <project name=”my project”>
3 <program name=”my program”>
4 <session name=”calc” hotkey="K_F1">
5 <say store="a">A:</say>
6 <say store="b">B:</say>
7 <calc store="c">A+B</calc>
8 <say wait="1" get="c">A+B:</say>
9 <clear />
10 </session>
11 </program>
12 </project>

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: Não
OCORRÊNCIA: Várias por arquivo.
FILHA DE: <session>
ATRIBUTOS(S) SIGNIFICADO REQUERIDO
store Nome da variável que será atribuído o resultado. Sim
CONTEÚDO: Uma expressão aritmética válida.

Exemplo

1 <?xml version="1.0" encoding="UTF-8"?>

2 <project name=”my project”>
3 <program name=”my program”>
4 <session name=”calc” hotkey="K_F1">
5 <say store="a">A:</say>
 6 <say store="b">B:</say>
7 <calc store="c">A+B</calc>
8 <say get="c">A+B:</say>
9 </session>
10 </program>
11 </project>

<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: Não
OCORRÊNCIA: Várias por arquivo.
FILHA DE: <session>
ATRIBUTOS(S) SIGNIFICADO REQUERIDO
to Nome de uma variável definida no atributo store Sim
de uma TAG <say>
say Mensagem a ser exibida no display do equipamento. Não
CONTEÚDO: Uma expressão lógica válida. O desvio ocorrerá se
a expressão for avaliada como verdadeira.

Exemplo

1 <?xml version="1.0" encoding="UTF-8"?>

2 <project name=”my project”>
3 <program name=”my program”>
4 <session name=”jump” hotkey="K_F1">
5 <say store="a">A:</say>
6 <say store="b">B:</say>
7 <say store="c">C:</say>
8 <say store="d">D:</say>
9 <get ns="db" url=”/web/service/” />
10 <jump to="a" say="A < 0">db.ret eq 1</calc>
11 <jump to="b" say="B < 0">db.ret eq 2</calc>
12 <jump to="c" say="C < 0">db.ret eq 3</calc>
13 <jump to="d">db.ret eq 4</calc>
14 </session>
15 </program>
16 </project>

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: Não
OCORRÊNCIA: Várias por arquivo.
FILHA DE: <session>
ATRIBUTOS(S) SIGNIFICADO REQUERIDO
session Nome da sessão a ser executada, caso a expressão Não
seja avaliada como verdadeira.
break Abandona a laço <repeat> atual caso a Não
expressão seja avaliada como verdadeira.
error Mensagem de erro a ser exibida, caso a expressão Não
seja avaliada como falsa.
CONTEÚDO: Uma expressão lógica válida.

Exemplo

1 <?xml version="1.0" encoding="UTF-8"?>

2 <project name=”my project”>
3 <program name=”my program”>
4
5 <session name=”menu” hotkey="K_F1">
6 <say>1-INCLUIR 2-EXCLUIR</say>
7 <say store="opcao">Opcao:</say>
8 <if session="incluir">opcao eq 1</if>
 9 <if session="excluir">opcao eq 2</if>
10 <say wait="1">Opcao invalida!</say>
11 </session>
12 …
13 <session name=”incluir” hotkey="K_F2">
14 <say>F1-MENU F3-EXCLUIR</say>
15 <say store="opcao">Opcao:</say>
16 </session>
17 …
18 <session name=”excluir” hotkey="K_F3">
19 <say>F1-MENU F2-INCLUIR</say>
20 <say store="opcao">Opcao:</say>
21 </session>
22 …
23 </program>
24 </project>

<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: Não
OCORRÊNCIA: Várias por arquivo.
FILHA DE: <session>
ATRIBUTOS(S) SIGNIFICADO REQUERIDO
ns Namespace(prefixo) atribuído aos dados válidos Sim
recebidos do servidor. Útil para evitar conflito de
nomes.
url URL da fonte de dados no servidor. Sim
CONTEÚDO: TAG vazia.

Exemplo

1 <?xml version="1.0" encoding="UTF-8"?>

2 <project name=”my project”>
3 <program name=”my program”>
4 <datasource name="server" type="http">
5 <host>http://meudominio.com</host>
 6 </datasource>
7 <session name=”main” hotkey="K_F1">
8 <say store="vendedor">Vendedor:</say>
9 <if error="invalido!">vendedor gt 0</if>
10 <get ns="db" url="/web/service/" />
11 <say get="db.nome">Nome:</say>
12 </session>
13 </program>
14 </project>

<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”.

Exemplo

1 ?xml version="1.0" encoding="UTF-8"?>

2 <project name=”my project”>
3 <program name=”my program”>
4 <datasource name="server" type="http">
5 <host>http://meudominio.com</host>
6 </datasource>
7 <session name="main" hotkey="K_F1">
8 ...
9 <put url="/web/service/" />
10 ...
11 </session>
12 </program>
13 </project>

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:

1 ?xml version="1.0" encoding="UTF-8"?>

2 <project name=”my project”>
3 <program name=”my program”>
4 <datasource name="server" type="http">
5 <host>http://meudominio.com</host>
6 </datasource>
7
8 <session name=”main” hotkey="K_F1">
9 <store name=”n”>12943390</store>
10 <get url="/service/cep" ns=”cep” />
11 ...
12 </session>
13 </program>
14 </project>

O exemplo de código acima, produzirá, automaticamente, a seguinte requisição HTTP

quando na execução da TAG <get> presente na linha 11.

http://meudominio.com/service/cep/n/12943390

Note que, “service=cep” (linha 9), foi introduzido no DataList antes de “n=12943390” (linha
10), 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 SIGNIFICADO
ne Diferente (not equal)
eq Igual (equal)
lt Menor que (less than)
gt Maior que (great than)
le Menor ou igual (less or equal)
ge 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 4 operações para duas entradas de dados: “a” e “b”.

1 <?xml version="1.0" encoding="UTF-8" ?>

2
3 <project name="calculadora">
4 <program name="calculadora">
5
6 <session name="menu" hotkey="K_F1">
7 <say store="opcao">1(+)2(-)3(*)4(/)Opcao:</say>
8 <if session="soma">opcao eq 1</if>
9 <if session="subtracao">opcao eq 2</if>
10 <if session="multiplicacao">opcao eq 3</if>
11 <if session="divisao">opcao eq 4</if>
12 <say wait="1">Opcao invalida!</say>
13 </session>
14
15 <session name="soma">
16 <say>SOM(F1-MENU)</say>
17 <say store="a">A:</say>
18 <say store="b">B:</say>
19 <calc store="r">a+b</calc>
20 <say get="r">A+B=</say>
21 </session>
22
23 <session name="subtracao">
24 <say>SUB(F1-MENU)</say>
25 <say store="a">A:</say>
26 <say store="b">B:</say>
27 <calc store="r">a-b</calc>
28 <say get="r">A-B=</say>
29 </session>
30
31 <session name="multiplicacao">
32 <say>MUL(F1-MENU)</say>
33 <say store="a">A:</say>
34 <say store="b">B:</say>
35 <calc store="r">a*b</calc>
36 <say get="r">A*B=</say>
37 </session>
38
39 <session name="divisao">
40 <say>DIV(F1-MENU)</say>
41 <say store="a">A:</say>
42 <say store="b">B:</say>
43 <if error="div por zero!">b gt 0</if>
44 <calc store="r">a/b</calc>
45 <say get="r">A/B=</say>
46 </session>
47
48 </program>
49
50 <terminal ip="192.168.1.103" name="terminal1" program="calculadora"
51 type="COLLETER_TC100" />
52
53 </project>

----