🧠 Explicação

O comando EXEC CICS RECEIVE MAP é utilizado para receber dados digitados pelo usuário no terminal 3270, mapeando-os automaticamente para uma área de dados no programa COBOL. Ele é parte essencial da comunicação entre a interface do usuário e o programa CICS.

Após o comando:

  • O campo EIBAID recebe o código da tecla pressionada (Enter, PFs, PA, etc.).

  • O campo EIBCPOSN recebe a posição do cursor no momento do envio.

🔧 Usos mais comuns

  • Capturar entradas do usuário em telas BMS.

  • Validar dados preenchidos pelo operador do terminal.

  • Iniciar lógica condicional com base no AID (Enter, PF3, etc.).

🧾 Sintaxe

EXEC CICS RECEIVE
     MAP('NOMMAP')
     MAPSET('MAPSET1')
     INTO(NOMMAPI)
END-EXEC.

Ou usando ponteiro:

EXEC CICS RECEIVE
     MAP('NOMMAP')
     MAPSET('MAPSET1')
     SET(ADDRESS OF TELAI)
END-EXEC.

💻 Exemplo prático

EXEC CICS RECEIVE
     MAP('TELA01')
     MAPSET('MAPSET1')
     INTO(TELA01I)
END-EXEC.

IF EIBAID = DFHAID(ENTER)
   PERFORM VALIDA-DADOS.
END-IF.

📌 Regras

  • A área de dados padrão para o mapa é o nome do mapa + sufixo I, ex: TELA01I.

  • Se o mapa tiver sido definido com TIOAPFX=YES, a área de dados incluirá um prefixo de 12 bytes.

  • Use SET(ptr-ref) se quiser acessar diretamente o buffer da tela (requer uso de LINKAGE SECTION).

  • Campos ocultos ou não modificados não são sobrescritos na área destino.

  • Para trabalhar com partições, use a opção INPARTN.

💡 Dicas

  • Sempre trate a condição MAPFAIL, comum quando o usuário pressiona ENTER sem preencher campos.

  • Use ASIS para capturar letras minúsculas do terminal, se necessário.

  • Utilize FROM e LENGTH se os dados da tela já estiverem em uma área específica (avançado).

  • Se o programa for multitarefa (THREADSAFE), certifique-se que o acesso ao buffer com SET seja feito com cautela.

🚨 Condições que podem ocorrer (HANDLE CONDITION)

  • MAPFAIL: Tela vazia ou com dados não formatados (ex: usuário apertou ENTER sem preencher campos).

  • INVMPSZ: Mapa maior que o terminal.

  • INVREQ: Tentativa de RECEIVE fora de uma tarefa de terminal.

  • EOC, EODS, RDATT, UNEXPIN: Situações específicas de LUs ou teclas especiais.

  • PARTNFAIL, INVPARTN: Problemas com partições incorretas ou inexistentes.

Conclusão

RECEIVE MAP é o principal mecanismo de leitura de dados do terminal no ambiente CICS. Ao usar o BMS, ele simplifica o tratamento dos campos da tela, permitindo que o programa processe os dados de forma estruturada e segura. O tratamento de exceções como MAPFAIL é essencial para garantir robustez nas interações com o usuário.