IBM Interface entre macros

IBM, que significa Interface Between Macros, define um padrão de comunicação entre macros. Essa interface foi concebida originalmente para realizar a integração dos módulos do framework Modular. Porém desde então a ideia vem sendo aperfeiçoada para atender a necessidades do grupo Macrosoft.

Este documento é dividido em duas partes:

Solicitante (requester)

Código necessário

Logo depois de toda requisição é necessário adicionar o código padrão para requisição

Requisição e passagem de parâmetros

A requisição a um provider é feita alterando o conteúdo da variável &ibm_request_ da seguinte forma. Se nome do arquivo do provedor é meuprovedor.txt, então para requisitar este arquivo basta alterar a variável para &ibm_request_="meuprovedor()";

Alternativamente é possível passar parâmetros da seguinte forma:
&ibm_request_="meuprovedor(parâmetro 1¬parâmetro 2¬hello world,7¬9)"; Nesta situação foram passados quatro parâmetros

  1. parâmetro 1
  2. parâmetro 2
  3. hello world,7
  4. 9
Os parâmetros devem ser separados pelo caractere ¬

Pegar retorno

Após a requisição, aguarda-se que o provider execute o seu código. O provedor pode retornar algum valor. Este valor estará disponível na variável &ibm_response_.

Status da transação

Após a requisição, a variável #ibm_success_ assume o valor 1 se a transação ocorreu com sucesso. Ou assume o valor 0 se a transação não ocorreu com sucesso, onde por exemplo a macro requisitada não existe.

Definir mensagem SYN

Alternativamente é possível definir uma mensagem de sincronização SYN. Isso pode ser feito da seguinte forma.
&ibm_request_="meuprovedor:olá mundo(foo¬baz)";
Neste caso a mensagem de sincronização foi

  • olá mundo

Provedor (provider)

Empacotar macro

Para que uma macro ser torne um provedor é necessário que trechos de código sejam inseridos início e no fim da sua macro. Isso já é feito automaticamente pelo criador de plugs IBM da Macrosoft®.

Parâmetros recebidos

Os parâmetros recebidos pelo requester ficam disponíveis nos arrays &inputs_[] e #inputs_[].

Definir retorno

Para definir um retorno para o requester modifique o conteúdo da variável &ibm_return_. Mas isso precisa ser feito antes do código do provedor inserido no fim da sua macro.

Definir mensagem ACK

Para definir uma mensagem de reconhecimento ACK modifique o conteúdo da variável &pim_ack_message_. Mas isso precisa ser feito antes do código do provedor inserido no início da sua macro.

Conceitos importantes
  • Conexão é o processo em que se estabelece um socket para a comunicação
  • Socket é um canal de comunicação entre macros. Sempre será uma variável global onde os agentes passivo e ativo poderão ambos ler e escrever. O protocolo define a coordenação da leitura/escrita
  • Em uma transação agente ativo é quem realiza a requisição e agente passivo aquele que responde à requisição
  • Transação é o processo síncrono que inclui conexão, requisição, resposta e o processamento da resposta
  • Requisição é o processo de enviar parâmetros para uma macro para usar os seus serviços
  • Doravante considere macro A como o agente ativo e a macro B como agente passivo.

Propósito

O propósito deste protocolo é:

  1. Estabelecer a conexão entre duas macros
  2. Garantir a transação entre essas duas macros conectadas
  3. Prover informação sobre o status da transação

Processo de Transação

Em uma transação, a conexão será o primeiro passo realizado.

  1. A macro A cria um socket (uma variável global com um nome numérico aleatório no formato @&pim_0000000)
  2. A macro A define o conteúdo do socket com a mensagem de sincronização SYN: PIMSYN:alguma mensagem. A mensagem é definida pelo conteúdo de &pim_syn_message_
  3. A macro A envia 10 parâmetros para a macro B via EXEC ou run. O 10º parâmetro é o nome do socket.
  4. A macro A aguarda no máximo a quantidade de loops definida por #api_request_timeout_ até receber a mensagem de reconhecimento ACK da macro B. Se a macro B demorar demais a responder, o processo é finalizado e o status de sucesso da transação #ibm_success_ é definido como False.
  5. A macro B atribui os parâmetros recebidos ao arrays &inputs_[] e #inputs_[] e acessa o socket cujo nome foi recebido no décimo parâmetro
  6. A macro B lê o socket, extrai a mensagem de sincronização
  7. A macro B sobrescreve o socket com uma mensagem de reconhecimento ACK: PIMACK:alguma mensagem. A mensagem é definida pelo conteúdo de &pim_ack_message_
  8. A macro A lê o socket e extrai a mensagem de reconhecimento ACK. Em seguida a macro A aguarda indefinidamente até que a macro B escreva no socket a mensagem de finalização END.
  9. A macro B executa o seu código
  10. A macro B sobrescreve o socket com a mensagem de finalização END: PIMEND:alguma mensagem e finaliza a sua execução. A mensagem é definida pelo conteúdo de &ibm_return_
  11. A macro A lê o socket e extrai a mensagem finalização END e apaga o socket. A mensagem de retorno fica armazenada em &ibm_response_ ou #ibm_response_. O status de sucesso da transação #ibm_success_ é definido como True.

Um plhgin IBM é um pacote de um ou mais serviços. Esses pacotes são construídos automaticamente pela aplicação de criação de plugs IBM da Macrosoft®.

Várias macros podem ser empacotadas em um único arquivo. Cada macro pode ser requisitada separadamente como um serviço. Basta requisitar o arquivo como um provider IBM e passar o nome do serviço através da mensagem de sincronização SYN.

O serviço comum entre todos os plugs IBM é o info. Este serviço retorna uma string contendo o nome do criador do plug e os serviços contidos naquele plug, cada um destes elementos sepadados por ,.

Os retornos comuns entre todos os plugs IBM são

  • empty que indica que a mensagem de sincronização SYN foi passada como uma string vazia
  • not_found que indica que o serviço requisitado não existe naquele plug