1. O que é uma copybook
Uma copybook é um arquivo de texto contendo código COBOL parcial — declarações de dados, parágrafos ou qualquer trecho reutilizável — que é inserido fisicamente no programa fonte durante a compilação. Não é um include em tempo de execução: o compilador copia o conteúdo da copybook para dentro do fonte antes de compilar.
🦕 Analogia — copybook é um carimbo
Imagine que você precisa colocar o mesmo endereço de empresa em dezenas de documentos. Em vez de escrever à mão cada vez, você tem um carimbo. A copybook é o carimbo: está guardada em um lugar central (copybook library no mainframe) e você a aplica nos programas com COPY. Quando o endereço muda, você atualiza o carimbo e reimprimi todos os documentos — no COBOL, você atualiza a copybook e recompila os programas.
No mainframe IBM, copybooks ficam armazenadas em partitioned datasets (PDS) — um dataset com múltiplos membros, um por copybook. O nome do membro é o nome da copybook. A DD SYSLIB no JCL de compilação aponta para esse PDS.
2. Instrução COPY
A instrução COPY especifica o nome da copybook a incluir. O compilador procura esse nome nas bibliotecas configuradas e insere o conteúdo no ponto onde o COPY aparece:
* Forma simples: inclui o membro CPFCLI do SYSLIB padrão COPY CPFCLI. * Especificando a biblioteca explicitamente COPY CPFCLI OF 'PROD.COPYBOOK.CLIENTES'. * Suprimindo a listagem do conteúdo no compilador COPY CPFCLI SUPPRESS.
*----------------------------------------------------------------*
* CPFCLI — Layout do registro de cliente *
* Versão: 3.1 Atualização: 2026-03-10 *
*----------------------------------------------------------------*
01 REG-CLIENTE.
05 CLI-CPF PIC X(11).
05 CLI-NOME PIC X(40).
05 CLI-DATA-NASC PIC 9(08).
05 CLI-SALDO PIC S9(13)V99.
05 CLI-LIMITE PIC S9(13)V99.
05 CLI-STATUS PIC X(01).
88 CLI-ATIVO VALUE 'A'.
88 CLI-INATIVO VALUE 'I'.
88 CLI-BLOQ VALUE 'B'.
05 CLI-AGENCIA PIC 9(04).
05 CLI-FILLER PIC X(17).
DATA DIVISION. FILE SECTION. FD ARQ-CLIENTE. COPY CPFCLI. *insere REG-CLIENTE com todos os campos WORKING-STORAGE SECTION. 01 WS-AREA-CLIENTE. COPY CPFCLI. *reutiliza o mesmo layout como área de trabalho
3. Onde o COPY pode aparecer
O COPY pode ser usado em qualquer divisão do programa COBOL. O conteúdo da copybook precisa ser válido para aquele contexto:
| Divisão | Uso típico | Exemplo de copybook |
|---|---|---|
ENVIRONMENT | Declarações de arquivo (SELECT) | SELCLI — SELECT do arquivo de clientes |
DATA — FILE SECTION | FD e layout do registro | FDCLI — FD + REG-CLIENTE |
DATA — WORKING-STORAGE | Áreas de trabalho, parâmetros | WSCLI — campos de trabalho do módulo de clientes |
DATA — LINKAGE SECTION | Parâmetros de CALL | LKCLI — área de interface para sub-programas |
PROCEDURE DIVISION | Parágrafos reutilizáveis | PRCEDT — edição e validação de data |
ENVIRONMENT DIVISION. INPUT-OUTPUT SECTION. FILE-CONTROL. COPY SELCLI. *SELECT ARQ-CLIENTE ASSIGN TO DDCLIEN... DATA DIVISION. FILE SECTION. FD ARQ-CLIENTE. COPY FDCLI. *FD com RECORDING MODE, BLOCK CONTAINS... WORKING-STORAGE SECTION. COPY WSCONT. *contadores, acumuladores e flags COPY WSERROS. *área de mensagens de erro padronizadas LINKAGE SECTION. COPY LKPARM. *parâmetros recebidos via CALL PROCEDURE DIVISION USING LK-AREA-PARM. COPY PRCEDT. *parágrafos de edição de data
4. COPY com REPLACING
A cláusula REPLACING substitui texto dentro da copybook durante a inclusão. É essencial quando você precisa incluir a mesma copybook mais de uma vez no mesmo programa com nomes de campos diferentes, ou adaptar prefixos de campos:
* Arquivo CPFMOV.cpy — layout genérico de movimento: * 05 ==MV==CPF PIC X(11). * 05 ==MV==DATA PIC 9(08). * 05 ==MV==VALOR PIC S9(11)V99. * 05 ==MV==TIPO PIC X(01). WORKING-STORAGE SECTION. * Inclui como registro de ENTRADA com prefixo EN- 01 WS-MOV-ENTRADA. COPY CPFMOV REPLACING ==MV== BY EN. * Resultado: EN-CPF, EN-DATA, EN-VALOR, EN-TIPO * Inclui como registro de SAÍDA com prefixo SA- 01 WS-MOV-SAIDA. COPY CPFMOV REPLACING ==MV== BY SA. * Resultado: SA-CPF, SA-DATA, SA-VALOR, SA-TIPO * Substituição de múltiplos termos no mesmo REPLACING COPY CPFMOV REPLACING ==MV== BY WK ==VALOR== BY MONTANTE ==9(08)== BY X(08).
✅ Convenção de pseudo-texto com ==
Os delimitadores == ao redor do texto a substituir são chamados de pseudo-text delimiters. Eles permitem que o REPLACING encontre o texto exato, mesmo que apareça como parte de um nome maior. Por exemplo, ==MV== encontra o token MV mas não afeta nomes como MVTO ou TOTAL-MV. É a forma mais segura de usar REPLACING.
5. Tipos de copybook em produção
Em sistemas bancários reais, copybooks são organizadas por finalidade. Cada tipo tem uma convenção de prefixo no nome:
*--- TIPO 1: Layout de arquivo (FD + registro) ---*
* Nome: FDxxxx — ex: FDCLIEN, FDMOVTO
FD ARQ-CLIENTE
RECORDING MODE IS F
BLOCK CONTAINS 0 RECORDS
RECORD CONTAINS 100 CHARACTERS.
01 REG-CLIENTE.
05 CLI-CPF PIC X(11).
* ...
*--- TIPO 2: Área de Working Storage ---*
* Nome: WSxxxx — ex: WSCONTS, WSFLAGS, WSDATAS
01 WS-CONTROLES.
05 WS-FIM-ARQ PIC X(01).
88 FIM-ARQUIVO VALUE 'S'.
05 WS-ERRO PIC X(01).
88 HOUVE-ERRO VALUE 'S'.
05 WS-MSG PIC X(80).
*--- TIPO 3: Área de CALL (LINKAGE + parâmetros) ---*
* Nome: LKxxxx ou CPxxxx — ex: LKCLI, CPFPARM
01 LK-AREA-CLIENTE.
05 LK-CPF PIC X(11).
05 LK-RETORNO PIC X(02).
88 LK-OK VALUE '00'.
88 LK-ERRO VALUE '01'.
*--- TIPO 4: Tabelas de código (code tables) ---*
* Nome: TBxxxx — ex: TBERROS, TBSTATUS
01 WS-STATUS-DADOS.
05 VALUE '00'. 05 VALUE 'OK - PROCESSADO'.
05 VALUE '01'. 05 VALUE 'CPF INVALIDO'.
05 VALUE '02'. 05 VALUE 'SALDO INSUFICIENTE'.
01 WS-TAB-STATUS REDEFINES WS-STATUS-DADOS.
05 WS-STATUS OCCURS 3 TIMES
INDEXED BY IDX-ST.
10 ST-CODIGO PIC X(02).
10 ST-DESCR PIC X(18).
*--- TIPO 5: Parágrafo de procedure (reutilizável) ---*
* Nome: PRxxxx — ex: PRCEDT, PRCDATA, PRCCPF
9800-VALIDA-DATA.
MOVE 'N' TO WS-DATA-VALIDA
IF WS-DATA-IN(5:2) > '12'
EXIT PARAGRAPH
END-IF
* ... lógica de validação ...
MOVE 'S' TO WS-DATA-VALIDA.
6. Convenções de nomenclatura
Em produção, os nomes de copybook seguem padrões rígidos definidos pelo time de arquitetura. Um esquema típico em sistemas bancários:
| Prefixo | Tipo | Exemplo | Conteúdo |
|---|---|---|---|
FD | File Description | FDCLIEN | FD + layout do registro de arquivo |
WS | Working Storage | WSCONTS | Contadores, flags, áreas de trabalho |
LK | Linkage | LKPARMS | Área de parâmetros de CALL |
CP | Communication Parameter | CPCLI | Interface completa (WS + LK) de um módulo |
TB | Table | TBERROS | Tabelas internas com dados de referência |
PR | Procedure | PRCEDT | Parágrafos reutilizáveis |
SQ | SQL | SQCLIEN | Área de comunicação DB2 (DCLGEN) |
💗 Para iniciantes — extensão .cpy vs sem extensão
No mainframe, copybooks são membros de um PDS e não têm extensão — o nome do membro é simplesmente FDCLIEN. Em projetos modernos que usam Git e desenvolvimento local (VS Code, zowe), é comum usar a extensão .cpy nos arquivos do repositório: FDCLIEN.cpy. O COPY FDCLIEN. no código continua igual — a extensão é transparente para o compilador.
7. Copybook de interface de CALL
O uso mais crítico de copybooks é padronizar a interface entre programas que se comunicam via CALL. Tanto o chamador quanto o sub-programa incluem a mesma copybook — garantindo que os layouts coincidam:
*----------------------------------------------------------------*
* CPCPF — Interface do módulo de validação de CPF *
* Incluir em WS do CHAMADOR e em LINKAGE do VALCPF *
*----------------------------------------------------------------*
01 CPF-AREA.
05 CPF-NUMERO PIC X(11).
05 CPF-RETORNO PIC X(02).
88 CPF-OK VALUE '00'.
88 CPF-INVALIDO VALUE '01'.
88 CPF-VAZIO VALUE '02'.
88 CPF-TODOS-IGUAIS VALUE '03'.
05 CPF-FILLER PIC X(01).
WORKING-STORAGE SECTION. COPY CPCPF. *inclui CPF-AREA com todos os campos e level 88 PROCEDURE DIVISION. MOVE WS-CPF-ENTRADA TO CPF-NUMERO CALL 'VALCPF' USING CPF-AREA END-CALL EVALUATE TRUE WHEN CPF-OK PERFORM 2000-PROCESSA WHEN CPF-INVALIDO PERFORM 9100-CPF-INVALIDO WHEN CPF-VAZIO PERFORM 9200-CPF-VAZIO WHEN CPF-TODOS-IGUAIS PERFORM 9300-CPF-INVALIDO END-EVALUATE
LINKAGE SECTION. COPY CPCPF. *mesmo layout, garantido pela copybook PROCEDURE DIVISION USING CPF-AREA. 0000-INICIO. PERFORM 1000-VALIDA GOBACK. 1000-VALIDA. IF CPF-NUMERO = SPACES SET CPF-VAZIO TO TRUE EXIT PARAGRAPH END-IF * ... lógica de validação ... SET CPF-OK TO TRUE.
🟣 Para quem já programa — DCLGEN (DB2)
No DB2, existe um gerador automático de copybooks chamado DCLGEN (Declarations Generator). Ele lê a definição de uma tabela do catálogo DB2 e gera automaticamente uma copybook com a área de host variables e o DECLARE TABLE para uso no programa COBOL. Nunca escreva manualmente os host variables de uma tabela DB2 — sempre use o DCLGEN. Isso garante que os tipos de dados COBOL coincidam exatamente com a definição da tabela, e quando a tabela mudar, você regenera a copybook e recompila.
8. Exemplo completo
Um sistema simples com três membros: uma copybook de layout, um sub-programa de cálculo e um programa principal — todos ligados pela mesma copybook:
*----------------------------------------------------------------*
* CPCONTR — Layout de contrato + área de retorno *
*----------------------------------------------------------------*
01 CONTR-AREA.
05 CT-NUMERO PIC 9(10).
05 CT-CPF-CLIENTE PIC X(11).
05 CT-VALOR PIC S9(11)V99.
05 CT-TAXA-MES PIC V9(06).
05 CT-PRAZO PIC 9(03).
05 CT-PARCELA PIC S9(09)V99.
05 CT-TOTAL-JUROS PIC S9(11)V99.
05 CT-STATUS PIC X(02).
88 CT-CALCULADO VALUE '00'.
88 CT-PRAZO-ZERO VALUE '01'.
88 CT-TAXA-ZERO VALUE '02'.
88 CT-VALOR-ZERO VALUE '03'.
05 CT-FILLER PIC X(04).
IDENTIFICATION DIVISION. PROGRAM-ID. CALCCONTR. DATA DIVISION. WORKING-STORAGE SECTION. 01 WS-FATOR PIC 9(03)V9(10). LINKAGE SECTION. COPY CPCONTR. *inclui CONTR-AREA PROCEDURE DIVISION USING CONTR-AREA. 0000-INICIO. EVALUATE TRUE WHEN CT-VALOR = 0 SET CT-VALOR-ZERO TO TRUE WHEN CT-TAXA-MES = 0 SET CT-TAXA-ZERO TO TRUE WHEN CT-PRAZO = 0 SET CT-PRAZO-ZERO TO TRUE WHEN OTHER PERFORM 1000-CALCULA SET CT-CALCULADO TO TRUE END-EVALUATE GOBACK. 1000-CALCULA. * Parcela Price simplificada: PV * i / (1 - (1+i)^-n) COMPUTE CT-PARCELA = CT-VALOR * CT-TAXA-MES COMPUTE CT-TOTAL-JUROS = (CT-PARCELA * CT-PRAZO) - CT-VALOR.
IDENTIFICATION DIVISION. PROGRAM-ID. PROCCONTR. DATA DIVISION. WORKING-STORAGE SECTION. COPY CPCONTR. *mesma copybook — layout garantido 01 WS-FS-CONTR PIC X(02). 01 WS-FIM PIC X(01). 88 FIM-ARQ VALUE 'S'. PROCEDURE DIVISION. 0000-INICIO. OPEN INPUT ARQ-CONTRATOS OUTPUT ARQ-RESULTADO MOVE 'N' TO WS-FIM READ ARQ-CONTRATOS INTO CONTR-AREA AT END SET FIM-ARQ TO TRUE END-READ PERFORM UNTIL FIM-ARQ CALL 'CALCCONTR' USING CONTR-AREA END-CALL IF NOT CT-CALCULADO PERFORM 9000-TRATA-ERRO ELSE WRITE REG-RESULTADO FROM CONTR-AREA END-IF READ ARQ-CONTRATOS INTO CONTR-AREA AT END SET FIM-ARQ TO TRUE END-READ END-PERFORM CLOSE ARQ-CONTRATOS ARQ-RESULTADO STOP RUN.
9. Erros comuns
1. Incluir a mesma copybook duas vezes sem REPLACING
* ERRADO: dois COPY da mesma copybook geram nomes duplicados 01 WS-ENTRADA. COPY CPFMOV. *declara MV-CPF, MV-DATA, MV-VALOR 01 WS-SAIDA. COPY CPFMOV. *ERRO: MV-CPF já foi declarado! * CORRETO: use REPLACING para diferenciar os nomes 01 WS-ENTRADA. COPY CPFMOV REPLACING ==MV== BY EN. *EN-CPF, EN-DATA... 01 WS-SAIDA. COPY CPFMOV REPLACING ==MV== BY SA. *SA-CPF, SA-DATA...
2. Modificar a copybook diretamente no programa
* ERRADO: adicionar campo à copybook "para resolver" um programa * Todos os outros programas que usam essa copybook * serão afetados — e o arquivo físico muda de tamanho! * CORRETO: se precisa de campo extra, declare em WS separado COPY CPFCLI. *mantém a copybook original intacta 01 WS-EXTENSAO-CLI. *campos adicionais só para este programa 05 WS-CLI-SCORE PIC 9(03). 05 WS-CLI-RISCO PIC X(01).
3. Copybook com ponto final causando problema em nível 01
*--- Copybook com ponto indevido no último campo ---*
01 REG-CLIENTE.
05 CLI-CPF PIC X(11).
05 CLI-NOME PIC X(40). *← ponto aqui termina o 01!
* No programa, após o COPY, o campo seguinte fica solto:
COPY CPFCLI.
05 WS-EXTRA PIC X(10). *erro: não pertence a nenhum 01
* CORRETO: copybooks NÃO devem ter ponto final no último item
* O ponto que fecha o grupo vem do programa, não da copybook
⚠️ Pontos dentro de copybooks de dados
Copybooks que contêm apenas declarações de dados (sem parágrafos) não devem ter ponto no último campo. Se a copybook termina com ponto, o compilador entende que a estrutura foi encerrada — e qualquer campo declarado depois, ainda dentro do mesmo 01 no programa, vira um grupo solto sem pai. Copybooks de PROCEDURE DIVISION (parágrafos) sim precisam de ponto ao final de cada parágrafo.