TSO File and Dataset Handling Commands

TSO provides powerful commands for handling files and datasets on the mainframe. Understanding these commands is essential for managing data, copying files, viewing contents, and working with dataset attributes. This tutorial covers the key TSO commands for dataset handling: ALLOCATE, FREE, REPRO, PRINT, and LISTDS.

These commands form the foundation of dataset operations in TSO. While ISPF provides menu-driven interfaces for many of these operations, knowing the TSO command syntax gives you flexibility, enables scripting, and allows you to perform operations from the command line efficiently.

ALLOCATE Command

The ALLOCATE command associates a dataset with a DD (Data Definition) name, making it available for use by programs or TSO commands. Allocation is a fundamental operation that connects datasets to the programs and commands that need to access them.

Basic ALLOCATE Syntax

The basic syntax for ALLOCATE is:

1
ALLOCATE FILE(DDNAME) DATASET('DSNAME') [options]

Where:

• FILE(DDNAME) specifies the DD name to assign to the dataset. DD names are used by programs to reference datasets.
• DATASET('DSNAME') specifies the dataset name to allocate. Dataset names are typically quoted.
• [options] are optional qualifiers that control how the dataset is allocated.

ALLOCATE Options

Common ALLOCATE options include:

• SHR: Allocates for shared access, allowing multiple users or jobs to access the dataset simultaneously. This is common for read operations.
• OLD: Allocates for exclusive access. Only one user or job can access it. Use OLD when you need exclusive write access.
• NEW: Allocates a new dataset. Use when creating a new dataset rather than accessing an existing one.
• MOD: Opens the dataset in modification mode, allowing you to append to it.
• REUSE: Allows reusing an existing allocation if the DD name is already allocated.
• VOLUME('VOLSER'): Specifies a particular volume for the dataset.
• UNIT('UNITNAME'): Specifies a device unit for allocation.

ALLOCATE Examples

Allocate a dataset for shared read access:

1
ALLOCATE FILE(INPUT) DATASET('USERID.SOURCE.COBOL') SHR

Allocate a dataset for exclusive write access:

1
ALLOCATE FILE(OUTPUT) DATASET('USERID.OUTPUT.DATA') OLD

Allocate a new dataset:

1
2
3
ALLOCATE FILE(NEWFILE) DATASET('USERID.NEW.DATA') NEW -
SPACE(TRK,(10,5)) -
RECFM(FB) LRECL(80) BLKSIZE(3120)

FREE Command

The FREE command releases an allocation, freeing the DD name and making it available for other uses. FREE is important for resource management and cleanup.

Basic FREE Syntax

To free a specific allocation:

1
FREE FILE(DDNAME)

To free all allocations:

1
FREE ALL

When to Use FREE

Use FREE when:

• You're done using an allocated dataset and want to release the allocation
• You need to free a DD name for a different allocation
• You want to clean up allocations before ending your session
• An allocation is no longer needed and you want to release system resources

While allocations are automatically freed when you log off, it's good practice to explicitly free allocations when you're done with them, especially in scripts or long-running sessions.

FREE Examples

Free a specific allocation:

1
FREE FILE(INPUT)

Free all current allocations:

1
FREE ALL

REPRO Command

The REPRO command copies data from one dataset to another. REPRO can copy entire datasets or specific members from partitioned datasets, making it useful for backing up data, duplicating datasets, or copying data between locations.

Basic REPRO Syntax

To copy data using REPRO, you first allocate both the input and output datasets, then use REPRO:

1
2
3
4
ALLOCATE FILE(INFILE) DATASET('SOURCE.DSNAME') SHR
ALLOCATE FILE(OUTFILE) DATASET('TARGET.DSNAME') OLD
REPRO INFILE(INFILE) OUTFILE(OUTFILE)
FREE FILE(INFILE) FILE(OUTFILE)

REPRO Options

REPRO supports various options:

• INFILE(DDNAME): Specifies the input dataset DD name.
• OUTFILE(DDNAME): Specifies the output dataset DD name.
• REPLACE: Replaces existing data in the output dataset.
• NOREAD: Skips reading certain records (advanced option).

REPRO Examples

Copy an entire sequential dataset:

1
2
3
4
ALLOCATE FILE(IN) DATASET('USERID.SOURCE.DATA') SHR
ALLOCATE FILE(OUT) DATASET('USERID.BACKUP.DATA') OLD
REPRO INFILE(IN) OUTFILE(OUT)
FREE FILE(IN) FILE(OUT)

Copy a member from a PDS:

1
2
3
4
ALLOCATE FILE(IN) DATASET('USERID.SOURCE.COBOL(MEMBER1)') SHR
ALLOCATE FILE(OUT) DATASET('USERID.BACKUP.COBOL(MEMBER1)') OLD
REPRO INFILE(IN) OUTFILE(OUT)
FREE FILE(IN) FILE(OUT)

PRINT Command

The PRINT command displays dataset contents on your terminal or sends them to a printer. PRINT is useful for viewing dataset contents, generating printed output, or examining data.

Basic PRINT Syntax

To print dataset contents to your terminal:

1
PRINT 'USERID.SOURCE.COBOL'

To send output to a printer:

1
PRINT 'USERID.SOURCE.COBOL' DEST(printername)

PRINT Options

PRINT may support options like:

• DEST(printername): Sends output to a specific printer.
• COPIES(n): Specifies the number of copies to print.
• CHAR: Prints in character format.
• HEX: Prints in hexadecimal format.

PRINT Examples

Display dataset contents on terminal:

1
PRINT 'USERID.SOURCE.COBOL'

Print a specific member:

1
PRINT 'USERID.SOURCE.COBOL(MEMBER1)'

LISTDS Command

The LISTDS command displays dataset attributes and information. LISTDS helps you understand dataset structure, properties, and characteristics.

Basic LISTDS Syntax

To list dataset information:

1
LISTDS 'USERID.SOURCE.COBOL'

LISTDS Output

LISTDS displays information including:

• Dataset Name: The full dataset name
• Organization: Dataset organization (PS, PDS, PDSE, etc.)
• Record Format (RECFM): The record format (F, V, U, FB, VB, etc.)
• Record Length (LRECL): The logical record length
• Block Size (BLKSIZE): The block size
• Volume Information: Volume serial numbers where the dataset resides
• Space Information: Space allocation details
• Catalog Status: Whether the dataset is cataloged
• Creation Date: When the dataset was created
• Last Referenced: When the dataset was last accessed

LISTDS Options

LISTDS may support options like:

• MEMBERS: For PDS datasets, lists all members
• VOLUME: Shows volume information
• HISTORY: Shows dataset history information

LISTDS Examples

List basic dataset information:

1
LISTDS 'USERID.SOURCE.COBOL'

List dataset information with members (for PDS):

1
LISTDS 'USERID.SOURCE.COBOL' MEMBERS

Working with These Commands Together

These commands are often used together in workflows. Here's an example workflow:

Example: Copying and Examining a Dataset

A complete workflow might look like:

1
2
3
4
5
6
7
LISTDS 'USERID.SOURCE.COBOL'
ALLOCATE FILE(IN) DATASET('USERID.SOURCE.COBOL') SHR
ALLOCATE FILE(OUT) DATASET('USERID.BACKUP.COBOL') OLD
REPRO INFILE(IN) OUTFILE(OUT)
FREE FILE(IN) FILE(OUT)
LISTDS 'USERID.BACKUP.COBOL'
PRINT 'USERID.BACKUP.COBOL'

This workflow:

• Lists information about the source dataset
• Allocates both source and target datasets
• Copies the data using REPRO
• Frees the allocations
• Lists information about the copied dataset
• Prints the copied dataset to verify

Best Practices for Dataset Handling Commands

Following best practices helps you use these commands effectively and safely:

• Always FREE Allocations: Free allocations when done to release resources and avoid conflicts.
• Verify Before Operations: Use LISTDS to verify dataset attributes before operations like REPRO.
• Check Space: Ensure target datasets have sufficient space before copying with REPRO.
• Use Appropriate Access Modes: Use SHR for read operations and OLD for write operations.
• Verify Dataset Names: Always verify dataset names before operations, especially DELETE or destructive operations.
• Test with PRINT: Use PRINT to verify dataset contents after operations like REPRO.
• Use LISTDS for Information: Use LISTDS to understand dataset structure before working with it.
• Clean Up: Always clean up allocations (FREE) when done, especially in scripts.

Common Use Cases

These commands are commonly used for:

• Backing Up Data: Using REPRO to create backups of important datasets
• Data Migration: Copying data between systems or locations using REPRO
• Dataset Inspection: Using LISTDS and PRINT to examine dataset contents and attributes
• Program Preparation: Using ALLOCATE to prepare datasets for program execution
• Resource Management: Using FREE to manage system resources and allocations
• Data Verification: Using PRINT to verify data after operations
• Attribute Checking: Using LISTDS to check dataset attributes before operations

Explain Like I'm 5: Dataset Handling Commands

Think of dataset handling commands like tools for working with filing cabinets:

• ALLOCATE is like opening a drawer and putting a label on it. You're telling the computer "this drawer (DD name) now holds this file (dataset)".
• FREE is like closing the drawer and taking the label off when you're done, so someone else can use that drawer name.
• REPRO is like making a photocopy. You take a file from one drawer, copy everything in it, and put the copy in another drawer.
• PRINT is like looking at what's in a file or making a paper copy. You can see what's in the file on your screen or send it to a printer.
• LISTDS is like reading the label on a file folder. It tells you what kind of file it is, how big it is, when it was made, and other important information.

So these commands help you work with the computer's filing system, opening drawers, copying files, looking at what's inside, and reading the labels!

Practice Exercises

Complete these exercises to reinforce your understanding of TSO dataset handling commands:

Exercise 1: Allocation Practice

Practice allocating datasets with different options. Allocate a dataset with SHR, then with OLD. Use LISTDS to verify the allocations. Practice freeing allocations individually and with FREE ALL. Document your experiences.

Exercise 2: REPRO Workflow

Create a complete workflow using REPRO: allocate source and target datasets, copy data using REPRO, verify the copy with LISTDS and PRINT, then free the allocations. Practice this workflow until it becomes natural.

Exercise 3: Dataset Inspection

Use LISTDS to examine various datasets in your environment. Document the attributes you find (RECFM, LRECL, BLKSIZE, organization, etc.). Use PRINT to view the contents of some datasets. Compare LISTDS output with what you see in PRINT.

Exercise 4: Command Combination

Create workflows that combine multiple commands. For example, list a dataset, allocate it, print it, copy it, list the copy, and clean up. Practice creating efficient command sequences for common tasks.

Exercise 5: Error Handling

Practice handling common errors: try to allocate a non-existent dataset, try to copy to a dataset that doesn't exist, try operations with insufficient permissions. Learn to read error messages and understand what went wrong.

Related Concepts