sexta-feira, 9 de março de 2007

O que é RETURN-CODE em COBOL?

Bellacosa Mainframe e o return-code no Cobol

O que é RETURN-CODE em COBOL?

O RETURN-CODE é uma variável especial utilizada para informar ao sistema operacional, ao JCL e aos schedulers o resultado da execução de um programa.

Em outras palavras:

é o código de retorno que o programa devolve ao z/OS quando termina.

Para que serve?

O RETURN-CODE informa se o programa:

executou com sucesso;
terminou com avisos;
encontrou erros;
deve interromper o fluxo do JOB.

Fluxo simplificado

PROGRAMA COBOL
       ↓
RETURN-CODE
       ↓
STEP JCL
       ↓
JES2
       ↓
Scheduler (IWS, Control-M, OPC)

Exemplo mais simples

MOVE 0 TO RETURN-CODE

Significa:

Execução OK

Valores mais comuns

Return Code	Significado
0	Sucesso
4	Aviso
8	Erro
12	Erro grave
16	Erro crítico

Exemplo

IF WS-ARQUIVO-VAZIO
   MOVE 4 TO RETURN-CODE
END-IF

Resultado:

Job terminou com Warning

Exemplo de erro

IF WS-ERRO-LEITURA
   MOVE 8 TO RETURN-CODE
END-IF

Onde o RETURN-CODE fica?

O compilador COBOL fornece automaticamente a variável especial:

RETURN-CODE

Não precisa ser declarada.

Exemplo completo

IDENTIFICATION DIVISION.
PROGRAM-ID. TESTE.

PROCEDURE DIVISION.

    DISPLAY 'PROCESSAMENTO OK'

    MOVE 0 TO RETURN-CODE

    GOBACK.

Como aparece no JCL?

Após o STEP terminar:

COND CODE 0000

CC 0000

Exemplo com erro

MOVE 8 TO RETURN-CODE

No spool:

COND CODE 0008

Uso em Scheduler

Ferramentas como:

IBM IWS (Tivoli Workload Scheduler)
OPC
Control-M
CA-7
ESP

avaliam o Return Code.

Exemplo

RC = 0000

Próximo JOB é liberado.

RC = 0008

Fluxo interrompido.

Uso com COND no JCL

//STEP2 EXEC PGM=RELATORIO,
// COND=(8,LT)

Significa:

Se RC anterior < 8
execute o STEP

Uso com IF no JCL

Mais moderno.

// IF (STEP1.RC = 0) THEN
//STEP2 EXEC PGM=PROG2
// ENDIF

Exemplo prático

Processamento de clientes.

IF QTDE-CLIENTES = ZERO
   MOVE 4 TO RETURN-CODE
END-IF

Resultado:

Nenhum cliente processado

Mas sem ABEND.

Return Code não é ABEND

Muitos iniciantes confundem.

RETURN-CODE

Programa terminou normalmente.

RC=8

ABEND

Programa terminou anormalmente.

S0C7
S0C4
U4038

Comparação

Situação	Resultado
MOVE 8 TO RETURN-CODE	Término normal
S0C7	ABEND
S0C4	ABEND
U0001	ABEND usuário

RETURN-CODE em Subprogramas

Pode ser utilizado antes do:

GOBACK

Exemplo

IF ERRO
   MOVE 12 TO RETURN-CODE
END-IF

GOBACK

RETURN-CODE x GOBACK

MOVE 8 TO RETURN-CODE
GOBACK

O sistema recebe:

RC=8

RETURN-CODE x STOP RUN

Também funciona.

MOVE 0 TO RETURN-CODE
STOP RUN

Convenções corporativas

Muitas empresas adotam padrões:

RC	Significado
0	OK
4	Warning
8	Erro funcional
12	Erro grave
16	Erro fatal

Exemplo bancário

EVALUATE TRUE

   WHEN ARQUIVO-VAZIO
      MOVE 4 TO RETURN-CODE

   WHEN REGISTRO-INVALIDO
      MOVE 8 TO RETURN-CODE

   WHEN ERRO-BANCO-DADOS
      MOVE 12 TO RETURN-CODE

END-EVALUATE

Como visualizar?

No SDSF:

ST

Exemplo:

JOB12345 ENDED RC=0000

JOB12345 ENDED RC=0008

Curiosidades

1. RETURN-CODE existe há décadas no COBOL

2. É fundamental para automação batch

3. Schedulers dependem fortemente dele

4. Grandes bancos possuem tabelas corporativas de RCs padronizados

Erros comuns de iniciantes

Esquecer de definir RETURN-CODE

Retornar sempre zero

Confundir RC com ABEND

Não documentar significado dos RCs

Resumo rápido

Comando	Função
RETURN-CODE	Código de retorno
RC=0	Sucesso
RC=4	Aviso
RC=8	Erro
RC=12	Erro grave
RC=16	Erro crítico
GOBACK	Retorna ao chamador
STOP RUN	Finaliza programa

Conclusão

O RETURN-CODE é o mecanismo utilizado pelos programas COBOL para informar ao z/OS, ao JES2, ao JCL e aos schedulers o resultado da execução. Ele é essencial para o controle de fluxos batch, automação corporativa e monitoramento de processos em ambientes Mainframe IBM Z.

Translate

sexta-feira, 9 de março de 2007