Documento: Serviço da cotações via socket em formato texto Disponibilidade: Servidor EGS Socket Server publicado em 02/10/02 por omar reis <omar@enfoque.com.br>

Serviço da cotações via socket em formato texto

É comum o uso de cotações em tempo real em aplicações especializadas. Tradicionalmente essas aplicações tem sido implementadas em planilhas, como o MS Excel, usando o protocolo DDE para receber as cotações. Nestes casos, o servidor DDE do Terminal Enfoque pode ser usado, tendo bom desempenho e baixo uso de recursos da maquina. Da mesma forma, aplicativos escritos para a plataforma Windows, usando Visual Basic, Delphi ou outras linguagens, podem receber cotações via DDE.

Contudo existem aplicações especiais onde o uso de DDE é difícil. É o caso de programas feitos para ambientes virtuais como Java ou .NET que não tem acesso nativo ao DDE. Além disso, em outros sistemas operacionais, como Linux, Unix e MacOS, o protocolo DDE não existe. Para estes casos a Enfoque criou um serviço especial de cotações em formato texto através de conexões TCP/IP (tipo client socket). Esse serviço usa um protocolo de aplicação simples, consistindo de comandos e dados em linhas de texto terminadas por CRLF (caracteres ASCII 13 e 10). Os campos são delimitados pelo caracter TAB (ASCII 9). O uso de texto facilita a implementação e debug do tratamento dos dados.

O protocolo do Socket Srv

O protocolo do servidor Socket Srv é simples: tanto comandos cliente -> servidor; como respostas servidor -> cliente são no formato "Letra:Texto CRLF" (crlf são os caracteres #13 e #10). A letra inicial determina o tipo do texto.

Comandos cliente > servidor

São os textos enviados pela sua aplicação ao servidor, para controlar o fluxo de dados. Tem formato letra:parâmetro

> Login - formato "L:username:password[:flags]"

O login deve ser o primeiro comando do cliente após a conexão ser aceita.

Esse comando associa a conexão a um contexto de usuário, onde fica guardada a lista de ativos assinados. Notar que, se a conexão cair, basta reconectar e refazer o login. Todos os ativos assinados continuarão atualizando, não havendo necessidade de ressolicitá-los. Neste caso, apenas o login é obrigatório após reconectar.

Exemplo:
L:MEULOGIN:MINHASENHA

Um login válido é saudado com a mensagem M:Hello, enquanto que um login inválido é informado do erro com mensagem E:ErrorMsg.

O campo FLAGS é opcional e permite configurar alguns parâmetros da conexão com o servidor de cotações. Os flags usados podem ser concatenados com '+'. Flags reconhecidos (case sensitive):

1. NMB (no mini book) - Inibe a transmissão do minilivro com 5 ofertas. O default da conexão é enviar o minilivro de 5 ofertas para todos os ativos subscritos com o comando S. Use esse flag se pretende receber o livro completo.
   
2. NTM (no time) - Inibe a transmissão do sinal horário ( pacote H )
3. TRD (Trades) - Ativa o envio dos trades (pacotes tipo N)

Exemplo:
L:JOSE:GFR795:NMB+TRD

> Assinatura de ativo - formato "S:Codigo" : Isso sinaliza ao servidor que o aplicativo deseja receber as atualizações de um ativo. Essas atualizações podem ser de dois tipos: cotações do ativo e livro de ofertas, como veremos abaixo.

Exemplo:
S:PETR4

Esse comando assina o ativo Petrobrás PN (PETR4).

Em resposta ao comando S o aplicativo passa a receber mensagens dos tipos T ( tick de cotações) e B (livro de ofertas). O livro de ofertas contém as 5 melhores ofertas em cada direção e é emitido somente para ações Bovespa. Uma mensagem de cada tipo é emitida imediatamente. Após isso são emitidas mensagens a cada atualização de qualquer dos campos. Isso inclui negócios realizados e inicializações diárias dos ativos.

Se o flag TRD foi especificado no login, começa o envio de mensagens de negócio do ativo (tipo N).

> Cancela assinatura de ativo - formato "U:Codigo" : Remove a assinatura do ativo (ticks e ofertas).

Exemplo: U:PETR4

> Limpa todas as assinaturas - formato "C:" : Remove todas as assinaturas do ativo. Não tem parâmetro.

Exemplo: C:

> Mensagem para Operador - formato "O:" : Envia mensagem ao operador.

Exemplo: O:Hello

Respostas servidor > cliente

São os textos enviados pelo servidor para a sua aplicação, contendo dados (cotações e livros de ofertas) e eventuais mensagens de erro.

> Tick de ativo (cotações) - formato "T:dados" : Os 'dados' consiste em uma lista de cotações em formato texto separado por TABs. A ordem dos campos é:

• Para ações: CODIGO ULT HOR VAR MAX MIN FEC ABE OCP OVD NEG QUL MED VOV VOC QTT
• Para mercadorias: CODIGO ULT HOR VAR MAX MIN FEC ABE OCP OVD CNG CAB AJU HOC HOV

Exemplo:

T:PETR4 42.0200 1312.0000 0.8800 42.1500 41.5500 41.6500 42.0000 41.9100 42.0000 375.0000 0.1000 41.9400 1000.0000 100.0000 591000.0 000

O pacote tipo tick é emitido a cada alteração de alguma das cotações do ativo (a cada novo negócio ou alteração das melhores ofertas).

> Livro de ofertas simplificado- formato "B:dados" : Os 'dados' consistem nas cinco melhores ofertas em cada direção, atualizadas em real time, com campos separados por TAB.

Cada oferta é do tipo: C 1.50 1k 30 24/02

Elas tem os seguintes campos:

1. direcao da oferta ('C' ou 'V')
2. preço da oferta
3. quantidade da oferta (pode vir abreviado por 'k' para milhar, 'M' para milhão e 'G' para bilhão).
4. Número da corretora na Bovespa (no site da BVSP tem a lista) 5) data da oferta, no formato dd/mm
   

Se a oferta não existir (ativo com menos de 5 ofertas), o preço e a quantidade estarão zerados.
Abaixo tem exemplo de pacote de livro.

B:PETR4 C 41.01 100 95 26/02 C 41.00 700 27 26/02 C 40.81 100 147 26/02 C 40.59 500 114 24/02 C 40.00 2k 27 03/02 V 44.10 100 27 26/02 V 44.30 100 114 26/02 V 45.00 100 74 25/02 V 45.00 1k 160 25/02 V 45.00 100 5 26/02

> Negócios - formato "N:dados" - Emitida quando há negócio do ativo. Esta mensagem contém dados de cada negócio. Para receber essas mensagens, é preciso passar o flag TRD no comando de login.

Além do código, elas tem os seguintes campos:

1. Hora (no formato numérico HHMM)
2. Preço do negócio
3. Quantidade do negócio
4. Número do negócio (id)
5. Número da corretora compradora
6. Número da corretora vendedora
   

Os números das corretoras são os usados pela Bovespa. A tabela com os nomes pode ser obtida no site da Bovespa.

Exemplos:

N: PETR4 1510 41.77 2100 3973 226 40
N: PETR4 1510 41.77 1800 3974 226 40

> Cancelamento de Negócio - formato "X:dados" - Emitida quando há cancelamento negócio do ativo.

X: Codigo > número do negócio (id)

Exemplo:

X: PETR4 1234

> Mensagem de Volumetria - formato "V:texto" : Contém dados de volume do ativo, em strings separados por TAB.

V:Código > Volume Financeiro > Num de negócios > Qde Total > Contratos Abertos (apenas para mercadorias)

Exemplo:

V:IGTA3 10718275 943 244000 0

> Mensagem de cotações diárias (snapshot) - formato "S:texto" : São cotações ou dados que não se alteram durante o dia. Esta mensagem é emitida apenas uma vez, quando o ativo é solicitado (subscrito). Formato:

S:Código > 1.Nome > 2.TipoPapel > 3.Preco Exercicio > 4.Data Vencimento > 5.Data Liquidacao > 6.Bolsa >
7. PapelObjeto > 8. SecurityId > 9. Lote > 10. Forma de Cotacao > 11. TickSizeDenominator >
12. Num de Saques até Vencimento > 13. Num de Dias Uteis até Vencimento>
14. Num de Dias Corridos até Vencimento > 15. Limite Min > 16. Limite Max > 17. Min Trade Vol>
18. Min Price Instrument > 19. Valor do Ponto > 20. Tunel Movel Inferior > 21. Tunel Movel Superior


Onde:
- datas de exercício e liquidação no formato 'dd/mm/aa'
- TickSizeDenominator é o numero de decimais das cotações
- Bolsa (BVSP=1, BMF=3)

> Mensagem de Leilão - formato "L:texto" : Estado do papel e parametros teóricos do leilão

L:Código > Estado De Negociação do Papel > Preço Teórico de Abertura > Qde Teórica >
Variação Teórica > Qde Não Atendida > Sentido da QNA > Horário Fim do Leilão

Onde:
Estados de negociação: 1=Negociação Normal, 2=Suspenso, 3=Congelado, 4=Leilão, 5=Abertura,
6=Impedido, 7=After Market, 8=Pré-Aberrtura, 9=Pré-Fechamento, 10=Preparação, 11=Leilão Prorrogado

Sentido da Qde Não Atendida - 'C' (compra) ou 'V' (venda)

> Mercado Anterior - formato "A:texto": São cotações do último mercado que o ativo foi negociado e não se alteram durante o dia. Está mensagem é emitida apenas um vez, quando o ativo é solicitado (subscrito). Formato:

L:CODIGO > Data > HOR > ULT> VAR > MAX > MIN > FEC > ABE > OCP > OVD > NEG > MED > VolTot > CNG/QTT > CAB > AJU > NumDecimais

Onde:

A:WINJ12 11/04/12 18:32:00 61255 -0.90 62445 61200 61780 62180 61235 61290 62031 61965 1794419649.00 144793 26822 61350 0

A:PETR4 11/04/12 00:00:00 21.35 +0.75 21.59 21.27 21.19 21.45 21.34 21.35 28452 21.43 528184512.00 24648400 0 0.00 2

A:IBOV 11/04/12 00:00:00 61293 -0.72 62356 61291 61738 61741 0 0 536890 61868 5406888448.00 316480608 0 0 0

> Melhor Oferta Agregada - formato "O:texto": Os dados das ofertas consistem na melhor oferta agrupada por preço em cada direção. Formato:

O:Código > QtdeCompra > NumOfertasCompra > PreçoCompra > PreçoVenda > NumOfertasVenda > QtdeVenda

Onde:

O:PETR4 100 1 21.83 21.84 5 6600

O:WINJ12 5 2 62310 62315 4 9

O:WDOK12 43 12 1839.00 1840.00 6 47

> Mensagem administrativa - formato "M:texto" : Mensagem do sistema. Pode requerer ação do operador.

Exemplo: M:Operator is online

> Mensagem de erro - formato "E:texto" : Provavelmente um comando inválido. Exemplo:

Exemplo: E:Instrument code ABCD4 not found

Teste do serviço

O protocolo do Socket Srv é semelhante a outros protocolos de texto, populares na internet, como TELNET. Isso permite o uso do programa cliente do TELNET para acesso a este serviço interativamenrte, para testes. Todas as versões de Windows contém um cliente de TELNET. Para acessá-lo, abra o prompt do MS-DOS e digite:

c:\> telnet servidor porta

depois basta digitar:

L:USERNAME:SENHA
S:TNLP4

Para começar a receber as cotações e ofertas do ativo TNLP4.

O tick do tipo B permite tratar facilmente as cinco melhores ofertas em cada sentido para cada ativo . Em aplicações que requerem maior número de ofertas, a Enfoque disponibiliza o livro de ofertas completo, com todas as ofertas em sinal stream online.

Como alguns ativos podem ter mais de 200 ofertas em cada sentido, não é prático fazer um dump completo do livro a cada atualização. Isso tornaria o sinal demasiamenete pesado e redundante. Por isso o sistema DynaBook Enfoque replica os pacotes de atualização do livro enviados pela Bovespa. Notar que é necessário tratar todos os pacotes: a perda de um só pacote resulta em erro na cópia local do livro de ofertas.

Outra diferença do sistema DynaBook ( em relação ao mini livro de 5 ofertas ) é que toda vez que a conexão TCP/IP for refeita, os livros assinados devem ser ressolicitados. Isso é necessário por que pacotes foram perdidos durante o tempo que a conexão ficou interrompida, e é necessário refazer as listas de ofertas.

Comandos do cliente

Assinatura de um livro - formato "D:Codigo" : Isso sinaliza ao servidor que o aplicativo deseja receber as atualizações do livro do ativo.

Exemplo: D:PETR4

Cancelamento de assinatura - formato "D:U:Codigo" : Isso sinaliza ao servidor que o aplicativo não deseja mais receber as atualizações do livro do ativo.

Exemplo: D:U:PETR4

Pacotes de resposta do servidor

Todos os pacotes de resposta do sistema DynaBook começam com 'D:'. Segue-se o tipo do pacote e eventuais parâmetros.

As ofertas podem ser em dois sentidos:

• Compra especificada pela letra A
• Venda especificada pela letra V

A posição da oferta no livro é especificada pelo índice. A melhor oferta em uma direção tem índice 0, a segunda indice 1 e assim por diante.

Pacote de Seleção de Livro - A fim de evitar a transmissão do código do ativo a cada pacote, o que prejudicaria o desempenho, o sistema DynaBook trabalha com o conceito de livro selecionado. Isto é, antes de enviar pacotes para um livro, o servidor envia um pacote especificando qual o livro que deverá receber os pacotes subsequentes. Seguem-se um ou mais pacotes para esse mesmo livro.

Formato: D:C:Código

Exemplo D:C:TNLP4

Pacote tipo Delete - Apaga uma ou mais ofertas em um sentido (compra ou venda). Pode ser de 3 subtipos:

1. Apaga a oferta especificada pelo índice
2. Apaga a oferta especificada pelo índice e todas as melhores que ela.
3. Apaga todas as ofertas (nas duas direções)
   

Formato:

D:D:1:Sentido:Indice
D:D:2:Sentido:Indice
D:D:3

Exemplos:

Pacote tipo Add - Este pacote insere uma oferta no final da lista. É enviado no momento que o livro é solicitado, para popular as listas de ofertas.

Formato: D:A:Sentido:Preço:Quantidade:IDCorretora:Data

onde:

• IDCorretora = número da corretora
• Data = data e hora da oferta no formato 'DDMMhhmm' ( dia/mes/hora/minuto, tudo junto com dois dígitos para cada parte )
• A quantidade pode vir abreviada ('k' para milhar, 'M' para milhão e 'G' para bilhão, como no mini-livro)

Exemplo: D:A:V:5.98:1k:27:28101105

Pacote tipo Update - Este pacote atualiza uma oferta. Pode também sinalizar a mudança na posição da oferta.

Formato: D:U:Sentido:Indice:IndiceAnt:Preço:Quantidade:IDCorretora:Data

onde:

• Indice atual da oferta ( melhor oferta tem índice 0)
• Indice anterior da oferta. Se diferente do atual, é necessário mover a oferta da posição anterior para a posição atual (após fazer o update)
• IDCorretora = número da corretora
• Data = data e hora da oferta no formato 'DDMMhhmm'
• A quantidade pode vir abreviada ('k' para milhar, 'M' para milhão e 'G' para bilhão, como no mini-livro)

Exemplo: D:U:V:0:2:5.19:14k:228:28101551

Acesso ao serviço

Para informações comerciais e solicitação de demonstração, consulte o suporte Enfoque.

Atualizações:

OFR 19/nov/03 - Sinal Horário e tratamento de mensagens operador <-> cliente.
OFR 28/out/04 - Descrição do Sistema DynaBook
OFR 05/01/05 - Implementações no sistema DynaBook
OFR 24/out/06 - Implementado o envio de negócios (pacote N)
OFR 15/mar/12 - Pacotes V, S e L

(c)copr 1988-2005 Enfoque Gráfico Sistemas Ltda - todos os direitos reservados