COBOL AWO Compiler Option: APPLY WRITE-ONLY for QSAM Files

A COBOL job that writes variable-length QSAM records can waste output buffer space when every block is cut for the largest possible record. The AWO compiler option applies APPLY WRITE-ONLY behavior to eligible files, so the buffer is written only when the next record will not fit. On the right file shape, that can reduce EXCPs and improve batch run time.

Use AWO for eligible VB output.

What is the COBOL AWO compiler option?

AWO stands for APPLY WRITE-ONLY. IBM documents that it activates APPLY WRITE-ONLY processing for physical sequential files with variable blocked format. The default is NOAWO.

In practical terms, AWO helps COBOL use output blocks more efficiently for QSAM files that have variable-length blocked records. It is a file-output option, not a general CPU tuning switch for every program.

AWO vs NOAWO

Option	Behavior	Good fit
NOAWO	Does not add implicit APPLY WRITE-ONLY to eligible files.	Programs that do not write variable blocked QSAM output, or programs where existing behavior must stay unchanged.
AWO	Applies APPLY WRITE-ONLY processing to eligible files.	Programs that write blocked variable-length QSAM files, especially when record sizes vary a lot.

How APPLY WRITE-ONLY changes buffering

Without APPLY WRITE-ONLY, the buffer can be written when there is not enough space left for the maximum-size record. With APPLY WRITE-ONLY, the buffer is written only when the next actual record does not fit in the unused part of the buffer.

That difference matters when output records vary in size. If many records are much smaller than the maximum record length, the program can fit more records into each block and issue fewer I/O calls.

Eligible file shape

AWO matters for physical sequential QSAM files with blocked variable-length records. It does not help a fixed-block file in the same way, and it is not meant for VSAM output.

SELECT OUT-FILE ASSIGN TO OUTDD.

FD  OUT-FILE
    RECORDING MODE IS V
    BLOCK CONTAINS 0 RECORDS.
01  OUT-REC.
    05 OUT-ID      PIC X(10).
    05 OUT-TEXT    PIC X(500).

The file must still be defined correctly in JCL. Check RECFM=VB, LRECL, and block-size rules with the storage and operations standards used at your site.

How to specify AWO

The exact place depends on your compile procedure. Some shops set compiler options in cataloged procedures or build tools. For a source-level example, the option can appear in a CBL statement.

CBL AWO

IDENTIFICATION DIVISION.
PROGRAM-ID. WRITVB.

ENVIRONMENT DIVISION.
INPUT-OUTPUT SECTION.
FILE-CONTROL.
    SELECT OUT-FILE ASSIGN TO OUTDD.

Keep the compile listing or build record with the change. AWO is easy to forget because it changes generated file handling code without changing the visible WRITE statement.

Performance expectation

IBM performance guidance says AWO can save time because fewer calls are made to data management services for input and output handling. IBM also gives examples where programs writing variable-length files ran faster with fewer EXCPs. Treat those examples as proof that the option can matter, not as a promise for every program.

The biggest gains usually come from output files with large variation in record length. If every output record is close to the maximum length, there may be little room to improve block usage.

AWO and BLOCK0

BLOCK0 can make more physical sequential files use system-determined block sizes when the FD does not specify a block size. IBM notes that when BLOCK0 is in effect, AWO might apply to more files because more files may become blocked.

That interaction is useful, but it also means the change deserves testing. A compile-option change can affect more files than the one the developer had in mind.

When to avoid AWO

Avoid treating AWO as a blanket answer for all I/O performance problems. It is useful only for a specific file pattern. Be careful when a job depends on immediate write behavior, custom recovery assumptions, or exact timing of output availability during execution.

If the written record must be forced out as soon as possible, IBM performance guidance recommends avoiding AWO. That is uncommon for ordinary batch output files, but it can matter for special operational files.

Review checklist before changing AWO

• Confirm the file is physical sequential QSAM output.
• Confirm the records are variable-length and blocked.
• Check whether record sizes vary enough to benefit from better buffer use.
• Review BLOCK0 because it can increase the files where AWO applies.
• Compare EXCP count, CPU time, and elapsed time before and after the compile change.
• Keep the compiler listing and JCL evidence with the change record.

Common mistakes

Using AWO on the wrong file type

AWO is not a VSAM tuning option and does not help ordinary fixed-block files in the same way. Start by checking the FD and JCL.

Ignoring the block-size setup

AWO works with blocked variable-length output. If the file is not blocked, review BLOCK CONTAINS, BLOCK0, and the JCL before expecting a result.

Comparing only elapsed time

Elapsed time can move because of system load. Compare EXCPs and CPU time too, especially when the job runs in a busy batch window.

Related Mainframe Forum guides

For nearby topics, read COBOL fixed vs variable-length records, COBOL file organization, COBOL WRITE statement, COBOL BLOCK0 compiler option, and COBOL performance tuning.

External references

IBM documents performance-related compiler options, APPLY WRITE-ONLY buffer behavior, and Enterprise COBOL option comparison.

FAQ

What does AWO do in COBOL?

AWO applies APPLY WRITE-ONLY processing to eligible physical sequential files with variable blocked records.

What is the default for AWO?

IBM documents the default as NOAWO, meaning the compiler does not implicitly apply APPLY WRITE-ONLY to eligible files.

When does AWO help most?

AWO helps most when a program writes blocked variable-length QSAM records and the actual record sizes vary enough to improve buffer use.

Does AWO apply to VSAM files?

No. The AWO compiler option is for eligible physical sequential QSAM files, not VSAM files.

JCL Spanned Records: RECFM=VBS, LRECL=X, and Safe Usage

A JCL DD statement with DCB=(RECFM=VBS,LRECL=X) tells z/OS that a logical record may be too large to fit in one physical block. The record is still one record to the program, but the access method can store it as segments across more than one block.

One record can span blocks.

What is a spanned record in JCL?

A spanned record is a variable-length logical record that is stored in pieces when the full record does not fit into a single block. You normally see this on sequential data sets that carry long business records, large print records, XML-like payloads, or converted reports where one logical row can grow past the normal block boundary.

In everyday batch work, most files use FB or VB. A fixed blocked file has the same record length on every row. A variable blocked file can hold records of different sizes, but each logical record still fits inside a block. A spanned variable file, commonly coded as VBS, allows one logical record to continue into the next block when needed.

When should you use RECFM=VBS?

Use RECFM=VBS only when the application has a real need for very long variable records. It is not a default choice for normal transaction files, control files, extract files, or small report feeds. If every record is short enough for a normal VB file, keeping RECFM=VB is simpler and easier for downstream jobs to handle.

Record format	Meaning	Common use
FB	Fixed blocked records	Flat files where every record has the same length
VB	Variable blocked records	Files where records have different lengths but fit inside a block
VBS	Variable blocked spanned records	Files where one logical record may need more than one block

JCL example for a spanned record data set

The DD statement usually carries the record format in the DCB parameter. Existing shops may also let SMS data classes supply these attributes, so check local standards before hard-coding every value.

//STEP010  EXEC PGM=MYPROG
//OUTFILE  DD  DSN=PROD.REPORT.LONGREC,
//             DISP=(NEW,CATLG,DELETE),
//             SPACE=(CYL,(20,10),RLSE),
//             DCB=(RECFM=VBS,LRECL=X)

The LRECL=X part is used for QSAM when the logical record length can be greater than 32,760 bytes. That is the detail many short notes miss. Without it, someone may copy RECFM=VBS into a job and still fail when the record length is not described correctly for the access method and program.

How RDW, BDW, and segments fit together

Variable records include a record descriptor word, usually called an RDW. Variable blocked records also use a block descriptor word, usually called a BDW, at the start of a block. In a spanned file, z/OS needs extra segment information so it can rebuild the logical record correctly when the record has been split across blocks.

For a COBOL or assembler program, the useful rule is simple: the program should process the logical record, not guess at physical block pieces. If a program reads the file through the normal access method, it should receive the data according to the file definition and program definition. Problems usually appear when a utility, copy program, FTP setup, or downstream reader assumes ordinary VB records.

Why DISP=MOD can be risky with spanned records

The old warning about DISP=MOD is worth keeping. Appending to a spanned-record data set can introduce short-block behavior that surprises later processing. If a job must add more records, the safer pattern is often to create a new output data set and copy or merge the old and new data with a controlled utility step.

//BADAPPND DD DSN=PROD.REPORT.LONGREC,
//            DISP=MOD
//*
//* Better: build a new output generation, then replace by standard process.

That approach also gives operations a cleaner restart point. A failed append can leave the support team asking whether the last logical record was complete, whether the block was closed correctly, and which downstream job consumed the partial file.

Checks before using a spanned record file

Before moving this kind of file into production, check the data set attributes, the program definition, and every job that reads the file. One weak reader in a later step can turn a good file design into a late-night incident.

• Confirm that the producing program really needs records larger than a normal variable blocked file can handle.
• Check whether the consumer supports RECFM=VBS, especially sort, copy, transfer, reporting, and unload steps.
• Use a naming standard or comment that tells support staff why the file is spanned.
• Avoid casual append processing with DISP=MOD.
• Test the longest realistic record, not only a small sample file.

Common mistakes

Using VBS for a normal file

Some developers use VBS because it sounds more flexible than VB. That adds a special case where none is needed. If the largest record is comfortably within the normal limit, VB is usually easier for utilities and support teams.

Forgetting the downstream jobs

A file may be created correctly and still fail in a later step. Check any JCL SORT, copy, archive, and transfer process that reads the data set.

Copying only the DCB line

The DCB line is only one part of the design. Space allocation, restart rules, file transfer rules, and program record definitions must match the expected long records.

Related Mainframe Forum guides

For the surrounding JCL basics, read JCL Tutorial: JOB, EXEC and DD Statements, JCL DD Statement, and JCL Data Set Protection. If the output is kept as generations, also review Generation Data Group in JCL.

External references

IBM documents the main record formats, including fixed, variable, blocked, undefined, and spanned formats, in its z/OS record-format material. See IBM: Data set record formats and IBM: Record formats for the formal wording.

FAQ

What does RECFM=VBS mean?

RECFM=VBS means variable blocked spanned records. Records can have different lengths, more than one record can be placed in a block, and a single logical record can continue into another block.

Is RECFM=VBS the same as RECFM=VB?

No. VB handles variable blocked records where each logical record fits in a block. VBS handles variable blocked records that may span blocks.

Why is LRECL=X used with spanned records?

For QSAM, LRECL=X indicates that the logical record length can be greater than 32,760 bytes. Use it only when the program and data set design require that behavior.

Should I use DISP=MOD with spanned records?

Avoid it unless your site has a tested standard for that exact case. Creating a new output data set is usually easier to restart, audit, and support.