IEBDG Utility JCL: Generate Test Data with DSD, FD, and CREATE

A regression test needs hundreds or thousands of records whose values change in a controlled way. Writing those records by hand is slow, and copying production data can introduce privacy and repeatability problems. The IEBDG utility can build predictable z/OS test data from field definitions and generation rules in one batch step.

IEBDG selects an output DD, defines fields, creates records, and writes a repeatable test data set.

What the IEBDG utility does

IEBDG is an IBM data-set utility that generates test records. It can construct records from IBM-supplied patterns, constants, and user-defined pictures; vary selected fields from record to record; and overlay fields in an existing input data set. Its purpose is controlled test-data generation, not copying files or producing cryptographically secure random values.

IEBDG is useful when a developer needs repeatable data for program testing, sort exercises, file-volume tests, or record-layout validation. For a broader view of batch tools, see the JCL utility overview.

IEBDG JCL structure and DD statements

Statement	Purpose	Required?
EXEC PGM=IEBDG	Runs the IEBDG utility.	Yes
SYSPRINT DD	Receives utility messages, diagnostics, and a listing of control statements.	Yes
Output DD	Names the sequential or partitioned data set that receives generated records.	At least one
Input DD	Supplies records when IEBDG will copy and overlay existing input.	Only for input processing
SYSIN DD *	Contains DSD, FD, CREATE, REPEAT, and END control statements.	Yes

The DD name referenced by DSD OUTPUT=(ddname) must exactly match an output DD statement in the same step. That simple naming rule prevents one of the most common IEBDG setup errors.

How DSD, FD, CREATE, and END work together

1. DSD begins a control-statement set and identifies its output and optional input DD names.
2. FD defines a field's length, content pattern, location, and change action.
3. CREATE assembles the named fields or a picture into output records and specifies how many to produce.
4. REPEAT, when used, repeats CREATE statements or groups of CREATE statements.
5. END closes the control-statement set.

A step can contain more than one DSD-to-END set. Each set can target a different output DD, so one execution can generate several related test files.

Complete IEBDG utility JCL example

//GENDATA JOB (ACCT),'IEBDG TEST',CLASS=A,MSGCLASS=X
//STEP01  EXEC PGM=IEBDG
//SYSPRINT DD SYSOUT=*
//OUTDATA DD DSN=USER.TEST.IEBDG,
//            DISP=(NEW,CATLG,DELETE),
//            SPACE=(CYL,(2,1)),
//            DCB=(RECFM=FB,LRECL=80,BLKSIZE=0)
//SYSIN   DD *
  DSD OUTPUT=(OUTDATA)
  FD NAME=ID,LENGTH=8,FORMAT=AN,ACTION=RP
  FD NAME=LABEL,LENGTH=12,PICTURE=12,'TEST RECORD '
  FD NAME=RANDOM,LENGTH=20,FORMAT=RA
  CREATE QUANTITY=1000,FILL=X'40',NAME=(ID,LABEL,RANDOM)
  END
/*

This sample creates 1,000 fixed 80-byte records. The three named fields occupy the first 40 bytes. FILL=X'40' initializes the rest of each record to EBCDIC blanks before the fields are placed. Change the data-set name, JOB parameters, storage class behavior, and space values to match local standards.

Why this example differs from many old samples: the DSD output name and the DD name are both OUTDATA, BLKSIZE=0 lets system-determined block size apply, and no fixed volume serial or device type is assumed. A site can still require explicit storage parameters.

Line-by-line explanation

EXEC PGM=IEBDG starts the utility, while SYSPRINT captures its messages. The OUTDATA DD allocates a new cataloged FB data set with an 80-byte logical record length. If the step fails, the DELETE disposition removes the incomplete new data set.

The DSD statement directs this control set to OUTDATA. The first FD defines an eight-byte alphanumeric field with a ripple action. LABEL supplies a fixed 12-byte literal. RANDOM uses IEBDG's random binary format for a 20-byte field. CREATE places the fields in NAME order, produces 1,000 records, and leaves the unused bytes as the selected fill character.

FD formats and pictures

An FD statement gives a field a name and describes the bytes IEBDG should supply. Common choices include the following:

Definition	Use	Planning note
FORMAT=AL	Alphabetic pattern	Useful for letter-only test values.
FORMAT=AN	Alphanumeric pattern	Useful for general display fields and identifiers.
FORMAT=CO	Collating-sequence pattern	Useful when exercising byte ordering.
FORMAT=ZD	Zoned-decimal pattern	Match length and sign expectations in the consuming program.
FORMAT=PD	Packed-decimal pattern	Verify precision, sign, and field size against the copybook.
FORMAT=BI	Binary pattern	Interpretation depends on the target field's binary definition.
FORMAT=RA	Random binary data	Good for varied bytes, but not security-sensitive randomness.
PICTURE=n,'text'	User-supplied repeating or literal pattern	Count the intended field bytes carefully.

Use the exact format and picture rules documented for the installed z/OS release. A value that merely looks numeric on a report is not interchangeable with packed decimal or binary storage.

FD ACTION values

ACTION controls how an IBM-supplied pattern changes across generated records. The supported action codes provide fixed, ripple, roll, shift, truncate, and wave behavior:

Action	Meaning	Typical testing use
FX	Fixed	Keep the field unchanged.
RO	Roll	Rotate a pattern through positions.
RP	Ripple	Vary values progressively between records.
SL / SR	Shift left / right	Exercise changing alignment.
TL / TR	Truncate left / right	Test shortening pattern content.
WV	Wave	Cycle a pattern back and forth.

Choose an action because it exercises a specific rule in the application. Test records are more useful when each changing field has a known purpose and expected result.

Fixed fields and literal values

Not every field should vary. Constants identify a scenario or keep mandatory values valid while another field changes. A picture can define a fixed label:

FD NAME=TYPE-CODE,LENGTH=2,PICTURE=2,'01'
FD NAME=SOURCE,LENGTH=8,PICTURE=8,'IEBDG   '
CREATE QUANTITY=100,NAME=(TYPE-CODE,SOURCE)

Include trailing blanks deliberately when a literal must fill a fixed-width field. Otherwise select a suitable CREATE fill value and place only the meaningful bytes.

Record layout, field order, and fill bytes

When CREATE names fields, IEBDG places them in the order shown unless location parameters direct otherwise. Later fields can overwrite earlier bytes when definitions overlap. That can be useful for an overlay test, but it can also hide a layout mistake.

Compare the total generated layout with the output LRECL. If named fields do not occupy the whole record, the initialized fill bytes remain. If fields or explicit starting locations extend beyond the intended record, correct the control statements rather than relying on truncation. The JCL DD statement guide explains the surrounding allocation parameters.

CREATE QUANTITY versus REPEAT

CREATE QUANTITY=n constructs the requested number of records from one CREATE definition. REPEAT is useful when a scenario contains several CREATE statements that must recur as a group.

DSD OUTPUT=(OUTDATA)
FD NAME=HEADER,LENGTH=8,PICTURE=8,'HEADER  '
FD NAME=DETAIL,LENGTH=8,PICTURE=8,'DETAIL  '
CREATE QUANTITY=1,NAME=(HEADER)
CREATE QUANTITY=5,NAME=(DETAIL)
REPEAT CREATE=2,QUANTITY=10
END

Here REPEAT applies to a group of CREATE statements according to its CREATE operand. IBM documents a maximum REPEAT QUANTITY of 65,535. For very large files, calculate allocation from expected record count and LRECL, then confirm the result under local SMS and storage policies.

Overlay fields in an existing input data set

IEBDG can read input records and replace selected fields while retaining the rest. DSD identifies both input and output DD names; input-related operands on FD or CREATE select the source bytes. This technique can preserve a safe test record structure while changing keys, dates, or status fields.

//INDATA  DD DSN=USER.TEST.INPUT,DISP=SHR
//OUTDATA DD DSN=USER.TEST.OVERLAY,
//            DISP=(NEW,CATLG,DELETE),
//            SPACE=(CYL,(2,1)),
//            DCB=*.INDATA
//SYSIN   DD *
  DSD INPUT=(INDATA),OUTPUT=(OUTDATA)
  ... input and field definitions for the required overlay ...
  END
/*

Do not treat an overlay as automatic anonymization. Fields that are not replaced remain from the input. Use approved nonproduction sources and validate every sensitive field before sharing or retaining the output.

Generate multiple data sets in one step

Add another output DD and a separate DSD-to-END set when a test needs related files, such as a valid master file and a transaction file containing controlled exceptions:

DSD OUTPUT=(MASTER)
  ... FD and CREATE statements ...
END
DSD OUTPUT=(TRANS)
  ... FD and CREATE statements ...
END

Keep each set self-contained and verify every referenced DD name. Separate sets also make it easier to recognize which control statements produced a failing output.

IEBDG user exits

For generation logic that control statements cannot express, CREATE can invoke a user routine through its EXIT operand. The exit receives control during record construction and can write a record, skip it, bypass the current set, or request termination through documented return codes.

A user exit adds program maintenance and operational dependencies, so use built-in formats, pictures, and actions when they are sufficient. If an exit is required, document its load-library location, interface assumptions, and return-code handling.

IEBDG return codes

Return code	Meaning	Response
00	Successful completion	Still verify record count and representative field values.
04	A user exit requested termination	Review the exit's logic and SYSPRINT messages.
08	A control-statement error occurred	Correct the named statement; later control sets may have continued.
12	An input or output data-set error occurred	Check allocation, DCB attributes, access, and DD names.
16	An unrecoverable error ended processing	Use SYSPRINT and job-log messages to find the failing resource or statement.

Return code alone is not enough evidence that the data is suitable. Confirm the generated count, record length, field encoding, boundary cases, and application results.

Common IEBDG errors and fixes

• DSD and DD names differ: make OUTPUT=(name) identical to the JCL DD name.
• Wrong record attributes: align RECFM and LRECL with the generated layout and consuming program.
• Unexpected binary zeros or blanks: choose CREATE FILL explicitly and inspect unused bytes.
• Bad packed or zoned data: match FORMAT, length, sign, and precision to the copybook.
• Overlapping fields: review STARTLOC and placement order; the later field can overwrite earlier bytes.
• Space failure: estimate output from record count and LRECL, then allow for blocking and local allocation rules.
• Wrong record count: distinguish CREATE QUANTITY from REPEAT QUANTITY and any input limits.
• No useful diagnostic: retain SYSPRINT and inspect the first reported control-statement error.

IEBDG production checklist

1. Confirm that generated rather than copied data is appropriate for the test.
2. Match each DSD input and output name to an actual DD statement.
3. Reconcile field lengths and locations with the copybook and output LRECL.
4. Select FORMAT, ACTION, PICTURE, and FILL values deliberately.
5. Estimate record count and allocate space under current site standards.
6. Run a small sample first and inspect records in hex when binary formats are present.
7. Check SYSPRINT, step return code, catalog result, and generated record count.
8. Test boundary and invalid values, not only normal records.

Use IEBGENER when the main job is copying or reformatting sequential data, IEBCOPY for partitioned data sets, IEBCOMPR for data-set comparison, and IEFBR14 when allocation or disposition processing is the real requirement. The JCL tutorial connects these utilities to JOB, EXEC, and DD fundamentals.

Official IBM IEBDG references

• IEBDG utility overview and basic example
• IEBDG utility control statements
• IEBDG job control statements
• CREATE statement
• FD statement
• DSD statement
• REPEAT statement
• IEBDG examples
• Using an IEBDG exit routine

Frequently asked questions

What is IEBDG in JCL?

IEBDG is an IBM z/OS data-set utility that creates patterned test records or overlays selected fields in input records. JCL supplies the input, output, SYSPRINT, and SYSIN DD statements; utility control statements define the generated data.

What is the difference between DSD, FD, and CREATE?

DSD begins a generation set and selects its data sets. FD defines reusable field content and behavior. CREATE assembles those fields into output records and controls how many records are generated.

Why does DSD OUTPUT not find my data set?

The value inside OUTPUT=(ddname) must be a DD name in the same IEBDG step, not a cataloged data-set name. Check spelling, continuation, and whether the DD appears in the correct step.

Can IEBDG generate random test data?

IEBDG provides random binary and changing pattern formats for test data. Those values are intended to exercise applications; they are not a substitute for a cryptographic random-number generator or a complete privacy-safe synthetic-data process.