TSO Command Syntax and Form

Understanding TSO command syntax is essential for effectively using TSO commands. TSO commands follow specific rules for format, structure, and syntax. Learning these rules enables you to construct commands correctly, understand command documentation, and use TSO commands effectively. This tutorial covers the general format of TSO commands, qualifiers, continuations, and other syntax elements.

TSO command syntax may seem complex at first, but it follows consistent patterns. Once you understand the basic structure and rules, you can construct and understand commands more easily. This knowledge is fundamental for using TSO commands, whether you're entering commands directly at the TSO READY prompt or including them in scripts and CLISTs.

General Format of TSO Commands

TSO commands follow a general format that consists of a command name followed by operands. Understanding this basic structure is the foundation for using TSO commands effectively.

Basic Command Structure

The general format of a TSO command is:

1
COMMAND operands

Where:

• COMMAND is the command name that identifies what operation to perform. Command names are typically verbs like ALLOCATE, FREE, LISTCAT, DELETE, etc.
• operands are parameters, qualifiers, and options that provide additional information or modify the command's behavior. Operands are separated by spaces.

For example, a simple TSO command might be:

1
LISTCAT

This command has no operands—it just lists catalog entries using default options. A more complex command might be:

1
ALLOCATE FILE(DDNAME) DATASET('USERID.SOURCE.COBOL')

This command includes operands (FILE and DATASET qualifiers) that specify what to allocate and how.

Command Name Rules

TSO command names follow specific rules:

• Case Insensitivity: Command names are not case-sensitive. You can type them in uppercase, lowercase, or mixed case. "LISTCAT", "listcat", and "ListCat" are all equivalent.
• Abbreviation: Many TSO commands can be abbreviated. For example, "LISTCAT" can often be abbreviated as "LISTC" or "LC". The minimum abbreviation is typically 4 characters, but this varies by command. You can use the full command name or an abbreviation.
• Uniqueness: Command names must be unique enough that TSO can identify which command you mean. If an abbreviation is ambiguous (matches multiple commands), you may need to use more characters.
• Reserved Words: Some words are reserved and cannot be used as command names. These are typically TSO keywords or system commands.

Using abbreviations can speed up command entry, but using full command names makes commands more readable, especially in scripts or documentation.

Entering Commands

TSO commands are entered at the TSO READY prompt:

• READY Prompt: After logging on to TSO, you see the READY prompt (or "TSO" prompt), which indicates TSO is ready to accept commands. The prompt typically looks like "READY" or shows your userid followed by ">>".
• Command Entry: Type your command on the command line after the prompt. You can type the command name and operands on the same line.
• Execution: Press Enter to execute the command. TSO processes the command and displays results or error messages.
• Command Line: The command line is where you type commands. It's typically at the bottom of the screen or after the prompt.

For example, at the READY prompt, you might type:

1
2
READY
LISTCAT

Then press Enter to execute the LISTCAT command.

Command Operands

Operands are the parameters, qualifiers, and options that follow the command name. They provide additional information that tells TSO what to do, how to do it, or what to operate on.

Types of Operands

Operands can take different forms:

• Positional Operands: Operands that are identified by their position in the command. The first operand might be a dataset name, the second might be a member name, etc. Position matters for positional operands.
• Keyword Operands: Operands that are identified by keywords. Keyword operands use the format KEYWORD(value), where KEYWORD is the parameter name and value is the parameter value. Keyword operands can appear in any order.
• Flags or Options: Single characters or words that enable or disable options. Flags are often preceded by a slash (/) or are standalone words that modify behavior.

For example, in the command:

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

FILE and DATASET are keyword operands (with values in parentheses), and SHR is a flag that specifies shared access.

Operand Syntax Rules

Operands follow specific syntax rules:

• Separation: Operands are separated by spaces. Multiple spaces are treated as a single space.
• Order: For positional operands, order matters. For keyword operands, order typically doesn't matter (though some commands may have restrictions).
• Quotes: Values containing spaces or special characters are often enclosed in quotes. Dataset names are frequently quoted, especially if they contain special characters.
• Parentheses: Keyword operands use parentheses to enclose values: KEYWORD(value).
• Commas: Some commands use commas to separate multiple values within an operand.

Understanding these rules helps you construct commands correctly and interpret command documentation.

Qualifiers

Qualifiers are keyword operands that modify command behavior or provide specific information. They use the format KEYWORD(value) and allow you to specify detailed parameters for commands.

Qualifier Format

Qualifiers use the format:

1
KEYWORD(value)

Where KEYWORD is the qualifier name and value is the value for that qualifier. For example:

1
FILE(DDNAME)

Here, FILE is the qualifier keyword and DDNAME is the value specifying the file (DD name) to allocate.

Multiple Qualifiers

Commands can have multiple qualifiers, separated by spaces:

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

This command has multiple qualifiers: FILE specifies the DD name, DATASET specifies the dataset name, SHR specifies shared access, and REUSE allows reusing an existing allocation.

Qualifier Order

For most commands, qualifier order doesn't matter when using keyword qualifiers. These two commands are equivalent:

1
ALLOCATE FILE(DDNAME) DATASET('DSNAME')

1
ALLOCATE DATASET('DSNAME') FILE(DDNAME)

However, some commands may have restrictions on qualifier order, and positional operands (if any) must come before keyword qualifiers. Always refer to command documentation for specific requirements.

Common Qualifiers

Many TSO commands use common qualifiers:

• FILE(DDNAME): Specifies a DD (Data Definition) name, often used for file allocation and operations.
• DATASET('DSNAME'): Specifies a dataset name. Dataset names are often quoted, especially if they contain special characters or spaces.
• MEMBER('MEMBERNAME'): Specifies a member name within a partitioned dataset.
• VOLUME('VOLSER'): Specifies a volume serial number for volume-specific operations.
• UNIT('UNITNAME'): Specifies a device unit name for allocation operations.

These qualifiers appear frequently across different TSO commands, so learning them helps you understand many commands.

Command Continuations

TSO commands can be continued across multiple lines for readability. This is especially useful for long commands with many qualifiers or complex parameters.

Continuation Characters

To continue a command on the next line, end the current line with a continuation character:

• Hyphen (-): The most common continuation character. End a line with a hyphen and press Enter, then continue the command on the next line.
• Plus Sign (+): An alternative continuation character. Some systems or commands may prefer plus signs, though hyphens are more common.

The continuation character tells TSO that the command continues on the next line, so it doesn't try to execute the command when you press Enter after the continuation character.

Using Continuations

Here's an example of a continued command:

1
2
3
ALLOCATE FILE(DDNAME) -
DATASET('USERID.SOURCE.COBOL') -
SHR REUSE

This command is spread across three lines. The hyphens at the end of the first two lines indicate continuation. When you press Enter after the last line (without a continuation character), TSO executes the complete command.

Continuation Rules

When using continuations:

• Continuation Character Position: The continuation character must be the last non-blank character on the line (except for trailing spaces, which are ignored).
• No Spaces After Continuation: Don't put spaces or other characters after the continuation character on the same line.
• Next Line: Continue the command on the next line. You can indent the continuation for readability, but it's not required.
• Final Line: The last line of the command should not have a continuation character. Press Enter on the final line to execute the command.
• Within Quotes: If you need to continue within a quoted string, the continuation character goes outside the quotes on the line where you want to continue.

Continuations make long commands more readable and easier to edit, especially in scripts or when entering complex commands.

Continuation Examples

Here are examples of continued commands:

1
2
3
ALLOCATE FILE(INFILE) -
DATASET('USERID.INPUT.DATA') -
SHR

This allocates a file with multiple qualifiers, continued across lines for readability.

1
2
3
SUBMIT 'USERID.JCL.JOB(MEMBER1)' -
CLASS(A) -
NOTIFY(USERID)

This submits a job with multiple parameters, using continuations to organize the command.

Quotes and Special Characters

Understanding how to use quotes and handle special characters is important for constructing TSO commands correctly.

When to Use Quotes

Quotes are used to enclose values that contain spaces or special characters:

• Dataset Names: Dataset names are often quoted, especially fully qualified names. Quotes ensure that spaces or special characters in dataset names are handled correctly.
• Values with Spaces: Any value containing spaces should be quoted to prevent TSO from interpreting the spaces as separators.
• Special Characters: Values containing special characters that have meaning in TSO syntax should be quoted to prevent misinterpretation.

For example:

1
LISTCAT ENT('USERID.SOURCE.COBOL')

The dataset name is quoted to ensure it's treated as a single value.

Quote Types

TSO typically accepts both single quotes (') and double quotes ("), though single quotes are more commonly used:

1
DATASET('USERID.SOURCE.COBOL')

1
DATASET("USERID.SOURCE.COBOL")

Both forms are usually equivalent. Use the type that's consistent with your organization's conventions or that matches the examples in your command documentation.

Special Characters

Some characters have special meaning in TSO commands:

• Parentheses (): Used to enclose values in keyword qualifiers: KEYWORD(value).
• Quotes '' or "": Used to enclose values containing spaces or special characters.
• Hyphen -: Used for command continuations.
• Slash /: Sometimes used for flags or options.
• Comma ,: Used to separate multiple values in some commands.
• Equal Sign =: Sometimes used in assignments or comparisons.

If you need to use these characters as literal characters (not with their special meaning), you may need to quote them or use escape sequences, depending on the command and context.

Command Abbreviations

Many TSO commands can be abbreviated to save typing. Understanding abbreviations helps you work more efficiently.

Abbreviation Rules

Command abbreviations follow rules:

• Minimum Length: Most commands can be abbreviated to a minimum of 4 characters, though some commands may require more characters for uniqueness.
• Uniqueness: The abbreviation must be unique enough that TSO can identify which command you mean. If multiple commands start with the same characters, you may need to use more characters.
• Case Insensitive: Abbreviations, like full command names, are case-insensitive.

For example, "LISTCAT" can often be abbreviated as "LISTC" or "LC", and "ALLOCATE" can be abbreviated as "ALLOC" or "AL".

Common Abbreviations

Here are some common TSO command abbreviations:

• LISTCAT → LISTC or LC: List catalog entries
• ALLOCATE → ALLOC or AL: Allocate a dataset
• DELETE → DEL or DE: Delete a dataset
• FREE → FR: Free an allocation
• SUBMIT → SUB: Submit a batch job
• PROFILE → PROF: Manage TSO profile

These abbreviations can speed up command entry, especially when typing commands frequently.

When to Use Abbreviations

Consider using abbreviations when:

• Interactive Use: You're typing commands interactively and want to save keystrokes.
• Familiar Commands: You're very familiar with the command and its abbreviation.
• Repetitive Tasks: You're entering the same command multiple times.

Consider using full command names when:

• Scripts: You're writing scripts or CLISTs where readability is important.
• Documentation: You're documenting procedures for others.
• Learning: You're learning commands and want to see the full names.
• Clarity: You want maximum clarity about what the command does.

Getting Help with Command Syntax

TSO provides help for command syntax, which is invaluable when learning commands or checking syntax details.

HELP Command

To get help for a TSO command, use the HELP command:

1
HELP commandname

For example:

1
HELP ALLOCATE

This displays help information for the ALLOCATE command, including syntax, qualifiers, examples, and descriptions.

Help Information

HELP typically provides:

• Syntax: The command syntax showing the format, qualifiers, and options.
• Parameter Descriptions: Explanations of what each parameter or qualifier does.
• Examples: Example commands showing how to use the command.
• Notes: Additional information, restrictions, or important notes about the command.

Using HELP is an excellent way to learn command syntax and discover available options.

Common Syntax Patterns

Many TSO commands follow common syntax patterns. Recognizing these patterns helps you understand and use commands more effectively.

Allocation Pattern

Commands that allocate resources often follow this pattern:

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

Where options might include SHR (shared), OLD (exclusive), REUSE, etc.

List Pattern

Commands that list information often follow this pattern:

1
LIST[CAT|DS|ALC] [ENT('name')] [options]

Where you specify what to list and optional filtering or display options.

Operation Pattern

Commands that perform operations often follow this pattern:

1
OPERATION target [qualifiers] [options]

Where you specify the operation, what to operate on, and how to perform the operation.

Recognizing these patterns helps you understand new commands and construct commands correctly.

Best Practices for TSO Command Syntax

Following best practices helps you use TSO commands effectively and avoid errors:

• Use Quotes for Dataset Names: Quote dataset names, especially fully qualified names, to ensure they're handled correctly.
• Use Continuations for Long Commands: Use continuations to make long commands more readable and easier to edit.
• Use HELP: Use the HELP command to check syntax when you're unsure about a command or its parameters.
• Be Consistent: Use consistent formatting and style in your commands, especially in scripts.
• Test Commands: Test commands, especially complex ones, before using them in scripts or for important operations.
• Document Complex Commands: Document complex commands or unusual syntax for future reference.
• Use Full Names in Scripts: In scripts and CLISTs, use full command names for readability, even if you use abbreviations interactively.
• Check Error Messages: When commands fail, read error messages carefully—they often indicate syntax problems.

Explain Like I'm 5: TSO Command Syntax

Imagine TSO commands are like sentences you tell the computer:

• The Command is like the verb—it tells the computer what action to do, like "LIST" (show me) or "DELETE" (remove).
• Qualifiers are like describing words that give more details. Like saying "show me the RED ball" instead of just "show me the ball"—the qualifiers tell the computer exactly what you want.
• Quotes are like putting a name tag on something. If something has a long or complicated name, you put quotes around it so the computer knows the whole thing is one name, not separate words.
• Continuations are like when you run out of space writing a sentence, so you put a dash at the end of the line and keep writing on the next line. The dash tells the computer "this sentence isn't finished yet!"
• Abbreviations are like nicknames. Instead of saying "Christopher" every time, you can say "Chris" and everyone still knows who you mean. Commands have nicknames too, like "LISTC" instead of "LISTCAT".

So TSO command syntax is like learning how to talk to the computer in its special language, using the right words in the right order!

Practice Exercises

Complete these exercises to reinforce your understanding of TSO command syntax:

Exercise 1: Command Structure Analysis

Take several TSO commands (from documentation or examples) and identify the command name, operands, qualifiers, and any flags or options. Document the structure of each command and explain what each part does. This helps you recognize patterns in command syntax.

Exercise 2: Continuation Practice

Write a long TSO command (like a complex ALLOCATE command with many qualifiers) and practice writing it with continuations. Try different ways of breaking it across lines and see which is most readable. Practice entering continued commands to become comfortable with the syntax.

Exercise 3: Quote Usage

Practice writing TSO commands with and without quotes for dataset names. Identify when quotes are necessary and when they're optional. Test commands to see how quotes affect command execution and learn the rules for your environment.

Exercise 4: Abbreviation Research

Use the HELP command to find common TSO commands and discover their abbreviations. Create a reference list of commands and their abbreviations. Practice using abbreviations and verify they work correctly in your environment.

Exercise 5: Syntax Documentation

Choose a TSO command you use frequently and document its complete syntax, including all qualifiers, options, and examples. Use the HELP command to gather information, then create your own reference document. This helps you understand the command deeply and creates a useful reference.

Related Concepts