🔷 EXEC CICS RECEIVE MAP

Comandos CICS

🧠 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

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.