🧠 Explicação

O comando EXEC CICS RETURN é utilizado para encerrar a execução de um programa e devolver o controle para o programa chamador, para o CICS ou para uma nova transação. É um dos comandos mais comuns em qualquer aplicação CICS, e também pode ser usado para passar dados (por COMMAREA, CHANNEL ou INPUTMSG) para o próximo programa ou transação.

🔧 Usos mais comuns

  • Encerrar a execução de um programa e retornar ao CICS.

  • Encaminhar dados (COMMAREA) para outra transação.

  • Iniciar outra transação (TRANSID) a partir da atual.

  • Encaminhar dados usando CHANNELS (mais modernos que COMMAREA).

  • Encerrar uma atividade BTS com ENDACTIVITY.

🧾 Sintaxe

EXEC CICS RETURN
     COMMAREA(DFHCOMMAREA)
     LENGTH(TAM-COMMAREA)
END-EXEC.
EXEC CICS RETURN
     TRANSID('ABCD')
     COMMAREA(DFHCOMMAREA)
     LENGTH(TAM-COMMAREA)
     IMMEDIATE
END-EXEC.

💻 Exemplo prático

EXEC CICS RETURN
     COMMAREA(DFHCOMMAREA)
     LENGTH(LENGTH-OF-DATA)
END-EXEC.

📌 Regras

  • O tamanho da COMMAREA deve estar entre 0 e 32.763 bytes.

  • Para passar COMMAREA, CHANNEL ou TRANSID, o RETURN precisa ser feito por um programa no nível mais alto (não pode ser um subprograma).

  • O uso de IMMEDIATE garante que a transação especificada será a próxima a ser executada, ignorando a fila ATI.

  • Em programas BTS, use a opção ENDACTIVITY para finalizar corretamente uma atividade.

⚙️ Opções disponíveis

  • COMMAREA(area): Área de comunicação a ser passada ao próximo programa.

  • LENGTH(valor): Tamanho da COMMAREA.

  • CHANNEL(nome): Canal com containers a serem passados à próxima transação.

  • TRANSID('XXXX'): Inicia outra transação ao final do RETURN.

  • IMMEDIATE: Garante que a transação da opção TRANSID execute imediatamente.

  • INPUTMSG(area): Passa dados como se fossem entrada de terminal.

  • INPUTMSGLEN(valor): Tamanho da entrada INPUTMSG.

  • ENDACTIVITY: Usado em aplicações BTS para indicar que a atividade terminou.

  • SET(ptr-ref): (Usado em outros comandos RETURN com containers, não aplicável com COMMAREA)

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

  • INVREQ: Parâmetro inválido ou RETURN em nível incorreto.

  • LENGERR: Tamanho especificado ultrapassa o limite da COMMAREA.

  • CHANNELERR: Canal inválido especificado.

💡 Dicas

  • Ao usar RETURN COMMAREA, o programa que receberá os dados deve declarar LINKAGE SECTION com a variável DFHCOMMAREA.

  • Use CHANNEL com containers quando precisar passar múltiplos dados estruturados (recomendado em projetos novos).

  • TRANSID deve ser uma transação válida no sistema e definida previamente.

  • Cuidado ao usar RETURN com TRANSID sem IMMEDIATE, pois outras transações na fila ATI podem interceptar a próxima execução.

Conclusão

EXEC CICS RETURN é fundamental para controle de fluxo entre programas e transações no CICS. Seja finalizando a execução ou iniciando uma nova transação com dados, o comando deve ser usado com atenção às restrições de nível lógico e ao tamanho da área de comunicação. O uso combinado com TRANSID, IMMEDIATE, COMMAREA e CHANNEL oferece flexibilidade e controle preciso na lógica das aplicações CICS.