CLIST

CONTENTS
Notices FRONT_1
Programming Interface Information FRONT_1.1
Trademarks FRONT_1.2
About This Book PREFACE

Who Should Use This Book PREFACE.1
How This Book Is Organized PREFACE.2
Where to Find More Information PREFACE.3
Referenced Program Products PREFACE.4
Summary of Changes CHANGES

SC28-1876-04 for TSO/E Version 2 Release 5 CHANGES.1
Online Update SK2T-0710-05 for TSO/E Version 2 Release 2 CHANGES.2
Online Update SK2T-0710-01 for TSO/E Version 2 Release 2 CHANGES.3
SC28-1876-01 for TSO/E Version 2 Release 1.1 CHANGES.6
Topic 1. Introduction 1.0

Features of the CLIST Language 1.1
Categories of CLISTs 1.2
Topic 2. Creating, Editing, and Executing CLISTs 2.0

CLIST Data Sets and Libraries 2.1
Creating and Editing CLIST Data Sets 2.2
Executing CLISTs 2.3
Allocating CLIST Libraries for Implicit Execution 2.4
Topic 3. Writing CLISTs - Syntax and Conventions 3.0

Overview of CLIST Statements 3.1
Syntax Rules 3.2
TSO/E Commands and JCL Statements 3.3
Operators and Expressions 3.4
The Double-Byte Character Set (DBCS) 3.5
Topic 4. Using Symbolic Variables 4.0

What is a Symbolic Variable? 4.1
Defining Symbolic Variables and Assigning Values to Them 4.2
More Advanced Uses of Variables 4.3
Topic 5. Using Control Variables 5.0

Overview of using Control Variables 5.1
Getting the Current Date and Time 5.2
Getting Terminal Characteristics 5.3
Getting Information about the User 5.4
Getting Information about the System 5.5
Getting Information about the CLIST 5.6
Setting Options of the CLIST CONTROL Statement 5.7
Getting Information about User Input 5.8
Trapping TSO/E Command Output 5.9
Getting Return Codes and Reason Codes 5.10
Getting Results of the TSOEXEC Command 5.11
Getting Data Set Attributes 5.12
Topic 6. Using Built-in Functions 6.0

Determining the Data Type of an Expression - &DATATYPE 6.1
Forcing Arithmetic Evaluations - &EVAL 6.2
Determining an Expression's Length in Bytes - &LENGTH 6.3
Determining an Expression's Length in Characters - &SYSCLENGTH 6.4
Preserving Double Ampersands - &NRSTR 6.5
Defining Character Data - &STR 6.6
Defining a Substring - &SUBSTR 6.7
Defining a Substring - &SYSCSUBSTR 6.8
Converting Character Strings to Uppercase Characters - &SYSCAPS 6.9
Converting Character Strings to Lowercase Characters - &SYSLC 6.10
IBM TSO Extensions for MVS - CLISTs 2
Determining Data Set Availability - &SYSDSN 6.11
Locating One Character String Within Another - &SYSINDEX 6.12
Limiting the Level of Symbolic Substitution - &SYSNSUB 6.13
Converting DBCS Data to EBCDIC - &SYSONEBYTE 6.14
Converting EBCDIC Data to DBCS - &SYSTWOBYTE 6.15
Topic 7. Structuring CLISTs 7.0

Making Selections 7.1
Loops 7.2
Subprocedures 7.3
Nesting CLISTs 7.4
GOTO Statements 7.5
Topic 8. Communicating with the Terminal User 8.0

Prompting the User for Input 8.1
Writing Messages to the Terminal 8.2
Receiving Responses from the Terminal 8.3
Passing Control to the Terminal 8.4
Using ISPF Panels 8.5
Topic 9. Performing File I/O 9.0

Characters Supported in I/O 9.1
Opening a File 9.2
Closing a File 9.3
Reading a Record from a File 9.4
Writing a Record to a File 9.5
Updating a File 9.6
End-of-File Processing 9.7
Special Considerations for Performing I/O 9.8
Topic 10. Writing ATTN and ERROR Routines 10.0

Writing Attention Routines 10.1
Writing Error Routines 10.2
Topic 11. Testing and Debugging CLISTs 11.0

Using Diagnostic Options of the CONTROL Statement 11.1
Getting Help for CLIST Messages 11.2
Obtaining CLIST Error Codes 11.3
Topic 12. Sample CLISTs 12.0

Including TSO/E Commands - The LISTER CLIST 12.1
Simplifying Routine Tasks - The DELETEDS CLIST 12.2
Creating Arithmetic Expressions from User-Supplied Input - The CALC CLIST
12.3
Using Front-End Prompting - The CALCFTND CLIST 12.4
Initializing and Invoking System Services - The SCRIPTDS CLIST 12.5
Invoking CLISTs to Perform Subtasks - The SCRIPTN CLIST 12.6
Including JCL Statements - The SUBMITDS CLIST 12.7
Analyzing Input Strings with &SUBSTR - The SUBMITFQ CLIST 12.8
Allowing Foreground and Background Execution of Programs - The RUNPRICE CLIST
12.9
Including Options - The TESTDYN CLIST 12.10
Simplifying System-Related Tasks - The COMPRESS CLIST 12.11
Simplifying Interfaces to Applications - The CASH CLIST 12.12
Using &SYSDVAL When Performing I/O - The PHONE CLIST 12.13
Allocating Data Sets to SYSPROC - The SPROC CLIST 12.14
Writing Full-Screen Applications Using ISPF Dialogs - The PROFILE CLIST
12.15
Allocating a Data Set with LISTDSI Information - The EXPAND CLIST 12.16
Topic 13. Reference 13.0

How to Read the CLIST Statement Syntax 13.1
ATTN Statement 13.2
CLOSFILE Statement 13.3
CONTROL Statement 13.4
DATA-ENDDATA Sequence 13.5
DATA PROMPT-ENDDATA Sequence 13.6
DO Statement 13.7
END Statement 13.8
ERROR Statement 13.9
EXIT Statement 13.10
GETFILE Statement 13.11
GLOBAL Statement 13.12
GOTO Statement 13.13
IF-THEN-ELSE Sequence 13.14
LISTDSI Statement 13.15
NGLOBAL Statement 13.16
OPENFILE Statement 13.17
PROC Statement 13.18
PUTFILE Statement 13.19
READ Statement 13.20
READDVAL Statement 13.21
RETURN Statement 13.22
SELECT Statement 13.23
SET Statement 13.24
SYSCALL Statement 13.25
SYSREF Statement 13.26
TERMIN and TERMING Statement 13.27
WRITE and WRITENR Statements 13.28
END Command 13.29
EXEC Command 13.30
Index INDEX
Communicating Your Comments to IBM BACK_1
Readers' Comments -- We'd Like to Hear from You COMMENTS
FIGURES Figures
1-1. Sample CLIST Consisting of TSO/E Commands 1.2

3-1. CLIST Statement Categories 3.1
3-2. Arithmetic, Comparative, and Logical Operators 3.4
: 5-1. Control Variable by Category 5.1
5-2. Modifiable Control Variables (alphabetically) 5.1
5-3. Non-modifiable Control Variables (alphabetically) 5.1
6-1. Built-in Functions 6.0
7-1. How a CLIST Executes a Compound DO Sequence 7.2
7-2. Nested CLISTs 7.4
: 8-1. TERMIN and TERMING Statement Comparison 8.4
10-1. A CLIST Containing an Attention Routine - The ALLOCATE
CLIST 10.1
10-2. An Attention Handling CLIST - The HOUSKPNG CLIST 10.1
10-3. The COPYDATA CLIST 10.2
11-1. Sample CLIST with Diagnostic CONTROL Options 11.1
11-2. Diagnostic Output from Sample CLIST 11.1
11-3. Error Messages in Diagnostic Output from Sample CLIST 11.1
11-4. CLIST Statement Error Codes (Decimal) 11.3
12-1. Sample CLISTs and Their Functions 12.0
12-2. The LISTER CLIST 12.1
12-3. The DELETEDS CLIST 12.2
12-4. The CALC CLIST 12.3
12-5. The CALCFTND CLIST 12.4
12-6. The SCRIPTDS CLIST 12.5
12-7. The SCRIPTN CLIST 12.6
12-8. The SCRIPTD CLIST 12.6
12-9. The OUTPUT CLIST 12.6
12-10. The SUBMITDS CLIST 12.7
12-11. The SUBMITFQ CLIST 12.8
12-12. The RUNPRICE CLIST 12.9
12-13. The TESTDYN CLIST 12.10
12-14. The COMPRESS CLIST 12.11
12-15. The CASH CLIST 12.12
12-16. The PHONE CLIST 12.13
12-17. The SPROC CLIST 12.14
12-18. Purpose of, and Figures Containing, PROFILE CLIST and Supporting
Panels 12.15
12-19. The PROFILE CLIST 12.15
12-20. The Terminal Characteristics Panel Definition (XYZABC10) 12.15
12-21. The LOG/LIST Characteristics Panel Definition (XYZABC20) 12.15
12-22. The PF Keys 1-12 Panel Definition (XYZABC30) 12.15
12-23. The PF Keys 13-24 Panel Definition (XYZABC40) 12.15
12-24. The EXPAND CLIST 12.16
13-1. Variables Set by LISTDSI 13.15
13-2. LISTDSI Return Codes 13.15
13-3. LISTDSI Reason Codes 13.15
FRONT_1.1 Programming Interface Information
This book is intended to help the customer to design and write CLISTs. It
contains syntax and usage information about the TSO/E CLIST language.
This book documents General-use Programming Interface and Associated
Guidance Information provided by TSO Extensions Version 2.
General-use programming interfaces allow the customer to write programs that
obtain the services of TSO Extensions Version 2.
FRONT_1.2 Trademarks
The following terms are trademarks of the IBM Corporation in the United States
or other countries or both:
* BookMaster
* IBM
* VTAM
Other company, product, and service names, which may be denoted by a

double asterisk (**), may be trademarks or service marks of others.
PREFACE About This Book

This book describes how to use the TSO/E CLIST language to write programs
called CLISTs. You can use CLISTs to perform a wide range of programming tasks
on TSO/E.
PREFACE.1 Who Should Use This Book
This book is intended for new and experienced CLIST programmers.

If you are a new user of the CLIST language, read each topic and try
coding the examples.
If you are experienced with CLISTs, review the topics and familiarize
yourself with the organization of this book. Then you'll be able to refer to the
appropriate topic when you have a question or want to refresh your memory.
To use the CLIST language effectively, you should be familiar with TSO/E
commands. Familiarity with the Interactive System Productivity Facility ISPF) is
also helpful. For information about TSO/E commands, see TSO/E V2 Command
Reference, SC28-1881. For information about ISPF, see the publications listed in
the TSO/E V2 Library Guide, GC28-1866.
PREFACE.2 How This Book Is Organized
* Topic 1, "Introduction" describes the types of functions CLISTs

perform.
* Topic 2, "Creating, Editing, and Executing CLISTs" describes how

to create and edit CLIST data sets, and how to execute CLISTs.
* Topic 3, "Writing CLISTs - Syntax and Conventions" describes the

rules for using CLIST statements, TSO/E commands, and JCL
statements in CLISTs.
* Topic 4, "Using Symbolic Variables" describes how to define
symbolic variables and assign values to them.
* Topic 5, "Using Control Variables" describes how to use CLIST

control variables to obtain current information about the
processing environment.
* Topic 6, "Using Built-in Functions" describes how to use CLIST

string-handling functions to process numeric data and character
strings.
* Topic 7, "Structuring CLISTs" describes how to use CLIST

statements to make decisions and loops, and how to use CLIST
subprocedures and nested CLISTs.
* Topic 8, "Communicating with the Terminal User" describes how to

write interactive CLISTs.
* Topic 9, "Performing File I/O" describes how to read and write

records to and from files.
* Topic 10, "Writing ATTN and ERROR Routines" describes how to

write routines that receive control when errors occur or when
the user presses the attention key while a CLIST is running.
* Topic 11, " Testing and Debugging CLISTs" describes how to find
and correct CLIST errors. This topic includes a list of error
codes and their meanings.
* Topic 12, "Sample CLISTs" provides sample CLISTs that perform a

broad range of application tasks. Each CLIST comes with a
description of the concepts that it illustrates. Generally, the
more advanced CLISTs expand upon concepts introduced in the
simpler examples.
* Topic 13, "Reference" contains complete syntax descriptions of

all of the CLIST statements.
PREFACE.3 Where to Find More Information

Please see the TSO/E V2 Library Guide, GC28-1866.
It describes all TSO/E Version 2 publications and how they are
organized.
It provides references to MVS publications and other product
publications.
PREFACE.4 Referenced Program Products

This book refers to the following products:
* All occurrences of DFHSM refer to Data Facility Hierarchical

Storage Manager, Program Number 5740-329.
* All occurrences of ISPF refer to Interactive System Productivity

Facility,, Program Number 5665-319.
* All occurrences of ISPF/PDF refer to Interactive System

Productivity Facility/Program Development Facility, Program
Number 5665-317.
* All occurrences of RACF refer to Resource Access Control

Facility,Program Number 5740-XXH.
CHANGES Summary of Changes
CHANGES.1 SC28-1876-04 for TSO/E Version 2 Release 5

* Various new control variables have been added to Topic 5, "Using
Control Variables".
* The SMSINFO keyword operand on the LISTDSI statement has been

added and new variables, set by LISTDSI, are available in
support of enhanced capabilities of DFSMS/MVS. See Topic 13,
"LISTDSI Statement"
in topic 13.15.
* Information about CLIST data set attributes has been added to

Topic 2, "Creating, Editing, and Executing CLISTs".
* This revision also reflects the changes caused by miscellaneous

maintenance items and the following APAR: OY65485.
CHANGES.2 : Online Update SK2T-0710-05 for TSO/E Version 2 Release 2

* This revision reflects the changes caused by miscellaneous
maintenance items and the following APARs: OY56172, OY63727.
CHANGES.3 : Online Update SK2T-0710-01 for TSO/E Version 2 Release 2

* This revision reflects the changes caused by miscellaneous maintenance
items and the following APARs: OY49633, OY50211, OY51862.

This revision consists of maintenance changes.

This revision consists of minor technical and editorial changes.
CHANGES.6 SC28-1876-01 for TSO/E Version 2 Release 1.1

* Changes have been made clarifying information about receiving
return codes, valid names of variables, and the use of
&SYSINDEX.
* Some of the information from the topic "Characters Supported in

I/O" in topic 9.1 in Topic 9 has been moved to "Characters
Supported in CLISTs" in topic 3.2 in Topic 3.

This book contains information previously presented in TSO/E V2
CLISTs,SC28-1304-03, which supports TSO/E Version 1 Release 4.
* Information about the ATLIB command has been added to Topic 2.
* Examples of the EXEC command have been changed to include the

optional CLIST operand that distinguishes CLISTs from REXX
execs.
* Reference information about the EXEC and END commands has been
moved from Topic 13 to TSO/E V2 Command Reference.
1.0 Topic 1. Introduction
The CLIST language enables you to work more efficiently with TSO/E. You can
write programs, called CLISTs, that perform given tasks or groups of tasks. From
then on, you can simply invoke the CLISTs to do those tasks.
The term CLIST (pronounced "sea list") is short for Command LIST, because the
most basic CLISTs are lists of TSO/E commands. When you invoke such a CLIST, it
issues the TSO/E commands in sequence.
Besides issuing TSO/E commands, CLISTs can perform more complex

programming tasks. The CLIST language includes the programming tools you need to
write extensive, structured applications. CLISTs can perform any number of
complex tasks, from displaying a series of full-screen panels to managing
programs written in other languages.
The CLIST language is an interpretive language. Like programs in other high-

level interpretive languages, CLISTs are easy to write and test. You don't have
to compile and link edit them. To test a CLIST, you execute it, correct any
errors, and re-execute it.
The CLIST language is one of two command languages available in TSO/E Version
2. For information about the other command language, REXX, see TSO/E V2 REXX/MVS
User's Guide, SC28-1882, and TSO/E V2 REXX/MVS
Reference, SC28-1883.
1.1 Features of the CLIST Language
The CLIST language provides a wide range of programming functions. Its

features include:
* An extensive set of arithmetic and logical operators for processing

numeric data
* String-handling functions for processing character data
* CLIST statements that let you structure your programs, perform I/O,
define and modify variables, and handle errors and attention interrupts.
1.2 Categories of CLISTs
A CLIST can perform a wide range of tasks. Three general categories of

CLISTs are:
* CLISTs that perform routine tasks

* CLISTs that are structured applications
* CLISTs that manage applications written in other languages.
CLISTs That Perform Routine Tasks
As a user of TSO/E, you probably perform certain tasks on a regular basis.

These tasks may involve entering TSO/E commands to check on the status of data
sets, to allocate data sets for particular programs, and to print files.
You can write CLISTs that significantly reduce the amount of time that you
have to spend on these routine tasks. By grouping together in a CLIST the
instructions required to complete a task, you reduce the time, number of
keystrokes, and errors involved in performing the task; thus, you increase your
productivity. Such a CLIST can consist of TSO/E commands only, or a combination
of TSO/E commands, JCL statements, or CLIST statements.
Figure 1-1 is an example of a CLIST that consists of TSO/E commands only.
allocate file(ABC) dataset(name1)

allocate file(DEF) dataset(name2)
call (prog1)
free file(ABC DEF)
Figure 1-1. Sample CLIST Consisting of TSO/E Commands

The CLIST in Figure 1-1 issues TSO/E commands to allocate files for a
program, call the program, and free the files when the program is finished.
Whenever you wanted to perform these related tasks, you could
simply execute the CLIST instead of retyping the commands.
If tasks require specific input from a user, you can obtain the input in a
CLIST by using CLIST statements or TSO/E commands to prompt the user for the
input.
CLISTs That Are Structured Applications
The CLIST language includes the basic tools you need to write complete,
structured applications. Any CLIST can invoke another CLIST, which isreferred to
as a nested CLIST. CLISTs can also contain separate routines called
subprocedures. Nested CLISTs and subprocedures let you separate your CLISTs into
logical units and put common functions in a single location. Specific CLIST
statements let you:
* Define common data for subprocedures and nested CLISTs

* Restrict data to certain subprocedures and CLISTs
* Pass specific data to a subprocedure or nested CLIST.
For interactive applications, CLISTs can issue commands of the Interactive

System Productivity Facility (ISPF) to display full-screen panels.
Conversely, ISPF panels can invoke CLISTs, based on input that a user types
on the panel. When the user changes a value on a panel, the change applies to
the value in the CLIST that displayed the panel. With ISPF, CLISTs can manage
extensive panel-driven dialogs.
CLISTs That Manage Applications Written in Other Languages
You might have access to applications that are written in other programming
languages. However, the interfaces to these applications might not be easy to
use or remember. Rather than write new applications, you can write CLISTs that
provide easy-to-use interfaces between the user and such applications.
A CLIST can send messages to, and receive messages from, the terminal to
determine what the user wants to do. Then, based on this information, the CLIST
can set up the environment and issue the commands required to invoke the program
that performs the requested tasks.
2.0 Topic 2. Creating, Editing, and Executing CLISTs
2.1 CLIST Data Sets and Libraries

CLISTs reside in either sequential or partitioned data sets (PDSs). A
sequential CLIST data set consists of only one CLIST, while a PDS can contain one
or more CLISTs. In a PDS, each CLIST is a member and has a unique member name.
When a PDS consists entirely of CLISTs, it is called a CLIST library.
CLIST libraries make CLISTs easy to maintain and execute. Your

installation can keep commonly used CLISTs in a system CLIST library, and you can
keep your own CLISTs in a private CLIST library. If you allocate a CLIST library
to the file SYSPROC, or specify the library on the ALTLIB command, you can
execute the CLISTs implicitly by simply typing their member names.
Implicit execution frees you from having to code the name of the CLIST
library on an EXEC command. Besides saving keystrokes, implicit execution lets
you keep different versions of a CLIST in different libraries, and control which
version executes at a given time. For more information, see "Allocating CLIST
Libraries for Implicit Execution" in topic 2.4.
2.2 Creating and Editing CLIST Data Sets

Before coding your first CLIST, you must create a CLIST data set. There
are two ways to create and edit a CLIST data set:
1. Using options 3 (UTILITIES) and 2 (EDIT) of ISPF/PDF:

a. Create a data set using the allocate panel in ISPF (usually option
3.2 on the primary menu).
* To simplify execution, specify CLIST as the data set type.
* To create a data set with the same attributes as another, such

as a system CLIST library, use option 3.2 to view the
attributes of the existing data set and then allocate the new
data set.
b. Code your CLIST in the full-screen environment using the ISPF/PDF

editor (usually option 2).
c. Modify the CLIST by making corrections directly to the data on the

screen.
For more information about creating and editing data sets under
ISPF/PDF, see TSO/E V2 Primer, GC28-1879.
2. Using the TSO/E EDIT command and its subcommands (this method includes
option 6 of ISPF/PDF.):
a. Include the CLIST keyword on the EDIT command.
b. Enter and save your CLIST statements, TSO/E commands, and TSO/E
subcommands.
c. Use subcommands of EDIT to modify the CLIST.
CLISTs created with the EDIT command cannot contain characters of the
double-byte character set (DBCS).
More information about creating and editing data sets under TSO/E can
be found in TSO/E V2 Command Reference, SC28-1881.
] CLIST Data Set Attributes
] If a CLIST data set is created by one of the previously described methods,

] and the CLIST keyword is specified on the EDIT command, the data set will
] be assigned the following default attributes (provided that your
] installation has not changed the default values):
] * A variable-length record format
] If you specify a LINE value on the EDIT command, the data set will be
] of a fixed-length record format in the specified length.
] * A logical record size of 255 characters
] * A block size of 3120 bytes
] * Line numbers are contained in the last eight bytes of all fixed-length
] records and in the first eight bytes of all variable-length records
] * All input data and modified data are converted to uppercase

] characters.
] Your installation may have changed these default attributes and may have
] established CLIST data set conventions to ease data set tasks.
] If you concatenate CLIST data sets, specify the same RECFM and LRECL
] values for these data sets.
] For a complete description of edited data sets see the EDIT command in
] TSO/E V2 Command Reference, SC28-1881. For a discussion of the formats
] and characteristics of the RECFM subparameter of the DCB parameter, see
] MVS/ESA SP V5 JCL Reference, GC28-1479. If you want to obtain information
] about a data set for use in CLIST variables, see "LISTDSI Statement" in
] topic 13.15.
Considerations for Copying CLIST Data Sets
When creating and editing CLISTs, you might copy an existing CLIST data
set into a new data set. If you do so under ISPF/PDF, be aware of the
record formats of the data sets. Variable-blocked data sets might contain
line numbers in columns 1-8 that do not normally appear when you edit the
data sets. If you copy a variable-blocked data set into a fixed-blocked
data set, the line numbers are copied as part of the data. This data must
then be removed. To find out if a data set contains line numbers, use the
ISPF EDIT command PROFILE.
If you copy a fixed-blocked data set with line numbers into a

variable-blocked data set, the system copies sequence numbers from columns
73-80 into the variable-blocked data set. This data must also be removed.
For information about how to remove the sequence numbers from a
variable-blocked data set, see ISPF/PDF Edit and Edit Macros.
2.3 Executing CLISTs
To execute a CLIST, use the EXEC command. From an ISPF command line, type
TSO in front of the command. In TSO/E EDIT or TEST mode, use the EXEC
subcommand as you would use the EXEC command. (CLISTs executed under EDIT
or TEST can issue only EDIT or TEST subcommands and CLIST statements, but
you can use the END subcommand in a CLIST to end EDIT or TEST mode and
allow the CLIST to issue TSO/E commands.)
The EXEC command (or subcommand) has two forms:
1. Explicit form -- Enter "exec" or "ex" followed by the data set name
and the optional CLIST operand. By default, the EXEC command assumes
that the data set type is CLIST and automatically suffixes all
specified names with .CLIST, unless the name is in quotes. For
example:
* If a CLIST, LISTPGM, is a member of a PDS named

PREFIX.CLISTLIB.CLIST, enter:
{exec} clistlib(listpgm) âCLISTã

{ex }
* If a CLIST, LISTPGM, is a member of a PDS named PREFIX.CLIST,

enter:
{exec} (listpgm) âCLISTã

{ex }
* If the CLIST is in a sequential data set named

PREFIX.LISTPGM.CLIST, enter:
{exec} (listpgm) âCLISTã

{ex }
* If the CLIST is in a sequential data set named PREFIX.LISTPGM,

enter:
{exec} 'prefix.listpgm' âCLISTã
{ex }
] If the EXEC command is used to execute a CLIST in a sequential data

] set, but the data set is found to be a partitioned one, it will assume
] a member TEMPNAME. The system will notify you if this member is not
] found, otherwise it will execute it.
2. Implicit form -- Enter only the name of the CLIST, optionally preceded
by a percent sign (%). The CLIST must be a member of a PDS allocated
to the file SYSPROC, or an alternative library specified with the
ALTLIB command. The two implicit forms are as follows:
a. Enter only the member name, for example:
listpgm
When you use this form, TSO/E first searches command libraries to
ensure that the name you entered is not a TSO/E command, then
searches CLIST libraries:
* Specified with the ALTLIB command or

* Allocated to the SYSPROC file.
b. Enter the member name prefixed with a percent sign (%), for
example:
%listpgm
When you use this form, called the extended implicit form, TSO/E
searches only the ALTLIB or SYSPROC libraries for the name, thus
reducing the amount of search time.
For information about preparing a CLIST for implicit execution, see

"Allocating CLIST Libraries for Implicit Execution" in topic 2.4.
You can execute a CLIST in either the foreground (from your terminal) or
in the background (submit it as a batch job). You can also execute a
CLIST from another CLIST (using the EXEC command) or from a program. To
invoke a CLIST from a program, use the TSO/E service facility described in
TSO/E V2 Programming Services, SC28-1875.
Passing Parameters to CLISTs
You can pass parameters to a CLIST when you execute it. Parameters are
variable input that may change from one execution to the next. To receive
parameters, a CLIST must begin with a PROC statement that assigns the
parameters to variables. "Using the PROC Statement" in topic 4.2 explains
how to code a PROC statement to receive parameters.
To pass parameters to a CLIST, include them on the EXEC command or

subcommand as follows:
* For the explicit form, pass parameters in single quotes:
EX clistname 'parm1 parm2'
* For the implicit or extended implicit form, omit the quotes:
%clistname parm1 parm2
For more information about the types of parameters you can pass, and how
to use them in a CLIST, see "Using the PROC Statement" in topic 4.2.
For a complete syntactical definition of the EXEC command, including

special considerations for passing parameters that contain single quotes,
see Topic 13, "Reference".
2.4 Allocating CLIST Libraries for Implicit Execution
After you have written CLISTs and executed them to make sure they run
correctly, you can allocate them to special files to make them easier to
execute.
When CLISTs are members of a partitioned data set (PDS) allocated to a

special file, users and applications can execute the CLISTs implicitly by
simply invoking the member names. How you can allocate CLIST libraries
for implicit execution depends on the feature of TSO/E installed on your
system.
The ALTLIB command gives you more flexibility in specifying CLIST

libraries for implicit execution. With ALTLIB, a user or ISPF application
can easily activate and deactivate CLIST libraries for implicit execution
as the need arises. This flexibility can result in less search time when
fewer CLISTs are activated for implicit execution at the same time.
In addition to CLISTs, the ALTLIB command lets you specify libraries of

REXX execs for implicit execution. For information about using ALTLIB
with REXX execs, see TSO/E V2 REXX/MVS User's Guide, SC28-1882.
Specifying Alternative CLIST Libraries with the ALTLIB Command
The ALTLIB command lets you specify alternative libraries to contain

implicitly executable CLISTs. You can specify alternative libraries on
the user, application, and system levels.
* The user level includes CLIST libraries allocated to the file

SYSUPROC. During implicit execution, these libraries are searched
first.
* The application level includes CLIST libraries specified on the ALTLIB

command by data set or file name. During implicit execution, these
libraries are searched after user libraries.
* The system level includes CLIST libraries allocated to file SYSPROC.

During implicit execution, these libraries are searched after user or
application libraries.
Using the ALTLIB Command
The ALTLIB command offers several functions, which you specify using the
following operands:
ACTIVATE
allows implicit execution of CLISTs in a library or libraries on the
specified level(s), in the order specified.
DEACTIVATE
excludes the specified level(s) from the search order.
DISPLAY
displays the current order in which CLIST libraries are searched for
implicit execution.
RESET
resets searching to the system level only, for CLISTs and REXX execs.
For complete information about the syntax of the ALTLIB command, see TSO/E
V2 Command Reference, SC28-1881.
Notes:
1. With ALTLIB, data sets concatenated to each of the levels can have
differing characteristics (logical record length and record format),
but the data sets within the same level must have the same
characteristics.
2. At the application and system levels, ALTLIB uses the virtual

lookaside facility (VLF) to provide potential increases in library
search speed.
Using ALTLIB with ISPF
ALTLIB works the same in line mode TSO/E and in ISPF. However, if you use
ALTLIB under line mode TSO/E and start ISPF, the alternative libraries you
specified under line mode TSO/E are unavailable until ISPF ends.
Application-level libraries that you define while running an ISPF

application are in effect only while that application has control. When
the application completes, the original application-level libraries are
automatically reactivated.
Under ISPF, you can pass the alternative library definitions from
application to application by using ISPEXEC SELECT with the PASSLIB
operand. For example, to pass ALTLIB definitions to a new ISPF
application (ABC), code:
ISPEXEC SELECT NEWAPPL(ABC) PASSLIB
The PASSLIB operand passes the ALTLIB definitions to the invoked

application. When the invoked application completes and the invoking
application regains control, the ALTLIB definitions that were passed take
effect again, regardless of whether the invoked application changed them.
If you omit the PASSLIB operand, ALTLIB definitions are not passed to the
invoked application.
For more information about writing ISPF applications, see ISPF Dialog
Management Services and Examples.
Stacking ALTLIB Requests
On the application level, you can stack up to eight activate requests with
the top, or current, request active.
Examples of the ALTLIB Command
In the following example, an application issues the ALTLIB command to

allow implicit execution of CLISTs in the data set NEW.CLIB, to be
searched ahead of SYSPROC:
ALTLIB ACTIVATE APPLICATION(CLIST) DATASET(new.clib)
The application could also allow searching for any private CLISTs that the
user has allocated to the file SYSUPROC, with the following command:
ALTLIB ACTIVATE USER(CLIST)

To display the active libraries in their current search order, use the
DISPLAY operand as follows:
ALTLIB DISPLAY
To deactivate searching for a certain level, use the DEACTIVATE operand;

for example, to deactivate searching for CLISTs on the system level (those
allocated to SYSPROC), issue:
ALTLIB DEACTIVATE SYSTEM(CLIST)
And, to reset CLIST and REXX exec searching back to the system level,
issue:
ALTLIB RESET
For more information about the search order EXEC uses for CLISTs and REXX
execs, see TSO/E V2 Command Reference, SC28-1881.
3.0 Topic 3. Writing CLISTs - Syntax and Conventions
This topic provides an overview of CLIST statements and describes how to

use the following:
* Syntax rules of the CLIST language

* TSO/E commands and JCL statements in CLISTs
* CLIST operators and expressions
* The double-byte character set (DBCS) in CLISTs.
When you are familiar with the contents of this topic, read the following
topics for information about how to use variables and terminal input in
CLISTs.
3.1 Overview of CLIST Statements
CLIST statements set controls, assign values to variables, monitor the

conditions under which CLISTs execute, and perform I/O. CLIST statements
execute in both the command and subcommand environment (under the TSO/E
EXEC command and the EXEC subcommand of TSO/E EDIT). They fall into the
categories shown in Figure 3-1.
]------------------------------------------------------------------------]
] Figure 3-1. CLIST Statement Categories ]
]-----------------]------------------]-----------------]-----------------]
] Control ] Assignment ] Conditional ] I/O ]
]-----------------]------------------]-----------------]-----------------]
] ATTN ] READ ] DO ] CLOSFILE ]
] CONTROL ] READDVAL ] IF-THEN-ELSE ] GETFILE ]
] DATA-ENDDATA ] SET ] SELECT ] OPENFILE ]
] DATA-PROMPT ] LISTDSI ] ] PUTFILE ]
] ERROR ] ] ] ]
] EXIT ] ] ] ]
] GLOBAL ] ] ] ]
] GOTO ] ] ] ]
] NGLOBAL ] ] ] ]
] PROC ] ] ] ]
] RETURN ] ] ] ]
] SYSCALL ] ] ] ]
] SYSREF ] ] ] ]
] TERMIN ] ] ] ]
] WRITE ] ] ] ]
] WRITENR ] ] ] ]
] ] ] ] ]
]-----------------]------------------]-----------------]-----------------]
Subsequent topics in this book describe all of the statements in detail.
Note: In addition to these CLIST statements, IBM provides an installation

exit that lets your installation add its own CLIST statements. For
information about this exit, see TSO/E V2 Customization, SC28-1872.
3.2 Syntax Rules
This section describes the syntax rules for CLIST statements relative to
those for TSO/E commands.
Delimiters
Most CLIST statements have operands. Operands are variables or data that
provide information to be used in processing the statement. Include one
or more blanks between a CLIST statement and its first operand. Also,
separate operands from each other by one or more blanks, a comma, or tabs.
Continuation Symbols
Line continuation symbols are the same as for TSO/E commands. If used,
the continuation symbol must be the last non-blank character on the line.
A hyphen (-) indicates that leading blanks in the next line are not
ignored. A plus sign (+) indicates that leading blanks in the next line
are ignored. For example, the following command executes successfully:
alloc da(jcl.cntl) shr-

reuse file(input)
However, if you substitute a plus sign for the hyphen in this example, the
command fails because, when the lines are joined logically, there is no
blank between the end of the shr keyword and the beginning of the reuse
keyword. You would have to insert a blank before the plus sign for
correct execution.
Capitalization
All CLIST statement names must be capitalized. If you use lowercase

letters for CLIST statement names, the CLIST fails. Capitalization of
CLIST variable names and built-in function names is optional.
Capitalization of TSO/E commands and subcommands in a CLIST is also
optional.
Formatting
You can use blank lines in a CLIST as a formatting aid, to separate parts
of the CLIST and make the CLIST easier to read. Blank lines do not affect
CLIST processing, except that a blank line after a continuation symbol
ends continuation, unless the blank line is also continued.
Length
The maximum length of a CLIST statement is 32,756 bytes.
Labels
You can prefix CLIST statements and TSO/E commands with a label. Other
statements can use the label to pass control to the statement or command.
Labels can consist of 1-31 alphameric characters (A-Z, 0-9, #, $, @, _)
beginning with an alphabetic character (A-Z). The label can appear on the
same line as the statement or command, or on the preceding line. A colon
must immediately follow the label name. For example,
label: IF A= ...
or
label: +
IF A= ...
Comments
You can include a comment:
* On a line by itself
* Before, in the middle of, or after a CLIST statement or TSO/E command.
You define a comment by coding a slash-asterisk (comment delimiter)

followed by the descriptive text. If you include the comment before or in
the middle of a CLIST statement or TSO/E command, you must end the comment
with a closing comment delimiter (asterisk-slash). The following example
shows a comment included before a CLIST statement:
/*get return code */ SET RC = &LASTCC
If you include a comment after a CLIST statement or TSO/E command, or on a

line by itself, the closing comment delimiter is not needed, as shown in
the following example:
alloc file(in) da(accounts.data) shr /* Input data set
If a comment appears after a CLIST statement or TSO/E command that

continues on the following line, the comment must end with a closing
comment delimiter and the continuation character must appear after the
comment delimiter, as shown in the following example:
IF &LASTCC ^= 0 THEN /* error occurred */ +

DO ...
CLISTs can begin with a comment, but the first line of a CLIST must not be
a comment containing the acronym REXX; if the first line contains "REXX"
in any position, the EXEC command attempts to process the CLIST as a REXX
exec.
Note that comments can be in both uppercase and lowercase letters.

Comments are unaffected by CLIST processing.
Characters Supported in CLISTs
CLIST statements can process all data characters represented by

hexadecimal codes 40 through FF. It should be noted that CLISTs translate
lowercase letters to uppercase letters, unless controlled by NOCAPS or
ASIS, and translate lowercase numbers (B0-B9) to standard numbers (F0-F9).
CLISTs also support the following control characters:
Hexadecimal code Control character

05 HT (horizontal tab)
0E Shift Out (starting delimiter for DBCS data)
0F Shift In (ending delimiter for DBCS data)
14 RES (restore)
16 BS (backscore)
17 IL (idle)
24 BYP (bypass)
25 LF (line feed).
All other hexadecimal codes between 00 and 3F are reserved for internal
processing and can cause errors if they appear in CLIST data. The use of
I/O statements to process data sets containing these codes is not
supported. For example, OBJ and LOAD type data sets contain unsupported
characters and must not be used for CLIST I/O.
For a list of the characters associated with the internal hexadecimal

codes, see ESA/370 MVS/ESA Quick Reference Summary.
Note: Some characters supported in CLIST, such as { (X'C0') and }

(X'D0'), cannot be written to the terminal because of TSO/E output
processing. To write such characters to a terminal, create TSO/VTAM*
translate tables and invoke the tables with the TSO/E TERMINAL command.
For more information about creating translate tables, see TSO/E V2
Customization, SC28-1872. For CLISTs executed under the TSO/E Session
Manager, these restrictions do not apply.
3.3 TSO/E Commands and JCL Statements
You can include TSO/E commands and subcommands, and JCL statements in a
CLIST as needed.
TSO/E Commands
You can include TSO/E commands and subcommands (and user-written commands
and subcommands) in a CLIST at any point where the specific functions (for
example, allocate, free, etc.) are required. For certain applications, a
CLIST might consist entirely of commands and subcommands. You can also
substitute CLIST variables as operands in commands and subcommands, or as
commands themselves. For more information about CLIST variables, see
Topic 4, "Using Symbolic Variables".
JCL Statements
From a CLIST, you might want to submit a jobstream for execution. In the
CLIST, you can include the required JCL statements (EXEC, DD, etc.).
However, when you include the following JCL statements in a CLIST, you
must use a particular CLIST function to prevent the CLIST from modifying
the statements and causing subsequent JCL errors.
1. Statements following the SYSIN statement - use the &STR built-in

function to preserve leading blanks and statements that have the same
names as CLIST statements.
2. A statement containing a single ampersand (&) or a double ampersand

(&&) - use the &SYSNSUB or &NRSTR built-in functions.
3. JCL comments - use the &STR built-in function. Because CLIST

processing detects the JCL comment as a comment for the CLIST, you
must set a variable equal to &STR(/*) and use this variable in place
of the JCL comment.
: 4. JCL imbedded in a CLIST can use the SUBMIT * form of the SUBMIT
: command; however, all JCL is converted to uppercase. If JCL
: conversion to uppercase is inappropriate or undesirable, use the
: SUBMIT (dataset_name) form of the SUBMIT command. For a description
: of the SUBMIT command, see TSO/E V2 Command Reference, SC28-1881.
Examples of using these built-in functions with JCL are provided in

Topic 6, "Using Built-in Functions" and in Figure 12-10 in topic 12.7.
3.4 Operators and Expressions
Operators cause a CLIST to perform evaluations on data; the data can be

numeric or character, or can be a variable or a built-in function.
Operators fall into three categories: arithmetic, comparative, and
logical, as shown in Figure 3-2.
* Arithmetic operators perform integer arithmetic on numeric operands.

The operators connect integers, variables, or built-in functions to
form expressions, such as 4-2.
* Comparative operators perform comparisons between two expressions, to
form comparative expressions, such as 4-2=3. The "=" is a comparative
operator.
The comparison produces a true or false condition. Comparative

expressions are often used to determine conditional branching within a
CLIST.
* Logical operators perform a logical comparison between the results of
two comparative expressions, to form logical expressions, such as &A=4
AND &B=&C. The 'AND' is a logical operator.
Logical expressions produce true or false conditions. Logical

expressions are often used to determine conditional branching within a
CLIST.
In Figure 3-2, if more than one accepted value exists for an operator, the
values are separated by commas.
]------------------------------------------------------------------------]
] Figure 3-2. Arithmetic, Comparative, and Logical Operators ]
]-------------]-----------------------------]----------------------------]
] ] For the function: ] Enter: ]
]-------------]-----------------------------]----------------------------]
] Arithmetic ] Addition ] + ]
] ] Subtraction ] - ]
] ] Multiplication ] * ]
] ] Division ] / ]
] ] Exponentiation ] ** (See note 1) ]
] ] Remainder ] // ]
] ] Prioritizing the order of ] ( ) (See note 2) ]
] ] evaluation ] ]
]-------------]-----------------------------]----------------------------]
] Comparative ] Equal ] =,EQ ]
] ] Not equal ] ^=,NE ]
] ] Less than ] <,LT ]
] ] Greater than ] >,GT ]
] ] Less than or equal ] <=,LE ]
] ] Greater than or equal ] >=,GE ]
] ] Not greater than ] ^>,NG ]
] ] Not less than ] ^<,NL ]
]-------------]-----------------------------]----------------------------]
] Logical ] And ] AND,&& ]
] ] Or ] OR,] ]
]-------------]-----------------------------]----------------------------]
] Notes: ]
] ]
] 1. Negative exponents are handled as exponents of zero, thus the ]
] result is always set to 1. ]
] 2. Put parentheses around operations to give them priority in the ]
] order of evaluation. ]
]------------------------------------------------------------------------]
CLISTs try to perform evaluation wherever an operator is found, including

the equal sign (=) in assignment statements. If you want CLISTs to treat
operators as character data instead, use the &STR built-in function. For
more information, see "Defining Character Data - &STR" in topic 6.6.
Order of Evaluations
A CLIST evaluates operations in the following default order. (Wherever

more than one operation is listed below, the CLIST performs the operations
sequentially, left to right in the order in which they appear on the CLIST
statement.)
: 1. Exponentiation remainder
] 2. Multiplication, division
3. Addition, subtraction
4. Comparative operators
5. Logical AND
6. Logical OR.
You can override the default order by placing parentheses around the
operations you want executed first. For example, without any parentheses,
the following example performs multiplication, division, then addition.
The statement sets X to the value 24.
SET X = 4+5*8/2
By placing parentheses around 4+5, you indicate to the CLIST that it

should perform addition first and then proceed with the default order
(multiplication, then division). The following statement sets X to the
value 36.
SET X = (4+5)*8/2
You can place parentheses around expressions that are themselves enclosed
in parentheses. This process is called nesting parenthesized expressions.
The CLIST evaluates the deepest level of nesting first and proceeds
outward until all nesting has been evaluated. In the following example, X
is set to the value 7.
SET X=((1+4)*2+4)/2
The parentheses around 1+4 indicate that the CLIST should add these
numbers before performing multiplication. The parentheses around the
compound expression to the left of the division operator indicate that the
CLIST should evaluate the compound expression before performing division.
In the preceding example, if you omit the outer-level parentheses, the

CLIST performs division as the third operation (4/2) and sets X to the
value 12:
SET X=(1+4)*2+4/2
Valid Numeric Ranges
The values of numeric variables must be integers in the range from

-2,147,483,648 (-2(31))
A CLIST terminates and issues an error message in the following

situations:
* You explicitly code a value outside the valid range.
* The evaluation of an expression produces an intermediate or final

value outside the valid range.
3.5 The Double-Byte Character Set (DBCS)
The CLIST language allows data to contain characters of the double-byte

character set. The double-byte character set (DBCS) is used in national
languages such as Japanese and Korean which have more than 256 characters,
the maximum number that can be represented with one byte of data. As the
name implies, double-byte characters are each composed of two bytes,
allowing a vastly increased number of characters.
DBCS Delimiters
The CLIST language uses the hexadecimal codes X'0E' and X'0F' to
distinguish double-byte characters from EBCDIC characters. The
hexadecimal code X'0E' indicates the beginning of a string of DBCS
characters, and the code X'0F' indicates the end of a DBCS string.
Properly delimited DBCS character strings can be passed as character data
in CLIST variables, in comments, and in the operands of CLIST statements.
This book commonly refers to the beginning and ending DBCS delimiters as
shift-out and shift-in characters, respectively. In examples, this book
uses the convention <d1d2> to represent DBCS strings enclosed in their
shift-out and shift-in characters, where d1 and d2 each represent a DBCS
character, < represents X'0E', and > represents X'0F'.
When DBCS strings are joined by continuation symbols, their contiguous

shift-in and shift-out characters are removed to create a single DBCS
string. For example:
SET A = ABC<d1d2> +
<d3d4>DEF /* result: &A = ABC<d1d2d3d4>DEF
DBCS Restrictions
The following restrictions apply to DBCS data in CLISTs:
* DBCS data cannot appear in any names, including the names of

variables, functions, statements, data sets, or labels.
* DBCS data cannot be used in variables or operands where numeric data

is expected, nor in any arithmetic operations.
* One of the following levels of VTAM must be installed before DBCS data
can be written to or read from the terminal:
- VTAM 3.1.1 for MVS with PTF UY90030

- VTAM 3.2 for MVS.
This book lists further DBCS considerations and restrictions wherever they
apply.
Two CLIST built-in functions, &SYSONEBYTE and &SYSTWOBYTE, convert data

between the DBCS and EBCDIC character sets. These functions are described
in Topic 6, "Using Built-in Functions".
4.0 Topic 4. Using Symbolic Variables
The CLIST language includes several types of variables. This topic

describes how to use symbolic CLIST variables. Later topics discuss other
types of variables, including control variables and variables set by CLIST
built-in functions.
4.1 What is a Symbolic Variable?
A symbolic variable is a string of characters that you define as a symbol.

Because the variable is a symbol, you can assign different values to it at
different times. By assigning different values, you can do the same
processing with different data.
For example, you could use the SET statement to assign different values to
a symbolic variable named PAY_RAISE:
SET PAY_RAISE = 20 /* Set the value of PAY_RAISE equal to 20
or
SET PAY_RAISE = 30 /* Set the value of PAY_RAISE equal to 30
You could use those different values of PAY_RAISE in the following

equation, to calculate your total annual raise based on various weekly
raises:
SET ANNUAL_RAISE = &PAY_RAISE * 52
In CLISTs, the ampersand (&) means "the value of." In the example above,
the CLIST multiplies the value of PAY_RAISE (20 or 30) by 52 and assigns
the resulting value to another variable, ANNUAL_RAISE. (In a SET
statement, the ampersand is required on variables to the right of the
equal sign, and is optional on variables to the left of the equal sign.)
When you execute a CLIST, it scans each line and replaces the symbolic
variables with their actual values. This process is called symbolic
substitution.
In a CLIST, you can use symbolic variables to include variable data on

TSO/E commands and subcommands, on JCL statements, and on many of the
CLIST statements.
Valid Names of Variables
You can define symbolic variables with meaningful names. Meaningful

variable names, like PAY_RAISE, describe the contents of the variable and
make CLISTs easy to read and maintain. Note that an ampersand (&) is not
part of a variable name; it simply tells the CLIST to use the value of the
variable. Follow these rules when naming a symbolic variable:
1. The first character must be one of the following: A-Z, (a-z), _, #,

$, @.
Note: The system recognizes the following hexadecimal codes for these
characters: _ (X'6D'), # (X'7B'), $ (X'5B'), @ (X'7C'). In countries
other than the U.S., these characters on a keyboard might generate
different hexadecimal codes and cause an error. For example, in some
countries the $ character might generate a X'4A'.
2. The remaining characters can be any of the above, and 0 through 9.
3. The variable name can be up to 252 characters in length (not counting

the ampersand).
4. Variable names must not match the character equivalents of CLIST

operators, such as "EQ" and "NE" (see Figure 3-2 for a list).
5. Special rules apply to the PROC statement. On PROC statements:
* All variables must begin with A-Z, and be in uppercase only.

* Names of keyword variables cannot contain the underscore (_), or
be longer than 31 characters. For more information, see "Using
the PROC Statement" in topic 4.2.
6. If variables are used on ISPF panels, they cannot exceed eight

characters in length.
7. Do not use the names of statements or their keywords as variable

names. This may cause unexpected results if used in a conditional
statement, as in the following sequence:
SET WHILE = &STR(ABC)

DO UNTIL &WHILE = &STR(ABC) WHILE (&COUNT<5)
SET &COUNT = &COUNT + 1
END
The results are also unpredictable if a keyword is used within a

string, as in the following:
SET COUNT = 0
SET VAR = ABC
DO UNTIL &VAR = &SUBSTR(3:3,WHILE) WHILE &COUNT < 5
SET COUNT = &COUNT + 1
END
Valid Values of Variables
The values of CLIST variables can generally include any characters you can
enter on a keyboard. See "Characters Supported in CLISTs" in topic 3.2
for information on special characters.
Values of symbolic variables can be up to 32,756 bytes long, minus the

length of the CLIST statement that assigns the value. For example, if the
assignment statement is six bytes long (SET A=), the value can contain
32,750 bytes.
4.2 Defining Symbolic Variables and Assigning Values to Them
There are several ways to define symbolic variables and assign values to
them in a CLIST. Here are some basic methods:
* Use the SET statement to define variables and give them specific
values.
* Use the READ statement to define variables and get their values from a
user.
* Use the PROC statement to define variables and get their values from
parameters passed to the CLIST.
The previous statements define variables explicitly. You can also define
a variable implicitly by referring to it in a CLIST statement before you
explicitly define it. The CLIST assigns a null value to such a variable.
Using the SET Statement
You can use the SET statement to define a symbolic variable and assign a
value to it. For example, to assign the character string JOHN to the
variable NAME, code:
SET NAME=JOHN
The variable NAME contains the value JOHN.
You can also use the SET statement to assign an initial value to a
variable, then increase or decrease the value as necessary. For example,
to control a loop you can initialize a counter:
SET COUNTER = 1
For each execution of the loop, you can increment the counter:
SET COUNTER = &COUNTER + 1
In the SET statement, the ampersand is required when a variable appears in

the expression on the right side of the equal sign, but is optional when a
variable appears on the left-hand side of the equal sign.
In addition to symbolic variables, you can also use CLIST control

variables and built-in functions in SET statements. For information about
control variables and built-in functions, see Topic 5, "Using Control
Variables" and Topic 6, "Using Built-in Functions".
Using the READ Statement
You can use the READ statement to define a variable and give it a value
provided by the CLIST user. To prompt the user for input, issue a WRITE
statement before the READ statement, for example:
WRITE What is your name?

READ &NAME
The user sees the question "What is your name?" displayed on the terminal.
The user's typed response, for example, JOHN, becomes the value of the
variable NAME. Your CLIST can then use this value in subsequent
statements, such as:
WRITE HELLO &NAME! /* (result: HELLO JOHN!)
For more information about the READ and WRITE statements, see Topic 8,
"Communicating with the Terminal User".
Using the PROC Statement
The PROC statement lets you pass parameters to a CLIST at invocation. The
PROC statement defines symbolic variables and assigns the parameters to
the variables. To do so, the PROC statement must be the first functional
line of the CLIST (only comments or blank lines can precede the PROC
statement).
Passing Parameters to a PROC Statement
When invoking a CLIST explicitly, pass parameters in single quotes, for

example:
EX clistname 'parm1 parm2(value)'
When invoking the CLIST implicitly, omit the quotes:
%clistname parm1 parm2(value)
To pass parameters that contain single quotes, you must follow special
rules that are discussed in TSO/E V2 Command Reference, SC28-1881.
The PROC statement accepts two types of parameters: positional parameters

and keyword parameters. Parameter values in lowercase are changed to
uppercase.
Using PROC with Positional Parameters
You can use the PROC statement to assign parameters to variables by

position. First, type a number on the PROC statement telling how many
positional parameters to expect (type 0 if none). Then specify the
variables that you want to use. For example, in the following PROC
statement, the number 1 tells the CLIST to assign the first parameter it
receives to the variable NAME.
PROC 1 NAME
Thus, if you invoke the CLIST with the parameter JOE:
EX clistname 'JOE'
the variable NAME contains the value JOE.
Suppose you wanted the PROC statement to assign a second parameter to the
variable ADDRESS. You could write the statement as follows:
PROC 2 NAME ADDRESS
The invoker must know the correct order in which to pass positional
parameters, and must pass as many as you specify by number on the PROC
statement. If the invoker doesn't pass a positional parameter as
expected, the CLIST prompts for it. Positional parameters can have up to
252 characters (A-Z, 0-9, #, $, @, _).
Using PROC with Keyword Parameters
When input parameters are optional or can have default values, use the
PROC statement to assign the parameters to variables by name rather than
by position. Such parameters (keyword parameters) must match a variable
name that you specify on the PROC statement. See item 5 in topic 4.1 for
special rules on naming variables specified on the PROC statement. The
PROC statement can accept keyword parameters with or without values.
Keyword parameters and their matching variables have up to 31 alphameric

characters (A-Z, 0-9, #, $, @). Keyword parameter values have the same
length restriction as symbolic variable values: 32,768 bytes.
Keywords with Values
If a CLIST has a value that applies to most but not all uses of the CLIST,
you can provide a default value and allow invokers to override it with a
keyword parameter.
In the following example, the 0 tells the CLIST to expect no positional

parameters. (If there are no positional parameters, a zero is required.)
The notation STATE(NY) gives the variable STATE the default value of NY.
PROC 0 STATE(NY)
The invoker can override the default value by passing the keyword
parameter with another value, for example:
EX clistname 'STATE(NJ)'
or
%clistname STATE(NJ)
Then the variable STATE takes the value NJ.
If you want a variable to have no default value but allow invokers to

specify a value, use empty parentheses. The following PROC statement lets
invokers pass keyword parameters such as STATE(NY) or STATE(NJ).
PROC 0 STATE()
In the example above, if an invoker passes the keyword parameter STATE

without a value, the CLIST prompts for the value. If a invoker does not
pass the keyword STATE at all, the variable STATE takes a null value.
Keywords without Values
You can use keyword parameters without values to let invokers specify a
CLIST option. For example, to let an invoker tell a CLIST to print its
results, you could code the following:
PROC 0 PRINT
Then, if the invoker passes the keyword parameter PRINT:
EX clistname 'PRINT'
the variable PRINT takes the value PRINT. If the invoker does not pass
the parameter PRINT, the variable PRINT takes a null value. Your CLIST
can test the value to see if the invoker wants the print option. You can
code this test using an IF-THEN-ELSE sequence:
PROC 0 PRINT
IF &PRINT = PRINT THEN (print results) /* If the value of PRINT = print
...*/
ELSE ...
(For more information about the IF-THEN-ELSE sequence, see "The

IF-THEN-ELSE Sequence" in topic 7.1.)
Using PROC with both Positional and Keyword Parameters
The following PROC statement receives both positional and keyword

parameters:
PROC 2 NAME ADDRESS STATE(NY) ZIP() PRINT
The number 2 indicates that the invoker must pass positional parameters
for the first two variables, NAME and ADDRESS. Invokers can also pass
keyword parameters with values for the variables STATE (the default value
is NY) and ZIP (which has no default). In addition, invokers can pass the
keyword parameter PRINT without a value, to specify a print option.
Examples
The following CLIST addresses a memo based on PROC variables, displaying

the address at the terminal. You could also use I/O statements (described
in Topic 9, "Performing File I/O") to write the address to a data set.
/********************************
/* Memo-addressing CLIST
/********************************
PROC 2 NAME ADDRESS STATE(NY) ZIP()
WRITE TO: &NAME
WRITE AT: &ADDRESS
WRITE &STATE &ZIP
Assume that the CLIST resides in the member MEMO of a partitioned data set
called PROC.CLIST. If you invoked it as follows:
ex proc(memo) 'Perry_Gordon 22_Oak_St._Pokville ZIP(10101)'
You would see the following output at your terminal:
TO: PERRY_GORDON
AT: 22_OAK_ST._POKVILLE
NY 10101
If you invoked it without parameters, for example,
ex proc(memo)
the CLIST would prompt you for a name and address. The state would
default to NY, and there would be no zip code.
The following CLIST issues the LISTDS command using the PROC, READ, and
SET statements to define variables and assign values to them.
/*********************************************************************/
/* This CLIST issues the LISTDS command, using a data set name and */
/* any options requested by the user. If the user enters OPTIONS */
/* as a parameter, READ and WRITE statements prompt for the options. */
/* The CLIST gets a LISTDS return code from the &LASTCC control */
/* variable, and writes the return code to the screen. */
/*********************************************************************/
PROC 1 DATASET OPTIONS /* Get a data set name */
IF &OPTIONS = OPTIONS THEN /* If the user wants options, */ +
DO /* prompt for input */
WRITE Type LISTDS options (MEMBER, HISTORY, or STATUS)
READ OPT
END
LISTDS &DATASET &OPT /* List data set with any options */
SET RETURN_CODE = &LASTCC /* Get return code from LISTDS */
WRITE RETURN CODE WAS &RETURN_CODE
4.3 More Advanced Uses of Variables
The previous sections of this topic discussed several basic ways to define
and assign values to symbolic variables, using the SET, READ, and PROC
statements. Other topics describe how to use symbolic variables in more
advanced applications with other CLIST statements:
* The GLOBAL, NGLOBAL, SYSCALL, and SYSREF statements let you define
variables for use in nested CLISTs and CLIST subprocedures. See
Topic 7, "Structuring CLISTs" for information about using variables
with these statements.
* The I/O statements OPENFILE, CLOSEFILE, GETFILE, and PUTFILE use

symbolic variables to send and receive input between files. See
Topic 9, "Performing File I/O" for information about using variables
with these statements.
* The LISTDSI statement uses a special set of CLIST variables for

retrieving information about data set attributes. See Topic 5, "Using
Control Variables" for information about this statement and its
variables.
Combining Symbolic Variables

You can combine one symbolic variable with another symbolic variable to
form a compound variable.
Suppose a CLIST invokes programs that reside in nine data sets named
PROGRAM1 through PROGRAM9. By combining &PROGRAM and &I you can use the
iterative DO loop structure to invoke PROGRAM1 through PROGRAM9 as
follows:
SET PROGRAM = PROGRAM

DO &I = 1 to 9
call mylib(&PROGRAM&I)
END
(For more information about using an iterative DO loop, see "The Iterative
DO Sequence" in topic 7.2.) By increasing the value of I from one to nine
in a loop, a CLIST could invoke the following set of programs without
having to modify the CALL command.
PROGRAM1
PROGRAM2
.
.
.
PROGRAM9
You can also combine symbolic variables and character strings. When the
variable precedes the character string, place a period after the symbolic
variable to distinguish it from the character string:
&PROGRAM.A
No period is required when the character string precedes the symbolic

variable because the ampersand distinguishes the variable from the string:
A&PROGRAM
: Using a Variable to Preserve Leading Spaces in a CLIST
: When TSO/E processes a job in a CLIST, statements following the DD *

: statement are left adjusted to column 1, thereby removing leading spaces.
: (This is unique to CLIST processing and is not a batch concern.) If you
: need to preserve the blanks, set a variable to a single blank or a string
: of blanks to provide as many blanks as required, that is &STR( ) and
: precede all statements following the DD * with that variable. The
: following example shows how to include the variable within your CLIST.
: PROC01
: CONTROL
: SET &A = STR( )
: SUBMIT * END(XX)
: //JOBCARD
: //OTHER
: //JCL
: //CARDS
: // DD *
: &A COPY ...
: &A ...
: &A ...
: &A ...
Nesting Symbolic Variables
In some situations, you might want to store the name of a variable in

another variable. For example, if you had to process two variables in the
same way, you could assign their names to a third variable.
When you store the name of a variable in another variable, you are
"nesting" variables.
To nest one variable in another variable, use an assignment statement with

double ampersands. For example, to nest the variable &CAT in the variable
&MAMMAL, code:
SET MAMMAL = &&CAT /* result: &MAMMAL contains &CAT */
The double ampersands (&&) prevent the CLIST from performing symbolic
substitution on the variable string &CAT. In the assignment statement,
the CLIST removes only the first ampersand, setting &MAMMAL to the value
&CAT.
It is most useful to nest variables when you have to process many

variables that have similar names. For example, if you have to set
&VARIABLE to different variables such as &LINE1, &LINE2, during
processing, you could code many SET statements, or code the following
sequence:
SET NUMBER=0
SET VARIABLE=&&LINE&NUMBER /* Initialize &VARIABLE to &LINE0 */
DO WHILE &NUMBER<8 /* Process from &LINE1-&LINE8 */
SET NUMBER = &NUMBER+1 /* Increase &NUMBER to create next
/* variable name */
SET VARIABLE=&&LINE&NUMBER /* Set &VARIABLE to next variable
/* name */
(processing)
END
For more examples of using nested variables, see "&SYSOUTLINE" in

topic 5.9, and Figure 12-17 in topic 12.14.
If you nest variables whose values contain double ampersands, the

outermost variable contains the name of the innermost variable. For
example, after the following statements execute, VARIABLE contains &LINE1
and DATA contains the value 430.
SET LINE1=430
SET NUMBER=1
SET VARIABLE=&&LINE&NUMBER
SET DATA=&VARIABLE
Combining Nested Variables with Character Strings
As previously stated, you can combine a preceding variable with a

character string by placing a period between them (&PROGRAM.A). If the
preceding variable is nested, place an additional period after the
variable for each level of nesting. For example,
SET &BUDGET = June

SET &PROGRAM = &budget
call mylib(&PROGRAM.A) /* result: call mylib(JuneA)
If the character string precedes the variable, no period is required:
SET &BUDGET = June

SET &PROGRAM = &budget
call mylib(A&PROGRAM) /* result: call mylib(AJune)
Substitution of Nested Variables
If a CLIST encounters nested symbolic variables in a line, it normally

scans the line (performs symbolic substitution) multiple times until all
symbolic variables are resolved. For example:
SET A = 50
SET B = &&C /* result: &B contains &C
SET C = &A+50 /* result: &C contains 100
SET D = &&A /* result: &D contains &A
SET X = (&D+&B)/&D /* result: &X contains 3
To resolve the fifth expression the CLIST uses the values assigned to the
symbolic variables A-D and assigns the value 3 to X.
You can limit the number of times the CLIST scans a line of nested
variables, using the &SYSNSUB built-in function. For example, you could
specify that the CLIST scan the fifth expression in the preceding example
only once, so the variables were resolved to only one level of symbolic
substitution. As a result, the CLIST would resolve &X from (&D+&B)/&D to
(&A+&C)/&A, and go no further. See Topic 6, "Using Built-in Functions" in
topic 6.0 for a description and examples of &SYSNSUB.
Combining Variables Containing DBCS Data
When variables containing data of the double-byte character set (DBCS) are
combined with other DBCS data, contiguous DBCS delimiters are removed to
create a single DBCS string. For example:
SET A = <d1d2>
SET B = <d3d4>&A.<d5d6> /* result: &B = <d3d4d1d2d5d6>
5.0 Topic 5. Using Control Variables
The CLIST language includes a set of control variables. Control variables

provide information about MVS, TSO/E, and the current session, such as
levels of software available, the time of day, and the date. Your CLISTs
can use the control variables to obtain such current information.
You code a control variable as you would a symbolic variable. For

example, to get the time of day, your CLIST could use the control variable
&SYSTIME as follows:
WRITE It's &SYSTIME
If your CLIST was executing at 2:32:58 PM, the result would be:
It's 14:32:58
You do not have to define control variables. Control variables have

constant names; you simply refer to the variable name to obtain
information.
Control variables to which you can assign values are called modifiable
control variables. The variable &SYSOUTTRAP is an example of a modifiable
control variable. &SYSOUTTRAP tells how many lines of TSO/E command
output should be saved in a CLIST. If you want to save 100 lines of
output from each TSO/E command in your CLIST, you can set &SYSOUTTRAP to
100, as follows:
SET &SYSOUTTRAP = 100
Your CLIST would then be able to retrieve and process up to 100 lines of
output from each command in the CLIST. If you did not want to save output
from some commands, you would reset &SYSOUTTRAP to zero before issuing
those commands.
5.1 Overview of using Control Variables
Figure 5-1 lists the control variables in related categories, and

: indicates what topic they are on, whether they are modifiable, and whether
: they are retrievable by the variable access routine, IKJCT441. For more
: information about IKJCT441, refer to TSO/E V2 Programming Services,
: SC28-1875.
] Figure 5-2 briefly describes the modifiable control variables, and

] Figure 5-3 briefly describes the control variables you cannot modify.
]------------------------------------------------------------------------]
: ] Figure 5-1. Control Variable by Category ]
]----------------------]-------------]-------------]-------------]-------]
: ] Category ] Variable ] Modifiable ] Retrievable ] Topic ]
: ] ] ] ] by IKJCT441 ] ]
]----------------------]-------------]-------------]-------------]-------]
: ] Current date and ] &SYSDATE ] No ] No ] 5.2 ]
: ] time ] &SYSJDATE ] No ] No ] 5.2 ]
: ] ] &SYSSDATE ] No ] No ] 5.2 ]
] ] ] &SYS4DATE ] No ] No ] 5.2 ]
] ] ] &SYS4JDATE ] No ] No ] 5.2 ]
] ] ] &SYS4SDATE ] No ] No ] 5.2 ]
: ] ] &SYSTIME ] No ] No ] 5.2 ]
: ] ] &SYSSTIME ] No ] No ] 5.2 ]
]----------------------]-------------]-------------]-------------]-------]
: ] Terminal-related ] &SYSLTERM ] No ] No ] 5.3 ]
: ] ] &SYSWTERM ] No ] No ] 5.3 ]
]----------------------]-------------]-------------]-------------]-------]
: ] User-related ] &SYSUID ] No ] No ] 5.4 ]
: ] ] &SYSPREF ] No ] No ] 5.4 ]
: ] ] &SYSPROC ] No ] No ] 5.4 ]
]----------------------]-------------]-------------]-------------]-------]
] ] System-related ] &SYSCLONE ] No ] No ] 5.5 ]
: ] ] &SYSCPU ] No ] No ] 5.5 ]
] ] ] &SYSDFP ] No ] No ] 5.5 ]
: ] ] &SYSHSM ] No ] No ] 5.5 ]
: ] ] &SYSISPF ] No ] No ] 5.5 ]
] ] ] &SYSJES ] No ] No ] 5.5 ]
: ] ] &SYSLRACF ] No ] No ] 5.5 ]
] ] ] &SYSAPPCLU ] No ] No ] 5.5 ]
] ] ] &SYSMVS ] No ] No ] 5.5 ]
] ] ] &SYSNAME ] No ] No ] 5.5 ]
] ] ] &SYSNODE ] No ] No ] 5.5 ]
: ] ] &SYSRACF ] No ] No ] 5.5 ]
] ] ] &SYSPLEX ] No ] No ] 5.5 ]
] ] ] &SYSSECLAB ] No ] No ] 5.5 ]
] ] ] &SYSSMFID ] No ] No ] 5.5 ]
] ] ] &SYSSMS ] No ] No ] 5.5 ]
: ] ] &SYSSRV ] No ] No ] 5.5 ]
] ] ] &SYSSYMDEF ] No ] No ] 5.5 ]
] ] ] &SYSTERMID ] No ] No ] 5.3 ]
: ] ] &SYSTSOE ] No ] No ] 5.5 ]
]----------------------]-------------]-------------]-------------]-------]
: ] CLIST-related ] &SYSSCAN ] Yes ] Yes ] 5.6 ]
: ] ] &SYSENV ] No ] No ] 5.6 ]
: ] ] &SYSICMD ] No ] No ] 5.6 ]
: ] ] &SYSPCMD ] No ] No ] 5.6 ]
: ] ] &SYSSCMD ] No ] No ] 5.6 ]
: ] ] &SYSNEST ] No ] No ] 5.6 ]
]----------------------]-------------]-------------]-------------]-------]
: ] CLIST-related (1) ] &SYSPROMPT ] Yes ] Yes ] 5.7 ]
: ] ] &SYSSYMLIST ] Yes ] Yes ] 5.7 ]
: ] ] &SYSCONLIST ] Yes ] Yes ] 5.7 ]
: ] ] &SYSLIST ] Yes ] Yes ] 5.7 ]
: ] ] &SYSASIS ] Yes ] Yes ] 5.7 ]
: ] ] &SYSMSG ] Yes ] Yes ] 5.7 ]
: ] ] &SYSFLUSH ] Yes ] Yes ] 5.7 ]
]----------------------]-------------]-------------]-------------]-------]
: ] Input-related ] &SYSDLM ] No ] Yes ] 5.8 ]
: ] ] &SYSDVAL ] Yes ] Yes ] 5.8 ]
]----------------------]-------------]-------------]-------------]-------]
: ] Output-related ] &SYSOUTTRAP ] Yes ] Yes ] 5.9 ]
: ] ] &SYSOUTLINE ] Yes ] Yes ] 5.9 ]
]----------------------]-------------]-------------]-------------]-------]
: ] Return codes ] &LASTCC ] Yes ] Yes ] 5.10 ]
: ] ] &MAXCC ] Yes ] Yes ] 5.10 ]
]----------------------]-------------]-------------]-------------]-------]
]------------------------------------------------------------------------]
] Figure 5-2. Modifiable Control Variables (alphabetically) ]
]-------------]----------------------------------------------------------]
] Modifiable ] Contents ]
] Variable ] ]
]-------------]----------------------------------------------------------]
] &LASTCC ] Contains the return code from the last operation (TSO/E ]
] ] command, subcommand, or CLIST statement). ]
]-------------]----------------------------------------------------------]
] &MAXCC ] Contains the highest return code issued up to this point ]
] ] in the CLIST or the highest passed back from a nested ]
] ] CLIST. ]
]-------------]----------------------------------------------------------]
] &SYSASIS ] ON specifies CONTROL NOCAPS/ASIS. OFF specifies CONTROL ]
] ] CAPS. ]
]-------------]----------------------------------------------------------]
] &SYSCONLIST ] ON specifies CONTROL CONLIST. OFF specifies CONTROL ]
] ] NOCONLIST. ]
]-------------]----------------------------------------------------------]
] &SYSDVAL ] (1) Contains the input line supplied by the user when ]
: ] ] the user returned control to the CLIST after a TERMIN or ]
: ] ] TERMING statement. (2) Contains the input line supplied ]
] ] by the user after a READ statement without operands. ]
] ] (3) Contains the value after the execution of a SET ]
] ] SYSDVAL=. ]
]-------------]----------------------------------------------------------]
] &SYSFLUSH ] ON specifies CONTROL FLUSH. OFF specifies CONTROL ]
] ] NOFLUSH. ]
]-------------]----------------------------------------------------------]
] &SYSLIST ] ON specifies CONTROL LIST. OFF specifies CONTROL ]
] ] NOLIST. ]
]-------------]----------------------------------------------------------]
] &SYSMSG ] ON specifies CONTROL MSG. OFF specifies CONTROL NOMSG. ]
]-------------]----------------------------------------------------------]
] &SYSOUTLINE ] Contains the number of lines of command output produced ]
] ] by a TSO/E command; points to the CLIST variables ]
] ] containing the output. ]
]-------------]----------------------------------------------------------]
] &SYSOUTTRAP ] Contains the maximum number of lines of TSO/E command ]
] ] output to be saved. ]
]-------------]----------------------------------------------------------]
] &SYSPROMPT ] ON specifies CONTROL PROMPT. OFF specifies CONTROL ]
] ] NOPROMPT. ]
]-------------]----------------------------------------------------------]
] &SYSSCAN ] Contains the maximum number of times a CLIST can rescan ]
] ] a line to evaluate variables. The default is 16 times. ]
] ] The maximum value is +2,147,483,647. The minimum is 0. ]
]-------------]----------------------------------------------------------]
] &SYSSYMLIST ] ON specifies CONTROL SYMLIST. OFF specifies CONTROL ]
] ] NOSYMLIST. ]
]-------------]----------------------------------------------------------]
]------------------------------------------------------------------------]
] Figure 5-3. Non-modifiable Control Variables (alphabetically) ]
]----------------]-------------------------------------------------------]
] Non-modifiable ] Contents ]
] Variable ] ]
]----------------]-------------------------------------------------------]
] ] &SYS4DATE ] Contains the current date in the form: ]
] ] ] month/day/year, where year is presented as four-digit ]
] ] ] number. ]
]----------------]-------------------------------------------------------]
] ] &SYS4JDATE ] Contains the Julian date in the form: year.days, ]
] ] ] where year is presented as four-digit number. ]
]----------------]-------------------------------------------------------]
] ] &SYS4SDATE ] Contains the date in the form: year/month/day, where ]
] ] ] year is presented as four-digit number. ]
]----------------]-------------------------------------------------------]
] ] &SYSCLONE ] Contains the MVS system symbol representing its ]
] ] ] system name. ]
]----------------]-------------------------------------------------------]
] &SYSCPU ] Contains the number seconds of CPU time used during ]
] ] the session in the form: ]
] ] seconds.hundredths_of_seconds ]
]----------------]-------------------------------------------------------]
] &SYSDATE ] Contains the current date in the form: month/day/year ]
]----------------]-------------------------------------------------------]
] ] &SYSDFP ] Contains the level of MVS/Data Facility Product ]
] ] ] (MVS/DFP) installed on your system. ]
]----------------]-------------------------------------------------------]
] &SYSDLM ] Contains the input line supplied by the user to ]
: ] ] return control to the CLIST after a TERMIN or TERMING ]
: ] ] statement. ]
]----------------]-------------------------------------------------------]
] &SYSENV ] Indicates whether the CLIST is executing in the ]
] ] foreground or background environment. ]
]----------------]-------------------------------------------------------]
] &SYSHSM ] Indicates the level of Data Facility Hierarchical ]
] ] ] Storage Manager (DFHSM) available to the CLIST; or, ]
] ] ] if DFSMS/MVS is installed rather than DFHSM, the ]
] ] ] level of the DFSMShsm component of DFSMS/MVS. ]
]----------------]-------------------------------------------------------]
] &SYSICMD ] Contains the name by which the invoker implicitly ]
] ] invoked this CLIST. (This value is null if the ]
] ] invoker explicitly invoked the CLIST.) ]
]----------------]-------------------------------------------------------]
] &SYSISPF ] Indicates whether ISPF dialog management services are ]
] ] available to the CLIST. ]
]----------------]-------------------------------------------------------]
] &SYSJDATE ] Contains the Julian date in the form: year.days ]
]----------------]-------------------------------------------------------]
] ] &SYSJES ] Contains the name and the level of the JES installed ]
] ] ] on your system. ]
]----------------]-------------------------------------------------------]
] &SYSLRACF ] Indicates the level of the Resource Access Control ]
] ] Facility (RACF) available to the CLIST. (See ]
] ] &SYSRACF below) ]
]----------------]-------------------------------------------------------]
] &SYSLTERM ] Contains the number of lines available for ]
] ] applications on your terminal screen. ]
]----------------]-------------------------------------------------------]
] ] &SYSAPPCLU ] Contains the APPC/MVS logical unit (LU) name. ]
]----------------]-------------------------------------------------------]
] ] &SYSMVS ] Contains the level of the base control program (BCP) ]
] ] ] component of MVS/ESA. ]
]----------------]-------------------------------------------------------]
] ] &SYSNAME ] Contains the system's name your CLIST is running on, ]
] ] ] as specified on the SYSNAME statement in SYS1.PARMLIB ]
] ] ] member IEASYSxx. ]
]----------------]-------------------------------------------------------]
] &SYSNEST ] Indicates whether the currently executing CLIST was ]
] ] invoked by another CLIST. ]
]----------------]-------------------------------------------------------]
] ] &SYSNODE ] Contains the network node name of your installation's ]
] ] ] JES. ]
]----------------]-------------------------------------------------------]
] &SYSPCMD ] Contains the name (or abbreviation of the name) of ]
] ] the most recently executed TSO/E command in this ]
] ] CLIST. ]
]----------------]-------------------------------------------------------]
] ] &SYSPLEX ] Contains the MVS sysplex name as found in the ]
] ] ] COUPLExx or LOADxx member of SYS1.PARMLIB. ]
]----------------]-------------------------------------------------------]
] &SYSPREF ] Contains the prefix that TSO/E uses to fully qualify ]
] ] data set names. ]
]----------------]-------------------------------------------------------]
] &SYSPROC ] Contains the name of the logon procedure used when ]
] ] the TSO/E user logged on. ]
]----------------]-------------------------------------------------------]
] &SYSRACF ] Indicates whether the Resource Access Control ]
] ] Facility (RACF) is installed and available to the ]
] ] CLIST. ]
]----------------]-------------------------------------------------------]
] &SYSSCMD ] Contains the name of the most recently executed ]
] ] subcommand. ]
]----------------]-------------------------------------------------------]
] &SYSSDATE ] Contains the date in the form: year/month/day ]
]----------------]-------------------------------------------------------]
] ] &SYSSECLAB ] Contains the security label (SECLABEL) name of the ]
] ] ] TSO/E session. ]
]----------------]-------------------------------------------------------]
] ] &SYSSMFID ] Identifies the system on which System Management ]
] ] ] Facilities (SMF) is active. ]
]----------------]-------------------------------------------------------]
] ] &SYSSMS ] Indicates whether DFSMS/MVS is available to your ]
] ] ] CLIST. ]
]----------------]-------------------------------------------------------]
] &SYSSRV ] Contains the number of System Resource Manager (SRM) ]
] ] service units used during the session. ]
]----------------]-------------------------------------------------------]
] ] &SYSSYMDEF ] Contains the symbolic name of the MVS system. ]
]----------------]-------------------------------------------------------]
] ] &SYSTERMID ] Contains the terminal ID of the terminal where the ]
] ] ] CLIST has been started. ]
]----------------]-------------------------------------------------------]
] &SYSSTIME ] Contains the time of day in the form: hours:minutes ]
]----------------]-------------------------------------------------------]
] &SYSTIME ] Contains the time of day in the form: ]
] ] hours:minutes:seconds ]
]----------------]-------------------------------------------------------]
] &SYSTSOE ] Indicates the level of TSO/E installed in the form: ]
] ] version release modification_number ]
]----------------]-------------------------------------------------------]
] &SYSUID ] Contains the user ID under which the current session ]
] ] is logged. ]
]----------------]-------------------------------------------------------]
] &SYSWTERM ] Contains the width of the screen. ]
]----------------]-------------------------------------------------------]
] (1) Lets you test or modify the CLIST CONTROL statement values.
5.2 Getting the Current Date and Time
The following control variables provide information related to the current

date and time. You cannot modify any of them with an assignment
statement.
&SYSDATE, &SYSSDATE, and &SYSJDATE
] Three variables provide the current date. Note that these variables
] return the current year as a two-digit number. In support of dates equal
] or greater than 2000, another set of variables is provided that returns
] the current year as four-digit number.
&SYSDATE provides the date in the American standard form: month/day/year.

If executed on October 13, 1987, the following statement displays the
message "Today is 10/13/87":
WRITE Today is &SYSDATE
&SYSSDATE provides the date in a form that can be sorted: year/month/day.

If executed on October 13, 1987, the following statement displays the
message "Today is 87/10/13":
WRITE Today is &SYSSDATE
&SYSJDATE provides the date in the Julian form: year.days. If executed on

October 13, 1987, the following statement displays the message "Today is
87.286":
WRITE Today is &SYSJDATE
&SYSDATE and &SYSSDATE provide data that contain slashes. As a result,

when they appear in expressions on comparative and assignment statements,
enclose them in &STR built-in functions. For example, in the following
example &SYSDATE appears in a statement containing comparative
expressions; therefore, enclose it in a &STR built-in function. However,
the use of &STR is unnecessary on the WRITE statement.
IF &STR(&SYSDATE) = &STR(10/13/87) THEN +

WRITE On &SYSDATE, the system was down for &TMIN minutes.
] &SYS4DATE, &SYS4SDATE, and &SYS4JDATE
] Three variables provide the current date in a format that presents years
] as four-digit numbers. As opposed to the variables that present the
] current year as two-digit numbers, these variables are capable to handle
] years beyond 1999.
] &SYS4DATE provides the date in the American standard form: month/day/year.

] If executed on August 29, 1995, the following statement displays the
] message "Today is 08/29/1995":
] WRITE Today is &SYS4DATE
] &SYS4SDATE provides the date in a form that can be sorted: year/month/day.

] If executed on August 29, 1995, the following statement displays the
] message "Today is 1995/08/29":
] WRITE Today is &SYS4SDATE
] &SYS4JDATE provides the date in the Julian form: year.days. If executed

] on August 29, 1995, the following statement displays the message "Today is
] 1995.241":
] WRITE Today is &SYS4JDATE

] &SYS4DATE and &SYS4SDATE provide data that contain slashes. As a result,
] when they appear in expressions on comparative and assignment statements,
] enclose them in &STR built-in functions. For example, in the following
] example &SYS4DATE appears in a statement containing comparative
] expressions; therefore, enclose it in a &STR built-in function. However,
] the use of &STR is unnecessary on the WRITE statement.
] IF &STR(&SYS4DATE) = &STR(08/29/1995) THEN +

] WRITE On &SYS4DATE, the system was down for &TMIN minutes.
&SYSTIME and &SYSSTIME
Two variables provide the current time of day.
&SYSTIME provides the time in the form: hours:minutes:seconds. If

executed at 2:32 and 58 seconds P.M., the following statement displays the
message "It's 14:32:58":
WRITE It's &SYSTIME
&SYSSTIME provides a shortened version of &SYSTIME, in the form:

hours:minutes. If executed at 2:32 and 58 seconds P.M., the following
statement displays the message "It's 14:32":
WRITE It's &SYSSTIME
5.3 Getting Terminal Characteristics
] Three control variables provide information about the terminal to which

] the user is logged on.
] &SYSTERMID
] &SYSTERMID contains the terminal ID of the terminal where the CLIST has
] been started. For example,
] PROC 0
] WRITE &SYSTERMID
] EXIT
] may return a terminal ID of M02XA06R, with a maximum length of eight

] characters. Trailing blanks are removed.
] If your CLIST runs in the background, the &SYSTERMID control variable

] returns a null string.
&SYSLTERM and &SYSWTERM
&SYSLTERM provides the number of lines available for applications on your

terminal screen. &SYSWTERM provides the width of the screen.
&SYSLTERM and &SYSWTERM can be used when a CLIST reformats the screen
using Session Manager commands. For example, a CLIST called HORZNTL
splits the terminal screen horizontally based on the number of lines on
the screen and its width. The following section of HORZNTL substitutes
the control variables in the Session Manager commands that define the
windows for the reformatted screen. By using &SYSLTERM and &SYSWTERM
instead of explicit screen positions, HORZNTL makes optimal use of the
space available on a given screen.
SET LINE = (&SYSLTERM-5)/2

SET TOPS = &LINE-1
SET BOT = &LINE+1
SET BOTS = (&SYSLTERM-1)-&BOT
SET BOTSX = (&SYSLTERM-3)-&BOT
smput /save screen;save.pfk;+
save.win main;save.win line;save.win current;+
del.win main;del.win line;del.win current;+
define.window main 1 1 &TOPS &SYSWTERM;+
define.window line &LINE 1 1 &SYSWTERM;+
define.window current &BOT 1 &BOTS &EVAL(&SYSWTERM-18)/
5.4 Getting Information about the User
Three control variables provide user-related information including the

current user ID, logon procedure, and data set prefix.
&SYSUID
&SYSUID provides the user ID under which the current TSO/E session is
logged on. Use this variable in messages and wherever logic depends on,
or references, the user ID. For example, the following message displays
information about how the CLIST is invoked:
WRITE CLIST invoked by user &SYSUID at &SYSTIME on &SYSSDATE
&SYSPREF
&SYSPREF provides the current data set name prefix that is prefixed to
non-fully-qualified data set names. The PROFILE command controls this
prefix. Use &SYSPREF when you want to allocate data sets that are unique
to the user who invoked the CLIST. For example, the following ALLOCATE
command allocates unique data sets for invokers of a CLIST containing the
command:
alloc da('&SYSPREF..records.data') shr reuse
Two periods are required between &SYSPREF and RECORDS; the first indicates
the end of the variable name, and the second is part of the text to be
concatenated. After substitution, the command has the following form:
alloc da('prefix.records.data') shr reuse
&SYSPROC
&SYSPROC provides the name of the logon procedure used when the user
logged on to the current TSO/E session. You can use &SYSPROC to determine
whether programs, such as Session Manager, are available to the user. For
example, before invoking the CLIST (HORZNTL) that reformats the screen
using Session Manager commands, verify that Session Manager is active.
One way to make the verification is to check the logon procedure as
follows:
IF &STR(&SYSPROC) = SMPROC THEN +

%horzntl
ELSE +
DO
WRITE Your screen cannot be reformatted.
WRITE Log on using SMPROC as logon proc.
END
5.5 Getting Information about the System

The following control variables provide information about the system

environment under which the CLIST is executing.
] You can use these control variables in your CLISTs for different purposes.
] For example, the new variables &SYSNAME, &SYSPLEX, &SYSCLONE, and
] &SYSSYMDEF, introduced with TSO/E 2.5, allow you to write common CLISTs
] that are to run in a sysplex environment. You can build or identify the
] system-specific data set names by using the values returned by these
] control variables.
] &SYSCLONE
] &SYSCLONE returns the MVS system symbol representing its system name. It
] is a 1- to 2-byte shorthand notation for the system name. The value is
] obtained from SYS1.PARMLIB member IEASYMxx (2). For example, if
] SYSCLONE(A1) is specified in IEASYMxx, then
] PROC 0
] WRITE &SYSCLONE
] EXIT
] returns a value of A1. A null string is returned if no MVS SYSCLONE ID is

] specified in IEASYMxx.
] Note: This control variable requires MVS/ESA SP 5.2 or later. If used

] with lower releases, an error message is issued.
&SYSCPU and &SYSSRV
&SYSCPU provides the number of seconds of central processing unit (CPU)

time used during the session in the form: seconds.hundredths_of_seconds.
&SYSSRV provides the number of System Resource Manager (SRM) service units
used during the session.
These variables can be used for measuring the performance of applications

and reporting session duration to the user.
For example, to measure the performance of an application invoked from a

CLIST, you can code the following:
SET CPU = &SYSCPU

SET SRV = &SYSSRV
call mylib(payroll) '50,84'
SET CPU = &STR(&SYSCPU-&CPU)
SET SRV = &STR(&SYSSRV-&SRV)
call mylib(calc) '&STR(&CPU),&STR(&SRV)' /* Measure performance */
.
.
.
/* Do calculations and pass back results */
.
.
.
WRITE &CPU &SRV
The user can then see the number of seconds of CPU time and SRM service
units used by the program PAYROLL.
] &SYSDFP
] &SYSDFP contains the level of MVS/Data Facility Product (MVS/DFP)

] installed on your system. For example,
] PROC 0
] WRITE &SYSDFP
] EXIT
] may return a value of 01.01.02.00. The value returned is in the format

] cc.vv.rr.mm, where cc is the component, vv the version, rr the release
] number, and m the modification level. All values are two-digit decimal
] numbers.
] A value of 00 for cc indicates a pre-DFSMS/MVS component, wheras any value

] other than 00 indicates a DFSMS/MVS component or a follow-on component.
&SYSHSM
] &SYSHSM indicates the status of the Data Facility Hierarchical Storage
] Manager (DFHSM) or the level of the DFSMShsm component of DFSMS/MVS,
] depending of what is installed.
When DFHSM is installed and active, &SYSHSM returns the level of DFHSM
installed, unless the level is before Version 1 Release 3. If a
pre-Release 3 level is installed and active, &SYSHSM returns the value
AVAILABLE. When DFHSM is not installed or not active, &SYSHSM returns a
null value.
If Version 1 Release 3 or higher is installed, &SYSHSM indicates it in the

following format:
PICTURE 1
] If DFSMS/MVS is installed and active, &SYSHSM returns the level of the

] DFSMShsm component, otherwise it returns a null string.
&SYSISPF
&SYSISPF indicates whether ISPF dialog manager services are available.

The variable can have one of two values:
ACTIVE ISPF services are available.

NOT ACTIVE ISPF is not initialized.
] &SYSJES
] &SYSJES contains the name and the level of the JES installed on your
] system. For example,
] PROC 0
] WRITE &SYSJES
] EXIT
] may return JES2 SP 4.3. In this example JES2 is the JES name and SP 4.3
] is the JES level, representing version and release number of JES2. The
] JES level may contain a modification level as well.
] The values returned are provided by the subsystem interface request

] routine (IEFSSREQ).
] Both strings are separated by a blank character; any trailing blank

] characters are removed. If either the JES name or level returns an empty
] character string, then no separating blank character is inserted.
] If the subsystem is not active the string -INACTIVE- is returned (note the
] string delimiters).
] If the system finds that the subsystem is neither JES2 4.3 or later nor
] JES3 5.1.1 or later, the &SYSJES control variable contains the string
] -DOWNLEVEL- (note the string delimiters).

] with lower releases, a null string is returned.
&SYSLRACF
&SYSLRACF indicates the version, release, and modification level of RACF

installed on the system. If RACF is not installed, &SYSLRACF contains a
null value. If RACF is installed, &SYSLRACF returns the level of RACF in
the following format:
PICTURE 2
] &SYSAPPCLU
] &SYSAPPCLU contains the MVS/APPC logical unit (LU) name. The LU name
] identifies the TSO/E address space your CLIST will be running in as the
] SNA addressable unit for Advanced-Program-to-Program-communication (APPC).
] The LU name is obtained via the APPC/MVS Advanced TP Callable Services
] (ATBEXAI - Information Extract Service). For example,
] PROC 0
] WRITE &SYSAPPCLU
] EXIT
] may return an LU name of LU0001. Trailing blanks are removed. A null

] string is returned if:
] * There is no APPC activity in the address space the CLIST is running

] in, or
] * No LU name is provided by the APPC/MVS Advanced TP Callable Services.
] Note: CLISTs do not support CPI Communication (a method to let one

] program communicate with another program on the same or other MVS system
] in an SNA network). Therefore the use of the &SYSAPPCLU control variable
] makes sense only in a CLIST that is invoked by a program (for example, a
] REXX exec) that has established APPC. If the control variable is used
] outside this environment, a null string is returned.

] &SYSMVS
] &SYSMVS contains the level of the base control program (BCP) component of
] MVS/ESA. For example,
] PROC 0
] WRITE &SYSMVS
] EXIT
] may return SP4.3.0 as the version, release, and modification level of the
] BCP component.
] The value returned is that of the CVTPRODN field in the communications

] vector table (CVT).
] Note: The format of the value returned by &SYSMVS may change in future,
] but will remain the content of the CVTPRODN field.
] &SYSNAME
] &SYSNAME returns the system's name your CLIST is running on, as specified
] in SYS1.PARMLIB member IEASYSxx on the SYSNAME statement. For example,
] PROC 0
] WRITE &SYSNAME
] EXIT
] may return ATQS as the MVS system name.
] You may want to use the &SYSNAME control variable to identify on which
] system in a multi-system global resource serialization complex your CLIST
] is running on. See MVS/ESA SP V5 Initialization and Tuning Reference,
] SC28-1452, on how the SYSNAME value is used in a multi-system complex.
] &SYSNODE
] &SYSNODE contains the network node name of your installation's JES. This
] name identifies the local JES in a network of systems or system complexes
] being used for network job entry (NJE) tasks. For example,
] PROC 0
] WRITE &SYSNODE
] EXIT
] may return a value of BOE9, which is the network node name of your local
] JES.
] The node name returned by the &SYSNODE control variable derives from the
] NODE initialization statement of JES.
] If the system finds that the subsystem is not active, the &SYSNODE control
] variable contains the string -INACTIVE- (note the string delimiters).
] If the system finds that the subsystem is neither JES2 4.3 or later nor
] JES3 5.1.1 or later, the &SYSNODE control variable contains the string
] -DOWNLEVEL- (note the string delimiters).

] with lower releases, a null string is returned.
&SYSRACF
&SYSRACF indicates the status of RACF. The variable can have one of three
values:
AVAILABLE RACF services are available.

NOT AVAILABLE RACF is not initialized.
NOT INSTALLED RACF is not installed.
] &SYSPLEX
] &SYSPLEX returns the MVS sysplex name as found in the COUPLExx or LOADxx
] member of SYS1.PARMLIB. For example,
] PROC 0
] WRITE &SYSPLEX
] EXIT
] may return a value of PLEXNY02. The value has a maximum of eight
] characters; trailing blanks are removed. If no sysplex name is specified
] in SYS1.PARMLIB, &SYSPLEX returns a null string.

] &SYSSECLAB
] &SYSSECLAB returns the SECLABEL name that is valid for the TSO/E session
] where the CLIST is started. For example,
] PROC 0
] WRITE &SYSSECLAB
] EXIT
] may return a value of SYSHIGH as the current security label name.

] Trailing blanks are removed.
] Note: The use of the &SYSSECLAB control variable requires that RACF 1.9
] or later is installed, and that security label checking has been
] activated. If no security information is found, the &SYSSECLAB contains a
] null string.
] &SYSSMS
] &SYSSMS indicates whether DFSMS/MVS is available to your CLIST. For

] example,
] PROC 0
] WRITE &SYSSMS
] EXIT
] returns one of the following character strings:
] UNAVAILABLE DFSMS/MVS is not available on your system.

] INACTIVE DFSMS/MVS is available on your system but not active.
] ACTIVE DFSMS/MVS is available and active, so your CLIST can depend
] on it.
] Note: This control variable requires MVS/Data Facility Product (MVS/DFP)

] Version 3.3 or later. If used with lower releases, an error message is
] issued.
] &SYSSMFID
] &SYSSMFID identifies the system on which System Management Facilities

] (SMF) is active. The value returned is as specified in SYS1.PARMLIB
] member SMFPRMxx on the SID statement. Trailing blanks are removed. For
] example,
] PROC 0
] WRITE &SYSSMFID
] EXIT
] returns ATQS as the SMF ID. Note that the value returned by &SYSSMFID and
] &SYSNAME may be the same in your installation. See MVS/ESA SP V5
] Initialization and Tuning Reference, SC28-1452, for more details on the
] SYSNAME and SID statement in member SMFPRMxx.
] &SYSSYMDEF
] &SYSSYMDEF returns the symbolic name of the MVS system, as specified in

] SYS1.PARMLIB member IEASYMxx (3) on the SYSDEF ... SYMDEF statement. For
] example, if SYMDEF(&SYSTEMA = 'SA') is specified in IEASYMxx, then
] PROC 0
] WRITE &SYSSYMDEF(SYSTEMA)
] EXIT
] returns a value of SA. A null string is returned if no MVS symbolic name

] is specified in IEASYMxx.
] The symbol name SYSTEMA is assigned a name of SA on the SYMDEF statement

] in IEASYMxx. The &SYSSYMDEF(symbol_name) control variable resolves to a
] string of SA.
] The SYSSYMDEF function goes through CLIST substution first, the result of
] which must be a 1-8 character name specifying the symbol that has been
] defined in the SYMDEF statement. Any other values including CLIST
] delimiters may cause unpredictible results.

&SYSTSOE
&SYSTSOE indicates the version, release, and modification level of TSO/E

installed on the system. &SYSTSOE returns the level of TSO/E in the
following format:
PICTURE 3
] (2) Introduced with MVS/ESA SP 5.2; provides a mechanism to

] assign system substitution symbols names and values.
] (3) Introduced with MVS/ESA SP 5.2; provides a mechanism to

] assign system substitution symbols names and values.
5.6 Getting Information about the CLIST
The following control variables provide information about the CLIST.
&SYSENV
&SYSENV indicates whether the CLIST is executing in the foreground (FORE)

or the background (BACK). You can use this variable when a CLIST must
make logical decisions based on the environment. For example, the way a
CLIST obtains its input is sensitive to background and foreground
executions. You can use &SYSENV to prevent the CLIST executing READ
statements in the background as follows:
GLOBAL LNAME /* Define global variable to be set by FETCHNAM */

.
.
.
IF &SYSENV=FORE THEN +
DO
WRITE Enter your last name.
READ LNAME
END
ELSE +
%fetchnam
&SYSSCAN
&SYSSCAN contains a number that defines the maximum number of times

symbolic substitution is performed on each line in a CLIST. The default
number is 16. You can assign &SYSSCAN a value from 0 to +2,147,483,647
(2úî-1). A zero limit inhibits all scans, preventing any substitution of
values for symbolic variables.
For example, to write a record containing an ampersand (&), and prevent a

CLIST from performing erroneous symbolic substitution, you can code the
following:
.
.
.
SET &SYSSCAN=0 /* Prevent symbolic substitution
WRITE Jack & Jill went up the hill
SET &SYSSCAN=16 /*Reset &SYSSCAN
&SYSICMD
&SYSICMD contains the name by which the user implicitly invoked the
currently executing CLIST. If the user invoked the CLIST explicitly, this
variable has a null value.
&SYSPCMD
&SYSPCMD contains the name of the TSO/E command that the CLIST most
recently executed. The initial value of &SYSPCMD depends on the
environment from which the CLIST was invoked. If the invoker used the
EXEC command, the initial value is EXEC. If the invoker used the EXEC
subcommand of EDIT, the initial value is EDIT.
&SYSSCMD
&SYSSCMD contains the name of the TSO/E subcommand that the CLIST most
recently executed. If invoker used the EXEC command, the initial value of
&SYSSCMD is null. If the invoker used the EXEC subcommand of EDIT, the
initial value is EXEC.
Relationship between &SYSPCMD and &SYSSCMD
The &SYSPCMD and &SYSSCMD control variables are interdependent. Following

the initial invocation, the values of &SYSPCMD and &SYSSCMD depend on the
TSO/E command or subcommand most recently executed. For example, if the
value of &SYSSCMD is EQUATE, a subcommand unique to the TEST command, the
value of &SYSPCMD is TEST.
You can use &SYSPCMD and &SYSSCMD in error and attention exits to
determine where the error or attention interrupt occurred.
&SYSNEST
&SYSNEST indicates whether the currently executing CLIST is nested. (A

nested CLIST is one that was invoked by another CLIST rather than
explicitly by the user.) If the CLIST is nested, &SYSNEST contains the
value YES. If it is not nested, &SYSNEST contains the value NO.
5.7 Setting Options of the CLIST CONTROL Statement
The following control variables let you test or modify options of the
CLIST CONTROL statement. For full information about the CONTROL statement
and its options, see "CONTROL Statement" in topic 13.4.
&SYSPROMPT
&SYSPROMPT indicates whether the CONTROL statement's PROMPT or NOPROMPT

option is active. The value ON indicates that CONTROL PROMPT is active,
and TSO/E commands in the CLIST can prompt the terminal for input. OFF
indicates that CONTROL NOPROMPT is active, and TSO/E commands cannot
prompt the terminal.
Your CLISTs can use &SYSPROMPT to test which option is active, or change
the option. For example, if you want the CLIST to allow prompting from
the LISTDS command only, you can code:
SET &SYSPROMPT = ON
LISTDS
SET &SYSPROMPT = OFF
&SYSSYMLIST
&SYSSYMLIST indicates whether the CONTROL statement's SYMLIST or NOSYMLIST

option is active. The value ON indicates that CONTROL SYMLIST is active,
and CLIST statements are displayed at the terminal before being scanned
for symbolic substitution. The value OFF indicates that CONTROL NOSYMLIST
is active, and CLIST statements are not displayed at the terminal before
symbolic substitution.
Your CLISTs can use &SYSSYMLIST to test which option is in effect, or to

change the option. For example, if you suspect an error in part of a
CLIST and you want to display certain statements before substitution, you
could code:
SET &SYSSYMLIST = ON
.
.
.
(suspected statements in error)
.
.
.
SET &SYSSYMLIST = OFF
&SYSCONLIST
&SYSCONLIST indicates whether the CONTROL statement's CONLIST or NOCONLIST

option is active. The value ON indicates that CONTROL CONLIST is active,
and CLIST statements are displayed at the terminal after symbolic
substitution. The value OFF indicates that CONTROL NOCONLIST is active,
and CLIST statements are not displayed at the terminal after symbolic
substitution.
Your CLISTs can use &SYSCONLIST to test which option is in effect, or to

CLIST and you want to display certain statements after substitution, you
could code:
SET &SYSCONLIST = ON
.
.
.
(suspected statements in error)
.
.
.
SET &SYSCONLIST = OFF
&SYSLIST
&SYSLIST indicates whether the CONTROL statement's LIST or NOLIST option

is active. The value ON indicates that CONTROL LIST is active, and TSO/E
commands and subcommands are displayed at the terminal after symbolic
substitution. The value OFF indicates that CONTROL NOLIST is active, and
commands and subcommands are not displayed at the terminal after symbolic
substitution.
Your CLISTs can use &SYSLIST to test which option is in effect, or to

CLIST and you want to display certain commands or subcommands, you could
code:
SET &SYSLIST = ON
.
.
.
(suspected commands in error)
.
.
.
SET &SYSLIST = OFF
&SYSASIS
&SYSASIS indicates whether the CONTROL statement's ASIS option is active.

The value ON indicates that CONTROL ASIS is active, and lowercase
characters are not converted to uppercase before processing. The value
OFF indicates that CONTROL CAPS is active, and lowercase characters are
converted to uppercase.
Your CLISTs can use &SYSASIS to test which option is in effect, or to

change the option. For example, if you want READ and WRITE statements to
preserve lowercase letters, you could code:
SET &SYSASIS = ON
WRITE Enter data exactly as you want it to appear.
WRITE Lowercase letters won't be changed to uppercase.
READ &Ulc_data
&SYSMSG
&SYSMSG indicates whether the CONTROL statement's MSG or NOMSG option is

active. The value ON indicates that CONTROL MSG is active, and the CLIST
can display informational messages at the terminal. The value OFF
indicates that CONTROL NOMSG is active, and the CLIST cannot display
informational messages at the terminal.
Your CLISTs can use &SYSMSG to test which option is in effect, or to

change the option. For example, if you wanted to make sure that
informational messages are displayed at the terminal, you could code:
SET &SYSMSG = ON
.
.
.
&SYSFLUSH
&SYSFLUSH indicates whether the CONTROL statement's FLUSH or NOFLUSH

option is active. The value ON indicates that CONTROL FLUSH is active,
and the system can erase (flush) any nested CLISTs when an error occurs.
The value OFF indicates that CONTROL NOFLUSH is active, and the system
cannot flush nested CLISTs. When CONTROL MAIN is active, &SYSFLUSH cannot
be set to ON.
Your CLISTs can use &SYSFLUSH to test which option is in effect, or to

change the option. For example, if your CLIST invokes other CLISTs, you
can set &SYSFLUSH to OFF to protect them from being flushed in the event
of an error. You could then use an error routine to recover from the
error and continue processing.
SET &SYSFLUSH = OFF

ERROR +
DO
.
.
.
(error routine)
.
.
.
END
For more information about error routines and protecting nested CLISTs,
see Topic 10, "Writing ATTN and ERROR Routines".
5.8 Getting Information about User Input
Two control variables are related to input supplied to a CLIST.
&SYSDLM
&SYSDLM (DLM is for delimiter) contains a number that identifies the

: position (first, second, third, and so on) of the TERMIN or TERMING
: statement character string entered by the user to return control to the
CLIST.
You can use this variable to determine what action should be taken when
the user returns control to the CLIST, based on the string chosen. For
example, the following statements inform the user what is requested
(WRITE), pass control to the terminal and establish valid control
: character strings (TERMIN or TERMING), and determine the subsequent action
based on the string entered.
WRITE The first phase of BUDGET has completed with

WRITE a return code of &RCODE.
WRITE Enter YES if you want the results printed.
WRITE Enter NO if you do not want them printed.
TERMIN YES NO
IF &SYSDLM = 1 THEN +
.
.
.
(Print results)
.
.
.
&SYSDVAL
&SYSDVAL (DVAL is for default value) contains one of the following at any
given time:
* A null value
: * The input the user entered when returning control to the CLIST after a
: TERMIN or TERMING statement
* The user's response after a READ statement without operands
* The value assigned to &SYSDVAL by an assignment statement.
Initially, &SYSDVAL contains a null value. It can also contain a null

value, if:
: * The user does not enter anything but a pre-defined character string or
: null line after a TERMIN or TERMING statement.
* The user does not enter any input after a READ statement without
operands.
* You assign a null value to &SYSDVAL.
You can also use &SYSDVAL when performing I/O to a data set. You can
assign the data to variables by defining SYSDVAL as the file name of the
data set and naming the variables on the READVAL statement. For an
example of using &SYSDVAL and READVAL in I/O, see "Using &SYSDVAL When
Performing I/O - The PHONE CLIST" in topic 12.13.
5.9 Trapping TSO/E Command Output
Two control variables allow you to trap TSO/E command output in a CLIST:
&SYSOUTTRAP and &SYSOUTLINE. These variables save output from TSO/E
commands and allow a CLIST or application to process the output. You can
modify the values of &SYSOUTTRAP and &SYSOUTLINE with assignment
statements. For example, the assignment statement
SET &SYSOUTTRAP = 100
lets you trap and save 100 lines of output from a TSO/E command.
&SYSOUTTRAP
Use &SYSOUTTRAP to specify the maximum number of lines of TSO/E command

output to be saved. If you want to save all the output from a TSO/E
command, set &SYSOUTTRAP to a number greater than or equal to the number
of output lines that the command produces. Any output lines produced in
excess of the &SYSOUTTRAP value are not saved.
To save the output of a single command, set &SYSOUTTRAP to zero after

issuing the command. Otherwise, output from subsequent commands may
replace the original saved output.
&SYSOUTLINE
When you use &SYSOUTTRAP, the CLIST saves TSO/E command output in
variables beginning with &SYSOUTLINE.
The CLIST uses the variable &SYSOUTLINE to record the number of output
lines produced by a command. The CLIST saves the actual command output in
the variables &SYSOUTLINEnn, where nn represents the positional number of
the line being saved. nn can be any decimal number up to 21 digits in
length. However, the value in &SYSOUTTRAP and the amount of storage
available determine the actual number of lines saved.
The following CLIST traps output from the TSO/E LISTD command, retrieves
it using nested variables, and writes each line of output.
PROC 0 DATASET(DEFAULT)
IF &DATASET = DEFAULT THEN +
DO
WRITE What data set do you want to process?
READ DATASET
END
] SET &SYSOUTTRAP = 1000 /* Expect command produces no */
: /* more than 1000 lines */
: LISTD '&SYSPREF..&DATASET' MEMBERS /* List data set members */
: SET B = &SYSOUTLINE /* Get number of lines produced */
] SET &SYSOUTTRAP = 0 /* Reset &SYSOUTTRAP */
: SET A = 1 /* Initialize counter */
: DO WHILE /* Loop for the lesser of */
: (&A <= 1000) AND /* num of lines expected and */
: (&A <= &B) /* num of lines produced */
: SET MEMBER = &STR(&&SYSOUTLINE&A) /* Get a &SYSOUTLINEnn variable */
: WRITE &STR(&MEMBER) /* Write the output line */
: SET A = &A +1 /* Increase the line counter */
END /* End of loop on counter */
For another example of using &SYSOUTTRAP and &SYSOUTLINE to process

command output, see "Allocating Data Sets to SYSPROC - The SPROC CLIST" in
topic 12.14.
Considerations for Using &SYSOUTTRAP and &SYSOUTLINE
* If you add the CONTROL LIST and SYMLIST options to a CLIST that uses
&SYSOUTTRAP, more output lines are produced and you might need to
adjust &SYSOUTTRAP and &SYSOUTLINEnn values to retrieve the desired
output lines.
* In order to trap the output of TSO/E commands under ISPF/PDF, you must
invoke a CLIST with command output trapping after ISPF or one of its
services has been invoked.
* If you try to display a line of output in &SYSOUTLINEnn where nn is

greater than the value of &SYSOUTTRAP, the &SYSOUTLINEnn variable
contains unreliable data.
* If you try to display a &SYSOUTLINEnn variable that contains no

command output, the CLIST returns a null line.
* Because CLISTs use the TSO/E EXEC command to invoke nested CLISTs,
&SYSOUTTRAP saves all output of nested CLISTs as TSO/E command output.
Therefore, if you need to trap all of the output of a command
processor that processes several subcommands, consider using a nested
CLIST to do so.
* &SYSOUTTRAP does not save command output sent to the terminal by a

TPUT macro, but does save output from the PUTLINE macro with DATA or
INFOR keywords.
* Whenever a CLIST starts to execute a TSO/E command or subcommand, it

resets &SYSOUTLINE to zero. However, if a CLIST invokes a CLIST or a
non-CLIST program containing TSO/E commands, the invoked program does
not reset &SYSOUTLINE to zero for each TSO/E command. To record the
number of command output lines in an invoked program, use an
assignment statement to reset &SYSOUTLINE to zero before each TSO/E
command. For information about assigning a value to CLIST variables
in a non-CLIST environment, see TSO/E V2 Programming Services,
SC28-1875.
5.10 Getting Return Codes and Reason Codes

Two control variables enable you to obtain return codes and reason codes.
You can modify both &LASTCC and &MAXCC with an assignment statement.
&LASTCC
When you use &LASTCC outside an error routine, &LASTCC contains the return
code from the last TSO/E command or subcommand, nested CLIST, or CLIST
statement executed. Because the value of this variable is updated after
the execution of each statement or command, store its value in a symbolic
variable before executing code that references the value.
In an error routine, &LASTCC is not updated after the execution of each

statement or command. Only the RETURN statement updates the value of
&LASTCC. If you use &LASTCC in an error routine, &LASTCC contains the
return code from the command or statement that was executing when the
error occurred.
&LASTCC does not support negative return codes. When a negative return
code is received from a REXX exec, CLIST converts it to binary, removes
the first byte, and stores the remainder in &LASTCC as a positive decimal
integer.
When &LASTCC receives an error return code from a TSO/E command,

subcommand, nested CLIST, or CLIST statement, control passes to an error
routine if present in the CLIST. However, when &LASTCC contains the
return code from a subprocedure RETURN statement, control does not pass to
an error routine.
&LASTCC can be used in error routines that handle multiple error

conditions. For example, if an error routine handles arithmetic errors,
it can use &LASTCC to determine what type of message to display at the
terminal:
ERROR +
DO
SET RCODE = &LASTCC
/* Character data in operands? */
IF &RCODE = 852 THEN +
WRITE Character data was found in numbers being added.
/* Numeric value too large? */
IF &RCODE = 872 THEN +
WRITE A numeric value in the addition was too large.
. (Other tests)
.
RETURN
END
SET SUM = &VALUE1 + &VALUE2 + &VALUE3
Note that &LASTCC itself does not get updated within the error routine.
: When an error occurs during CLIST I/O processing, use an error routine to
: obtain the error code in &LASTCC. For example, to trap the error code
: generated by OPENFILE when attempting to open a file (BADFILE) that does
: not exist, code the following CLIST:
: PROC 0
: ERROR DO
: SET RC=&LASTCC.
: RETURN
: END
: OPENFILE BADFILE
: WRITE LASTCC=&RC.
See Figure 11-4 in topic 11.3 for a list of the CLIST error codes that
&LASTCC can contain.
&MAXCC
&MAXCC contains the highest return code returned by a nested CLIST or by a

TSO/E command, subcommand, or CLIST statement in the currently executing
CLIST.
&MAXCC is not set when a subprocedure returns to the CLIST.
You can use &MAXCC with &LASTCC to determine error conditions. For
example, error codes caused by evaluation errors are in the 800-899 range.
You can modify the error routine in the example under &LASTCC to determine
first whether the error was caused by an arithmetic evaluation. Insert
the following IF-THEN-ELSE sequence before the check for character data in
operands:
.
.
.
/* Evaluation error? */
IF &MAXCC <800 OR &MAXCC >899 THEN +
GOTO ...
ELSE +
.
.
.
5.11 Getting Results of the TSOEXEC Command
Three variables are related to the use of the TSOEXEC command: &SYSABNCD,
&SYSABNRC, and &SYSCMDRC. You can modify any one of them with an
assignment statement.
&SYSABNCD, &SYSABNRC, and &SYSCMDRC contain, respectively, the ABEND code,

ABEND reason code, and command return code returned by the command most
recently invoked by the TSOEXEC command. You can use these variables in
situations similar to those in which you would use &LASTCC and &MAXCC.
For example, to determine if the TRANSMIT command terminated abnormally,
you can code:
tsoexec transmit plpsc.d00abc1 dataset(letter.text)

/* Abend code non-zero? */
IF &SYSABNCD^=0 THEN +
DO
WRITE The transmission of LETTER.TEXT to
WRITE PLPSC.D00ABC1 abended.
END
5.12 Getting Data Set Attributes
Control variables include certain predefined variables set by CLIST

statements. The LISTDSI statement sets a number of variables with
information about data set attributes. These LISTDSI variables cannot be
modified.
The LISTDSI Statement
You can use the LISTDSI (list data set information) statement to retrieve
detailed information about a data set's attributes. The statement stores
the information in CLIST variables. The CLIST can use the information to
determine if the data set has enough space or the correct format for a
given task. The CLIST can also use the information as input to the TSO/E
ALLOCATE command to create a new data set with some attributes of the old
data set while modifying others.
To retrieve a data set's allocation information, specify the data set's

name on the LISTDSI statement. You can also specify that a data set
migrated by the Data Facility Hierarchical Storage Manager (DFHSM) be
recalled, and that directory information be retrieved for a partitioned
data set.
In response to the LISTDSI statement, the CLIST stores each of the data
set's allocation attributes in a specific variable. For example, the data
set's primary space allocation is stored in the variable &SYSPRIMARY, and
its organization is stored in &SYSDSORG. For a complete list of the CLIST
variables set by LISTDSI, see "LISTDSI Statement" in topic 13.15.
For an example of using LISTDSI, see "Allocating a Data Set with LISTDSI
Information - The EXPAND CLIST" in topic 12.16.
6.0 Topic 6. Using Built-in Functions
The CLIST language includes built-in functions that you can perform on
variables, expressions, and character strings. If necessary, CLIST
evaluates the variable or expression first, and then performs the
requested function. The CLIST then stores the result under the name of
the built-in function.
To use a built-in function, type its name, followed by the variable,

expression, or character string in parentheses. The variable, expression,
or character string is also called the argument of the built-in function.
The argument must immediately follow the built-in function name, with no
blanks between them. Figure 6-1 describes each of the built-in functions
briefly and gives topic numbers where you can find more information.
]------------------------------------------------------------------------]
] Figure 6-1. Built-in Functions ]
]--------------------------------------]------------------------]--------]
] Built-in Function ] Function ] Topic ]
]--------------------------------------]------------------------]--------]
] &DATATYPE(expression) ] Indicates whether the ] 6.1 ]
] ] evaluation of ] ]
] ] expression is a ] ]
] ] character string or a ] ]
] ] numeric value. ] ]
]--------------------------------------]------------------------]--------]
] &EVAL(expression) ] Performs an arithmetic ] 6.2 ]
] ] evaluation of ] ]
] ] expression. ] ]
]--------------------------------------]------------------------]--------]
] &LENGTH(expression) ] Evaluates expression ] 6.3 ]
] ] if necessary and ] ]
] ] indicates the number ] ]
] ] of bytes in the ] ]
] ] result. ] ]
]--------------------------------------]------------------------]--------]
] &NRSTR(string) ] Preserves double ] 6.5 ]
] ] ampersands, defines ] ]
] ] non-rescannable ] ]
] ] strings. ] ]
]--------------------------------------]------------------------]--------]
] &STR(string) ] Defines data to be ] 6.6 ]
] ] used as a character ] ]
] ] string. ] ]
]--------------------------------------]------------------------]--------]
] &SUBSTR(expâ:expã,string) ] Uses certain bytes in ] 6.7 ]
] ] a character string. ] ]
]--------------------------------------]------------------------]--------]
] &SYSCAPS(string) ] Converts the string to ] 6.9 ]
] ] uppercase characters. ] ]
]--------------------------------------]------------------------]--------]
] &SYSCLENGTH(expression) ] Evaluates expression ] 6.4 ]
] ] if necessary and ] ]
] ] indicates the number ] ]
] ] of characters in the ] ]
] ] result. ] ]
]--------------------------------------]------------------------]--------]
] &SYSCSUBSTR(expâ:expã,string) ] Uses certain ] 6.8 ]
] ] characters in a ] ]
] ] character string. ] ]
]--------------------------------------]------------------------]--------]
] &SYSDSN(dsnameâ(member)ã) ] Indicates whether the ] 6.11 ]
] ] specified data set ] ]
] ] exists. ] ]
]--------------------------------------]------------------------]--------]
] &SYSINDEX(string_1,string_2â,startã) ] Finds the position of ] 6.12 ]
] ] a character string ] ]
] ] (string_1) within ] ]
] ] another (string_2), ] ]
] ] from a specific ] ]
] ] starting point. ] ]
]--------------------------------------]------------------------]--------]
] &SYSLC(string) ] Converts the string to ] 6.10 ]
] ] lowercase characters. ] ]
]--------------------------------------]------------------------]--------]
] &SYSNSUB(level,expression) ] Limits the level of ] 6.13 ]
] ] symbolic substitution ] ]
] ] in the expression. ] ]
]--------------------------------------]------------------------]--------]
] &SYSONEBYTE(string) ] Converts a string of ] 6.14 ]
] ] data from the ] ]
] ] double-byte character ] ]
] ] set (DBCS) to EBCDIC. ] ]
]--------------------------------------]------------------------]--------]
] &SYSTWOBYTE(string) ] Converts a string of ] 6.15 ]
] ] data from EBCDIC to ] ]
] ] the double-byte ] ]
] ] character set (DBCS). ] ]
]--------------------------------------]------------------------]--------]
In addition to these built-in functions, TSO/E provides an installation

exit that lets your installation add its own CLIST built-in functions.
For information about the exit, see TSO/E V2 Customization, SC28-1872.
Note: With the exception of &SYSNSUB, built-in functions will not resolve
double ampersands (&&) that appear in an argument.
6.1 Determining the Data Type of an Expression - &DATATYPE
Use the &DATATYPE built-in function to determine what type of data an

evaluated expression contains. After evaluating the expression, a CLIST
replaces this built-in function with one of the following strings: CHAR,
NUM, DBCS, or MIXED. The strings indicate the following:
* CHAR -- The evaluated expression contains at least one non-numeric

EBCDIC character and no double-byte character set (DBCS) characters.
* NUM -- The evaluated expression is entirely numeric.
* DBCS -- The evaluated expression is a single delimited string of DBCS

data.
* MIXED -- The evaluated expression contains both DBCS and EBCDIC data.
The following examples show the evaluations of various expressions:
SET A = &DATATYPE(ALPHABET) /* result: &A = CHAR

SET B = &DATATYPE(1234) /* result: &B = NUM
SET C = &DATATYPE(SYS1.PROCLIB) /* result: &C = CHAR
SET D = &DATATYPE(3*2/4) /* result: &D = NUM
SET E = &DATATYPE(12.34) /* result: &E = CHAR
For example, the following clause evaluates as true:
IF &DATATYPE(12.34)=CHAR THEN
The following examples use the convention d1d2 to represent two DBCS
characters and < and > to represent the shift-out and shift-in delimiters
(X'0E' and X'0F') that mark the beginning and end of the DBCS string.
SET A = &DATATYPE(<d1d2>) /* result: &A = DBCS

SET B = &DATATYPE(ABC<d1d2>123) /* result: &B = MIXED
SET C = &DATATYPE(<>) /* result: &C = DBCS
SET D = &DATATYPE(A<>C) /* result: &D = MIXED
SET E = &DATATYPE(<d1d2><d3d4>) /* result: &E = MIXED
For example, the following clauses evaluate as true:
IF &DATATYPE(<d1d2d3>)=DBCS THEN
IF &DATATYPE(A<d1d2d3>B)=MIXED THEN
6.2 Forcing Arithmetic Evaluations - &EVAL
On most statements, the appearance of arithmetic expressions results in

evaluations of those expressions when a CLIST executes the statements.
However, on the WRITE statement, you must explicitly instruct a CLIST to
evaluate an arithmetic expression by using the &EVAL built-in function.
For example, to create a WRITE statement that adds two variables, &FNUM
and &SNUM, and displays the results, code the following:
WRITE &FNUM + &SNUM = &EVAL(&FNUM+&SNUM)
Assuming &FNUM is four and &SNUM is three, the CLIST displays the
following message:
4 + 3 = 7
6.3 Determining an Expression's Length in Bytes - &LENGTH
Use the &LENGTH built-in function to determine the number of bytes in an

expression or character string. &LENGTH performs symbolic substitution
and arithmetic evaluations before determining the length. If a variable
has a null value, &LENGTH returns a value of zero.
For example, after the following statement executes, &LENANSWR has the
value 2 because there are two bytes in the result of the addition, 11.
SET LENANSWR = &LENGTH(1+1+9)
&LENGTH can also reference symbolic variables. Assume you want to save a
value that is triple the length of the value of a variable called
&CSTRING. To save the value in a variable called &NXTFIELD, code:
SET NXTFIELD = 3 * &LENGTH(&CSTRING)
If &CSTRING contains the value 100, &NXTFIELD contains the value 9.
If a string contains data of the double-byte character set (DBCS), &LENGTH

counts each DBCS character as two bytes, and counts each DBCS delimiter as
one byte. For example, using d1d2 to denote two DBCS characters and using
< and > to represent the DBCS delimiters X'0E' and X'0F':
SET A = &LENGTH(<d1d2>) /* result: &A = 6
The same is true when a string contains mixed EBCDIC and DBCS characters.
For example:
SET A = &LENGTH(ABC<d1d2>) /* result: &A = 9
Suppressing Arithmetic Evaluations
If you do not want a CLIST to perform arithmetic evaluations of a &LENGTH

expression, enclose the expression in a &STR built-in function as follows:
SET LENANSWR = &LENGTH(&STR(1+1+9))
After the previous statement executes, &LENANSWR contains the value 5.
Including Leading and Trailing Blanks and Leading Zeros
If you want leading and trailing blanks and leading zeros in a &LENGTH
expression included in the assignment, enclose the expression in a &STR
built-in function. Otherwise, the blanks and zeroes are ignored.
For example, suppose that you want to save the length of the variable
&IFIELD in a variable called &SLNGTH. The contents of &IFIELD are 0
472.20 . Include &IFIELD in the &STR built-in function to include the
blanks and the leading zero as part of the assignment:
SET SLNGTH= &LENGTH(&STR(&IFIELD))
After the previous statement executes, &SLNGTH contains the value 8.
6.4 Determining an Expression's Length in Characters - &SYSCLENGTH
Use &SYSCLENGTH built-in function to determine the number of characters in

an expression or string that contains characters of the double-byte
character set (DBCS). &SYSCLENGTH differs from &LENGTH in that
&SYSCLENGTH counts each DBCS character as one character instead of two
bytes, and does not count DBCS delimiters. For example:
SET A = &SYSCLENGTH(<d1d2>) /* result: &A = 2
The same is true when a string contains mixed EBCDIC and DBCS characters.
For example:
SET A = &SYSCLENGTH(ABC<d1d2>) /* result: &A = 5
Except for the difference in counting DBCS characters, &SYSCLENGTH is

identical to &LENGTH.
6.5 Preserving Double Ampersands - &NRSTR
You can use the &NRSTR built-in function to prevent a CLIST from:
* Removing the first ampersand when it encounters a character string

with a prefix of double ampersands.
* Performing more than one level of symbolic substitution on a variable.
You can use &NRSTR with JCL statements that include the name of a
temporary data set (for example, &&TEMP). Using &NRSTR prevents a CLIST
from changing the name of a temporary data set (&&TEMP) to a symbolic
parameter (&TEMP).
Double Ampersands
To assign the character string &&DATA to the variable &FILE, code:
SET FILE = &NRSTR(&&DATA)
One Level of Symbolic Substitution
To set two variables, &A and &C, to the value &B code:
.
.
.
SET A = &&B
SET C = &NRSTR(&A)
.
.
.
After the execution of the first SET statement, &A contains the value &B.
When the second SET statement is executed, the CLIST performs symbolic
substitution and substitutes &B for &A. &NRSTR prevents any further scan
of the statement; therefore, &C is assigned the value &B.
Records Containing JCL Statements
The following paragraphs discuss the use of the &NRSTR built-in function
when processing records that contain JCL statements.
Temporary Data Set Names
If a JCL statement contains a temporary data set name (for example,

&&TEMP), enclose the statement in a &NRSTR built-in function to prevent
the CLIST from removing the first ampersand. The following CLIST uses
&NRSTR to preserve a temporary data set name in a JCL statement.
submit *
//&sysuid.1 job 'Y2803P,?,S=C','SteveR',msgclass=r,class=j
// exec pgm=IEFBR14
//dd1 dd dsn=&NRSTR(&&temp),disp=(,pass),unit=sysda
&null
Symbolic Parameters
If a JCL statement contains a symbolic parameter (for example, &LIBRARY),
use the &SYSNSUB built-in function to prevent the CLIST from performing
erroneous symbolic substitution. Assume that the preceding CLIST
contained the JCL statement:
//dd2 dd dsn=&library,disp=(,pass),unit=sysda
To prevent any symbolic substitution, you can enclose the symbolic

parameter IBM TSO Extensions for MVS in the &SYSNSUB built-in function as
follows:
//dd2 dd dsn=&SYSNSUB(0,&library),disp=(,pass),unit=sysda
The number 0 in parentheses after &SYSNSUB tells the CLIST how many levels
of symbolic substitution you want performed on the parameter (in this
case, zero levels). For more information about the &SYSNSUB built-in
function, see "Limiting the Level of Symbolic Substitution - &SYSNSUB" in
topic 6.13.
6.6 Defining Character Data - &STR
Use the &STR built-in function to define character data and prevent the
CLIST from evaluating it. The data can be any expression or statement,
and can include nested variables and characters of the double-byte
character set (DBCS) within DBCS delimiters.
For example, the statement SET DIMENSNS=&STR(2*4) defines 2*4 as a

character string and assigns the string to the variable &DIMENSNS.
Without the &STR built-in function, you could not make the desired
assignment because a CLIST would evaluate 2*4 as an arithmetic expression
and set &DIMENSNS to the value 8.
The &STR built-in function suppresses arithmetic evaluations only for the
data between the parentheses. If you set &STATS to &DIMENSNS, &STATS will
contain the value 8, not the character string 2*4. In order to preserve
the character string, code the following:
SET STATS=&STR(&DIMENSNS)
Special procedures are required when defining parentheses as character

data. Unlike other CLIST operators, left and right parentheses can appear
at the beginning or in the middle of character data without having to be
defined as character data. Only when they appear at the end of a
character string do parentheses have to be defined with &STR, like the
other operators.
The following examples show how to define right and left parentheses to
appear as character data at the end of a character string called TEXT:
Right parenthesis:
SET &A = )
SET &B = TEXT&STR(&A) /* result: B = TEXT)
Left parenthesis:
SET &C = &STR((

SET &D = TEXT&STR(&C) /* result: D = TEXT(
Using &STR with &SYSDATE or &SYSSDATE
If you use &SYSDATE or &SYSSDATE on a CLIST statement other than WRITE,

enclose the variable in an &STR built-in function. Otherwise, a CLIST
views the slashes separating the day, month, and year as division
operators and performs division.
SET TODAY = &STR(&SYSDATE)
Using &STR with Leading and Trailing Blanks
Use the &STR built-in function to preserve leading and trailing blanks in
a character string. For example, the following statement sets the
variable &CMNDFLD to a blank, 2 hyphens, a greater than symbol, and four
blanks:
SET CMNDFLD= &STR( --> )
Using &STR with Strings that Match CLIST Statement Names
You can use the &STR built-in function to distinguish installation-written

commands that match the names of CLIST statements. For example, if your
installation had written a command named NGLOBAL, you could use &STR to
issue the command from a CLIST and prevent the CLIST from misinterpreting
it as the NGLOBAL statement:
&STR(NGLOBAL)
Similarly, to issue the SELECT subcommand of the RACF command RACFRW, you
need to use the &STR built-in function to distinguish the subcommand from
the SELECT statement. For more information, see "Distinguishing the
SELECT Statement from the RACF SELECT Subcommand" in topic 7.1.
Using &STR When Supplying Input Using SYSIN JCL Statements
When you submit a background job that invokes a program, you sometimes
include a '//SYSIN DD *' JCL statement that supplies the input statements.
If any input statement contains leading blanks or is the same as a CLIST
statement, enclose that statement in a &STR built-in function. For
example, suppose a hypothetical language called SES has an IF-THEN-ELSE
sequence. If you were to include such a sequence in the SYSIN input
statements, you would have to enclose it in an &STR built-in function as
shown in the following background invocation of a hypothetical SES program
called MATRIX.
PROC 1 FORMAT ACCT() CLASS(A)

CONTROL MAIN
.
.
.
submit * end(nn)
//&SYSUID.1 JOB &ACCT,&SYSUID,CLASS=&CLASS
//STEP1 EXEC PGM=MATRIX
.
.
.
//SYSIN DD *
&STR( IF &FORMAT=1 THEN OPEN DS1)
&STR(ELSE OPEN DS2)
GETFILES 1-12
&STR(SET COLUMNS=GETFILES)
.
.
.
nn
Only those input statements that contain leading blanks or are the same as
CLIST statements are enclosed in &STR built-in functions. If the CLIST
invoked MATRIX in the foreground, the &STR built-in functions would be
unnecessary because the program's statements would appear in the data set
containing MATRIX. Thus, they would be associated with the program, not
the CLIST.
6.7 Defining a Substring - &SUBSTR
Use the &SUBSTR built-in function to request that a CLIST use only certain
bytes of an indicated string when performing substitution. You indicate
the starting and ending positions of the string from which the
substitution is made.
For example, assuming a variable called &ANIMALS contains the character

string "DOGSCATSSEALS", to set a variable called &FELINE to the character
string "CATS", code the following:
SET FELINE = &SUBSTR(5:8,&ANIMALS)
Note that the character string "CATS" begins in the fifth position of
&ANIMALS and ends in the eighth position.
A &SUBSTR built-in function can contain other built-in functions. Assume

your CLIST receives input from the user and assigns it to a variable
called &NAME. &NAME contains a person's first and middle initial followed
immediately by the last name. To add a blank between the initials and the
last name, you can set a variable called &NFIELD to a character string
consisting of the following:
1. The first and middle initials

2. A blank
3. The last name.
SET NFIELD = &STR(&SUBSTR(1:2,&NAME) &SUBSTR(3:&LENGTH(&NAME)+

,&NAME))
If you want the substring to contain only one character, you can omit the
colon and end-expression. For example, if you are interested only in the
first letter of the last name, code the following:
SET FLTRLNAME = &SUBSTR(3,&NAME)
You can substitute variables for starting and ending expressions. For
instance, to set the section of &STRING beginning at the second position
and ending at the eighth position to a variable called &WIDGET, you can
create a variable and substitute it in the SET statement. Assume that the
substring data represents a part number.
SET PART# = &STR(2:8,)

SET WIDGET = &SUBSTR(&PART#&STRING)
When a variable is named in &SUBSTR, arithmetic evaluation of the

variable's contents is suppressed, as in &STR. For example:
SET DIMENSNS = &STR(2*4)

SET X = &SUBSTR(1:2,&DIMENSNS) /result: X = 2*
However, when another built-in function such as &LENGTH is specified in

the &SUBSTR, the variable within the built-in function is evaluated before
the &SUBSTR. To protect that variable from arithmetic evaluation, use
&STR:
SET DIMENSNS = &STR(2*4)

SET X = &SUBSTR(1:&LENGTH(&STR(&DIMENSNS)),&DIMENSNS)
/* result: X = 2*4
If a string contains data of the double-byte character set (DBCS), &SUBSTR

counts each DBCS character as two bytes, and counts each DBCS delimiter as
one byte. For example, using d1d2 to denote two DBCS characters and using
< and > to denote the DBCS delimiters X'0E' (shift-out) and X'0F'
(shift-in):
SET X = &SUBSTR(8:9(A<d1d2>BC) /* result: X = BC
When &SUBSTR returns DBCS data, &SUBSTR encloses the data between the DBCS
delimiters X'0E' and X'0F'. &SUBSTR attempts to return the exact bytes
requested. However, when the starting or ending positions of the
substring are DBCS data or DBCS delimiters, &SUBSTR makes the following
adjustments:
]------------------------------------]-----------------------------------]
] If the substring: ] &SUBSTR does the following: ]
]------------------------------------]-----------------------------------]
] Starts on the first byte of a DBCS ] Replaces that byte with a ]
] character ] single-byte blank and the ]
] ] right-next byte with a shift-out ]
] ] delimiter ]
]------------------------------------]-----------------------------------]
] Starts on the second byte of a ] Replaces that byte with a ]
] DBCS character ] shift-out delimiter ]
]------------------------------------]-----------------------------------]
] Starts on a shift-in delimiter ] Replaces that byte with a ]
] ] single-byte blank ]
]------------------------------------]-----------------------------------]
] Ends on shift-out delimiter ] Replaces that byte with a ]
] ] single-byte blank ]
]------------------------------------]-----------------------------------]
] Ends on the first byte of a DBCS ] Replaces that byte with a ]
] character ] shift-in delimiter ]
]------------------------------------]-----------------------------------]
] Ends on the second byte of a DBCS ] Replaces that byte with a ]
] character ] single-byte blank and the ]
] ] left-next byte by a shift-in ]
] ] delimiter. ]
]------------------------------------]-----------------------------------]
In addition, if the adjustment causes an invalid DBCS character, or a

contiguous pair of DBCS delimiters, &SUBSTR replaces those by single-byte
blanks. However, SUBSTR does not change any contiguous pairs of DBCS
delimiters that were part of the original data string.
The following are several examples of the adjustment process. In the

examples, the characters s, Dn, <, >, and b denote a single-byte
character, double-byte character, shift-out delimiter, shift-in delimiter,
and single-byte blank, respectively.
&SUBSTR(4:10,ss<D1D2D3D4>) /* result: b<D2D3>
&SUBSTR(5:11,ss<D1D2D3D4>) /* result: <D2D3>b
&SUBSTR(6:10,ss<D1><D3D4>) /* result: b<D3>
&SUBSTR(1:3,ss<D1D2D3D4>) /* result: ssb
&SUBSTR(3:5,ss<D1D2D3D4>) /* result: bbb
Because &SUBSTR may truncate data in DBCS strings, you can use &SYSCSUBSTR
as an alternative to &SUBSTR for DBCS data.
6.8 Defining a Substring - &SYSCSUBSTR
Use the &SYSCSUBSTR built-in function when you want a CLIST to treat
double-byte character set (DBCS) characters as single characters in a
substring operation. &SYSCSUBSTR differs from &SUBSTR in that &SYSCSUBSTR
counts each DBCS character as one character, and does not count DBCS
delimiters. If resulting substrings begin or end with DBCS characters,
&SUBSTR adds DBCS delimiters as needed. For example:
] SET X = &SUBSTR(2:3,<d1d2d3>) /* result: X = <d2d3>
The same is true if a string contains both EBCDIC and DBCS characters:
] SET Y = &SUBSTR(1:3,AB<d1d2d3>) /* result: X = AB<d1>
Except for the difference in treating DBCS characters, &SYSCSUBSTR is

identical to &SUBSTR.
6.9 Converting Character Strings to Uppercase Characters - &SYSCAPS
Use &SYSCAPS to convert character strings to uppercase characters.

&SYSCAPS does not modify special characters or DBCS characters included in
the string. If a string begins with leading zeros, &SYSCAPS strips them
off. Otherwise, &SYSCAPS does not modify numbers in the string. You can
use variables containing the character strings in &SYSCAPS built-in
functions.
You can use &SYSCAPS with &SYSLC to control the capitalization of text in
a CLIST. For an example, see "Controlling Uppercase and Lowercase for
READ Statement Input" in topic 8.3.
6.10 Converting Character Strings to Lowercase Characters - &SYSLC
Use &SYSLC to convert character strings to lowercase characters. &SYSLC

does not modify numbers, special characters, or DBCS characters included
in the string. You can use variables containing the character strings in
&SYSLC built-in functions. For data to be changed to lowercase, CONTROL
ASIS or NOCAPS must be in effect or &SYSASIS must be set to the value ON.
6.11 Determining Data Set Availability - &SYSDSN
Use the &SYSDSN built-in function to determine whether a specified data

set or a specified data set and member exist and are available for use.
: If a data set has been migrated, &SYSDSN attempts to recall it. The data
: set name can be the name of any cataloged data set or cataloged
: partitioned data set with a member name. Additionally, if you specify a
member of a partitioned data set, &SYSDSN checks whether or not you have
access to the data set.
: To suppress TSO/E messages issued by the &SYSDSN function, use the CONTROL
: NOMSG statement. For information about the CONTROL statement, see
: "CONTROL Statement" in topic 13.4.
&SYSDSN returns one of the following values:
OK /* the data set or the data set and member exist

/* and are available
MEMBER SPECIFIED, BUT DATASET IS NOT PARTITIONED
MEMBER NOT FOUND
DATASET NOT FOUND
ERROR PROCESSING REQUESTED DATASET
PROTECTED DATASET /* a member was specified but the
/* data set is RACF-protected
VOLUME NOT ON SYSTEM
UNAVAILABLE DATASET /* another user has an exclusive
/* ENQ on the specified data set
INVALID DATASET NAME, data-set-name
MISSING DATA SET NAME
: Once a data set is available for use, you may find it useful to get more
: detailed information. For example, if you later need to invoke a service
: that requires a specific data set organization, then use the LISTDSI
: statement. For a description of the LISTDSI statement, see "LISTDSI
: Statement" in topic 13.15.
For example, you can use the &SYSDSN built-in function with conditional
logic (see Topic 7, "Structuring CLISTs") to determine which data set to
allocate for use in a CLIST.
IF &SYSDSN('SYS1.MYLIB')=OK THEN +
DO
alloc f(utility) da('SYS1.MYLIB')
call (iecompar)
END
ELSE +
IF &SYSDSN('SYS1.INSTLIB(IECOMPAR)')=OK THEN +
DO
alloc f(utility) da('SYS1.INSTLIB')
call iecompar
END
ELSE +
.
.
.
Enclose fully-qualified data set names in single quotes when they appear
in &SYSDSN built-in functions. You can use variables containing data set
names in &SYSDSN built-in functions.
: The &SYSDSN function issues message IKJ56709I if a syntactically invalid

: data set name is passed to the function. To prevent this message from
: being displayed, use CONTROL NOMSG.
: --------------------------------------------------------------------
: PROC 0
: SET DSNAME = ABCDEFGHIJ.XYZ /* Syntactically invalid name,
: /* because a qualifier is longer
: /* than 8 characters
: CONTROL NOMSG /* Set OFF to suppress any SYSDSN
: /* TSO/E messages
: WRITE VALUE RETURNED BY SYSDSN ==> &SYSDSN(&DSNAME)
: EXIT CODE(0)
: --------------------------------------------------------------------
6.12 Locating One Character String Within Another - &SYSINDEX
Use the &SYSINDEX built-in function to locate the position where one
character string begins within another character string. In other words,
&SYSINDEX returns the numeric index (or offset) of string_1 within
string_2. If SYSINDEX does not find string_1 within string_2, &SYSINDEX
returns a value of zero.
Use the following syntax:
&SYSINDEX(string_1,string_2â,startã)
where:
string_1 is the character string that you are searching for.
string_2 is the character string to be searched in.
start is a numeric expression indicating where in string_2 the search for

string_1 should begin. If omitted or zero, this value defaults to
one.
In examples 1-4, assume that &X is DOG, &Y is CATDOGSDOG and &Z is 2:
1. SET A = &SYSINDEX(&X,&Y) /* result: A = 4
&SYSINDEX found DOG in the fourth position of CATDOGSDOG, thus the

index is 4.
2. SET A = &SYSINDEX(&X,&Y,&Z) /* result: A = 4
&SYSINDEX started searching at the second position, and found DOG

again at the fourth position.
3. SET A = &SYSINDEX(&X,&Y,3+&Z) /* result: A = 8
Because the search started in the fifth position (3+2) &SYSINDEX found
the second occurrence of DOG, in the eighth position.
4. SET A = &SYSINDEX(&X,&Y,9) /* result: A = 0
The search started in the ninth position and &SYSINDEX could not find
the target string DOG.
Blanks are valid in string_1 and string_2. For example:
SET A = &SYSINDEX(is full,the car is full) /* result: A = 9
To search for a blank in string_2, you can set string_1 to a variable

containing the value &STR( ). For example:
SET BLANK = &STR( )

SET TARG = THIS IS A TEST
SET LOC = &SYSINDEX(&BLANK,&TARG) /* result: &LOC = 5
If string_1 or string_2 might contain a comma or right parenthesis, first

set the string to a variable's value using &STR, then use the variable in
&SYSINDEX, again enclosed in &STR(...). For example:
SET ARG = &STR(,)

SET TARG = &STR((80,60))
SET &LOC = &SYSINDEX(&STR(&ARG),&STR(&TARG)) /* result: &LOC = 4
SET ARG = &STR())

SET TARG = &STR((80,60))
SET &LOC = &SYSINDEX(&STR(&ARG),&STR(&TARG)) /* result: &LOC = 7
Using &SYSINDEX with DBCS Strings
&SYSINDEX can search for strings that contain characters of the

double-byte character set (DBCS). The following considerations apply:
* Always include DBCS delimiters around DBCS characters in string_1 and

string_2. For example, using < and > to denote the DBCS delimiters
X'0E' (shift-out) and X'0F' (shift-in):
SET A = &SYSINDEX(<d2>,<d1d2d3>) /* result: A = 2
* String_1 and string_2 can have EBCDIC, DBCS, or mixed data. For
example:
SET X = &SYSINDEX(CD,A<d1d2>BCD) /* result: X = 5

SET X = &SYSINDEX(<d2>,A<d1d2>BCD) /* result: X = 3
EBCDIC and DBCS strings never match, even when they have the same
hexadecimal values. For example:
SET X = &SYSINDEX(AB,<d1d2d3>) /* result: X = 0

/* where EBCDIC characters 'AB' and a DBCS character 'd2'
/* have the same hexadecimal value.
* Contiguous shift-out/shift-in delimiters and contiguous

shift-in/shift-out delimiters in string_1 are treated as parts of the
target. For example:
SET X = &SYSINDEX(<d1><d2>,A<d1><d2>B) /* result: X = 1

SET X = &SYSINDEX(<d1><d2>,A<d1d2>B) /* result: X = 0
* If string_1 consists of DBCS delimiters only, they are searched for in

string_2, and the result is the position of the character following
the delimiters. For example:
SET X = &SYSINDEX(<>,A<>BCD) /* result: X = 3
6.13 Limiting the Level of Symbolic Substitution - &SYSNSUB
Use the &SYSNSUB built-in function to limit the number of times a CLIST
performs symbolic substitution in a statement. With &SYSNSUB, you can
limit the CLIST to between zero and 99 levels of substitution.
&SYSNSUB has the following syntax:
&SYSNSUB(level,expression)
where:
level is a positive whole number, or a symbolic variable that resolves to

a positive whole number, from 0 to 99. This number tells the CLIST
how many levels of symbolic substitution to perform on the expression.
The level parameter cannot contain other built-in functions or
expressions.
expression is a CLIST expression whose level of symbolic substitution is

to be controlled, and whose final value is to be frozen without
further evaluation of any kind.
For example,
SET Y = 30 /* result: &Y contains 30

SET X = &&Y /* result: &X contains &Y
SET Z = &&X /* result: &Z contains &X
SET A = &SYSNSUB(2,&Z) /* result: &A contains &Y
As specified, the CLIST performs only two levels of substitution,

substituting &X for &Z and then substituting &Y for &X. The CLIST does
not continue and resolve &Y to 30, as it would without the &SYSNSUB limit.
You can use &SYSNSUB to override the rule for double ampersands, in which
the CLIST removes the first ampersand and does no substitution of the
remaining variable. &SYSNSUB counts removal of the first ampersand as one
level of substitution, and allows substitution to continue until the value
in the level parameter is reached.
For example:
SET X = 10 /* result: &X = 10

SET Y = &&X /* result: &Y = &X (rule for double &&)
SET Y = &SYSNSUB(2,&&X) /* result: &Y = 10 (&SYSNSUB overrides &&)
Note: The control variable &SYSSCAN restricts the levels of substitution

that you can specify with &SYSNSUB. &SYSSCAN must contain a number
greater than or equal to the number you specify in &SYSNSUB's level
parameter.
6.14 Converting DBCS Data to EBCDIC - &SYSONEBYTE
Use the &SYSONEBYTE built-in function to convert character strings from

the double-byte character set (DBCS) to the EBCDIC character set.
&SYSONEBYTE converts only DBCS characters that have EBCDIC equivalents:
the DBCS blank (X'4040') and DBCS characters that begin with the value
X'42'.
&SYSONEBYTE converts the DBCS characters that have EBCDIC equivalents by

removing the first byte (X'40' or X'42'). The second byte, which remains,
represents the character in EBCDIC.
&SYSONEBYTE places DBCS delimiters around DBCS characters that are not
convertible (those that lack EBCDIC equivalents).
The following example represents a complete conversion from DBCS to

EBCDIC:
SET X = &SYSONEBYTE(<d1d2d3d4>) /* result: X = ABCD
The following example represents a partial conversion from DBCS to EBCDIC,

assuming that d5 and d6 do not start with X'42' and are not the hex blank
(X'4040'):
SET X = &SYSONEBYTE(<d3d4d5d6d7d8>) /* result: X = CD<d5d6>EF
6.15 Converting EBCDIC Data to DBCS - &SYSTWOBYTE
Use the &SYSTWOBYTE built-in function to convert EBCDIC characters to the

double-byte character set (DBCS). The EBCDIC characters that can be
converted are those with the hexadecimal equivalents X'40' and in the
range from X'41' to X'FE'. Any other EBCDIC characters cause errors when
used with &SYSTWOBYTE.
&SYSTWOBYTE converts the EBCDIC characters to DBCS by prefixing them with

the value X'42'. In the case of the EBCDIC blank (X'40'), &SYSTWOBYTE
prefixes it with the value X'40' to create the DBCS blank.
&SYSTWOBYTE encloses the resulting DBCS strings in DBCS delimiters (X'0E'

and X'0F').
The following example represents a complete conversion from EBCDIC to

DBCS:
SET X = &SYSTWOBYTE(ABCD) /* result: X = <dAdBdCdD>
The following example represents a partial conversion from EBCDIC to DBCS:

SET X = &SYSTWOBYTE(CD<d5d6>EF) /* result: X = <dCdDd5d6dEdF>
7.0 Topic 7. Structuring CLISTs
A CLIST can be:
* A single list of commands and statements
* A series of short lists connected by statements indicating which list

is to be executed next.
When you create a CLIST as a series of short lists, you can connect the
lists using structured programming techniques. In structured programming,
you direct the flow of execution from list to list in a generally top-down
sequence, from the highest to the lowest level of detail. At the lower
levels of detail, the lists can be independent modules (subprocedures and
nested CLISTs) containing common code that you can call from other parts
of the CLIST. A structured CLIST helps you avoid repetitive code and is
easier to read and maintain than an unstructured CLIST.
This topic describes the structural elements of the CLIST language and how
to use them to move from one list of commands and statements to another.
Structural CLIST statements belong to the following categories:
* Selection
* Loops
* Calls to subprocedures
* Calls to other CLISTs.
7.1 Making Selections
To tell the CLIST which commands or statements to execute next, you can
use the IF Statement or the SELECT statement. These statements combine
each selection with a test; if the test proves true, the CLIST executes
the instructions, if not, the CLIST can execute alternative instructions.
The IF-THEN-ELSE Sequence
The IF-THEN-ELSE sequence tests a condition or set of conditions, then

determines the logical path of execution (action) based on the results of
the test.
The condition must be either a comparative expression or a variable

containing a comparative expression. You may code multiple conditions, in
which case the comparative expressions (and/or variables) must be joined
by logical operators.
The action can be one or more instructions. If the condition or set of

conditions is true, the CLIST executes the instructions in the THEN
action. If the condition or set of conditions is false, the CLIST
executes the instructions in the ELSE action.
The Standard Format
The standard format includes actions for both true and false conditions,
for example:
IF condition THEN action ELSE action

If an action involves more than one statement or command, it is necessary

to enclose the action in a DO-END sequence, for example:
IF condition THEN +
DO
.
.
.
action /* action consists of a list of statements or commands
.
.
.
END
ELSE action /* action consists of a single statement or command
For example, assume a CLIST optionally prints a data set it has updated
based on user input. Assume the CLIST has prompted the user to determine
whether to print the data set and has saved the response in a variable
called &PRINT. The following IF-THEN-ELSE sequence performs the desired
processing:
/***********************************************************************/
/* If the user wants data set printed, issue a message */
/* saying that it is being printed and issue the command */
/* that prints it. If user does not want data set printed */
/* just issue a message saying that the data set is not */
/* being printed. */
/***********************************************************************/
IF &PRINT=YES THEN +
DO
WRITE We are printing the data set as you requested.
printds da(&dsn)
END
ELSE +
WRITE The data set will not be printed.
When there is only one instruction in an action, you may place the
instruction on the same line as the THEN or ELSE statement. For example,
you could code the ELSE statement in the previous example as follows:
ELSE WRITE The data set will not be printed.
The Null ELSE Format
When a specific ELSE action is not required, you can code a null ELSE
clause in one of two ways: omit the ELSE clause entirely or just code ELSE
without operands (an action). The following IF-THEN-ELSE sequence omits
the ELSE entirely:
DO
printds da(&dsn)
END
You can also code the following:
DO
printds da(&dsn)
END
ELSE
The Null THEN Format
Assume a CLIST prints a data set itself and does not have to invoke
another CLIST to do the printing. By coding a condition that is true when
the data set should not be printed, you define a null THEN clause that
effectively branches to the end of the ELSE clause, avoiding the code that
prints the data set.
The following IF-THEN-ELSE sequence bypasses the printing action when

&PRINT=NO. (If &PRINT has any other value, such as YES or null, then
printing is performed.)
IF &PRINT=NO THEN
ELSE +
DO
.
.
.
(The rest of the CLIST, which prints the data set)
.
.
.
.
END
Nesting IF-THEN-ELSE Sequences
IF-THEN-ELSE sequences can contain other (nested) IF-THEN-ELSE sequences.

For example, the following IF-THEN-ELSE sequence uses a nested
IF-THEN-ELSE sequence as the action of its ELSE clause:
IF condition1 THEN +
DO
action1 /* Do if condition 1 is true
END
ELSE +
IF condition2 THEN +
DO
action2 /* Do if condition1 is false and
END /* condition2 is true
ELSE +
DO
action3 /* Do if condition1 and condition2
END /* are both false
Nested IF-THEN-ELSE sequences allow you to control the flow of processing

under very precise conditions. However, multiple nested IF-THEN-ELSE
sequences can be difficult to write and maintain. As an alternative, you
can use the SELECT statement in many cases.
The SELECT Statement
In situations where you might want to use multiple IF-THEN-ELSE

statements, you can often use a single SELECT statement instead. The
SELECT statement allows a CLIST to select actions from a list of possible
actions. An action consists of one or more statements or commands. The
SELECT statement has the following syntax, ending with the END statement.
You can use the SELECT statement with or without the initial test
expression.
SELECT âtest expressionã

WHEN expression1
.
.
.
(action)
.
.
.
WHEN expression2
WHEN expression3
âOTHERWISEã
.
.
.
(action)
.
.
.
END
Using SELECT without a Test Expression (Simple SELECT)
If you omit the test expression from the SELECT statement, the CLIST tests
the WHEN expressions in sequence for a true value. If a true value is
found (for example, 1 = 1) the CLIST executes the action of that WHEN
clause only. Then the CLIST passes control to the END statement. If none
of the expressions evaluate to a true value, the CLIST executes the
OTHERWISE action, if any.
For example, the following SELECT statement selects an action based on a

return code from previous processing:
SELECT
WHEN (&RTNCODE = 0) CALL 'A.B.LOAD(PGM)'
WHEN (&RTNCODE = 1) +
DO
SET &X = X + 1
SET RETRY = &STR(YES)
END
OTHERWISE SET &MSG = &STR(SEVERE ERROR)
END
For other examples of using the simple SELECT statement, see Figure 10-3
in topic 10.2 and Figure 12-19 in topic 12.15.
Using SELECT with a Test Expression (Compound SELECT)
If you include a test expression on the SELECT statement, the CLIST

compares the test expression to the expressions on the WHEN clauses. On
each WHEN clause, you can specify multiple expressions, or a range of
values by using a colon (:) between the low and high values in the range.
You can combine expressions and ranges on a WHEN clause by using the
operator OR or ].
If a test expression matches a value or falls within a range of values in

a WHEN expression, the CLIST executes the action for that WHEN clause,
then passes control to the END statement.
For example, in the following SELECT statement, the CLIST executes the
action of the first WHEN clause because the test expression (5) falls
within the range of values 4:6 on that WHEN clause:
SELECT 5
WHEN (3 ] 7 ] 4:6) action...
WHEN (9 ] &A + &Z) action...
END
If no WHEN expressions satisfy the test expression, the CLIST executes the
OTHERWISE action, if any.
For example, the following CLIST uses a SELECT statement to invoke other
CLISTs that print quarterly reports. The CLIST bases its selection on a
test expression (the number of the month) that the invoker supplies. When
the number of the month falls within a certain range, the CLIST prints the
appropriate report. Otherwise, the CLIST writes an error message.
PROC 1 MONTH
SELECT (&MONTH)
WHEN (1:3) %FIRSTQTR
WHEN (4:6) %SECNDQTR
WHEN (7:9) %THIRDQTR
WHEN (10:12) %FORTHQTR
OTHERWISE WRITE The month must be a number from 1 to 12.
END
Distinguishing WHEN Clauses from WHEN Commands
The WHEN clause in a SELECT statement is syntactically distinct from the

WHEN SYSRC TSO/E command. In a SELECT statement, a left parenthesis must
follow a WHEN clause. If you want to use the WHEN command as part of an
action in a SELECT statement, enclose the WHEN command in a DO-END
sequence to prevent the SELECT statement from interpreting the command as
an invalid WHEN clause. For example, the following syntax is acceptable:
SELECT
WHEN (&X=1) +
DO /* The action of the WHEN clause */
WHEN SYSRC(= 8) TIME /* is the WHEN SYSRC TSO command. */
END /* End of the DO group */
END /* End of the SELECT statement */
For more information about using the WHEN SYSRC TSO/E command, see TSO/E
V2 Command Reference, SC28-1881.
Distinguishing the SELECT Statement from the RACF SELECT Subcommand
If, in a CLIST, you invoke the SELECT subcommand of the RACF command
RACFRW, you must distinguish the subcommand from the SELECT statement. To
do so, use the &STR built-in function. For example, you could specify the
subcommand name as follows:
RACFRW
&STR(SELECT) VIOLATIONS
7.2 Loops
Unlike the simple DO-END sequence, the other DO-sequences in the CLIST
language create loops. Loops are lists of statements or commands that can
be executed one or more times or not at all, depending on conditions that
you specify in the loop. A CLIST executes a loop as many times as the
conditions dictate. When the conditions are satisfied or no longer true,
execution continues at the instruction after the loop.
The following sections describe how to create loops with the DO statement.
The DO-WHILE-END Sequence
The DO-WHILE-END sequence creates a loop that executes while a specified

condition is true. If the condition is not true, the loop does not
execute.
To use the DO-WHILE-END sequence, code:

DO WHILE condition
.
.
.
action
.
.
.
END

containing a comparative expression. You can code multiple conditions by
joining expressions and/or variables with logical operators.
The action can be one or more instructions. The CLIST executes the
instructions within the sequence repeatedly while the condition on the
WHILE clause is true. When the condition is false, the CLIST executes the
next instruction after the END statement.
For example, you can initialize a variable (usually a counter) before the
sequence and include it in the conditional expression. Then, you can
modify the variable in the action so that eventually the condition is
false.
For example, to process a set of instructions five times, you can code the
following:
SET &COUNTER = 5 /* Initialize counter

/* Perform the action while counter is greater than 0 */
DO WHILE &COUNTER > 0
.
.
.
(Set of instructions)
.
.
.
SET COUNTER = &COUNTER - 1 /* Decrease counter by 1 */
END
The variable &COUNTER is a loop counter initially set to a value of five.

WHILE tests of the value of this counter each time the CLIST begins to
execute the DO-WHILE-END sequence. As long as the value of &COUNTER is
greater than zero (the test condition is true), the CLIST executes the
sequence, whose last instruction decreases the counter's value by one.
When the counter's value reaches zero (the test condition is false), the
CLIST ends the loop, and continues processing at the instruction following
the END statement.
If an error occurs in a DO-WHILE sequence, execution stops. In previous

releases, a warning message was issued and execution continued, with the
DO-WHILE sequence treated as a simple DO-END sequence.
The DO-UNTIL-END Sequence
The DO-UNTIL-END sequence creates a loop that executes at least once and
continues until a specified condition is true.
To use the DO-UNTIL-END sequence, code:
DO UNTIL condition
.
.
.
action
.
.
.
END

containing a comparative expression. You can code multiple conditions by
joining expressions and/or variables with logical operators.
The action can be one or more instructions. The CLIST executes the
instructions within the sequence once, then tests whether the condition on
the UNTIL clause is true. If the condition is false, the CLIST repeats
the loop until the condition is true. When the condition is true, the
CLIST ends the loop and executes the next instruction after the END
statement.
For example, to repeat some instructions until a condition is true, you

can code the following:
DO UNTIL &INPUT = YES /* Perform action until condition is YES

.
.
.
(action)
.
.
.
WRITE Type YES if you are finished
READ &INPUT
END
The DO UNTIL sequence is useful for requesting input from a user. Because
the decision is made after the input is received, the loop can continue or
end depending on the value of the input.
The Iterative DO Sequence
The iterative DO sequence creates a loop that executes as long as a

numeric value stays within a given range of values. The values can be
variables derived from CLIST processing. The iterative DO sequence has
the following structure:
DO variable = from_expression TO to_expression +

âBY by_expressionã
.
.
.
(action)
.
.
.
END
where:
variable is the control variable for the loop. Its value changes each
time the loop executes, increasing by one (the default) or by a value
that you specify in the BY expression.
from_expression is a decimal integer, or an expression that evaluates to a

decimal integer, from which the control variable starts. The CLIST
sets the control variable to this value when the loop begins.
to_expression is a decimal integer, or an expression that evaluates to a

decimal integer, that the control variable must increase or decrease
to. The CLIST executes the loop as long as the value of the control
variable stays within the range created by the FROM and TO
expressions.
by_expression is a decimal integer, or an expression that evaluates to a

decimal integer, by which the control variable increases or decreases.
The default value is one. After the loop executes, the control
variable increases or decreases by this amount. If the control
variable is no longer within the FROM-TO range, execution continues at
the instruction after the END statement.
For example, a CLIST would execute the following loop ten times:
DO &count = 1 to 10 /* using default BY, increase &count by one

/* each time through the loop
.
.
.
END /* &count is now equal to 11
And a CLIST would execute the following loop five times:
DO &count = 1 TO 10 BY 2 /* increase &count by two

/* each time through the loop
.
.
.
END /* &count is now equal to 12
The FROM, TO, and BY expressions can all contain CLIST variables:
DO &count = &min TO &max BY &increment

.
.
.
END
Compound DO Sequences
The preceding sections describe different ways to control the execution of

loops. You can combine these different types of loop control in a
compound DO sequence. A compound DO sequence combines an iterative DO
sequence with a DO-WHILE and/or DO UNTIL sequence.
In a compound DO sequence, the iterative DO sequence comes first, followed

by either the DO-WHILE or DO-UNTIL sequence:
DO variable = from_exp TO to_exp BY by_exp +

WHILE condition1 +
UNTIL condition2 +
.
.
.
(action)
.
.
.
END
The CLIST executes the compound DO sequence as shown in Figure 7-1.
The following example demonstrates a possible compound DO sequence:
SET &increment = 2 /* Initialize BY condition

SET &year = 87 /* Initialize WHILE condition
DO &count = 1 TO 10 BY &increment +
WHILE &year=87 UNTIL &input=YES
.
.
.
(action)
.
.
.
WRITE Type YES if you are finished
READ &INPUT
END
--------------------------------------------------------------------------
1.
]--------------------------]
] Set control variable to ]
] value of from_expression ]
]------------]-------------]
]
2. v
]--------------------------]
]--->] Use TO value to test ]--> If TO value is exceeded,
] ] control variable for ] discontinue execution
] ] termination ]
] ]------------]-------------]
] ]
] 3. v
] ]--------------------------]
] ] Use WHILE expression to ]--> If WHILE condition is not
] ] test for termination ] met, discontinue execution
] ]------------]-------------]
] ]
] 4. v
] ]--------------------------]
] ] ]
] ] Execute Action ]
] ] ]
] ]------------]-------------]
] ]
] 5. v
] ]--------------------------]
] ] Use UNTIL expression to ]--> If UNTIL condition is met,
] ] test for termination ] discontinue execution
] ]------------]-------------]
] ]
] 6. v
] ]--------------------------]
] ] Use BY value to update ]
] ] control variable ]
] ]------------]-------------]
] ]
]-----------------]
--------------------------------------------------------------------------
Figure 7-1. How a CLIST Executes a Compound DO Sequence
If you want a WHILE or UNTIL expression to contain a return code from the
action of the DO sequence, obtain the return code from &LASTCC and store
it into another variable as part of the action. For example:
DO &I = 1 to 10 WHILE (&RCODE = 0)

.
.
.
SET RCODE = &LASTCC
END
Nesting Loops
The action of a loop can contain other loops. Loops within loops are
called nested loops. Loops can contain nested loops of the same type or
of a different type.
Nested loops of the same type are often iterative DO-loops within other
iterative DO-loops. For example, to execute 100 CLISTs named PROC00
through PROC99, you could code:
DO &I = 0 to 9
DO &J = 0 to 9
%proc&I&J
END
END
Nested loops of a different type are often DO-UNTIL loops within DO-WHILE
loops, for example:
SET &COUNTER1 = 0 /* Initialize outer loop counter */

SET &COUNTER2 = 3 /* Initialize nested loop counter */
DO WHILE &COUNTER1 < 5
/* Perform action while &counter1 is less than 5 */
.
.
.
(action) /* Executes 5 times */
.
.
.
DO UNTIL &COUNTER2 = 0
/* Perform action until &counter2 is equal to 0 */
.
.
.
(Subset of action) /* Executes 3 times */
.
.
.
SET COUNTER2 = &COUNTER2 - 1 /* Increase nested loop counter by 1 */
END
.
.
.
SET COUNTER1 = &COUNTER1 + 1 /* Increase outer loop counter by 1 */
END
Distinguishing END Statements from END Commands or Subcommands
You can issue TSO/E END commands or subcommands in a CLIST. The END
command terminates the CLIST, and END subcommands terminate certain
commands, such as the TEST command. When you include TSO/E END commands
or subcommands in the action of a DO-sequence or a SELECT statement, you
must distinguish the END commands or subcommands from the END statement.
You can distinguish the END statement using the CONTROL statement or the
DATA-ENDDATA sequence.
Using the CONTROL Statement
One way to distinguish an END statement from an END command or subcommand

is by coding a CONTROL statement with the END operand. The value you code
for the END operand must then be substituted for the END statement
anywhere in the CLIST, unless another CONTROL END overrides the value.
For example, if you want to substitute ENDO for the END statement, you can
code the following:
CONTROL END(ENDO)
SET COUNTER = 10
DO WHILE &COUNTER GT 0
.
.
.
(action)
.
.
.
test datapak(newpgm) /* Issue TSO/E TEST command */
.
.
.
(TEST subcommands)
.
.
.
end /* Issue END subcommand of TSO/E TEST */
.
.
.
(more action)
.
.
.
ENDO
Using the DATA-ENDDATA Sequence
Another way to identify END commands or subcommands in DO-sequences or

SELECT statements, is to place them in a DATA-ENDDATA sequence. For
example:
SET COUNTER = 10
DO WHILE &COUNTER GT 0
.
.
.
(action)
.
.
.
DATA
test datapak(newpgm) /* Issue TSO/E TEST command */
.
.
.
(TEST subcommands)
.
.
.
end /* Issue END subcommand of TSO/E TEST */
ENDDATA
.
.
.
(more action)
.
.
.
END
Only TSO/E commands and subcommands can appear within the DATA-ENDDATA
sequence. If a CLIST statement is included, TSO/E attempts to execute it
as a TSO/E command, causing an error. For more information about the
DATA-ENDDATA sequence, see "Coding Responses to Prompts - The DATA
PROMPT-ENDDATA Sequence" in topic 8.1.
7.3 Subprocedures
A subprocedure is a part of a CLIST that you can call from one or more
places in a CLIST. With subprocedures, you can organize a CLIST into
logical units, making the CLIST easier to write and maintain. You can
also keep common code in a single location and call it from other parts of
the CLIST, thus avoiding repetitive code.
Subprocedures offer a variety of ways to communicate information within a

CLIST. You can:
* Pass parameters to and from subprocedures, for reference or

modification
* Share variables globally among subprocedures
* Isolate variables in a subprocedure from the rest of the CLIST.
Calling a Subprocedure
You call a subprocedure using the SYSCALL statement. On the SYSCALL

statement, name the subprocedure and any parameters you want to pass to
the subprocedure. The parameters can be data strings, variable values, or
variable names.
For example, the following CLIST uses the SYSCALL statement to pass a data
string (Jones), a variable value (&A), and a variable name (B) to a
subprocedure (XYZ):
SET &A = AL
SET &B = Jr.
SYSCALL XYZ Jones &A B /* pass parameters to XYZ */
XYZ: PROC 3 PARM1 PARM2 PARM3 /* receive parameters on PROC stmt */

SYSREF PARM3 /* indicate parm3 holds a var. name */
WRITE &PARM1, &PARM2 &PARM3 /* result: JONES, AL Jr. */
END
Subprocedures always begin with a labeled PROC statement. The label can
consist of 1-31 characters (A-Z, 0-9, #, $, @) beginning with an
alphabetic character (A-Z). In the example above, the label is XYZ; the
number 3 on the PROC statement indicates that the subprocedure receives 3
positional parameters; those parameters are assigned to the variables
PARM1, PARM2, and PARM3. For more information about the PROC statement,
see "PROC Statement" in topic 13.18.
The SYSREF statement tells the CLIST that PARM3 contains the name of a
variable (B). The SYSREF statement allows other statements in
subprocedure to reference and modify the variable's value (Jr.). For more
information, see "Using the SYSREF Statement".
To pass a parameter containing blanks to a subprocedure, set a variable

equal to the parameter value, then refer to that variable (without the
ampersand) using &STR on the SYSCALL statement. In the subprocedure, use
the SYSREF statement to refer to the PROC statement parameter that
corresponds to the variable name passed on the SYSCALL statement. For
example,
SET &A = JOHN AL

SYSCALL XYZ &STR(A) /* Pass variable to XYZ, omitting & from
/* the variable name
.
.
.
XYZ: PROC 1 PARM /* Subprocedure XYZ
SYSREF &PARM /* indicate PARM holds a variable name
WRITE &PARM /* result: JOHN AL
Subprocedures must always end with the END statement. When subprocedures
end, they pass control back to the statement following the SYSCALL
statement.
Subprocedures can use the SYSCALL statement to:
* Call other subprocedures and pass parameters to them

* Call themselves
* Call the CLIST's main procedure, if it has a label.
Returning Information from a Subprocedure
Subprocedures can return information to the caller using:
* Return codes
* SYSREF variables
* NGLOBAL variables.
Using the RETURN CODE Statement
Subprocedures can return information to the caller using the CODE option
of the RETURN statement. Like return codes from TSO/E commands, return
codes from subprocedures are stored in the control variable &LASTCC, but
error return codes from subroutines will not cause an error routine to
receive control.
In the following example, the subprocedure passes a return code to the

statement following SYSCALL:
SET &A = AL
SYSCALL XYZ &A /* pass variable &A to XYZ */
IF &LASTCC = 0 THEN +
WRITE All's Well!
XYZ: PROC 1 PARM1

WRITE &PARM1
RETURN CODE(0)
END
Using the SYSREF Statement
When a SYSCALL statement passes a variable name (without the ampersand),

the subprocedure can use a SYSREF statement to let following statements
reference and modify the variable's value. All changes to a SYSREF
variable are retroactive; that is, the new values are assigned to the
original variable back in the caller.
In the following example, the subprocedure gives a new value to the

variable whose name is passed (A). The new value (GEORGE) replaces the
old value (AL) in the caller.
SET &A = AL
SYSCALL XYZ A /* pass var. &A to XYZ, omitting the &*/
WRITE &A /* result: GEORGE
XYZ: PROC 1 &PARM1

SYSREF &PARM1 /* refer changes to the caller */
SET &PARM1 = GEORGE
RETURN CODE(0)
END
Reminder: For SYSREF variables, always omit the ampersand (&) from
corresponding variables on the SYSCALL statement. By omitting the
ampersand on SYSCALL, you pass the name of the variable, not its value, to
the subprocedure. Using the SYSREF statement, the subprocedure can then
assign new values to the variable.
Sharing Variables among Subprocedures
In addition to passing return codes and variable values, you can define
common variables to be shared among different CLISTs, or among
subprocedures in a single CLIST.
Variables shared among different CLISTs are called GLOBAL variables.

GLOBAL variables are defined using the GLOBAL statement, and are fully
described in "Nesting CLISTs" in topic 7.4.
Variables shared by subprocedures in one CLIST are called NGLOBAL (named

global) variables. You define named global variables with the NGLOBAL
statement. When you define an NGLOBAL variable, any subprocedure in the
same CLIST can refer to it by name and modify its value.
The NGLOBAL variables differ from GLOBAL variables in that:
* They are not global to (shared with) other CLISTs.

* They are defined by name only (not position).
* They need to be defined only once.
Using the NGLOBAL Statement
The NGLOBAL statement names variables that all the subprocedures in a

CLIST can use. The following subprocedure (ABC) defines variables A, B,
and C and uses the NGLOBAL statement to make them available to other
subprocedures in the CLIST:
ABC: PROC 0 /* In subprocedure ABC,

NGLOBAL A,B,C /* define NGLOBAL variables
SET A = apples
SET B = bananas
SET C = cantaloup
SYSCALL XYZ /* call subprocedure XYZ
END
XYZ: PROC 0 /* In subprocedure XYZ,

WRITE Mix &A, &B, and &C /* use the NGLOBAL variables
END
The NGLOBAL statement must precede any statement that uses its variables.
The number of variables that you can name on the NGLOBAL statement is
unlimited.
For another example of using the NGLOBAL statement with subprocedures, see
Figure 12-24 in topic 12.16.
Restricting Variables to a Subprocedure
Variables that you define in a subprocedure are local to that

subprocedure, unless you specifically name them on a GLOBAL or NGLOBAL
statement. Different subprocedures in a CLIST can have variables with the
same name, and each variable is local to the subprocedure that defined it.
Therefore, when you define a variable, you don't have to check to see if
that name has been used in the CLIST before.
Considerations for Using Other Statements in Subprocedures
Some CLIST statements require special consideration when used in

subprocedures. The following sections describe these statements and
considerations.
Using ATTN and ERROR statements in Subprocedures
Subprocedures can have their own attention and error routines. These are
routines that receive control when the CLIST user presses the attention
key on a terminal keyboard, or an error occurs. See Topic 10, "Writing
ATTN and ERROR Routines" in topic 10.0 for a full description of these
routines, including special considerations for using them with
subprocedures. For example, a subprocedure's attention or error routine
cannot contain a nested attention or error routine.
When a subprocedure receives control, the caller's attention and error

routines remain in effect until the subprocedure issues an ATTN or ERROR
statement. Then the subprocedure's attention or error routine prevails
until the routine is turned off or replaced, or the subprocedure ends.
When the subprocedure ends, the caller's attention and error routines take
control again.
Using CONTROL Statements in Subprocedures
CLISTs can establish special conditions by issuing the CONTROL statement

and certain control variables. These conditions, comprising a CONTROL
environment, remain in effect when you call a subprocedure. Subprocedures
can set up their own CONTROL environment, but it only applies to the
subprocedure and any subprocedures it calls. When a subprocedure ends,
the caller's CONTROL environment takes effect again.
Using GOTO statements in Subprocedures
If you use a GOTO statement in a subprocedure, it can only branch to

labels in the same subprocedure. Also, GOTO statements cannot branch to
PROC statements.
7.4 Nesting CLISTs
A CLIST can invoke another CLIST, which in turn can invoke another, and so
forth. CLISTs that are invoked by other CLISTs are called nested CLISTs.
When a nested CLIST ends, it automatically branches back to the statement
following the one that invoked it. You can define global variables that
allow nested CLISTs to communicate with each other.
You can structure a series of nested CLISTs in levels. The CLIST invoked
by the user is the top-level or outer-level CLIST in the nesting chain.
CLISTs invoked by the outer-level CLIST are nested within it, and they may
have lower-level CLISTs nested within them.
In Figure 7-2, PROC1 is the outer-level CLIST. It invokes PROC2 and then
PROC3, which are nested within it. PROC2 invokes PROC4, and PROC4 invokes
PROC5. PROC4 is nested within PROC2, and PROC5 within PROC4.
PICTURE 4
Figure 7-2. Nested CLISTs
Because CLISTs are executed sequentially, PROC1 cannot invoke PROC3 until
PROC5, PROC4, and PROC2 finish processing.
The same CLIST can be invoked at two or more levels of a nested hierarchy
because each invocation of a nested CLIST causes a new copy of it to be
brought into storage. For example, PROC2 and PROC4 could both invoke
PROC5.
Protecting the Input Stack from Errors or Attention Interrupts
When a CLIST is executed, it translates each statement into an executable

format and places it in a section of storage called the input stack. The
input stack is the source from which TSO/E obtains its input (TSO/E
commands and CLIST statements).
For nested CLISTs, the input stack holds the contents of the CLISTs in the
order in which they are nested.
You can protect the input stack from being erased (flushed) when an error
or attention interrupt occurs. To protect the input stack, code the
CONTROL statement with the NOFLUSH or MAIN operand at the beginning of a
CLIST that you want to receive control when an error or attention
interrupt occurs.
Any options established by a nested CLIST are in effect only when that
nested CLIST is executing. In particular, a nested CLIST's CONTROL
statement options and attention and error routines are no longer in effect
when the nested CLIST returns control to its caller.
Nested CLISTs in the subcommand environment (those invoked under the EXEC
subcommand of EDIT) can execute only subcommands and CLIST statements.
They cannot execute TSO/E commands, nor can any nested CLISTs that they
invoke, until the END subcommand is executed.
Global Variables
Global variables are variables defined on a GLOBAL statement. They allow

communication between nested CLISTs. Any CLIST in the nested chain can
modify or reference the value of a global variable.
All global variables in a given CLIST must have unique names. You cannot
have more global variables on the GLOBAL statement in a nested CLIST than
there are on the GLOBAL statement in the top-level CLIST.
To establish global variables, first determine the total number of

symbolic variables that are referenced by more than one of the CLISTs in
the nested chain. (Include the top-level CLIST among those in the nested
chain.) Then, code GLOBAL statements in each of the CLISTs in the chain
that are involved in the passing of data.
For example, in Figure 7-2, assume the following global variable

definitions in each of the CLISTs:
In PROC1: GLOBAL A B C D
In PROC2: GLOBAL X Y Z
In PROC3: GLOBAL F G H K
In PROC4: GLOBAL Q
In PROC5: GLOBAL R S.
Variables &A, &X, &F, &Q, and &R can be shared by all the CLISTs. If
PROC4 sets &Q equal to D777, then &A, &X, &F, and &R are also set equal to
D777.
Within nested CLISTs, global variables are positional; that is, all
variables defined first refer to the same variable; all variables defined
second refer to the same variable; and so on.
Exiting from a Nested CLIST
There are three ways to exit from a nested CLIST:
* Let control automatically return to the calling CLIST at the end of

the nested CLIST.
* Issue an END command.
* Issue an EXIT statement.
Using the END Command
The END command only allows you to terminate a CLIST. Control returns to
the CLIST that invoked it, but you cannot set a return code. To use the
END command, code:
end
Using the EXIT Statement
To cause a nested CLIST to return control to the CLIST that invoked it,
you can also code:
EXIT
You can specify a return code on the EXIT statement. The return code
provides a way for lower-level CLISTs to pass back to their callers
indications of errors or successful execution. To pass a return code when
you exit, code:
EXIT CODE(expression)
: The expression must be a positive integer, zero, or a symbolic variable

whose value, after substitution, is an integer. The nested CLIST stores
the value of the expression into the control variable &LASTCC.
If an error or attention interrupt occurs, a nested CLIST can pass control

back to a CLIST that is protected from termination by the CONTROL MAIN or
CONTROL NOFLUSH options. To return control to such a CLIST, code:
EXIT QUIT
or
EXIT CODE(expression) QUIT
If a CLIST in the nested chain is protected from termination, execution

continues based on actions in the CLIST's active error or attention
routine. For information on writing error and attention routines, see
Topic 10, "Writing ATTN and ERROR Routines".
If no CLIST in the nested chain is protected from being terminated after

an error or an attention interrupt, coding QUIT causes control to return
to the environment from which the CLIST was invoked: TSO/E, TSO/E EDIT
mode, or ISPF.
7.5 GOTO Statements
The GOTO statement causes an unconditional branch to a label within a

CLIST. The label may be a variable whose value, after symbolic
substitution, is a valid label within the CLIST. Examples of using GOTO
statements are:
IF &A = 555 THEN GOTO A1

IF &A NE 0 THEN GOTO A2
A1: processing
.
.
A2: processing
.
.
SET TARGET = B1
IF &X = 777 THEN GOTO &TARGET
ELSE +
DO
SET TARGET = B2
.
.
IF LASTCC = 0 THEN +
SET TARGET = B1
GOTO &TARGET
END
B1: processing
B2: processing
.
.
GOTO statements cannot branch:
* To another CLIST
* To a subprocedure's PROC statement
* From one subprocedure to another
* From a subprocedure to the CLIST's main procedure.
8.0 Topic 8. Communicating with the Terminal User
The CLIST language offers several ways to communicate with the terminal
user. These methods are:
* Prompting the user for input

* Writing messages to the user
* Receiving replies from the user
* Passing control to the user
* Using ISPF panels.
8.1 Prompting the User for Input
A CLIST can prompt for input by:
* Using a PROC statement with positional or keyword parameters on the

first line of the CLIST
* Using WRITE and WRITENR statements
* Using TSO/E commands.

Prompting with the PROC Statement
When you include positional parameters on a PROC statement at the

beginning of a CLIST, the CLIST user must supply a value for each of them.
If the user does not specify a value at execution, the CLIST prompts until
the user specifies a value. For example, the PROC statement
PROC 2 NAME ADDRESS
requires the user to pass two positional parameters at execution, for

example:
EX clistname 'Jones Fishville'
If the user does not pass a parameter, the CLIST prompts for a NAME and an
ADDRESS. A PROC statement at the beginning of a CLIST also prompts when a
user passes a keyword parameter without a required value. For example,
the following PROC statement allows the user to pass the parameter ACCT
with a value in parentheses:
PROC 0 ACCT()
If the user passes ACCT without a value, for example,
EX clistname 'ACCT'
the CLIST prompts for a value.
Unlike PROC statements at the beginning of a CLIST, PROC statements on

subprocedures do not prompt for missing parameters.
For more information about the PROC statement, see "Using the PROC
Statement" in topic 4.2.
Prompting with the WRITE and WRITENR Statements
You can use either a WRITE or WRITENR statement, or a combination of both,

to send a message to the terminal user and prompt for input. To obtain
input after a WRITE or WRITENR, use the READ statement. For details about
how to use the WRITE and WRITENR statements, see "Using the WRITE and
WRITENR Statements" in topic 8.2.
Prompting with TSO/E Commands
Some TSO/E commands, such as LISTDS, require more information than just
the name of the command and they prompt when that information is not
supplied. However, TSO/E commands included in a CLIST can prompt for
input only when the CLIST allows prompting. Prompting in a CLIST is
controlled by the TSO/E commands PROFILE and EXEC, and by the CLIST
statement CONTROL and the control variable &SYSPROMPT.
The following table illustrates the effect on prompting using different

explicit specifications of PROMPT/NOPROMPT on the PROFILE and EXEC
commands and on the CONTROL statement. Note that SET &SYSPROMPT = ON has
the same effect as CONTROL PROMPT and SET &SYSPROMPT = OFF has the same
effect as CONTROL NOPROMPT.
PICTURE 5
Notes:
1. PROFILE PROMPT is the default specification and applies to a TSO/E

session, not to a particular CLIST. You don't need to specify PROFILE
PROMPT unless you want to override a prior PROFILE NOPROMPT command.
2. The PROFILE command can be executed either outside of, or within, a

CLIST.
3. EXEC NOPROMPT is the default specification and applies only to the

CLIST that it invokes.
4. The CONTROL statement applies only to the CLIST in which it appears.
5. If a CONTROL statement does not appear in a CLIST, CONTROL NOPROMPT is

implied, unless &SYSPROMPT is set to a value of ON.
Coding Responses to Prompts - The DATA PROMPT-ENDDATA Sequence
If you execute a CLIST in the background, a user cannot respond to prompts

from the CLIST. To avoid this problem, use the DATA PROMPT-ENDDATA
sequence. The DATA PROMPT-ENDDATA sequence lets you designate responses
to prompts by TSO/E commands or subcommands.
To use the DATA PROMPT-ENDDATA sequence, code:
DATA PROMPT
.
.
.
/* Responses */
ENDDATA
If the sequence is not immediately preceded by a TSO/E command or

subcommand that prompts, an error occurs (error code 968 appears in
control variable &LASTCC). You can ignore the error condition if a
command or subcommand that could prompt, does not prompt.
The responses in the DATA PROMPT-ENDDATA sequence must appear exactly as

if a user entered the response. Each DATA PROMPT-ENDDATA sequence can
respond only to prompts issued by the immediately preceding command or
subcommand. However, you can include multiple responses to satisfy
multiple prompts. Excess responses can result in an error message and
termination of the CLIST if an error routine is not present.
To stop TSO/E commands from prompting after a DATA PROMPT-ENDDATA

sequence, code a null line after ENDDATA. To code a null line, first set
a variable equal to null:
SET &abc =
Then place that variable on the line after ENDDATA:
ENDDATA
&abc
Some TSO/E commands prompt for input when you code certain operands. For
example, the LINK command invokes the linkage editor. When you substitute
an asterisk (*) for the data set name, TSO/E prompts for control
statements. If you include such a LINK command in a CLIST that might run
in the background, place the control statements within a DATA
PROMPT-ENDDATA sequence. The following CLIST, when run in the background,
link edits the member X, which resides in the file DD1:
CONTROL PROMPT LIST

IF &SYSENV=FORE THEN /* CLIST is running in the foreground */ +
link (*) /* Prompt user for control statements */ +
load('d32kds1.load') pr(*) ncal xref list let
ELSE /* CLIST is being run in the background */ +
DO
SET NULL = /* set null line to stop prompting after ENDDATA
link (*) +
load('d32kds1.load') pr(*) ncal xref list let
DATA PROMPT /* Designate responses to prompts */
include dd1(x)
entry x
name x
ENDDATA
&NULL /* null line stops prompting */
END
There are additional considerations for using the DATA PROMPT-ENDDATA

sequence:
* The CLIST must allow prompting.
* The CLIST performs symbolic substitution before using the responses to

satisfy the prompt. (You can include variables in the responses.)
8.2 Writing Messages to the Terminal
CLISTs send two types of messages to the terminal user: messages that you
specifically write from the CLIST, and informational messages from
commands or statements in the CLIST.
Using the WRITE and WRITENR Statements
Two CLIST statements are available for sending messages to the terminal
and prompting for input:
* WRITE - Displays a message at the terminal and causes the terminal's

display cursor to return to the beginning of the next line after the
message is displayed.
* WRITENR - Displays a message at the terminal and causes the terminal's

display cursor to remain at the end of the message. (The NR in
WRITENR is for No Return.)
You can use either statement to send messages. You might find WRITENR
preferable when the message prompts the user for input.
When prompting the user for input, include a READ statement after the
WRITE or WRITENR statement. The READ statement reads the user input into
a variable or variables. For more information, see "Using the READ
Statement" in topic 8.3.
Both WRITE and WRITENR must be followed by one or more blanks and the text
of the message. For example:
CONTROL ASIS
.
.
.
WRITE Your previous entry was invalid.
WRITE Do you want to continue?
WRITENR Enter yes or no.
As a result of these statements, the terminal user sees the following

messages on the screen:
Your previous entry was invalid.

Do you want to continue?
Enter yes or no. __
The cursor stops after the period in the last line to indicate the CLIST
is waiting for the user's response. Since CONTROL ASIS is specified the
CLIST displays the message 'as written', in both uppercase and lowercase
letters.
You can also use the WRITENR statement to join text. For example:
CONTROL CAPS
.
.
.
WRITENR Please enter your userid
WRITE followed by two blanks.
As a result of these statements, the terminal user sees the following

message:
PLEASE ENTER YOUR USERID FOLLOWED BY TWO BLANKS.
Because CONTROL CAPS is specified, the message is translated to all

capital letters before being displayed.
Controlling the Display of Informational Messages
You can request that informational messages from commands or statements in

a CLIST be displayed or suppressed using operands on the CONTROL statement
or the &SYSMSG control variable.
* To request that they be displayed, code:
CONTROL MSG
or
SET &SYSMSG = ON
* To suppress the display of informational messages, code:
CONTROL NOMSG
or
SET &SYSMSG = OFF
The MSG/NOMSG option has no effect on error messages, they are always
displayed.
8.3 Receiving Responses from the Terminal
The READ and READDVAL statements provide two ways for CLISTs to access
user input from the terminal. The READ statement obtains input directly
from the terminal, usually following a WRITE or WRITENR statement. The
READDVAL statement obtains input from the &SYSDVAL control variable.
Using the READ Statement
The READ statement makes terminal input available to a CLIST in the form
of symbolic variables. You normally precede a READ statement with one or
more WRITE or WRITENR statements to let the user know that the CLIST is
expecting input, and what sort of input it is expecting.
You can include one or more symbolic variables on a READ statement. If a

READ statement does not include any variables, the CLIST stores the
information the user enters into the control variable &SYSDVAL.
Assume that a WRITE statement requests that the user enter four names.
The accompanying READ statement could be coded as follows:
READ A,B,C,D
Note that variables on a READ statement do not require ampersands.
If the user's response to the previous WRITE statement is:
SMITH,JONES,KELLY,INGALLS,GREENE
The CLIST assigns the names to the symbolic variables on the READ
statement as follows:
&A has the value SMITH.

&B has the value JONES.
&C has the value KELLY.
&D has the value INGALLS.
Because the READ statement only includes four variables, the CLIST ignores
the fifth name (GREENE).
You can also code READ statements without variables:
READ
If the user responded with the same five names, they would all be stored
in the control variable &SYSDVAL. To preserve the input strings, the
CLIST does not remove the delimiters. For example, if the user responds
to the previous READ statement by entering
"SMITH,JONES,KELLY,INGALLS,GREENE", &SYSDVAL has the following value:
SMITH,JONES,KELLY,INGALLS,GREENE
To assign a null value to one of the variables on a READ statement, the

user can enter either a double comma or a double apostrophe (two single
quotes). For example, assume that the CLIST sends a message to the user
requesting four numbers. The READ statement to obtain these numbers is:
READ NUM1,NUM2,NUM3,NUM4
If the user responds either:
15,24,,73
or
'15' '24' '' '73'
The symbolic variables on the READ statement then have the following
values:
&NUM1 has the value 15.

&NUM3 has a null value.
The fact that single quotes are valid delimiters requires that you
exercise care when reading fully-qualified data set names into variables.
Precautions are necessary because, if the user enters the data set name
within single quotes (according to TSO/E naming conventions), the CLIST
normally reads them as delimiters, not data. If a WRITE statement
requests the name of a fully-qualified data set, the CLIST can obtain the
data set name as entered by the user, with single quotes preserved, by
using the READ statement with the &SYSDVAL control variable.
The following CLIST uses a READ statement and &SYSDVAL to preserve single
quotes around a data set name. It also checks for the quotes to see if
the user entered a fully-qualified data set name and, if not, adds the
quotes and the user's prefix to the name.
PROC 0
WRITE Enter the name of a data set.
READ
SET &DSN = &SYSDVAL /* Get name from &SYSDVAL. */
IF &SUBSTR(1:1,&DSN) ^= &STR(') THEN +
DO /* If not fully qualified, */
SET &DSN = '&SYSPREF..&DSN' /* add prefix and quotes. */
END
WRITE &DSN
You can also use the READ statement to obtain values for PROC statement
keywords that were not supplied on the invocation of the CLIST. For
example, suppose a PROC statement defines &ALPHA as a keyword with a
default null value. Assume &ALPHA contains the number of golf balls on
the moon and that the user does not assign a value to &ALPHA when invoking
the CLIST. However, a variable, &SPACEVENTS, in the CLIST results in code
being executed that requires a non-null value for &ALPHA. To obtain a
value for &ALPHA, the following code sends a message to the user
requesting a value for &ALPHA. Then, it issues a READ statement with
&ALPHA as a parameter.
PROC 0 ALPHA()
.
.
.
SET SPACEVENTS = &ALPHA
DO WHILE &SPACEVENTS = /* Null */
WRITE Enter the number of golf balls there
WRITE are on the moon. A null value is unacceptable.
READ ALPHA
SET SPACEVENTS = &ALPHA
END
If a user ends a line of READ input with a plus sign or hyphen, the READ
statement treats it as a continuation symbol and waits for another line of
input. For more information, see "Continuation Symbols" in topic 3.2.
Controlling Uppercase and Lowercase for READ Statement Input
To control uppercase and lowercase for READ statement input, use the
CAPS/ASIS/NOCAPS operand on the CONTROL statement, or the &SYSASIS control
variable, or the &SYSLC and &SYSCAPS built-in functions. The &SYSASIS
control variable and the CAPS/ASIS/NOCAPS operand indicate whether the
CLIST should translate all READ statement input to uppercase characters.
(The CLIST does not modify numbers, national characters, special
characters, or DBCS characters in such input.)
If you want the CLIST to translate all input obtained by READ statements
to uppercase characters, you can use the default value (CAPS) or code:
CONTROL CAPS
or
SET &SYSASIS = OFF

To request that the CLIST leave all input obtained by READ statements in
the format in which it was entered, code:
CONTROL ASIS
or
CONTROL NOCAPS
or
: SET &SYSASIS = ON
The CAPS/ASIS/NOCAPS operands affect output from WRITE statements the same
as they affect input from READ statements.
&SYSLC and &SYSCAPS enable you to tailor individual strings as well as

substrings of input strings.
For example, a CLIST that prompts for first, middle, and last names, might
want to guarantee that the name is properly capitalized before saving it.
The following section of code shows a way to do so:
CONTROL ASIS /* Do not translate READ input to uppercase */

WRITENR Enter first name:
READ FNAME
WRITENR Enter middle name:
READ MNAME
WRITENR Enter last name:
READ LNAME
/********************************************************************/
/* Set the lengths of the first, middle, and last names to */
/* variables so that the substring notation is easier to read. */
/********************************************************************/
SET LGTHFNAME = &LENGTH(&FNAME)

SET LGTHMNAME = &LENGTH(&MNAME)
SET LGTHLNAME = &LENGTH(&LNAME)
/********************************************************************/
/* Capitalize the first letters in first, middle, and last names */
/* and make sure all other letters are in lowercase characters. */
/********************************************************************/
SET F = &SUBSTR(1,&SYSCAPS(&FNAME))&SUBSTR(2:&LGTHFNAME,&SYSLC(&FNAME))
SET M = &SUBSTR(1,&SYSCAPS(&MNAME))&SUBSTR(2:&LGTHMNAME,&SYSLC(&MNAME))
SET L = &SUBSTR(1,&SYSCAPS(&LNAME))&SUBSTR(2:&LGTHLNAME,&SYSLC(&LNAME))
SET NAME = &STR(&F &M &L)
If the input entered is CADman haVVy fisH, &NAME contains the string
"Cadman Havvy Fish".
Using the READDVAL Statement
The READDVAL statement accesses the contents of the &SYSDVAL control

variable. &SYSDVAL contains one of three types of information:
* Information obtained by a READ statement without operands
* The non-delimiter data on the line returning control to the CLIST

after a TERMIN statement, as described in "Passing Control to the
Terminal" in topic 8.4
* Information that the CLIST explicitly placed into &SYSDVAL with an

assignment statement.
The CLIST successively places each input string in &SYSDVAL into each
variable on the READDVAL statement.
Assume for the remainder of this topic that the following strings are in
&SYSDVAL:
SMITH JONES KELLY
The following statement assigns the strings to symbolic variables:
READDVAL NAME1,NAME2,NAME3
Note that variables on the READDVAL statement do not require ampersands.
The preceding READDVAL statement produces the following results:
&NAME1 has the value SMITH.

&NAME2 has the value JONES.
&NAME3 has the value KELLY.
Note: The variables &NAME1, &NAME2, and &NAME3 can be set to different
values during the execution of a CLIST. However, if the contents of
&SYSDVAL is not modified and READDVAL is executed again, those variables
are reset to the current value of SYSDVAL.
The following statement also reads all three strings from &SYSDVAL:
READDVAL NAME1,NAME2,NAME3,NAME4
The value of &NAME4 is null because there are not enough input strings in
&SYSDVAL to provide a fourth value.
The following statement, however, assigns values only to the variables

NAME1 and NAME2:
READDVAL NAME1,NAME2
Because there are only two variables on READDVAL to which the CLIST can
assign the input strings in &SYSDVAL, the CLIST ignores the excess
strings. In the previous example, the CLIST ignores KELLY.
8.4 Passing Control to the Terminal
: Two CLIST statements are available for transferring control to the

: terminal and establishing a means for the user to return control to the
: CLIST:
: 1. TERMIN transfers control to the terminal and establishes a means for

: the user to return control to the CLIST. A CLIST executed from the
: TERMIN is considered to be not nested within the CLIST that issued the
: TERMIN statement, and global variables sharing between the two CLISTs
: is not allowed.
: 2. TERMING transfers control to the terminal and establishes a means for

: the user to return control to the CLIST. A CLIST executed from the
: TERMING is considered to be nested within the CLIST that issued the
: TERMING statement, and global variables sharing between the two CLISTs
: is allowed.
: Other differences in how TERMIN and TERMING transfer control are listed in
: Figure 8-1.
]------------------------------------------------------------------------]
: ] Figure 8-1. TERMIN and TERMING Statement Comparison ]
]----------------------------------------------------]---------]---------]
: ] Characteristic ] TERMIN ] TERMING ]
]----------------------------------------------------]---------]---------]
: ] Share GLOBAL variables across the TERMIN(G) ] No ] Yes ]
: ] element ] ] ]
]----------------------------------------------------]---------]---------]
: ] Variable access across the TERMIN(G) element ] No ] Yes ]
: ] through CLIST access routine IKJCT441 ] ] ]
]----------------------------------------------------]---------]---------]
: ] Checking Command Output Trapping - IKJCT441 and ] No ] Yes ]
: ] IRXEXCOM recognize CLIST and REXX execs on ] ] ]
: ] opposing sides of a TERMIN(G) element ] ] ]
]----------------------------------------------------]---------]---------]
: ] CONTROL NOMSG statement - allow checking the NOMSG ] No ] Yes ]
: ] setting on opposing sides of a TERMIN(G) element ] ] ]
]----------------------------------------------------]---------]---------]
: Because the TERMIN and TERMING elements are CLIST-generated type elements
: which cannot be added to the input stack through the external STACK
: service routine, they are considered to be of the same type. If the
: topmost stack element is a TERMIN or TERMING element, return code 60
: (X'3C') is returned. For more information see "TERMIN and TERMING
: Statement" in topic 13.27.
: Note: If you issue a CLIST containing a TERMIN or TERMING statement,

: under either ISPF or a REXX exec, or in the TSO/E background, the TERMIN
: or TERMING statement ends the CLIST. For CLISTs issued in the TSO/E
: background, TSO/E also issues message IKJ56550I to indicate that the
: TERMIN or TERMING statement is not supported for background processing.
: The TERMIN or TERMING statement either defines character strings, one of

which the user must enter to return control to the CLIST; or null lines,
where the user must press the ENTER key to return control to the CLIST.
: The TERMIN or TERMING statement normally does not function alone. WRITE
: statements preceding the TERMIN or TERMING statement inform the user why
control is being transferred to the terminal and how to return control to
the CLIST.
: Unlike the READ statement, TERMIN or TERMING enables the user to enter
commands or subcommands, and invoke programs before responding to the
WRITE statement prompts.
: As soon as the CLIST issues the TERMIN or TERMING statement, the user
receives control at the terminal. The user might receive a mode message
: after the TERMIN or TERMING statement is issued. If issued, the mode
message might be READY or the name of the command under which the CLIST
was invoked. (When READY is displayed, users might think the CLIST has
terminated. You may want to avoid any confusion by telling them otherwise
: in the WRITE statement that precedes the TERMIN or TERMING statement.)
Returning Control After a TERMIN or TERMING Statement
: To return control to the CLIST after a TERMIN or TERMING statement, code

: the TERMIN or TERMING statement and define one or more character strings
that return control to the CLIST. For example:
TERMIN IGNORE,PROCESS,TERMINATE
The user then enters IGNORE, PROCESS, or TERMINATE to return control to

the CLIST. The &SYSDLM control variable identifies the position of the
string used. For example, if the user enters TERMINATE to return control,
&SYSDLM contains a 3 because TERMINATE is the third variable on the TERMIN
: or TERMING statement. Multiple strings enable the user to indicate
desired actions to the CLIST.
You can allow a null line as one of the valid strings but it must be the
: first string on the TERMIN or TERMING statement. To do so, place a comma
directly before the first character string as follows:
TERMIN ,PROCESS,TERMINATE
The previous statement enables the user to return control by entering one
of the following:
* Null line (pressing the ENTER key)

* PROCESS
* TERMINATE.
: You can issue a TERMIN or TERMING statement that lets the user return
control by entering a null line (pressing the ENTER key). To do so, code:
TERMIN
Exercise care in using a null line as the means for a user to return
control to the CLIST, because some TSO/E command processors use null lines
as function delimiters (for example, to switch between input and edit
modes under EDIT).
Entering Input After a TERMIN or TERMING Statement
The user can optionally enter input when returning control by appending
the input to the string that returns control. The CLIST stores the input
in the &SYSDVAL control variable, which the CLIST can then access by
executing a READDVAL statement. The READDVAL statement changes the input
to upper case, unless you code CONTROL ASIS in the CLIST.
Suppose a WRITE statement prompts the user to inform the CLIST, when
: returning control after a TERMIN or TERMING statement, if any data sets
should be deleted. The user affirms the request by entering the
following:
PROCESS JCL.CNTL(BUDGT) ACCOUNT.DATA
The following CLIST deletes the data sets in the previous statement:
WRITE Check your catalog and enter the names of

WRITE up to two data sets you want deleted.
WRITE They must be separated by a comma or blank and
WRITE the first name must be preceded by the word PROCESS
WRITE and a blank. If you do not want to delete any data
WRITE sets, type in the word IGNORE. If you want to end
WRITE the CLIST, type in TERMINATE.
TERMIN IGNORE,PROCESS,TERMINATE
/* Read the two data set names (if any) in &SYSDVAL into
/* variables called &DSN1 and &DSN2
READDVAL DSN1 DSN2
/* If the user wants to delete data sets (PROCESS),
/* delete them
DO
IF &DSN1^= THEN +
delete &DSN1
IF &DSN2^= THEN +
delete &DSN2
END
/* If the user wants the CLIST to ignore the deletion request
/* but continue processing, execute the rest of CLIST. The
/* null ELSE path covers the request to terminate immediately.
DO
(Rest of CLIST)
END
8.5 Using ISPF Panels
A CLIST can communicate with terminal users by displaying panels of the

Interactive System Productivity Facility (ISPF). ISPF panels allow users
to make selections and enter data; the selections and entries are then
available for the CLIST to use. ISPF panels can also invoke CLISTs based
on user input. With ISPF, CLISTs can conduct extensive panel-driven
dialogs with users.
CLISTs use the ISPEXEC command to display ISPF panels. For complete
information about using the ISPEXEC command and its operands, see ISPF
Dialog Management Guide and ISPF Dialog Management Services and Examples.
ISPF Restrictions
The names of variables used on ISPF panels can be no longer than eight
characters.
Sample CLIST with ISPF Panels
For an example of displaying ISPF panels from a CLIST, see "Writing

Full-Screen Applications Using ISPF Dialogs - The PROFILE CLIST" in
topic 12.15. The PROFILE CLIST displays any of four panels, based on
input passed at invocation. On two of the panels, user input (pressing
the ENTER or END PF key) causes the CLIST to display another panel or end
the session.
The panels for the PROFILE CLIST are illustrated in their ISPF
panel-definition form. Instructions for allocating the panels are
included.
9.0 Topic 9. Performing File I/O
CLISTs can perform I/O to a physical sequential data set, a member of a

partitioned data set (PDS), or the terminal when allocated to a file.
Four CLIST statements are available for opening, reading, writing, and
closing files:
* OPENFILE opens a previously allocated file for input, output, or

updating. You may have allocated the file using the TSO/E ALLOCATE
command or using step allocation (JCL statements in a logon
procedure).
] * GETFILE reads a record from a file opened in the same CLIST.
] * PUTFILE writes a record to a file opened in the same CLIST.
] * CLOSFILE closes a file opened in the same CLIST.
Whenever a CLIST performs I/O, include an error routine that can handle
end-of-file conditions and errors that may occur. "End-of-File
Processing" in topic 9.7 shows a CLIST with an error routine that handles
end-of-file conditions.
] Whenever CLISTs are nested, corresponding OPENFILE, GETFILE, PUTFILE, and

] CLOSFILE statements must be in the same CLIST.
9.1 Characters Supported in I/O
CLIST I/O statements can process all data characters represented by

hexadecimal codes 40 through FF. See "Characters Supported in CLISTs" in
topic 3.2 for more information and warnings for doing I/O from data sets
containing special characters.
9.2 Opening a File
The OPENFILE statement has the following syntax:
OPENFILE filename {INPUT } /* to read records from the file

{OUTPUT} /* to write records to the file
{UPDATE} /* to update records in the file
To open a data set for I/O, you must allocate the data set to a file name,
: then use that file name on the OPENFILE statement. In order to preserve
: data integrity, once the file is opened for I/O, CLIST performs only one
: level of substitution against the file name variable. That is, after the
: file name is substituted with a file record, and to ensure the file record
: can be saved in its original format, CLIST does not re-scan the record.
To allocate the data set to a file name, use the ALLOCATE command with the
FILE keyword. The file name is an arbitrary value; you can create it on
the allocation.
For example, you can code the following:
.
.
.
allocate file(paycheks) da('d58tan1.checks.data') shr
OPENFILE PAYCHEKS
.
.
.
You can also code the file name as a symbolic variable as follows:
.
.
.
SET FILEID= PAYCHEKS
.
.
.
allocate file(&FILEID) da('d58tan1.checks.data') shr
OPENFILE &FILEID
.
.
.
You can open a member of a PDS after allocating the member to a file name,
for example:
allocate file(income) da('d58tan1.receipts(july)') shr

OPENFILE INCOME
However, do not use OPENFILE statements to open more than one member of a
PDS for output at the same time.
9.3 Closing a File
To close an open file, use a CLOSFILE statement that includes the same
file name as that specified on the corresponding OPENFILE statement. For
example, if you opened a file by coding:
OPENFILE &FILEID
close that file by coding:
CLOSFILE &FILEID
If you do not close an open file before the CLIST terminates, you may not
be able to process that file again until you logoff and logon again.
For examples of CLOSFILE, see the examples in "Reading a Record from a

File" in topic 9.4 and "Writing a Record to a File" in topic 9.5
9.4 Reading a Record from a File
To read a record from an open file, use a GETFILE statement. The CLIST
creates a variable of the same name as the file name and places the record
into it. As long as the file remains open, successive GETFILE statements
read successive records from the file. When the end of the file has been
reached, &LASTCC contains the error code 400. For information about how
to detect and handle end-of-file conditions, see "End-of-File Processing"
in topic 9.7.
Assume a data set called D58TAN1.CHECKS.DATA contains the following

records:
200BLACKBUY
449REFY
450YARRUM
To read the records into three variables, you could code the following:
.
.
.
(error routine)
.
.
.
allocate file(paycheks) da('d58tan1.checks.data') shr reu
OPENFILE PAYCHEKS /* Defaults to INPUT */
SET COUNTER=1
DO WHILE &COUNTER ^> 3
GETFILE PAYCHEKS /* Read a record */
SET EMPLOYEE&COUNTER=&PAYCHEKS /* Store the record */
SET COUNTER=&COUNTER+1 /* Increase counter by one */
END
CLOSFILE PAYCHEKS /* Close the file */
If you use GETFILE to read data from the terminal, the data is translated
to uppercase, and the terminal user must end the data with a symbol that
the CLIST recognizes as an end-of-file.
9.5 Writing a Record to a File

To write a record to a file, do the following:
1. Open the file for output (OPENFILE filename OUTPUT).
2. Set a variable of the same name as the file name to the record you are
writing to the file.
3. Specify the file name on the PUTFILE statement to write the record to
the data set, for example:
OPENFILE PRICES OUTPUT /* open the file for output

SET PRICES = $2590.00 /* set variable to input record
PUTFILE PRICES /* put variable record into the file
Note: If you use a variable for the filename on a PUTFILE statement, use
a nested variable to contain the record, for example:
OPENFILE &FILEID OUTPUT /* open the file for output

SET &&FILEID = $2590.00 /* set variable to input record
PUTFILE &FILEID /* put variable record into the file
As long as the file remains open, successive PUTFILE statements write

successive records to the data set. For a data set with a disposition of
NEW, OLD, or SHR, if you close the file and then re-open it, a subsequent
PUTFILE statement overlays the first record in the data set. For a data
set with a disposition of MOD, if you close the file and then re-open it,
a subsequent PUTFILE statement adds a record to the end of the data set.
Assume a CLIST contains the following variables:
&EMPLOYEE1, which contains the value 'BLACKBUY: $200.00'.

&EMPLOYEE2, which contains the value 'REFY: $449.00'.
&EMPLOYEE3, which contains the value 'YARRUM: $450.00'.
To place the previous values in a data set called D58TAN1.CURNTSAL.DATA,

you could code the following:
allocate file(salaries) da('d58tan1.curntsal.data') shr reu

OPENFILE SALARIES OUTPUT /* Open the file for output */
SET COUNTER=1
DO WHILE &COUNTER ^> 3
SET EMPLOYEE=&&EMPLOYEE&COUNTER
SET SALARIES=&EMPLOYEE /* Set the record to be written */
PUTFILE SALARIES /* Write the record */
SET COUNTER=&COUNTER+1 /* Increase counter by one */
END
CLOSFILE SALARIES /* Close the file */
9.6 Updating a File
To update a record in an open file, use the GETFILE and PUTFILE

statements. After opening a file for updating (OPENFILE filename UPDATE),
perform successive GETFILE statements until the desired record is read.
After assigning the new value to a variable of the same name as the file
name, perform a PUTFILE statement to update the record.
As long as the file remains open, you may update records.
Assume a data set called D58TAN1.CHECKS.DATA has a variable-blocked record

format and contains the following records:
200BLACKBUY
449REFY
450YARRUM
To update the record for REFY, you can code the following:
.
.
.
(error routine)
.
.
.
allocate file(paycheks) da('d58tan1.checks.data') shr reu
OPENFILE PAYCHEKS UPDATE /* Open file for updating */
GETFILE PAYCHEKS /* Read first record */
DO WHILE &SUBSTR(4:7,&PAYCHEKS)^=REFY
GETFILE PAYCHEKS /* Read another record */
END
SET PAYCHEKS = 000REFY /* Set new value */
PUTFILE PAYCHEKS /* Write new value to data set */
9.7 End-of-File Processing
Whenever a CLIST performs I/O, include code that handles end-of-file

conditions. In a CLIST, end-of-file causes an error condition (error code
400). To process this condition, provide an error routine before the code
that performs the I/O.
An error routine is a block of code that gets control when an error occurs
in a CLIST. The error routine can try to identify the error (such as
error code 400) and take appropriate action. For a complete description
of how to write an error routine, see Topic 10, "Writing ATTN and ERROR
Routines".
The following error routine saves the value of &LASTCC, closes and frees
the open file, and branches to a statement that determines whether
end-of-file was reached.
SET RCODE=0 /* Initialize the return code variable to 0 */

SET EOF=OFF /* Set the end-of-file indicator off */
.
.
.
ERROR +
DO
SET RCODE = &LASTCC /* Save the value of &LASTCC */
IF &RCODE=400 THEN +
DO
CLOSFILE PAYCHEKS /* Close the open file
free f(paycheks) /* Free the open file
WRITE No record to update because end-of-file was reached.
SET EOF=ON
RETURN /* Branch to statement that tests for
END /* EOF (IF &EOF=ON THEN...)
ELSE EXIT /* For other errors, EXIT
END
allocate file(paycheks) da('d58tan.checks.data') shr reu /* Allocate
/* file */
/* and establish file name of paycheks */
OPENFILE PAYCHEKS UPDATE /* Open file for updating */
SET COUNTER=1 /* Initialize counter to 1 */
DO WHILE &COUNTER <= 4
GETFILE PAYCHEKS /* Skip records */
SET COUNTER= &COUNTER+1 /* Increase counter by 1 */
/* If EOF reached, end loop. Null else */
IF &EOF=ON THEN GOTO OUT
END
SET PAYCHEKS = 480BUZZBEE /* Set variable to new value */
PUTFILE PAYCHEKS /* Update fourth record */
.
.
.
(rest of CLIST)
.
.
.
OUT: END
9.8 : Special Considerations for Performing I/O
: * MOD operand
: When allocating the data set you can use the MOD operand. It allows
: you to append data to the end of a sequential data set. For more
: information on the MOD operand see TSO/E V2 Command Reference,
: SC28-1881, and TSO/E V2 REXX/MVS User's Guide, SC28-1882.
: * Records Containing JCL Statements
: If a CLIST reads or writes records containing JCL statements, that

: CLIST could make unwanted modifications to the statements by symbolic
: substitution. To prevent the unwanted modifications, use the &NRSTR
: or &SYSNSUB built-in functions. See Topic 6, "Using Built-in
: Functions" for details and examples.
: * Concatenated Data Sets
: You can perform I/O on multiple data sets that are allocated
: (concatenated) to a single file name. However, the first data set in
: the concatenation must not be empty: if a GETFILE statement is issued
: and the first data set in the concatenation is empty, all other data
: sets allocated to the file are ignored, and no records are read.
10.0 Topic 10. Writing ATTN and ERROR Routines
Two types of events cause the execution of a CLIST to halt prematurely:

attention interrupts and errors. The CLIST language provides two
statements that enable you to code routines to handle attention interrupts
and errors. They are ATTN and ERROR, respectively. The ATTN statement is
described in "Writing Attention Routines" in topic 10.1. The ERROR
statement is described in "Writing Error Routines" in topic 10.2.
An attention interrupt occurs when the user presses the attention key
(usually PA1 or ATTN) on the terminal keyboard. The user may enter an
attention interrupt for any number of reasons, such as to terminate an
: infinite loop or simply to end the CLIST. The user cannot enter an
: attention interrupt when a CLIST error routine is in execution as a result
: of a CLIST-invoked command processor abend or before a TSO/E command is
: executed within the CLIST. Any attention interruption received while a
: command abend is in progress is ignored.
An error can occur for any number of reasons, such as a numeric value that
exceeds 2(31)-1, an end-of-file condition, or a non-zero return code from
a TSO/E command.
10.1 Writing Attention Routines
Use the ATTN statement to identify an action to be taken when the user
enters an attention interrupt. The action can be any executable statement
and is often a DO-sequence that performs operations tailored to the CLIST.
You can structure an ATTN action as follows:
ATTN +
DO
.
.
.
(action)
.
.
.
END
The ATTN statement and its action must precede the code to which it
applies. Multiple CLIST statements may be executed in the action but only
one TSO/E command, TSO/E subcommand, or null line may be executed. (A
null line returns control to the statement or command that was executing
when the attention interrupt occurred.) If the one TSO/E command executed
is an invocation of an attention handling CLIST, you may execute as many
TSO/E commands or subcommands as you wish in the attention handling CLIST.
If an attention action does not execute a TSO/E command, subcommand, or

null line, the action must include an EXIT or RETURN statement. The EXIT
statement ends the CLIST, and the RETURN statement returns control to the
CLIST statement, command, or subcommand following the one that was
executing when the user entered the attention interrupt.
You should inform the user at the beginning of the attention routine that
TSO/E is processing the attention interrupt. Otherwise, the user may
enter another attention interrupt. For a description of how TSO/E
processes multiple attention interrupts, see TSO/E V2 Programming
Services, SC28-1875.
Cancelling Attention Routines
You can cancel an attention routine at any point, letting the CLIST
continue without any special attention processing. To cancel an attention
routine, code:
ATTN OFF
This entry nullifies the most recently established attention routine.

ATTN OFF should not be used within an attention routine itself.
You can also code attention routines that override previous ones. Each
attention routine overrides all previous ones. You can initialize new
attention routines as many times as you wish.
Protecting the Input Stack from Attention Interrupts

commands, CLIST statements).
If you write an attention routine that does not terminate the CLIST,
protect the input stack from being erased (flushed) from storage when an
attention interrupt occurs. You can protect the input stack by coding a
CONTROL statement with the MAIN operand. The MAIN operand indicates that
the CLIST is the main CLIST in the invoker's TSO/E environment and
prevents TSO/E from flushing the input stack in the event of an attention
interrupt.
Attention routine processing depends on whether or not CONTROL MAIN has

been coded, and whether the routine executes a TSO/E command, RETURN
statement, or null line.
* If CONTROL MAIN has not been coded, the CLIST terminates and the user
sees the READY message, indicating that control has returned to the
terminal.
* If CONTROL MAIN has been coded, and a null line executes in the
attention routine, the CLIST continues at the statement or command
that was executing when the user entered the attention interrupt.
* If CONTROL MAIN has been coded, and a TSO/E command or RETURN

statement is issued, the CLIST continues at the statement or command
following the one that was executing when the user entered the
attention interrupt.
: Also refer to TSO/E V2 User's Guide, SC28-1880, for a further explanation

: of attention interrupt processing.
Sample CLIST with an Attention Routine
The ALLOCATE CLIST shown in Figure 10-1 contains an attention routine that
prompts the user to indicate whether he or she wants to end the CLIST.
If the user types YES to end the CLIST, and data sets have been allocated,
the attention routine invokes a CLIST called HOUSKPNG (see Figure 10-2),
which frees the allocated data sets. Then the attention routine ends the
ALLOCATE CLIST.
If the user does not type YES to end the ALLOCATE CLIST, the attention
routine issues CONTROL MAIN and a null line to return control to the point
where the attention interrupt occurred.
Note that the attention routine in Figure 10-1 issues only one TSO/E
command: %houskpng or the null line. However, the HOUSKPNG CLIST itself
issues up to three commands, depending on how many data sets it has to
free.
--------------------------------------------------------------------------
/*****************************************************************/
/* THE ALLOCATE CLIST ALLOCATES THREE DATA SETS REQUIRED FOR */
/* A PROGRAM. IT IS EQUIPPED TO HANDLE ATTENTION INTERRUPTS */
/* ENTERED AT ANY POINT. WHEN NECESSARY, IT INVOKES HOUSKPNG. */
/*****************************************************************/
PROC 2 &DS1 &DS2

CONTROL END(STOP) /* substitute "STOP" for END statement */
CONTROL PROMPT
ATTN +
DO
WRITE TSO is processing your attention
WRITENR Do you want to end? If so, type YES ====>
READ &END
IF &END = YES THEN +
/* If user wants to end, terminate the CLIST after the HOUSKPNG routine */
+
/* frees any data sets allocated by the CLIST. */
DO
CONTROL FLUSH /* flush the input stack after HOUSKPNG */
STOP
ELSE +
CONTROL MAIN /* return control to the CLIST */
IF &FOOTPRINT = YES AND &END = YES THEN +
%houskpng &ds1 &ds2 &cleanup /* call HOUSKPNG to free data sets */
ELSE +
DO
SET &NULL =
&NULL /* issue null line to continue at the */
/* point where the attention occurred. */
STOP
STOP
alloc f(input) da(&ds1..text) shr reu
SET FOOTPRINT = YES
SET CLEANUP=1
alloc f(output) da(&ds2..text) reu
SET CLEANUP=2
alloc f(temp) da(temp.text)
SET CLEANUP=3
call 'myid.myprog.load(member)'
free f(temp) da(temp.text)
SET CLEANUP=2
free f(output) da(&ds2..text)
SET CLEANUP=1
free f(input) da(&ds1..text)
SET FOOTPRINT = /* Set FOOTPRINT back to null */
--------------------------------------------------------------------------
Figure 10-1. A CLIST Containing an Attention Routine - The ALLOCATE CLIST
--------------------------------------------------------------------------
/*****************************************************************/
/* THE HOUSKPNG CLIST IS INVOKED WHEN THE USER WANTS TO END THE */
/* ALLOCATE CLIST AFTER AN ATTENTION AND DATA SETS ARE ALREADY */
/* ALLOCATED. BASED ON THE VALUE OF THE VARIABLE CLEANUP, */
/* THE CLIST FREES FROM ONE TO THREE OF THE DATA SETS ALLOCATED */
/* IN THE ALLOCATE CLIST. */
/*****************************************************************/
PROC 3 &DS1 &DS2 &CLEANUP

CONTROL END(ENDO)
ATTN +
EXIT QUIT
IF &CLEANUP=1 THEN +
DO
ENDO
DO
free f(temp) da(temp.text)
ENDO
--------------------------------------------------------------------------
Figure 10-2. An Attention Handling CLIST - The HOUSKPNG CLIST
Subprocedures and Attention Routines

Attention routines can call CLIST subprocedures. TSO/E commands in called

subprocedures have the same effect as TSO/E commands in the attention
routine itself: when the first TSO/E command executes, attention
processing ends and control passes to the line in the CLIST following the
one that was executing when the attention interrupt occurred.
Subprocedures can contain attention routines. However, attention routines

in subprocedures cannot contain nested attention or error routines.
CLIST Attention Facility
The CLIST attention facility (in TSO/E) and the CLSTATTN parameter of the
STAX macro provide greater flexibility in the handling of attention
interruptions. The CLSTATTN parameter of the STAX macro lets a program
establish an attention routine that receives control when an attention
interruption occurs during the processing of a CLIST that contains an
attention routine. The program's attention routine can invoke the CLIST
attention facility to process the CLIST attention routine.
Previously, the terminal monitor program (TMP) handled attention

interruptions for CLISTs with attention routines. Now a program can
maintain control by having its own attention routine perform that
processing. For more information about using the CLIST attention facility
and the STAX macro, see TSO/E V2 Programming Services, SC28-1875.
10.2 Writing Error Routines
Use the ERROR statement to create an error routine. The error routine
defines an action to be taken when a CLIST receives a non-zero return code
from something other than a CLIST subprocedure. (Figure 11-4 lists the
CLIST error codes.) The action can be any executable statement and is
often a DO-group that performs operations tailored to the indicated error.
You can structure an ERROR action as follows:
ERROR +
DO
.
.
.
(action)
.
.
.
END
The ERROR statement and its action must precede the code to which it
applies. An action may contain TSO/E commands and subcommands, subject to
the mode in which the CLIST is executing when the error occurs. Unlike
attention routines, error routine actions can issue multiple TSO/E
commands or subcommands.
If an error routine action does not end the CLIST, it must include a
RETURN statement. The RETURN statement returns control to the CLIST
statement, TSO/E command, or TSO/E subcommand following the one that was
executing when the error occurred. Repeated errors which activate the
same error routine may cause the CLIST to terminate.
You may also code error routines that override previous ones. Each error
routine overrides all previous ones. You may initialize new error
routines as many times as you want.
Cancelling Error Routines

To cancel the most recently established error routine in a CLIST, code

either:
ERROR OFF
or
ERROR
following the error routine to be cancelled.
: When ERROR OFF is coded, processing continues as if an error routine had

: never been established. When a failure occurs, one of the following
: occurs depending on the type of failure:
: * If the failure was due to an ABEND or non-zero return code from a

: TSO/E command or subcommand, the CLIST continues execution with the
: next sequential instruction following the failing instruction.
: * If the failure was in a CLIST statement or in expression evaluation,

: the failing instruction and explanatory CLIST error messages are
: displayed, and the CLIST terminates.
: When ERROR is entered with no operands, the CLIST displays the command,
: subcommand, or statement on the CLIST that ended in error. No explanatory
: CLIST error messages are displayed. &LASTCC is reset to 0 and the CLIST
: continues with the next sequential statement or command.
Protecting the Input Stack from Errors

commands, CLIST statements).
If you write a CLIST that contains an error routine, protect the input
stack from being erased from storage (flushed) when an error occurs. You
can protect the input stack by coding a CONTROL statement that includes
the NOFLUSH or MAIN operand. The CONTROL statement must appear before any
error routine, preferably at the beginning of the CLIST.
Sample CLIST with an Error Routine
The COPYDATA CLIST, shown in Figure 10-3, contains an error routine that
handles:
* Pre-allocation errors
* End-of-file condition
* Allocation errors.
The CLIST allocates the data sets required to copy an existing data set
into an output data set. If the copy is successful, the CLIST cancels the
error routine by executing an ERROR statement with no operands and
continues.
Subprocedures and Error Routines
Error routines can call CLIST subprocedures, and subprocedures can issue
the RETURN statement to return control to the error routine. The error
routine itself must issue RETURN to return control to the statement after
the one in error. For example, the following error routine calls a
subprocedure:
ERROR +
DO
SET &ECODE = 8
SELECT
WHEN (&FOOTPRINT=2) SYSCALL ABC ECODE
.
.
.
END /* End of SELECT
RETURN /* return control to CLIST
END /* End of error routine
.
.
.
ABC: PROC 1 CODEPARM /* subroutine ABC
SYSREF &CODEPARM /* refer variable back to caller's &ECODE
free f(indata) /* free data sets
free f(outdata)
SET &CODEPARM = 12 /* set error code
RETURN /* return control to error routine
END /* end of subroutine ABC
Subprocedures can contain error routines. However, error routines in

subprocedures cannot contain nested attention or error routines.
--------------------------------------------------------------------------
/*****************************************************************/
/* THE COPYDATA CLIST COPIES RECORDS FROM A DATA SET INTO AN */
/* OUTPUT DATA SET. IT IS EQUIPPED TO HANDLE ERRORS CAUSED BY */
/* END-OF-FILE, ALLOCATION ERRORS, AND ERRORS CAUSED BY OTHER */
/* STATEMENTS AND COMMANDS IN THE CLIST. */
/*****************************************************************/
CONTROL NOFLUSH END(ENDO) /* Protect the stack from being flushed

/* so that when error is caused by end-of-file, CLIST can continue
ERROR +
DO
SET RCODE=&LASTCC /* Save return code
/* If end-of-file, branch to CLOSFILE statements
SELECT
WHEN (&RCODE=400) +
DO /* IF End-of-file is reached, */
SET EOFFLAG = YES /* Set flag and return to the */
RETURN /* I/O procedure. */
ENDO
/* If error occurred before allocation, set exit code to 4
WHEN (&FOOTPRINT=0) SET ECODE=4
/* If allocation of file OUTDS failed, free file INDATA and set
/* exit code to 8
WHEN (&FOOTPRINT=1) +
DO
free f(indata) da(text.data)
SET ECODE=8
ENDO
/* If the error was not caused by end-of-file or allocation error,
/* free both files and set exit code to 12. In this case, error was
/* caused by one of the file I/O statements
WHEN (&FOOTPRINT=2) +
DO
free f(indata) da(text.data)
free f(outds)
SET ECODE=12
ENDO
ENDO /* End of SELECT statement
EXIT CODE(&ECODE) /* For all errors except end-of-file condition,
/* exit the CLIST with the appropriate exit code
ENDO /* End of error routine
SET FOOTPRINT=0 /* Identify pre-allocation errors
.
.
.
SET FOOTPRINT=1 /* Identify allocation error for file INDATA
alloc f(indata) da(d15rbo1.text.data) shr reu /* Allocate input data set
SET FOOTPRINT=2 /* Identify allocation error for file OUTDS
alloc f(outds) sysout(a) /* Allocate output data set
OPENFILE INDATA /* Open input data set
OPENFILE OUTDS OUTPUT /* Open output data set
/* Copy records from input data set to output data set */
DO WHILE &EOFFLAG ^= YES /* Do the following until EOF is reached*/

GETFILE INDATA /* Read input record
IF &EOFFLAG ^= YES THEN +
DO
SET OUTDS=&INDATA /* Set output record to value of input record
PUTFILE OUTDS /* Write output record to output data set
ENDO
ENDO
EOF: CLOSFILE INDATA /* Close input data set
CLOSFILE OUTDS /* Close output data set
ERROR /* From this point on, display statement that causes error
/* along with any error messages
.
.
.
--------------------------------------------------------------------------
Figure 10-3. The COPYDATA CLIST
11.0 Topic 11. Testing and Debugging CLISTs
This topic describes how to test CLISTs using diagnostic procedures to

find and correct errors. The diagnostic procedures include:
* Using diagnostic options of the CONTROL statement to find errors in

CLIST statements and TSO/E commands
* Getting help for CLIST messages
* Finding and understanding CLIST error codes.
11.1 Using Diagnostic Options of the CONTROL Statement
The CONTROL statement lets you define processing options for a CLIST.
Some of the CONTROL statement options can help you diagnose CLIST errors.
These diagnostic options, LIST, CONLIST, SYMLIST, and MSG, cause a CLIST
to display its statements, commands, and any informational messages at the
terminal when you execute the CLIST. From the displayed information, you
can often find statements or commands that contain errors.
You can use the diagnostic options separately or together on the CONTROL
statement. To obtain the most complete diagnostic information, code the
options together (the order is not significant):
CONTROL LIST CONLIST SYMLIST MSG

You can place the CONTROL statement at the top of the CLIST or in any part
of the CLIST that you want to test or debug. Each CONTROL statement
overrides any previous CONTROL statements. To turn off the diagnostic
options, type:
CONTROL NOLIST NOCONLIST NOSYMLIST NOMSG
As an alternative to retyping the CONTROL statement when you want to

change options, you can use the control variables &SYSLIST, &SYSCONLIST,
&SYSSYMLIST, and &SYSMSG to test or change the current settings. For more
information about using these control variables, see "Setting Options of
the CLIST CONTROL Statement" in topic 5.7.
The diagnostic options have the following effects:
SYMLIST
The CLIST displays each TSO/E command, subcommand, or CLIST statement
at the terminal before scanning it for symbolic substitution.
LIST
The CLIST displays each TSO/E command or subcommand at the terminal
after symbolic substitution but before execution.
CONLIST
The CLIST displays each CLIST statement at the terminal after symbolic
substitution but before execution.
MSG
The CLIST displays informational messages at the terminal.
Note: SYMLIST and CONLIST do not display the GLOBAL or NGLOBAL

statements.
The CLIST in Figure 11-1 contains diagnostic options on the CONTROL

statement. When you execute the CLIST, the commands and statements appear
at the terminal as shown in Figure 11-2.
]----------------------------------------------------------------------------
------]
]
]
] CONTROL LIST CONLIST SYMLIST MSG
]
] SET INPUT = data.set.name
]
] SET DSN = &INPUT
]
] allocate file(a) dataset('myid.&dsn')
]
] free file(a)
]
]
]
]
]
Figure 11-1. Sample CLIST with Diagnostic CONTROL Options
]----------------------------------------------------------------------------
------]
]
]
]
]
] SET DSN = &INPUT
]
] SET DSN = data.set.name
]
]
] allocate file(a) dataset('myid.data.set.name')
]
] free file(a)
]
] free file(a)
]
]
]
]
]
Figure 11-2. Diagnostic Output from Sample CLIST
Notice that each statement and command appears twice at the terminal. The
first version is caused by CONTROL SYMLIST and shows the statement or
command as it appears in the CLIST. The second version shows the results
of symbolic substitution on the preceding line. If a line undergoes no
substitution (contains no variables), both versions are the same.
Messages in Diagnostic Output
The CLIST executes each statement or command after performing symbolic

substitution on it. Therefore, when you use the MSG option with LIST and
CONLIST, messages about execution errors appear at the terminal after the
line that caused the error.
For example, the CLIST in Figure 11-1 fails when the input data set is not
cataloged. When the input data set is not cataloged, the CLIST displays
the following information at the terminal, with messages after the
statement that failed to execute.
]----------------------------------------------------------------------------
------]
]
]
]
]
] SET DSN = &INPUT
]
] SET DSN = data.set.name
]
]
] allocate file(a) dataset('myid.data.set.name')
]
] IKJ56228I DATA SET MYID.DATA.SET.NAME NOT FOUND IN CATALOG
]
] OR CATALOG CANNOT BE ACCESSED
]
] IKJ56701I MISSING DATA SET NAME+
]
] IKJ56701I MISSING NAME OF DATA SET TO BE ALLOCATED
]
]
]
]
]
Figure 11-3. Error Messages in Diagnostic Output from Sample CLIST
The diagnostic output ends after the ALLOCATE command, when the CLIST
detects the error. Working backwards from the last line, you can find and
correct the source of the error (in this case, the value of &INPUT).
Note that the last line in Figure 11-3 is a continuation of the preceding
message line. When the CLIST is executed under ISPF, the continuation is
displayed as shown in Figure 11-3. Under line-mode TSO/E, you must type a
question mark (?) after the plus sign to see the continuation.
How to Make Diagnostic Output Optional in a CLIST
You can make the diagnostic output available as an option to anyone who
invokes your CLIST. To do so, code a keyword parameter such as DEBUG on
the PROC statement as follows:
PROC 0 DEBUG
IF &DEBUG=DEBUG THEN +
CONTROL LIST CONLIST SYMLIST MSG
The CONTROL options take effect when you invoke the CLIST with the DEBUG
parameter, for example (explicit invocation):
EX clistname 'DEBUG'
or, implicit invocation:
%clistname DEBUG
11.2 Getting Help for CLIST Messages
CLIST message numbers begin with the characters IKJ. For explanations of
CLIST messages, look up the message number in the IKJ section of TSO/E V2
Messages, GC28-1885. The message explanations include information about
the action, if any, you need to take to correct a problem.
11.3 Obtaining CLIST Error Codes
The CLIST control variable &LASTCC contains an error code from the last
TSO/E command or CLIST statement executed. After each command or
statement in a CLIST, you can retrieve the error code from &LASTCC, for
example, by coding
SET ECODE = &LASTCC
You can then write the error code to the terminal or use it as a basis for
further processing. For more information about using &LASTCC, see
"Getting Return Codes and Reason Codes" in topic 5.10.
Note: With the exception of the RETURN statement, CLIST statements and
TSO/E commands in error routines do not update the value of &LASTCC. If
you use &LASTCC in an error routine, &LASTCC contains the return code from
the command or statement that was executing when the error occurred.
Figure 11-4 lists and explains the error codes that CLIST statements
return in &LASTCC. Except as otherwise noted, the codes are in decimal
format.
]--------------------------------------------------------------------------]
] Figure 11-4. CLIST Statement Error Codes (Decimal) ]
]---------------]----------------------------------------------------------]
] Error Code ] Meaning ]
]---------------]----------------------------------------------------------]
] 16 ] Not enough virtual storage. Log on with more storage. ]
]---------------]----------------------------------------------------------]
] 300 ] User tried to update a control variable that can only be ]
] ] updated by the system. ]
]---------------]----------------------------------------------------------]
] 304 ] Invalid keyword found on EXIT statement. ]
]---------------]----------------------------------------------------------]
] 308 ] CODE keyword specified, but no code given on EXIT ]
] ] statement. ]
]---------------]----------------------------------------------------------]
] 312 ] Internal GLOBAL processing error. ]
]---------------]----------------------------------------------------------]
] 316 ] TERMIN delimiter has more than 256 characters. ]
]---------------]----------------------------------------------------------]
] 324 ] GETLINE error. ]
]---------------]----------------------------------------------------------]
] 328 ] More than 64 delimiters on TERMIN. ]
]---------------]----------------------------------------------------------]
] 332 ] Invalid file name syntax. ]
]---------------]----------------------------------------------------------]
] 336 ] File already open. ]
]---------------]----------------------------------------------------------]
] 340 ] Invalid OPEN type syntax. ]
]---------------]----------------------------------------------------------]
] 344 ] Undefined OPEN type. ]
]---------------]----------------------------------------------------------]
] 348 ] File specified did not open. (For example, the file ]
] ] name was not allocated.) Reallocate the file. ]
]---------------]----------------------------------------------------------]
] 352 ] GETFILE - file name is not currently open. ]
]---------------]----------------------------------------------------------]
] 356 ] GETFILE - the file has been closed by the system. (For ]
] ] example, the file was opened under EDIT mode and EDIT ]
] ] mode has been terminated.) ]
]---------------]----------------------------------------------------------]
] 360 ] PUTFILE - file name not currently open. ]
]---------------]----------------------------------------------------------]
] 364 ] PUTFILE - file closed by system (see code 356). ]
]---------------]----------------------------------------------------------]
] 368 ] PUTFILE - CLOSFILE - file not opened by OPENFILE. ]
]---------------]----------------------------------------------------------]
] 372 ] PUTFILE - issued before GETFILE on a file opened for ]
] ] update. ]
]---------------]----------------------------------------------------------]
] 376 ] Unable to open the directory of a PDS using a variable ]
] ] record format. ]
]---------------]----------------------------------------------------------]
] 380 ] Data sets with a logical record length greater than ]
] ] 32767 are not supported for CLIST I/O. ]
]---------------]----------------------------------------------------------]
] 400 ] GETFILE - end of file. TSO/E treats this condition as ]
] ] an error that can be handled by an ERROR action. ]
]---------------]----------------------------------------------------------]
] 404 ] User tried to write to a file open for INPUT. ]
]---------------]----------------------------------------------------------]
] 408 ] User tried to read from a file open for OUTPUT. ]
]---------------]----------------------------------------------------------]
] 412 ] User tried to update a file after end of file was ]
] ] reached. ]
]---------------]----------------------------------------------------------]
] 416 ] User tried to update an empty file. ]
]---------------]----------------------------------------------------------]
] 500 ] The TO value on a DO statement is non-numeric. ]
]---------------]----------------------------------------------------------]
] 502 ] The FROM value on a DO statement is non-numeric. ]
]---------------]----------------------------------------------------------]
] 504 ] The BY value on a DO statement is non-numeric. ]
]---------------]----------------------------------------------------------]
] 508 ] A SYSCALL statement contains an undefined procedure ]
] ] name. ]
]---------------]----------------------------------------------------------]
] 512 ] A RETURN statement contains an undefined keyword. ]
]---------------]----------------------------------------------------------]
] 516 ] The name of a procedure is used as a variable. ]
]---------------]----------------------------------------------------------]
] 524 ] Unable to establish an ESTAE routine. ]
]---------------]----------------------------------------------------------]
] 528 ] A positional specification on the PROC statement was ]
] ] invalid. ]
]---------------]----------------------------------------------------------]
] 532 ] Invalid characters were found in a symbolic parameter on ]
] ] the PROC statement. ]
]---------------]----------------------------------------------------------]
] 536 ] A symbolic parameter name on the PROC statement is too ]
] ] long. ]
]---------------]----------------------------------------------------------]
] 540 ] The number of positional parameters defined on the PROC ]
] ] statement is fewer than the number passed. ]
]---------------]----------------------------------------------------------]
] 544 ] No symbolic parameters were defined on the PROC ]
] ] statement. ]
]---------------]----------------------------------------------------------]
] 548 ] Duplicate parameter names were found on the PROC ]
] ] statement. ]
]---------------]----------------------------------------------------------]
] 552 ] A keyword parameter has an invalid default value. ]
]---------------]----------------------------------------------------------]
] 556 ] A default keyword value was missing an ending quote on ]
] ] the PROC statement. ]
]---------------]----------------------------------------------------------]
] 560 ] A PARSE error occurred while processing the PROC ]
] ] statement. ]
]---------------]----------------------------------------------------------]
] 568 ] Abnormal termination ]
]---------------]----------------------------------------------------------]
] 572 ] SYSREF variable was not passed as a parameter. ]
]---------------]----------------------------------------------------------]
] 576 ] SYSREF variable was not defined on a PROC statement. ]
]---------------]----------------------------------------------------------]
] 580 ] An ERROR statement was found within a subprocedure's ]
] ] ERROR or ATTN routine. ]
]---------------]----------------------------------------------------------]
] 584 ] An ATTN statement was found within a subprocedure's ]
] ] ERROR or ATTN routine. ]
]---------------]----------------------------------------------------------]
] 588 ] A character between DBCS delimiters was outside the ]
] ] range of double-byte characters. ]
]---------------]----------------------------------------------------------]
] 592 ] A DBCS string contains an odd number of bytes, ]
] ] indicating that one of the characters is incomplete. ]
]---------------]----------------------------------------------------------]
] 596 ] A beginning DBCS delimiter was found without a ]
] ] corresponding ending delimiter. ]
]---------------]----------------------------------------------------------]
] 600 ] Two beginning DBCS delimiters were found without an ]
] ] intervening ending delimiter. ]
]---------------]----------------------------------------------------------]
] 604 ] An error occurred while processing an ]
] ] installation-written CLIST built-in function in ]
] ] IKJCT44B. ]
]---------------]----------------------------------------------------------]
] 608 ] An error occurred while processing an ]
] ] installation-written CLIST statement in IKJCT44S. ]
]---------------]----------------------------------------------------------]
] 612 ] An error occurred in an installation exit. ]
]---------------]----------------------------------------------------------]
] 620 ] EBCDIC &SYSTWOBYTE data is outside valid DBCS range. ]
]---------------]----------------------------------------------------------]
] ] 624 ] An error occurred while processing a system variable ]
] ] ] (see note below). ]
]---------------]----------------------------------------------------------]
] 708 ] The preceding statement has an invalid &SYSINDEX ]
] ] expression. ]
]---------------]----------------------------------------------------------]
] 712 ] The preceding statement has an invalid &SYSINDEX start ]
] ] parameter; the start parameter must be a non-negative ]
] ] number. ]
]---------------]----------------------------------------------------------]
] 716 ] The preceding statement has an invalid &SYSNSUB level ]
] ] parameter; the level parameter must be a number from 0 ]
] ] to 99. ]
]---------------]----------------------------------------------------------]
] 720 ] The preceding statement has a missing &SYSNSUB level ]
] ] and/or expression parameter. ]
]---------------]----------------------------------------------------------]
] 724 ] The preceding statement has a &SYSNSUB level parameter ]
] ] that uses a built-in function as a symbolic variable. ]
]---------------]----------------------------------------------------------]
] 8xx ] Evaluation routine error codes. ]
]---------------]----------------------------------------------------------]
] 800 ] Data was found where operator was expected. ]
]---------------]----------------------------------------------------------]
] 804 ] An operator was found where data was expected. ]
]---------------]----------------------------------------------------------]
] 808 ] A comparison operator was used in a SET statement. ]
]---------------]----------------------------------------------------------]
] 812 ] (Reserved). ]
]---------------]----------------------------------------------------------]
] 816 ] An operator was found at the end of a statement. ]
]---------------]----------------------------------------------------------]
] 820 ] Operators are out of order; data may resemble operators. ]
]---------------]----------------------------------------------------------]
] 824 ] More than one exclusive operator was found. ]
]---------------]----------------------------------------------------------]
] 828 ] More than one exclusive comparison operator found. ]
]---------------]----------------------------------------------------------]
] 832 ] The result of an arithmetic calculation is outside the ]
] ] valid range, -2,147,483,647 to +2,147,483,647. ]
]---------------]----------------------------------------------------------]
] 836 ] (Reserved). ]
]---------------]----------------------------------------------------------]
] 840 ] Not enough operands. ]
]---------------]----------------------------------------------------------]
] 844 ] No valid operators. ]
]---------------]----------------------------------------------------------]
: ] 848 ] An attempt was made to load data as character data, but ]
: ] ] the data was numeric (an arithmetic operation had been ]
: ] ] performed on the data). ]
]---------------]----------------------------------------------------------]
] 852 ] Addition error - character data. ]
]---------------]----------------------------------------------------------]
] 856 ] Subtraction error - character data. ]
]---------------]----------------------------------------------------------]
] 860 ] Multiplication error - character data. ]
]---------------]----------------------------------------------------------]
] 864 ] Divide error - character data or division by 0. ]
]---------------]----------------------------------------------------------]
] 868 ] Prefix found on character data. ]
]---------------]----------------------------------------------------------]
] 872 ] Numeric value is too large. ]
]---------------]----------------------------------------------------------]
] 900 ] Single ampersand was found. ]
]---------------]----------------------------------------------------------]
] 904 ] (Reserved). ]
]---------------]----------------------------------------------------------]
] 908 ] An error occurred in an error action that received ]
] ] control because of another error. ]
]---------------]----------------------------------------------------------]
] 912 ] Substring range is invalid. ]
]---------------]----------------------------------------------------------]
] 916 ] A non-numeric value was found in a substring range. ]
]---------------]----------------------------------------------------------]
] 920 ] Substring range value too small (zero or negative). ]
]---------------]----------------------------------------------------------]
] 924 ] Substring syntax is invalid. ]
]---------------]----------------------------------------------------------]
] 932 ] Substring found outside of the range of the string. ]
] ] (For example, an &SUBSTR variable attempted to substring ]
] ] the first three positions of data that contains only two ]
] ] characters.) ]
]---------------]----------------------------------------------------------]
] 936 ] A built-in variable that requires a value was entered ]
] ] without a value. ]
]---------------]----------------------------------------------------------]
] 940 ] Invalid symbolic variable. ]
]---------------]----------------------------------------------------------]
] 944 ] A label was used as a symbolic variable. ]
]---------------]----------------------------------------------------------]
] 948 ] Invalid label syntax on a GOTO statement. ]
]---------------]----------------------------------------------------------]
] 952 ] A GOTO label was not defined. ]
]---------------]----------------------------------------------------------]
] 956 ] A GOTO statement has no label. ]
]---------------]----------------------------------------------------------]
] 960 ] &SYSSCAN was set to an invalid value. ]
]---------------]----------------------------------------------------------]
] 964 ] &LASTCC was set to an invalid value and EXIT tried to ]
] ] use it as a default value. ]
]---------------]----------------------------------------------------------]
] 968 ] DATA PROMPT-ENDDATA statements supplied, but no prompt ]
] ] occurred. ]
]---------------]----------------------------------------------------------]
] 972 ] TERMIN statement cannot be used in background jobs. ]
]---------------]----------------------------------------------------------]
] 976 ] READ statement cannot be used in background jobs. ]
]---------------]----------------------------------------------------------]
: ] 984 ] TERMING delimiter has more than 256 characters. ]
]---------------]----------------------------------------------------------]
: ] 988 ] TERMING has more than 64 delimiters. ]
]---------------]----------------------------------------------------------]
: ] 992 ] TERMING statement cannot be used in background jobs. ]
]---------------]----------------------------------------------------------]
] 980 ] Maximum statement length (32756) exceeded during ]
] ] symbolic substitution. ]
]---------------]----------------------------------------------------------]
] 999 ] Internal CLIST error. ]
]---------------]----------------------------------------------------------]
] Sxxx ] A system abend code, printed in hexadecimal. ]
]---------------]----------------------------------------------------------]
] Uxxx ] A user abend code, printed in hexadecimal. ]
]---------------]----------------------------------------------------------]
] ] Note: The underlaying error, which is summarized by error code 624, ]
] ] will always be shown by a more detailed error message; this message will ]
] ] not be suppressed when using an error routine. ]
]--------------------------------------------------------------------------]
12.0 Topic 12. Sample CLISTs
This topic contains examples of CLISTs that illustrate the CLIST functions
described in previous topics. The examples assume that the CLISTs reside
in a PDS allocated to SYSPROC.
Figure 12-1 lists the names of the CLISTs and provides short descriptions
of the functions they illustrate. Many of these CLISTs include examples
of symbolic variables, control variables, built-in functions, and
conditional sequences.
]------------------------------------------------------------------------]
] Figure 12-1. Sample CLISTs and Their Functions ]
]----------]-----------------------------------------------------]-------]
] CLIST ] Function ] Topic ]
]----------]-----------------------------------------------------]-------]
] LISTER ] Including TSO/E commands ] 12.1 ]
]----------]-----------------------------------------------------]-------]
] DELETEDS ] Simplifying routine tasks ] 12.2 ]
]----------]-----------------------------------------------------]-------]
] CALC ] Creating arithmetic expressions from user supplied ] 12.3 ]
] ] input ] ]
]----------]-----------------------------------------------------]-------]
] CALCFTND ] Performing front-end prompting ] 12.4 ]
]----------]-----------------------------------------------------]-------]
] SCRIPTDS ] Initializing and invoking system services ] 12.5 ]
]----------]-----------------------------------------------------]-------]
] SCRIPTN ] Invoking CLISTs to perform subtasks ] 12.6 ]
]----------]-----------------------------------------------------]-------]
] SUBMITDS ] Including JCL; performing front-end prompting ] 12.7 ]
]----------]-----------------------------------------------------]-------]
] SUBMITFQ ] Performing substringing; adding flexibility ] 12.8 ]
]----------]-----------------------------------------------------]-------]
] RUNPRICE ] Allowing foreground or background submittal of jobs ] 12.9 ]
]----------]-----------------------------------------------------]-------]
] TESTDYN ] Providing invoker with options and performing ] 12.10 ]
] ] initialization based on options specified ] ]
]----------]-----------------------------------------------------]-------]
] COMPRESS ] Simplifying routine, system-related tasks ] 12.11 ]
] ] ] ]
]----------]-----------------------------------------------------]-------]
] CASH ] Simplifying invoker's interface to complex ] 12.12 ]
] ] applications ] ]
]----------]-----------------------------------------------------]-------]
] PHONE ] Performing I/O; reading records into &SYSDVAL ] 12.13 ]
] ] ] ]
]----------]-----------------------------------------------------]-------]
] SPROC ] Using &SYSOUTTRAP and &SYSOUTLINE variables to ] 12.14 ]
] ] manage command output ] ]
]----------]-----------------------------------------------------]-------]
] PROFILE ] Using ISPF dialog management services in CLISTs to ] 12.15 ]
] ] create full-screen applications ] ]
]----------]-----------------------------------------------------]-------]
] EXPAND ] Using LISTDSI statement to allocate a new data set ] 12.16 ]
] ] with characteristics of an existing data set. ] ]
]----------]-----------------------------------------------------]-------]
12.1 Including TSO/E Commands - The LISTER CLIST

You can organize related activities so that users can simply invoke a
CLIST to perform a given task or group of tasks. The simplest example is
a CLIST that groups TSO/E commands together.
The LISTER CLIST consists of two TSO/E commands. (See Figure 12-2.) The
LISTCAT command lists all of the entries in the invoker's catalog. The
LISTALC command lists the names and status of all data sets allocated to
the invoker's user ID. TSO/E displays the output produced by these
commands in the same order as that in which it executes the commands. The
invoker does not have to enter a command, view its output, then enter
another command; all input required from the invoker is supplied at one
time.
--------------------------------------------------------------------------
listcat
listalc status
--------------------------------------------------------------------------
Figure 12-2. The LISTER CLIST
12.2 Simplifying Routine Tasks - The DELETEDS CLIST
One way to simplify routine tasks is to write CLISTs that make the process
as interactive as possible. For example, the syntax of the DELETE command
could confuse users who simply want to delete some of their data sets.
For those users, you could write a CLIST that simplifies the process. The
DELETEDS CLIST shown in Figure 12-3 is an example of such a CLIST. It
prompts the invoker for a data set name or a completion indicator.
--------------------------------------------------------------------------
/**********************************************************************/
/* THIS CLIST PROMPTS THE USER FOR THE NAMES OF THE DATA */
/* SETS TO BE DELETED, ONE AT A TIME. */
/**********************************************************************/
SET DONE=NO
DO WHILE &DONE=NO
WRITE Enter the name of the data set you want deleted.
WRITE Omit the identification qualifier (userid).
WRITE Do not put the name in quotes.
WRITE When you are finished deleting all data sets, type an 'f'.
READ DSN
IF &DSN = F THEN SET DONE=YES
ELSE delete &DSN
END
--------------------------------------------------------------------------
Figure 12-3. The DELETEDS CLIST
12.3 Creating Arithmetic Expressions from User-Supplied Input - The CALC CLIST
The CALC CLIST, shown in Figure 12-4, contains a PROC statement that
requires three input strings from the invoker:
* A numeric value
* An arithmetic operator
* Another numeric value.
The CLIST creates an arithmetic expression using the positional parameter

variables that represent these three values. A WRITE statement displays a
message made up of the unevaluated expression, an equal sign, and the
evaluated expression. CALC contains no validity-checking statements;
therefore, input that does not meet the above requirements causes the
&EVAL built-in function to fail and generate an error code.
--------------------------------------------------------------------------
PROC 3 FVALUE OPER LVALUE
/**********************************************************************/
/* DISPLAY THE ENTIRE EQUATION AT THE TERMINAL, INCLUDING THE RESULT */
/* OF THE EXPRESSION. */
/**********************************************************************/
WRITE &FVALUE&OPER&LVALUE = &EVAL(&FVALUE&OPER&LVALUE)
--------------------------------------------------------------------------
Figure 12-4. The CALC CLIST
12.4 Using Front-End Prompting - The CALCFTND CLIST
Front-end prompting verifies input data before the CLIST uses it in other
statements. For example, the CALC CLIST in Figure 12-4 in topic 12.3
assumed that &FVALUE and &LVALUE represented valid numeric values or
variables containing valid numeric values. It also assumed that &OPER
represented a valid arithmetic operator.
In CALCFTND, shown in Figure 12-5, the CLIST first ensures that &FVALUE is
numeric, not character data. The WRITE statement message is tailored to
address the possibility that the invoker is including decimal points in
the value. The CLIST views such a value as character data, not numeric
data. The DO-WHILE-END sequence executes until the invoker supplies a
valid numeric value. A similar DO-WHILE-END sequence is provided for
&LVALUE.
The verification of &OPER is somewhat more involved. &OPER must be a

valid arithmetic operator, one of the following symbols: +,-,*,/,**,//.
Therefore, the condition for the corresponding DO-WHILE-END sequence
requires a logical ANDing of comparative expressions. Each expression is
true when &OPER does not equal the operator in the expression. When all
of the expressions are true, &OPER is not a valid arithmetic operator. To
ensure that the CLIST views &OPER and the valid arithmetic operators as
character data, enclose them in &STR built-in functions.
--------------------------------------------------------------------------
PROC 0 FVALUE( ) OPER( ) LVALUE( )
/**********************************************************************/
/* IF &FVALUE IS INVALID, CONTINUE PROMPTING THE USER TO ENTER */
/* AN ACCEPTABLE VALUE. */
/**********************************************************************/
CONTROL ASIS /* Allow upper and lower case WRITE statements */
SET &NULL =
DO WHILE &DATATYPE(&FVALUE) ^= NUM
IF &STR(&FVALUE) = &NULL THEN +
WRITE Please enter a first value without decimal points &STR(-)
ELSE +
DO
WRITENR Your first value is not numeric. Reenter a number without
WRITE decimal points &STR(-)
END
READ &FVALUE
END
/**********************************************************************/
/* IF &OPER IS INVALID, CONTINUE PROMPTING THE USER TO ENTER */
/**********************************************************************/
DO WHILE &STR(&OPER)^=&STR(+) AND &STR(&OPER)^=&STR(-) AND +

&STR(&OPER)^=&STR(*) AND &STR(&OPER)^=&STR(/) AND +
&STR(&OPER)^=&STR(**) AND &STR(&OPER)^=&STR(//)
IF &STR(&OPER) = &NULL THEN +
DO
WRITE Please enter a valid arithmetic operator (+,-,*,/,**,//)
WRITE enclosed in parentheses, for example, (+) or (-).
END
ELSE +
DO
WRITE Your second value is not a valid operator (+,-,*,/,**,//).
WRITE Reenter this value, using one of the valid arithmetic
WRITE operators enclosed in parentheses, for example, (+) or (-).
END
READ &OPER
END
/**********************************************************************/
/* IF &LVALUE IS INVALID, CONTINUE PROMPTING THE USER TO ENTER */
/**********************************************************************/
DO WHILE &DATATYPE(&LVALUE) ^= NUM

IF &STR(&LVALUE) = &NULL THEN +
WRITE Please enter a second value without decimal points &STR(-)
ELSE +
DO
WRITENR Your last value is not numeric. Reenter a number without
WRITE decimal points &STR(-).
END
READ LVALUE
END
/**********************************************************************/
/* ONCE THE OPERANDS HAVE BEEN VERIFIED, EVALUATE THE EXPRESSION AND */
/* DISPLAY THE RESULT AT THE TERMINAL. */
/**********************************************************************/
WRITE &FVALUE&OPER&LVALUE = &EVAL(&FVALUE&OPER&LVALUE)
--------------------------------------------------------------------------
Figure 12-5. The CALCFTND CLIST
12.5 Initializing and Invoking System Services - The SCRIPTDS CLIST
The SCRIPTDS CLIST enables a user to run the SCRIPT program against an
input data set and have the output printed.
As shown in Figure 12-6, SCRIPTDS requires a positional parameter, &DSN.

The invoker supplies the name of a PDS member to be printed. The CLIST
includes the &DSN variable as the member name of the memo.text data set on
the invocation of the SCRIPT program. The invoker does not have to supply
input for &SYSPREF because it is a control variable whose value is
available to the CLIST. The inclusion of &SYSPREF as the identification
qualifier of the input data set frees the invoker from having to enter a
fully-qualified data set name. The CLIST also substitutes &SYSPREF and
&DSN on the allocation of the output data set so that its name corresponds
to the name of the input data set.
--------------------------------------------------------------------------
PROC 1 DSN LIST

/**********************************************************************/
/* THIS CLIST (SCRIPTDS) SETS UP THE ENVIRONMENT FOR SCRIPTING A */
/* DATA SET, ISSUES THE SCRIPT COMMAND, AND PRINTS THE OUTPUT. */
/**********************************************************************/
CONTROL NOFLUSH NOMSG
IF &LIST=LIST THEN +
CONTROL LIST
/**********************************************************************/
/* DELETE THE OUTPUT DATA SET INTO WHICH THE SCRIPTED FILE WILL BE */
/* PLACED IN CASE IT IS STILL ALLOCATED FROM A PREVIOUS INVOCATION */
/* OF SCRIPTDS. */
/**********************************************************************/
delete '&SYSPREF..&DSN..list'
/**********************************************************************/
/* DEFINE A FILE NAME (DDNAME) FOR THE OUTPUT DATA SET SO THAT THE */
/* SCRIPT PROGRAM CAN REFERENCE IT. FREE THE FILE BECAUSE SCRIPT WILL*/
/* ALSO ALLOCATE THE DATA SET. */
/**********************************************************************/
alloc f(a) da('&SYSPREF..&DSN..list') dsorg(ps) recfm(v,b,m) +
blk(3156) sp(10,10) tr new release reu
free f(a)
CONTROL LIST
/**********************************************************************/
/* ISSUE THE SCRIPT COMMAND, SPECIFYING THE NAME OF THE DATA SET */
/* MEMBER TO BE SCRIPTED: MEMO.TEXT(&DSN). */
/**********************************************************************/
script '&SYSPREF..memo.text(&DSN)' +
message(delay id trace) device(3800n6) twopass +
profile('script.r3.maclib(ssprof)') +
lib('script.r3.maclib') +
sysvar(c 1 d yes) +
bind(8 8) chars(gt12 gb12) file('&SYSPREF..&DSN..list') continue
/**********************************************************************/
/* FREE THE FILES REQUIRED TO PRINT THE SCRIPTED DATA SET. */
/* THEN ALLOCATE THEM, REQUESTING TWO COPIES ON THE 3800 PRINTER. */
/**********************************************************************/
SET RC=&LASTCC /* Get SCRIPT return code */

IF RC<=4 THEN +
DO
CONTROL NOMSG
CONTROL MSG
alloc f(sysprint) dummy reuse
alloc f(sysut1) da('&SYSPREF..&DSN..list') shr reuse
alloc f(sysut2) sysout(n) fcb(std4) chars(gt12,gb12) +
copies(2) optcd(j) reuse
alloc f(sysin) dummy reuse
/**********************************************************************/
/* INVOKE THE UTILITY TO HAVE THE DATA SET PRINTED AND FREE THE */
/* FILES. */
/**********************************************************************/
call 'sys1.linklib(iebgener)'
free f(sysut1,sysut2,sysprint,sysin)
END
--------------------------------------------------------------------------
Figure 12-6. The SCRIPTDS CLIST
12.6 Invoking CLISTs to Perform Subtasks - The SCRIPTN CLIST
While you can write CLISTs that perform application tasks directly, you
can also write CLISTs that subdivide application tasks among nested CLISTs
and control their execution. For example, you can write a CLIST that
invokes two other CLISTs to perform the same tasks as those performed by
SCRIPTDS in Figure 12-6 in topic 12.5.
SCRIPTN, shown in Figure 12-7, produces the same results as SCRIPTDS. The
invoker provides a data set name qualifier as done for SCRIPTDS. SCRIPTN
defines &DSNAM as a global variable because SCRIPTN invokes two CLISTs
that refer to the variable. SCRIPTN invokes a CLIST called SCRIPTD, which
includes the &DSNAM variable as the member name of the memo.text data set
on the invocation of the SCRIPT command (See Figure 12-8). When finished
with these tasks, SCRIPTD returns control to SCRIPTN and execution
continues at the command following the invocation of SCRIPTD. This
command is the invocation of a CLIST called OUTPUT (See Figure 12-9).
OUTPUT performs the required allocations to invoke the IEBGENER utility to
print the output data set.
--------------------------------------------------------------------------
PROC 1 DSN
GLOBAL DSNAM
SET DSNAM=&DSN
IF &LENGTH(&DSN) LE 8 AND /* ENSURE VALID NAME AND */ +
&DATATYPE(&SUBSTR(1,&DSN))=CHAR THEN /* VALID FIRST CHARACTER */ +
DO
/**********************************************************************/
/* INVOKE THE SCRIPTD CLIST TO SET UP THE ENVIRONMENT REQUIRED TO */
/* SCRIPT THE INPUT DATA SET AND THEN EXECUTE THE SCRIPT COMMAND. */
/**********************************************************************/
%scriptd
/**********************************************************************/
/* INVOKE THE OUTPUT CLIST TO PRINT 2 COPIES OF THE SCRIPTED */

/* DATA SET ON THE 3800 PRINTER. */
/**********************************************************************/
IF &LASTCC<=4 THEN /* Test return code from SCRIPTD */ +

DO
%output
END
ELSE WRITE SCRIPTD FAILED
END
ELSE +
WRITE The name entered must be less than 9 characters long and +
the first character must not be numeric.
--------------------------------------------------------------------------
Figure 12-7. The SCRIPTN CLIST
--------------------------------------------------------------------------
GLOBAL DSNAM
/**********************************************************************/
/* THIS CLIST (SCRIPTD) SETS UP THE ENVIRONMENT FOR SCRIPTING A */
/* DATA SET PROVIDED BY THE USER AND ISSUES THE SCRIPT COMMAND. */
/**********************************************************************/
CONTROL NOFLUSH NOMSG

ERROR +
DO /* If an error occurs,
SET RC=&LASTCC /* get return code
EXIT CODE(&RC)/* and pass control back to SCRIPTN
END
/**********************************************************************/
/* DELETE THE OUTPUT DATA SET INTO WHICH THE SCRIPTED FILE WILL BE */
/* PLACED IN CASE IT IS STILL ALLOCATED FROM A PREVIOUS INVOCATION */
/* OF SCRIPTN. */
/**********************************************************************/
delete '&SYSPREF..&DSNAM..list'
/**********************************************************************/
/* DEFINE THE OUTPUT DATA SET SO THAT THE SCRIPT PROGRAM CAN REFERENCE*/
/* IT. FREE THE FILE BECAUSE SCRIPT WILL ALSO ALLOCATE THE DATA SET */
/**********************************************************************/
alloc f(a) da('&SYSPREF..&DSNAM..list') dsorg(ps) recfm(v,b,m) +

blk(3156) sp(50,30) tr new release reu
free f(a)
CONTROL LIST
/**********************************************************************/
/* ISSUE THE SCRIPT COMMAND, SPECIFYING THE NAME OF THE DATA SET */
/* MEMBER TO BE SCRIPTED: MEMO.TEXT(&DSNAM). */
/* THEN RETURN CONTROL TO SCRIPTN. */
/**********************************************************************/
script '&SYSPREF..memo.text(&DSNAM)' +
message(delay id trace) device(3800n6) twopass +
profile('script.r3.maclib(ssprof)') +
lib('script.r3.maclib') +
sysvar(c 1 d yes) +
bind(8 8) chars(gt12 gb12) file('&SYSPREF..&DSNAM..list') continue
--------------------------------------------------------------------------
Figure 12-8. The SCRIPTD CLIST
--------------------------------------------------------------------------
GLOBAL DSNAM
/**********************************************************************/
/* THIS CLIST (OUTPUT) FREES FILES REQUIRED TO PRINT THE SCRIPTED */
/* DATASET, ALLOCATES THEM REQUESTING TWO COPIES ON THE 3800 */
/* PRINTER, AND INVOKES IEBGENER TO HAVE THEM PRINTED. */
/**********************************************************************/
CONTROL NOMSG
CONTROL MSG
alloc f(sysprint) dummy reuse
alloc f(sysut1) da('&SYSPREF..&DSNAM..LIST') shr reuse
alloc f(sysut2) sysout(n) fcb(std4) chars(gt12,gb12) +
copies(2) optcd(j) reuse
alloc f(sysin) dummy reuse
/**********************************************************************/
/* INVOKE THE UTILITY TO HAVE THE DATA SET PRINTED AND FREE THE */
/* FILES. THEN RETURN CONTROL TO SCRIPTN. */
/**********************************************************************/
call 'sys1.linklib(iebgener)'
free f(sysut1,sysut2,sysprint,sysin)
--------------------------------------------------------------------------
Figure 12-9. The OUTPUT CLIST
12.7 Including JCL Statements - The SUBMITDS CLIST
You can include job control language (JCL) statements in CLISTs. The
SUBMITDS CLIST, shown in Figure 12-10, uses the SUBMIT * command to
indicate that the JCL statements immediately follow the command.
SUBMITDS verifies job card information using front-end prompting and then
submits a job that copies one data set into another. The
validity-checking does not go beyond verifying that the account number is
a four-digit number.
Because an account number may contain leading zeros that are ignored by
the &LENGTH built-in function, the CLIST uses the &STR built-in function
in the evaluation of the length of &ACCT.
The SUBMITDS CLIST assumes that:
* The account number is required and must be a four-digit number.

* The account number may contain leading zeros.
* The default CLASS for the job is C.
--------------------------------------------------------------------------
PROC 2 DSN ACCT CLASS(C)
/**********************************************************************/
/* IF &ACCT IS INVALID, CONTINUE PROMPTING UNTIL THE USER ENTERS */
/**********************************************************************/
DO WHILE &LENGTH(&STR(&ACCT)) ^= 4 OR &DATATYPE(&ACCT) ^= NUM

WRITE Your account number is invalid.
WRITE Reenter a four-digit number.
READ ACCT
END
/**********************************************************************/
/* ONCE ACCOUNT NUMBER HAS BEEN VERIFIED, SUBMIT THE JOB. */
/**********************************************************************/
SET SLSHASK=&STR(/*) /* Set the /* required for jcl comment statement */

SUBMIT * END($$)
//&SYSUID.1 JOB &ACCT,&SYSUID,CLASS=&CLASS,NOTIFY=&SYSUID
/&SLSHASK THIS STEP COPIES THE INPUT DATASET TO SYSOUT=A
//COPY EXEC PGM=COPYDS
//SYSUT1 DD DSN=&SYSUID..&DSN,DISP=SHR
//SYSUT2 DD SYSOUT=A
$$
--------------------------------------------------------------------------
Figure 12-10. The SUBMITDS CLIST
12.8 Analyzing Input Strings with &SUBSTR - The SUBMITFQ CLIST

You can use the &SUBSTR built-in function to analyze input from the
invoker and to modify the input if necessary.
The SUBMITFQ CLIST, shown Figure 12-11, determines whether the data set
name supplied by the invoker is a fully-qualified name or not. If the
data set name is not fully qualified (does not include a user ID), the
SUBMITFQ adds the user ID and submits the data set name in the correct
form on a JCL statement.
SUBMITFQ determines whether the data set name is fully qualified by

comparing the first character in &DSN to a single quote ('). If the
logical comparison is true, the CLIST assumes a fully-qualified data set
name and removes the quotes. (Unlike on the ALLOCATE command,
fully-qualified data set names are not enclosed in single quotes on JCL
statements.) If the first character of &DSN is not a single quote, the
CLIST assumes the data set name is not fully qualified and prefixes the
character string "&SYSUID.." to the value of &DSN. In either case, &DSN
contains a fully-qualified data set name when referenced on the SYSUT1 JCL
statement.
--------------------------------------------------------------------------
PROC 2 DSN ACCT CLASS(C)
/*********************************************************************]/
/* IF &ACCT IS INVALID, CONTINUE PROMPTING UNTIL THE USER ENTERS */
/**********************************************************************/
DO WHILE &LENGTH(&STR(&ACCT)) ^= 4 OR &DATATYPE(&ACCT) ^= NUM

WRITE Your account number is invalid.
WRITE Reenter a four-digit number.
READ ACCT
END
/**********************************************************************/
/* IF THE DATA SET IS FULLY QUALIFIED, REMOVE THE QUOTES. OTHERWISE, */
/* PREFIX THE CURRENT USERID. */
/**********************************************************************/
IF &STR(&SUBSTR(1,&DSN)) = ' THEN +

SET DSN = &STR(&SUBSTR(2:&LENGTH(&DSN)-1,&DSN))
ELSE SET DSN=&STR(&SYSUID..&DSN)
WRITE &DSN
/**********************************************************************/
/* ONCE ACCOUNT NUMBER HAS BEEN VERIFIED, SUBMIT THE JOB. */
/**********************************************************************/
SET SLSHASK=&STR(/*) /* Set the /* req. for the jcl comment statement */
SUBMIT * END($$)
//&SYSUID.1 JOB &ACCT,&SYSUID,CLASS=&CLASS
/&SLSHASK THIS STEP COPIES THE INPUT DATASET TO SYSOUT=A
//COPY EXEC PGM=COPYDS
//SYSUT1 DD DSN=&DSN,DISP=SHR
//SYSUT2 DD SYSOUT=A
$$
--------------------------------------------------------------------------
Figure 12-11. The SUBMITFQ CLIST
12.9 Allowing Foreground and Background Execution of Programs - The RUNPRICE

CLIST
You can write CLISTs that invoke programs in either the foreground or the
background. By creating a background job, the CLIST can have the job
invoke any program, including itself, in the background. You can use this
type of a CLIST to enable users who are unfamiliar with JCL to submit
programs. By placing the JCL in a CLIST, you simplify the user's work,
while adding greater range to the tasks the user can perform. The
RUNPRICE CLIST, shown in Figure 12-12, illustrates this type of a CLIST.
RUNPRICE either executes a COBOL program called APRICE in the foreground

or submits a job that executes APRICE in the background. The CLIST
determines which type of invocation to perform based on whether the
invoker includes the BATCH keyword on the invocation of RUNPRICE.
--------------------------------------------------------------------------
PROC 0 M(R) BATCH
/**********************************************************************/
/* THIS CLIST (RUNPRICE) SUBMITS A JOB FOR EXECUTION EITHER IN THE */
/* FOREGROUND OR BACKGROUND, BASED ON WHETHER THE INVOKER INDICATES */
/* 'BATCH' ON THE INVOCATION. THE MESSAGE CLASS DEFAULTS TO 'R', */
/* THOUGH THE INVOKER MAY CHANGE IT. */
/**********************************************************************/
CONTROL END(ENDO)
/**********************************************************************/
/* IF &BATCH DOES NOT EQUAL A NULL, THIS INDICATES THAT THE INVOKER */
/* INCLUDED THE KEYWORD ON THE INVOCATION. IN THIS CASE, THE INVOKER*/
/* WANTS THE JOB SUBMITTED IN THE BACKGROUND, SO CREATE A JOB THAT */
/* EXECUTES THE TMP AND THEN INVOKES RUNPRICE WITHOUT THE 'BATCH' */
/* KEYWORD. ON THIS SECOND INVOCATION OF RUNPRICE, ONLY THE */
/* APRICE PROGRAM IS EXECUTED. */
/* IF &BATCH EQUALS A NULL, THIS INDICATES THAT THE INVOKER WANTS */
/* TO EXECUTE THE PROGRAM IN THE FOREGROUND. IN THIS CASE, SIMPLY */
/* INVOKE THE APRICE PROGRAM DIRECTLY. */
/**********************************************************************/
SET SLSHASK=&STR(/*) /* Set the /* for JOBPARM to a variable */

IF &BATCH=BATCH THEN +
DO
CONTROL NOMSG
SUBMIT * END(NN)
//STEVE1 JOB 'accounting info','STEVE',
// MSGLEVEL=(1,1),CLASS=T,NOTIFY=&SYSUID,MSGCLASS=&M,
// USER=????????,PASSWORD=????????
&SLSHASK.JOBPARM COPIES=1
//BACKTMP EXEC PGM=IKJEFT01,REGION=4096K,DYNAMNBR=10
//SYSPRINT DD DUMMY
//SYSTSPRT DD SYSOUT=*
//SYSTSIN DD *
ex 'd84rlh1.tsoer2.pubs.clist(runprice)'
NN
ENDO
ELSE call 'd60fot1.allot.cobol(aprice)'
--------------------------------------------------------------------------
Figure 12-12. The RUNPRICE CLIST
12.10 Including Options - The TESTDYN CLIST
You can code options in a CLIST so that the CLIST performs different
functions depending on what the invoker specifies.
The TESTDYN CLIST, shown in Figure 12-13, sets up the environment needed
to execute a program called PARMTEST, which tests dynamic allocation input
parameters entered from the terminal. In TESTDYN, conditional
IF-THEN-ELSE sequences and optional keywords on the PROC statement enable
the invoker to select a number of options when invoking the CLIST. For
example, one option is whether or not the invoker wants the system
messages that PARMTEST produces sent to a data set rather than to the
terminal. TESTDYN includes a keyword parameter, SYSPRINT, on its PROC
statement and assigns it a default value of *, which sends system messages
to the terminal. The invoker can override that default value and have
system messages sent to a system output data set.
Note that special considerations are taken in the processing that

determines whether SYSOUT has been coded for SYSPRINT. On the IF
statement, the variable &SYSPRINT is enclosed in a &STR built-in function
because &SYSPRINT defaults to an asterisk, which the CLIST views as a
multiplication operator. The &STR built-in function defines the asterisk
as character data and prevents the CLIST from using it arithmetically.
--------------------------------------------------------------------------
PROC 0 MBR(PARMTEST) SYSPRINT(*) SYSLIB(LOAD) OUTFILE(VLDPARMS) LISTDSETS
/**********************************************************************/
/* THIS CLIST SETS UP THE ENVIRONMENT NEEDED FOR EXECUTION OF */
/* A PROGRAM NAMED 'PARMTEST' WHICH TESTS DYNAMIC ALLOCATION */
/* INPUT PARAMETERS ENTERED FROM THE TERMINAL. */
/**********************************************************************/
/**********************************************************************/
/* IF THE USER REQUESTED THAT DATA SETS BE LISTED, LIST THEM. */
/**********************************************************************/
IF &LISTDSETS = LISTDSETS THEN +

DO
WRITE PROGRAM: &MBR
WRITE SYSPRINT: &SYSPRINT
WRITE SYSLIB: &SYSLIB
WRITE OUTFILE: &OUTFILE
END
/**********************************************************************/
/* IF THE USER REQUESTED THAT SYSTEM MESSAGES BE SENT TO A SYSTEM */
/* OUTPUT DATA SET, ALLOCATE SYSPRINT TO SYSOUT. OTHERWISE, */
/* ALLOCATE SYSPRINT TO THE DATA SET NAME (OR TERMINAL) AS */
/* INDICATED BY THE USER. */
/**********************************************************************/
IF &STR(&SYSPRINT) = SYSOUT THEN +

alloc f(sysprint) sysout reu
ELSE alloc f(sysprint) da(&SYSPRINT) reu
/**********************************************************************/
/* ALLOCATE THE SYSTEM LIBRARY, WHETHER IT BE THE DEFAULT (LOAD) */
/* OR ANOTHER LIBRARY. */
/**********************************************************************/
alloc f(syslib) da(&SYSLIB) reu shr
/**********************************************************************/
/* ALLOCATE THE OUTPUT DATA SET FOR THE PROGRAM. ALLOCATE THE */
/* INPUT DATA SET TO THE TERMINAL. */
/**********************************************************************/
alloc f(outfile) da(&OUTFILE) lrecl(121) blksize(1210) recfm(f,b) reu

alloc f(sysin) da(*) reu
/**********************************************************************/
/* CALL PARMTEST AND NOTIFY THE USER THAT THE INVOCATION WAS */
/* SUCCESSFUL OR UNSUCCESSFUL. */
/**********************************************************************/
CONTROL NOFLUSH
call 'steve.lib.load(&MBR)'
WRITE &MBR invoked successfully at &SYSTIME on &SYSDATE.
ELSE +
WRITE &MBR invoked unsuccessfully at &SYSTIME on &SYSDATE.
--------------------------------------------------------------------------
Figure 12-13. The TESTDYN CLIST
12.11 Simplifying System-Related Tasks - The COMPRESS CLIST
From time to time, users must compress a data set they have updated
multiple times to free some space for additional members. The process
involves allocating the data sets required by the IEBCOPY utility, which
performs the copying involved in compressing the data set, and invoking
the utility.
The COMPRESS CLIST, shown in Figure 12-14, performs all of the functions
required to compress a data set.
The COMPRESS CLIST includes special procedures to make the best use of
storage space. For example, COMPRESS could allocate a data set to contain
the input required by the IEBCOPY utility. However, IEBCOPY requires only
the following command for input:
copy indd=output,outdd=output
Rather than waste permanent storage for the one command, COMPRESS creates
a virtual I/O (VIO) data set for the SYSIN file using an ALLOCATE command
that does not specify a data set name. The ALLOCATE command assigns the
file name SYSIN to the VIO data set and then writes a record containing
the COPY command to the SYSIN file.
--------------------------------------------------------------------------
PROC 1 DSNAME DISP(OLD) LIST

CONTROL NOFLUSH /* Preserve the input stack for errors */
/**********************************************************************/
/* THIS CLIST (COMPRESS) COMPRESSES A DATA SET AND INFORMS THE USER */
/* WHETHER OR NOT THE COMPRESS WAS SUCCESSFUL. */
/**********************************************************************/
/* SET UP AN ERROR ROUTINE TO FREE ALLOCATED FILES WHEN AN ERROR OCCURS.
/**********************************************************************/
ERROR +
DO
ERROR OFF
WRITE An error has occurred prior to the actual compress.
free file(sysin,sysprint,sysut3,sysut4,output)
GOTO FINISH
END
/**********************************************************************/
/* IF THE USER WANTS TO VIEW THE TSO COMMANDS AS THEY EXECUTE, ISSUE */
/* THE CONTROL LIST STATEMENT. */
/**********************************************************************/
CONTROL LIST
/**********************************************************************/
/* ESTABLISH ENVIRONMENT NEEDED BY IEBCOPY UTILITY. */
/**********************************************************************/
allocate file(sysin) space(1,1) track lrecl(80) recfm(f) blksize(80) reuse

IF &SYSDSN(COMPRESS.LIST) ^= OK THEN +
allocate file(sysprint) dataset(compress.list) recfm(f,b,a) +
lrecl(121) blksize(12947) space(1,1) track reuse
ELSE +
allocate file(sysprint) dataset(compress.list) shr reuse
allocate file(sysut3) unit(sysda) space(1,1) cylinders reu
allocate file(sysut4) unit(sysda) space(1,1) cylinders reu
allocate file(output) dataset(&DSNAME) &DISP reu
/**********************************************************************/
/* PLACE THE COPY COMMAND INTO THE SYSIN FILE REQUIRED BY IEBCOPY. */
/**********************************************************************/
OPENFILE SYSIN OUTPUT

SET SYSIN = &STR( COPY INDD=OUTPUT,OUTDD=OUTPUT)
PUTFILE SYSIN
CLOSFILE SYSIN
/**********************************************************************/
/* Set up an error routine to notify user of compress errors. */
/**********************************************************************/
ERROR +
DO
WRITE Compress error--Details in '&SYSPREF..compress.list'
GOTO FINISH
END
/**********************************************************************/
/* INVOKE IEBCOPY UTILITY TO PERFORM THE COMPRESS. */
/**********************************************************************/
tsoexec call 'sys1.linklib(iebcopy)' 'size=512k'

WRITE &DSNAME compressed at &SYSTIME
FINISH: end /* End the CLIST */
--------------------------------------------------------------------------
Figure 12-14. The COMPRESS CLIST
12.12 Simplifying Interfaces to Applications - The CASH CLIST
You may have access to applications written in other programming

languages. However, the interfaces required to invoke these programs may
not be easily mastered by users who use the system infrequently. Rather
than write new applications, you can write CLISTs that act as
intermediaries between users and such programs.
For example, a program called CASHFLOW creates and prints weekly and
monthly reports. If the invoker wants a weekly report, the invocation is:
call 'sys1.plib(cashflow)' 'a,,,38,ccfdacr'
If the invoker wants a monthly report, the invocation is:
call 'sys1.plib(cashflow)' 'x,,,49,ccfmacr'

Not only are the preceding invocations quite technical, they are difficult
to remember.
CASHFLOW also requires the allocation of a file. For weekly reports, it

requires:
alloc f(projwkly) da(weekly) shr
For monthly reports, it requires:
alloc f(projmtly) da(monthly) shr
To simplify the process of invoking CASHFLOW, the CASH CLIST, shown in

Figure 12-15, performs the following intermediary tasks:
1. It determines whether the invoker wants a weekly or monthly report.
2. It assigns values to the variables substituted in the parameter string

on the CALL command that invokes CASHFLOW. The values correspond to
the parameters required for the type of report requested.
3. It allocates the appropriate data set.
--------------------------------------------------------------------------
/* PROMPT THE USER FOR THE WORD 'WEEKLY' or 'MONTHLY' */
DO WHILE &TYPE^=WEEKLY AND &TYPE^=MONTHLY

WRITE Enter the word WEEKLY or MONTHLY to indicate the
WRITE type of report you want to create.
READ TYPE
END
/**********************************************************************/
/* NOW THAT A VALID REQUEST HAS BEEN ESTABLISHED, ALLOCATE THE */
/* APPROPRIATE DATA SET, ASSIGN THE APPROPRIATE VALUES TO CALL */
/* COMMAND PARAMETER VARIABLES, AND INVOKE CASHFLOW. */
/**********************************************************************/
IF &TYPE=WEEKLY THEN +
DO
alloc f(projwkly) da(weekly) shr
SET INVOKE=38
SET CHAR=a
SET OPT=ccfdacr
END
ELSE +
DO
alloc f(projmtly) da(monthly) shr
SET INVOKE=49
SET CHAR=x
SET OPT=ccfmacr
END
call 'sys1.plib(cashflow)' '&CHAR,,,&INVOKE,&OPT'
--------------------------------------------------------------------------
Figure 12-15. The CASH CLIST
12.13 Using &SYSDVAL When Performing I/O - The PHONE CLIST

Data records often contain related pieces or blocks of information. For
instance, a sequential record could contain a person's name and phone
number. When you read records of this type, you may want to separate the
blocks of information. By defining SYSDVAL as the file name of the data
set containing the records, you read each record into SYSDVAL, which the
CLIST equates with the &SYSDVAL control variable. Then you can issue a
READDVAL statement that contains the names of the variables into which you
want the blocks of information stored.
The PHONE CLIST, shown in Figure 12-16, takes advantage of this technique.
PHONE receives a last name as input using a positional parameter called
NAME. PHONE then allocates a data set called SYS1.STAFF.DIRECTRY and
assigns it the file name SYSDVAL. Each record in SYS1.STAFF.DIRECTRY
contains a last name, followed by a blank and a phone number. Sample
records are:
PICKERELL 555-5555
GORGEN 555-4444
PHONE sets the first character string in the record to a variable called
&LNAME and sets the second string to a variable called &PHONUMBR. Then,
it compares &NAME to &LNAME and, if they are equal, displays the
corresponding phone number (contained in &PHONUMBR) at the terminal. If
the names are not equal, PHONE reads another record and performs the same
test.
If none of the names in the directory match the name supplied by the
invoker, the CLIST branches to the end-of-file error routine. The
end-of-file routine informs the invoker that a name was not found, and
sets the variable DONE=YES to cause the loop to terminate.
--------------------------------------------------------------------------
PROC 1 NAME
/**********************************************************************/
/* THIS CLIST (PHONE) SEARCHES A DATA SET FOR A NAME THAT MATCHES THE */
/* NAME SUPPLIED TO THE CLIST. IF A MATCH IS FOUND, THE CORRESPONDING */
/* PHONE NUMBER IS DISPLAYED AT THE TERMINAL. OTHERWISE, A MESSAGE IS */
/* ISSUED INFORMING THE USER THAT A MATCH WAS NOT FOUND. */
/**********************************************************************/
/**********************************************************************/
/* ALLOCATE THE INPUT DATA SET FOR THE CLIST. */
/**********************************************************************/
alloc f(sysdval) da('sys1.staff.directry') shr reu
/**********************************************************************/
/* OPEN THE FILE, AND SET UP AN ERROR ROUTINE TO HANDLE END-OF-FILE. */
/**********************************************************************/
CONTROL NOMSG NOFLUSH

ERROR +
DO
DO
WRITENR The name requested, &NAME, was not found in the staff
WRITE directory.
SET DONE=YES
END
RETURN
END /* END OF END-OF-FILE ROUTINE */
SET DONE=NO
OPENFILE SYSDVAL
/**********************************************************************/
/* THIS LOOP RETRIEVES RECORDS FROM THE INPUT DATA SET UNTIL A MATCH */
/* IS FOUND OR END OF FILE IS REACHED. IF A MATCH IS FOUND, THE */
/* SECOND VARIABLE ON THE READDVAL STATEMENT (THE ONE CONTAINING */
/* THE PHONE NUMBER) IS DISPLAYED. */
/**********************************************************************/
DO WHILE &DONE=NO
GETFILE SYSDVAL
READDVAL LNAME PHONUMBR
IF &STR(&NAME) = &STR(&LNAME) THEN +
DO
WRITE &PHONUMBR
SET DONE=YES
END
END
CLOSFILE SYSDVAL
free file(sysdval)
--------------------------------------------------------------------------
Figure 12-16. The PHONE CLIST
12.14 Allocating Data Sets to SYSPROC - The SPROC CLIST
The SPROC CLIST allocates a CLIST data set to the file SYSPROC, so users
can implicitly execute CLISTs that are in that data set. The SPROC CLIST
allocates the CLIST data set as the first in the list of data sets
allocated to SYSPROC, so TSO/E searches that data set for CLISTs before
searching any of the others.
Note: You can also use the ALTLIB command to define CLIST data sets and
establish their search order for implicit execution.
SPROC performs the following steps: finds all data sets currently
allocated to SYSPROC and concatenates them; then adds the invoker's data
set to the beginning of the concatenation and allocates the concatenation
to SYSPROC.
The CLIST, shown in Figure 12-17, uses &SYSOUTTRAP to intercept the output
from the LISTALC STATUS command and saves the command output in
&SYSOUTLINEnn variables. The output produced by the LISTALC STATUS
command is formatted as follows:
--DDNAME---DISP--
DATA-SET-NAME1
FILE-NAME1 DISPOSITION
DATA-SET-NAME2
FILE-NAME2 DISPOSITION
DATA-SET-NAME3
DISPOSITION
: DATA-SET-NAME4
: FILE-NAME3 DISPOSITION
In the previous format, DATA-SET-NAME1 is allocated to FILE-NAME1;

DATA-SET-NAME2 and DATA-SET-NAME3 are allocated to FILE-NAME2; and
DATA-SET-NAME4 is allocated to FILE-NAME3. The name of a file always
begins in the third position, whereas a data set name begins in the first
position of the output line. SPROC does the following:
1. Loops through &SYSOUTLINEnn variables until either the string SYSPROC

is found or until all output has been searched. (It is possible no
data sets are allocated to SYSPROC.)
2. If SYSPROC is found, SPROC sets a variable to the name of the previous

data set in the list and encloses it in single quotes.
3. Begins with the &SYSOUTLINEnn variable three lines after the one
containing the name of the first data set allocated to SYSPROC. This
line either contains a new file name, in which case SPROC has found
all data sets allocated to SYSPROC, or it contains the disposition of
the next data set in the concatenation. By setting a variable to
three blanks, SPROC determines the contents of the line.
If the line contains a disposition, SPROC decreases &SYSOUTLINEnn by

one to get the data set name and add it to the variable (&CONCAT)
representing the data sets in the new concatenation. SPROC repeats
this procedure until another file name is encountered or until all
command output has been searched. Once all data sets have been added
to the concatenation list, SPROC issues the ALLOCATE command, adding
the user's data set name to the beginning of the concatenation list.
SPROC contains an error routine to handle allocation errors should they

occur. SPROC may itself be allocated to SYSPROC, in which case the user
can invoke SPROC implicitly. However, if the CLIST fails after it frees
the SYSPROC file, but before it is able to re-establish the concatenation,
the user cannot re-invoke SPROC implicitly without first logging off and
logging on again.
--------------------------------------------------------------------------
PROC 0 LIST
CONTROL LIST CONLIST
/**********************************************************************/
/* THIS CLIST (SPROC) CONCATENATES DATA SETS AND ALLOCATES THEM */
/* TO THE FILE SYSPROC. */
/* THE USER IS PROMPTED TO SUPPLY THE NAME OF THE DATA */
/* SET TO BE ADDED TO THE BEGINNING OF THE CONCATENATION. */
/**********************************************************************/
/**********************************************************************/
/* IF ALLOCATION FAILS, TELL THE USER TO LOG OFF, LOG ON, AND, IF */
/* DESIRED, TRY EXECUTING SPROC AGAIN. */
/**********************************************************************/
CONTROL NOFLUSH
ERROR +
DO
WRITE An error has been encountered in the SYSPROC concatenation.
WRITE Please log off, then log on again, and, if desired, re-invoke
WRITE SPROC. If the problem persists, see your system programmer.
GOTO OUT
END
/**********************************************************************/
/* PROMPT THE USER FOR THE NAME OF THE DATA SET TO BE ADDED TO THE */
/* BEGINNING OF THE SYSPROC CONCATENATION. */
/**********************************************************************/
WRITE Enter the fully-qualified data set name you want
WRITE added to the beginning of the SYSPROC concatenation.
WRITE Do N O T place quotes around the dataset name.
READ ADD
/**********************************************************************/
/* SET A VARIABLE TO THREE BLANKS. THIS VARIABLE IS USED TO CHECK */
/* THE LISTALC COMMAND OUTPUT FOR THE BEGINNING OF A DIFFERENT */
/* FILENAME AFTER SYSPROC DATA SETS HAVE BEEN LISTED. */
/**********************************************************************/
SET BLANKS = &STR( )
/**********************************************************************/
/* SET &SYSOUTTRAP TO A LARGE ENOUGH VALUE TO ENSURE THAT ALL OF */
/* THE LINES OF OUTPUT FROM THE LISTALC COMMAND CAN BE VIEWED. */
/**********************************************************************/
] SET &SYSOUTTRAP = 300
/**********************************************************************/
/* ISSUE THE LISTALC STATUS COMMAND AND LOOP THROUGH THE VARIABLES */
/* CONTAINING THE OUTPUT LINES UNTIL THE LINE CONTAINING */
/* THE FILENAME */
/* SYSPROC IS FOUND OR UNTIL ALL LINES HAVE BEEN VIEWED. */
/* (ALL LINES HAVE BEEN VIEWED WHEN A NULL LINE IS RETURNED.) */
/* AN AUXILIARY VARIABLE MUST BE CREATED (&DSN) TO LOOP THROUGH */
/* &SYSOUTLINEnn. &I REPRESENTS THE VALUE OF nn. */
/* NOTE THAT, IN ORDER TO SET &DSN TO &SYSOUTLINE, TWO AMPERSANDS */
/* MUST BE PLACED BEFORE SYSOUTLINE TO AVOID SYMBOLIC SUBSTITUTION */
/* OF &SYSOUTLINE. */
/* IF SYSPROC IS FOUND, SET THE VARIABLE &CONCAT EQUAL TO */
/* THE PREVIOUS LINE (CONTAINING THE NAME */
/* OF THE FIRST DATA SET ALLOCATED TO SYSPROC). */
/**********************************************************************/
lista st
] SET &SYSOUTTRAP = 0
SET SPROC = &STR(SYSPROC)
SET FOUND = NO
SET I=1
DO WHILE &STR(&FOUND) = NO AND &I <= &SYSOUTLINE
SET DSN = &&SYSOUTLINE&I
>=9 ITHENE+GTH(&STR(&DSN))
IF &STR(&SUBSTR(3:9,&DSN)) = &SPROC THEN +
DO
SET FOUND = YES
SET I = &I-1
SET CONCAT = '&DSN'
END
ELSE SET I = &I+1
ELSE SET I = &I+1
END
/**********************************************************************/
/* IF SYSPROC WAS FOUND, LOOP THROUGH DATA SETS UNTIL ANOTHER */
/* FILENAME IS ENCOUNTERED OR UNTIL THE REST OF THE OUTPUT HAS */
/* BEEN PROCESSED. SETTING &I = &I+3 MAPS &DSN TO THE LINE AFTER */
/* THE NEXT DATA SET NAME, WHICH WILL CONTAIN ANOTHER FILENAME IF */
/* WE HAVE ALREADY PROCESSED THE LAST DATA SET ALLOCATED TO SYSPROC */
/* AND WE HAVE NOT REACHED THE END OF THE COMMAND OUTPUT. */
/**********************************************************************/
IF &FOUND=YES THEN +
DO WHILE &I+3 <= &SYSOUTLINE
SET I = &I+3
IF &STR(&SUBSTR(1:3,&DSN)) = &BLANKS THEN +
DO
SET I = &I-1
SET CONCAT = &CONCAT&STR( ')&DSN'
END
ELSE +
SET I=&SYSOUTLINE
END
/**********************************************************************/
/* WHEN ALL DATA SETS ALLOCATED TO SYSPROC HAVE BEEN ADDED TO THE */
/* VARIABLE &CONCAT, ADD THE USER'S DATA SET TO THE BEGINNING OF */
/* THE CONCATENATION. (INSERT THE VARIABLE &ADD BEFORE &CONCAT.) */
/* THIS CLIST ASSUMES THAT THE DATA SET HAS BEEN ENTERED CORRECTLY */
/* BY THE USER. */
/**********************************************************************/
alloc f(sysproc) da('&ADD' &CONCAT) shr reu
OUT: end
--------------------------------------------------------------------------
Figure 12-17. The SPROC CLIST
12.15 Writing Full-Screen Applications Using ISPF Dialogs - The PROFILE CLIST
The CLIST language is well-suited for applications that invoke ISPF dialog
management services to display full-screen panels.
For more information about ISPF, see ISPF Dialog Management Guide and ISPF
Dialog Management Services and Examples. The PROFILE CLIST is an example
of a CLIST that displays entry panels on which the user can modify
information. The PROFILE CLIST allows the user to perform any of the
following functions to modify his or her profiles:
* Set terminal characteristics.

* Set LOG/LIST parameters.
* Set PF keys (1-12).
* Set PF keys (13-24).
The PROFILE CLIST receives control from a CLIST that displays the primary
selection panel. The primary selection panel prompts the user to indicate
which function he wants to perform (QCMD); and if the function is setting
PF keys, which PF keys he wants to view (QKEYS). Then, the CLIST invokes
PROFILE, passing the values for QCMD and QKEYS.
PROFILE determines which selection was requested by referencing PROC

statement keywords called QCMD and QKEYS.
If &QCMD is 1, PROFILE displays the terminal characteristics panel

definition.
If &QCMD is 2, PROFILE displays the LOG/LIST parameters panel definition.
If &QCMD is 3 and &QKEYS is 12, PROFILE displays the PF keys 1-12 panel
definition.
If &QCMD is 3 and &QKEYS is 24, PROFILE displays the PF keys 13-24 panel
definition.
Panels are displayed using the ISPEXEC command.
When the user presses the END key after viewing and/or modifying a
particular panel, the value of &LASTCC is 8. By testing the value of
&LASTCC, PROFILE can determine when the user is finished with the
selection.
When the user is viewing one of the two PF key panels, he or she can
switch to the other panel by pressing the ENTER key. PROFILE sets &QKEYS
to the PF key (12 or 24) that represents the other panel so that the user
can continue to switch back and forth if desired. Pressing ENTER
re-executes the DO-UNTIL-END sequence, causing PROFILE to test the value
of &QKEYS to determine which panel to display. As with the other
selection sequences, the PF key sequence ends when the user presses the
END key.
Values set or changed on any of the four panels displayed by PROFILE are
stored in the corresponding variables on the panel definitions.
Figure 12-18 contains the purpose of, and figures containing, the PROFILE
CLIST and its supporting four panel definitions.
]------------------------------------------------------------------------]
] Figure 12-18. Purpose of, and Figures Containing, PROFILE CLIST and ]
] Supporting Panels ]
]-------------]-------------------------------------------------]--------]
] CLIST/Panel ] Purpose ] Figure ]
]-------------]-------------------------------------------------]--------]
] PROFILE ] Manage user profile panels ] 12-19 ]
]-------------]-------------------------------------------------]--------]
] XYZABC10 ] Terminal characteristics panel ] 12-20 ]
]-------------]-------------------------------------------------]--------]
] XYZABC20 ] LOG/LIST parameters panel ] 12-21 ]
]-------------]-------------------------------------------------]--------]
] XYZABC30 ] PF keys 1-12 panel ] 12-22 ]
]-------------]-------------------------------------------------]--------]
] XYZABC40 ] PF keys 13-24 panel ] 12-23 ]
]-------------]-------------------------------------------------]--------]
--------------------------------------------------------------------------
PROC 0 QCMD(1) QKEYS(12)
/**********************************************************************/
/* THIS CLIST (PROFILE) DISPLAYS THE PANEL THAT CONTAINS THE PROFILE */
/* DATA THE USER WANTS TO UPDATE. IT SETS THE FINISH FLAG TO NO AND */
/* THEN DETERMINES WHICH OF THE FOUR POSSIBLE PANELS THE USER NEEDS */
/* DISPLAYED. */
/**********************************************************************/
CONTROL MSG END(ENDO)

SET FINISH = NO
/**********************************************************************/
/* IF THE USER WANTS TO UPDATE TERMINAL CHARACTERISTICS, DISPLAY */
/* THE ASSOCIATED PANEL. */
/**********************************************************************/
SELECT
WHEN (&QCMD = 1) +
DO UNTIL (&FINISH = YES)
ISPEXEC DISPLAY PANEL(XYZABC10) /* Display first panel */
IF &LASTCC = 8 THEN /* If user presses END, */ +
SET FINISH = YES /* end panel display */
ENDO
/**********************************************************************/
/* IF THE USER WANTS TO UPDATE LOG/LIST PARAMETERS, DISPLAY */
/* THE ASSOCIATED PANEL. */
/**********************************************************************/
WHEN (&QCMD = 2) +
ISPEXEC DISPLAY PANEL(XYZABC20) /* Display 2nd panel */
SET FINISH = YES /* end panel display. */
ENDO
/**********************************************************************/
/* IF THE USER WANTS TO UPDATE PF KEYS, DETERMINE WHICH GROUP THE */
/* USER WANTS TO UPDATE: 1-12 or 13-24. DISPLAY THE ASSOCIATED PANEL.*/
/**********************************************************************/
WHEN (&QCMD = 3) +
IF &QKEYS = 12 THEN +
DO
ISPEXEC DISPLAY PANEL(XYZABC30) /* Display PF keys 1-12 */
ELSE +
SET QKEYS = 24 /* If user presses ENTER, */
ENDO /* display next panel. */
ELSE +
DO
ISPEXEC DISPLAY PANEL(XYZABC40) /* Display PF keys 13-24 */
ELSE +
SET QKEYS = 24 /* If user presses ENTER, */
ENDO /* display previous panel. */
ENDO
ENDO /* End of SELECT statement
/*
/* EXIT ROUTINE
/*
FINAL: +
SET FCODE = 0
EXIT CODE(&FCODE)
--------------------------------------------------------------------------
Figure 12-19. The PROFILE CLIST
The panels displayed by the PROFILE CLIST appear on the following pages in
panel definition form. In order for the PROFILE CLIST to display them,
the panels must be members of a partitioned data set allocated to the file
ISPPLIB, for example:
allocate file(ispplib) dataset(test.panels)
For more information about how to create and allocate ISPF panel
definitions, see ISPF Dialog Management Services and Examples.
--------------------------------------------------------------------------
)ATTR DEFAULT(%+_)
/* % TYPE(TEXT) INTENS(HIGH) defaults displayed for */
/* + TYPE(TEXT) INTENS(LOW) information only */
/* _ TYPE(INPUT) INTENS(HIGH) CAPS(ON) JUST(LEFT) */
@ TYPE(INPUT) INTENS(HIGH) PAD(_) CAPS(ON)
)BODY
+ SAMPLE - SET THE TERMINAL CHARACTERISTICS
_ZCMDOMMAND === +
%
+Type the information where requested, or change the information shown
+by typing over it:
+
@Z + +TERM3277,T3277A, 3278, 3278A, or 3278T +
+ NUMBER OF PF KEYS%===>@Z + 12 or 24
+ INPUT FIELD PAD %===>@Z+ Nulls (N) or Blanks (B)
+ SCREEN FORMAT %===>@Z + (3278 Model 5 only) DATA, STD, or MAX
+ COMMAND DELIMITER%===>@Z+ Any special character
+
+
+
+
+
+
+
+
+
+
+
+
+
)INIT
.ZVARS = '(ZTERM ZKEYS ZPADC ZSF ZDEL)'
&ZSF = TRANS (&ZFMT D,DATA S,STD M,MAX *,' ')
)PROC
IF (&ZCMD ^= ' ') .MSG = ISPZ001 /* INVALID COMMAND */
VER (&ZTERM NB LIST 3277,3277A,3278,3278A,3278T)
&ZCHARLM = TRANS(&ZTERM
3277 , ISP3277
3277A , ISP3277A
3278 , ISP3278
3278A , ISP3278A
3278T , ISP3278T)
VER (&ZKEYS NB LIST 12,24)
IF (&ZKEYS = 24)
VER (&ZTERM LIST 3278 MSG=ISPO002)
VER (&ZPADC NB LIST N,B)
VER (&ZSF,NONBLANK)
&ZFMT = TRUNC (&ZSF,1)
VER (&ZFMT,LIST D,S,M)
VER (&ZDEL NB PICT C)
IF (.MSG ^= ' ')
.RESP = ENTER
)END
--------------------------------------------------------------------------
Figure 12-20. The Terminal Characteristics Panel Definition (XYZABC10)
--------------------------------------------------------------------------
)ATTR DEFAULT(%+_)
)BODY
+ SAMPLE - SET THE LOG/LIST PARAMETERS
%COMMAND ===>_ZCMD +
%
+by typing over it:
+
+ %LOG %LIST
+
+
+ PROCESS OPTION %===>@Z+ @Z+
+ SYSOUT CLASS %===>@Z + @Z +
+ LOCAL PRINTER ID %===>@Z + @Z +
+ LINES PER PAGE %===>@Z + @Z +
+ PRIMARY PAGES %===>@Z + @Z +
+ SECONDARY PAGES %===>@Z + @Z +
+
+
+
+
+
+
+
+
+
+
)INIT
.ZVARS = '(ZLOGFDSP,ZLSTFDSP,ZLOGCLA,ZLSTCLA,ZLOGPID,ZLSTPID, +
ZLOGLIN,ZLSTLIN,ZLOG1PG,ZLST1PG,ZLOG2PG,ZLST2PG)'
)PROC
IF (&ZCMD ^= ' ') .MSG = ISPZ001 /* INVALID COMMAND */
VER (&ZLOGFDSP LIST J,L,K,D,' ')
VER (&ZLSTFDSP LIST J,L,K,D,' ')
IF (&ZLOGFDSP = J)
VER (&ZLOGCLA,NB)
IF (&ZLOGFDSP = L)
VER (&ZLOGPID,NB)
IF (&ZLSTFDSP = J)
VER (&ZLSTCLA,NB)
IF (&ZLSTFDSP = L)
VER (&ZLSTPID,NB)
VER (&ZLOGLIN NB NUM)
VER (&ZLOGLIN RANGE 1,99)
VER (&ZLSTLIN NB NUM)
VER (&ZLSTLIN RANGE 1,99)
VER (&ZLOG1PG NB NUM)
VER (&ZLOG1PG RANGE 0,9999)
VER (&ZLST1PG NB NUM)
VER (&ZLST1PG RANGE 1,9999)
VER (&ZLOG2PG NB NUM)
VER (&ZLOG2PG RANGE 0,9999)
VER (&ZLST2PG NB NUM)
VER (&ZLST2PG RANGE 1,9999)
IF (&ZLOG1PG = 0)
VER (&ZLOG2PG,NB)
VER (&ZLOG2PG,RANGE,0,0)
IF (&ZLOG1PG ^= 0)
VER (&ZLOG2PG,NB NUM)
VER (&ZLOG2PG,RANGE,1,9999)
IF (.MSG ^= ' ' )
.RESP = ENTER
)END
--------------------------------------------------------------------------
Figure 12-21. The LOG/LIST Characteristics Panel Definition (XYZABC20)
--------------------------------------------------------------------------
)ATTR DEFAULT(%+_)
)BODY
+ SAMPLE - SET PF KEYS 1-12
%+OMMAND ===>_ZCMD
%
+by typing over it:
+
++ PF1 %===>@QPF01
++ PF2 %===>@QPF02
++ PF3 %===>@QPF03
++ PF4 %===>@QPF04
++ PF5 %===>@QPF05
++ PF6 %===>@QPF06
++ PF7 %===>@QPF07
++ PF8 %===>@QPF08
++ PF9 %===>@QPF09
++ PF10 %===>@QPF10
++ PF11 %===>@QPF11
++ PF12 %===>@QPF12
+
+
+
+
+
+
)INIT
IF (&QPF01 = ' ')
&QPF01 = HELP
IF (&QPF02 = ' ')
&QPF02 = SPLIT
IF (&QPF03 = ' ')
&QPF03 = END
IF (&QPF04 = ' ')
&QPF04 = RETURN
IF (&QPF05 = ' ')
&QPF05 = RFIND
IF (&QPF06 = ' ')
&QPF06 = RCHANGE
IF (&QPF07 = ' ')
&QPF07 = UP
IF (&QPF08 = ' ')
&QPF08 = DOWN
IF (&QPF09 = ' ')
&QPF09 = SWAP
IF (&QPF10 = ' ')
&QPF10 = LEFT
IF (&QPF11 = ' ')

&QPF11 = RIGHT
IF (&QPF12 = ' ')
&QPF12 = CURSOR
)PROC
IF (&ZCMD ^= ' ') .MSG = ISPZ001
IF (&QPF01 = ' ')
&QPF01 = HELP
IF (&QPF02 = ' ')
&QPF02 = SPLIT
IF (&QPF03 = ' ')
&QPF03 = END
IF (&QPF04 = ' ')
&QPF04 = RETURN
IF (&QPF05 = ' ')
&QPF05 = RFIND
IF (&QPF06 = ' ')
&QPF06 = RCHANGE
IF (&QPF07 = ' ')
&QPF07 = UP
IF (&QPF08 = ' ')
&QPF08 = DOWN
IF (&QPF09 = ' ')
&QPF09 = SWAP
IF (&QPF10 = ' ')
&QPF10 = LEFT
IF (&QPF11 = ' ')
&QPF11 = RIGHT
IF (&QPF12 = ' ')
&QPF12 = CURSOR
IF (.MSG ^= ' ')
.RESP = ENTER
)END
--------------------------------------------------------------------------
Figure 12-22. The PF Keys 1-12 Panel Definition (XYZABC30)
--------------------------------------------------------------------------
)ATTR DEFAULT(%+_)
)BODY
+ SAMPLE - SET PF KEYS 13-24
%COMMAND ===>_ZCMD +
%
+by typing over it; then, to set PF keys 1-12, press ENTER.
+
+ PF13 %===>@QPF13 +
+ PF14 %===>@QPF14 +
+ PF15 %===>@QPF15 +
+ PF16 %===>@QPF16 +
+ PF17 %===>@QPF17 +
+ PF18 %===>@QPF18 +
+ PF19 %===>@QPF19 +
+ PF20 %===>@QPF20 +
+ PF21 %===>@QPF21 +
+ PF22 %===>@QPF22 +
+ PF23 %===>@QPF23 +
+ PF24 %===>@QPF24 +
+
+
+
+
+
+
)INIT
IF (&QPF13 = ' ')
&QPF13 = HELP
IF (&QPF14 = ' ')
&QPF14 = SPLIT
IF (&QPF15 = ' ')
&QPF15 = END
IF (&QPF16 = ' ')
&QPF16 = RETURN
IF (&QPF17 = ' ')
&QPF17 = RFIND
IF (&QPF18 = ' ')
&QPF18 = RCHANGE
IF (&QPF19 = ' ')
&QPF19 = UP
IF (&QPF20 = ' ')
&QPF20 = DOWN
IF (&QPF21 = ' ')
&QPF21 = SWAP
IF (&QPF22 = ' ')
&QPF22 = LEFT
IF (&QPF23 = ' ')

&QPF23 = RIGHT
IF (&QPF24 = ' ')
&QPF24 = CURSOR
)PROC
IF (&ZCMD ^= ' ') .MSG = ISPZ001
IF (&QPF13 = ' ')
&QPF13 = HELP
IF (&QPF14 = ' ')
&QPF14 = SPLIT
IF (&QPF15 = ' ')
&QPF15 = END
IF (&QPF16 = ' ')
&QPF16 = RETURN
IF (&QPF17 = ' ')
&QPF17 = RFIND
IF (&QPF18 = ' ')
&QPF18 = RCHANGE
IF (&QPF19 = ' ')
&QPF19 = UP
IF (&QPF20 = ' ')
&QPF20 = DOWN
IF (&QPF21 = ' ')
&QPF21 = SWAP
IF (&QPF22 = ' ')
&QPF22 = LEFT
IF (&QPF23 = ' ')
&QPF23 = RIGHT
IF (&QPF24 = ' ')
&QPF24 = CURSOR
IF (.MSG ^= ' ')
.RESP = ENTER
)END
--------------------------------------------------------------------------
Figure 12-23. The PF Keys 13-24 Panel Definition (XYZABC40)
12.16 Allocating a Data Set with LISTDSI Information - The EXPAND CLIST
The EXPAND CLIST, shown in Figure 12-24, reallocates a data set with more
space to prevent the data set from running out of space.
The EXPAND CLIST uses the LISTDSI statement to retrieve information about
a base data set's allocation. The information is stored in CLIST
variables. The CLIST then uses the information as input to a
subprocedure. The subprocedure issues the TSO/E ALLOCATE command to
create a new data set using the same attributes as the base data set, but
doubling the primary space.
For more information about the CLIST variables set by LISTDSI, see
"LISTDSI Statement" in topic 13.15.
--------------------------------------------------------------------------
/**********************************************************************/
/* PROCEDURE: EXPAND */
/* */
/* INPUT: BASEDS - NAME OF DATA SET WITH THE ALLOCATION */
/* ATTRIBUTES YOU WANT THE NEW DATA SET */
/* TO HAVE. */
/* NEWDS - NAME OF NEW DATA SET TO BE ALLOCATED. */
/* */
/* OUTPUT: NEW DATA SET ALLOCATED WITH THE SAME ATTRIBUTES AS */
/* THE BASE DATA SET BUT WITH A PRIMARY ALLOCATION */
/* TWICE THE SIZE OF THE BASE DATA SET. */
/* */
/* DESCRIPTION: ISSUE BUILT-IN FUNCTION &SYSDSN TO ENSURE THE BASE */
/* DATA SET EXISTS. ISSUE LISTDSI STATEMENT TO SET */
/* CLIST VARIABLES WITH ATTRIBUTES OF THE BASE DATA */
/* SET. DOUBLE THE CONTENTS OF THE PRIMARY SPACE */
/* VARIABLE, THEN USE THE VARIABLES AS INPUT TO */
/* THE ALLOCATE COMMAND TO ALLOCATE A NEW DATA SET. */
/**********************************************************************/
PROC 2 BASEDS NEWDS

IF &SYSDSN(&BASEDS) = OK THEN +
DO /* If the base data set exists */
LISTDSI &BASEDS /* Issue LISTDSI statement */
NGLOBAL &SYSPRIMARY,&SYSSECONDS /* Make LISTDSI variables avail- */
SET &RC = &LASTCC /* able to subprocedures */
IF &RC = 0 THEN +
SYSCALL ALC &BASEDS &NEWDS /* Call subprocedure ALC */
ELSE +
DO /* If LISTDSI failed */
WRITE &SYSMSGLVL1 /* First-level message */
WRITE &SYSMSGLVL2 /* Second-level message */
WRITE RETURN CODE = &RC /* Return code */
WRITE REASON CODE = &SYSREASON /* LISTDSI reason code */
END
END
ELSE +
WRITE DATA SET &BASEDS NOT FOUND
ALC: PROC 2 BASE NEW /* Subprocedure ALC */

SET NEWPRIMARY = 2 * &SYSPRIMARY /* Compute new primary space */
ALLOCATE DA(&NEW) NEW SPACE(&NEWPRIMARY,&SYSSECONDS) +
LIKE(&BASE) CATALOG /* Allocate the new data set */
WRITE DATA SET &NEW HAS BEEN ALLOCATED
END
--------------------------------------------------------------------------
Figure 12-24. The EXPAND CLIST
13.0 Topic 13. Reference
This topic describes the syntax of the CLIST statements. For information
about the two TSO/E commands--EXEC and END--that you use to start and end
CLIST execution, see TSO/E V2 Command Reference, SC28-1881.
13.1 How to Read the CLIST Statement Syntax
Throughout this topic, syntax is described using the structure defined

below.
Read the syntax diagrams from left to right, from top to bottom, following
the path of the line.
] Double arrows indicate the beginning and ending of a statement.

]
] >>--STATEMENT-----------------------------------------------------------><
] If a statement syntax requires more than one line to be shown, single

] arrows indicate their continuation.
]
] >>--STATEMENT--............--............--............--............---->
] >--............--............-------------------------------------------><
] Required items appear on the horizontal line (the main path).

]
] >>--STATEMENT--required_item--------------------------------------------><
] Optional items appear below the main path.

]
] >>--STATEMENT--]---------------]----------------------------------------><
] ]-optional_item-]
] If you can choose from two or more items, they are stacked vertically.
] * If you must choose one of the items, an item of the stack appears on
] the main path.
]
] >>--STATEMENT--]-required_choice_1-]--------------------------------><
] ]-required_choice_2-]
] * If choosing one of the items is optional, the entire stack appears

] below the main path.
]
] >>--STATEMENT--]-------------------]--------------------------------><
] ]-optional_choice_1-]
] ]-optional_choice_2-]
] An arrow returning to the left above the main line indicates an item that
] can be repeated.
]
] <-----------------]
] >>--STATEMENT----repeatable_item-]--------------------------------------><
] A repeat arrow above a stack indicates that you can make more than one
] choice from the stacked items, or repeat a single choice.
] Default values appear underlined in the diagrams. In newer diagrams

] default values appear above the main path, without being underlined.
]
] ]-choice_1-]
] >>--STATEMENT--]-choice_1-]--]-choice_2-]-------------------------------><
] ]-choice_2-]
] If a syntax diagram becomes too large or too complex to be printed or

] shown, fragments of it are shown below the main diagram as details.
]
] >>----STATEMENT----required_variable--]----------------------]----------->
] ]-'optional_parameter'-]
] >--] FRAGMENT ]---------------------------------------------------------><
] FRAGMENT:
] ]--OPERAND--]--------------------]--]--------------------]--------------->
] ]-optional_choice_1a-] ]-optional_choice_2a-]
] ]-optional_choice_1b-] ]-optional_choice_2b-]
] >--]--------------------]--]--------------------]------------------------]
] The previous syntax diagram is equivalent to the following diagram:

]
] >>----STATEMENT----required_variable--]----------------------]----------->
] ]-'optional_parameter'-]
] >--OPERAND--]--------------------]--]--------------------]--------------->
] >--]--------------------]--]--------------------]-----------------------><
In a CLIST statement, use uppercase letters, numbers, and the set of

symbols listed below exactly as shown in the syntax.
apostrophe or single quote '

asterisk *
comma ,
equal sign =
parentheses ( )
period .
ampersand &
percent %
colon :
Lowercase letters and symbols appearing in the syntax represent variable

information for which you substitute specific information in the
statement. For example, if name appears in the syntax, substitute a
specific value (for example, ALPHA) for the variable when you enter the
statement.
Hyphens join lowercase words and symbols to form a single variable. For
example, if member-name appears in the syntax, substitute a specific value
(for example, BETA) for the variable in the statement.
Alphameric characters: unless otherwise indicated, an alphameric

character is one of the following:
Alphabetic: A-Z
Numeric: 0-9
Special: $ # @.
CLIST statements may be prefixed with a label consisting of 1-31

alphameric characters, beginning with an alphabetic character. The label
may appear on a separate line. A colon must immediately follow the label
name. For example,
label: +
IF A= ...
13.2 ATTN Statement
Use the ATTN statement to define a routine that TSO/E executes when the
user causes an attention interrupt. The attention interrupt halts
execution of a CLIST so that the user can terminate or alter its
processing.
]-OFF----]
>>--]--------]--ATTN--]-action-]----------------------------------------><
]-label:-]
label
A name the CLIST can reference in a GOTO statement to branch to this
ATTN statement. label is one-to-31 alphameric characters, beginning
with an alphabetic character.
OFF
Any previous attention action is nullified. Do not use ATTN OFF
within an attention routine.
action
specifies either:
1. One TSO/E command, commonly an EXEC command that invokes an

attention processing CLIST, or a null (blank) line. An attention
processing CLIST can execute multiple TSO/E commands, while the
action can execute only one.
2. A DO-END sequence constituting an attention exit routine. This

routine can contain CLIST statements, including the RETURN
statement or EXIT statement, and one TSO/E command, or a null
line.
If a null line is executed, TSO/E ignores the attention and execution

continues at the point where the interruption occurred.
If an EXIT statement is executed, the attention is ignored and the

CLIST is terminated.
If a TSO/E command is executed, control is given to the command.
Once a TSO/E command, an EXIT statement, or a null line is executed,

TSO/E ignores all other.
If the attention routine does anything other than terminate the CLIST,
use the MAIN operand of the CONTROL statement to protect the CLIST
from being flushed from the input stack when an attention interrupt
occurs. For more information, see "CONTROL Statement" in topic 13.4.
13.3 CLOSFILE Statement
Use the CLOSFILE statement to close a QSAM file that has been previously
opened by an OPENFILE statement. Only one file can be closed with each
CLOSFILE statement.
] Note: The CLOSFILE statement must be issued in the same CLIST as the
] corresponding OPENFILE statement.
>>--]--------]--CLOSFILE--]-file_name---------------]-------------------><
]-label:-] ]-&symbolic_variable_name-]
label
CLOSFILE statement. label is one-to-31 alphameric characters,
beginning with an alphabetic character.
file_name ] symbolic_variable_name
file_name is the file name (ddname) assigned to the file (data set)
when it was allocated in the current session.
symbolic_variable_name is the symbolic variable to which you assigned

file_name.
13.4 CONTROL Statement
Use the CONTROL statement to define processing options for a CLIST. The
options are in effect from the time CONTROL executes until either the
CLIST terminates or it issues another CONTROL statement.
You can also set CONTROL options on or off in the following variables:
&SYSPROMPT ON equals PROMPT, OFF equals NOPROMPT

&SYSSYMLIST ON equals SYMLIST, OFF equals NOSYMLIST
&SYSCONLIST ON equals CONLIST, OFF equals NOCONLIST
&SYSLIST ON equals LIST, OFF equals NOLIST
&SYSASIS ON equals ASIS, OFF equals CAPS
&SYSMSG ON equals MSG, OFF equals NOMSG
&SYSFLUSH ON equals FLUSH, OFF equals NOFLUSH.
CLISTs that do not issue CONTROL statements or one of the above variables
execute with the following options: NOPROMPT, NOSYMLIST, NOLIST,
NOCONLIST, CAPS, MSG, and FLUSH. The user can set PROMPT and LIST by
entering them as keywords on the EXEC command or subcommand issued to
invoke the CLIST.
CONTROL has no default operands. If you enter CONTROL with no operands,

the system uses options already defined by system default, the EXEC
command, or a previous CONTROL statement. In addition, when there are no
operands specified, the system displays those options currently in effect.
Note: CONTROL operands cannot be entered as symbolic variables.
>>--]--------]--CONTROL--]----------]--]-----------]--]--------]--------->
]-label:-] ]-PROMPT---] ]-SYMLIST---] ]-LIST---]
]-NOPROMPT-] ]-NOSYMLIST-] ]-NOLIST-]
>--]-----------]--]--------]--]-------]--]---------]--]------]----------->
]-CONLIST---] ]-CAPS---] ]-MSG---] ]-FLUSH---] ]-MAIN-]
]-NOCONLIST-] ]-NOCAPS-] ]-NOMSG-] ]-NOFLUSH-]
]-ASIS---]
>--]-------------]------------------------------------------------------><
]-END(string)-]
label
CONTROL statement. label is one-to-31 alphameric characters,
PROMPT ]NOPROMPT
PROMPT TSO/E commands in the CLIST may prompt the terminal for input.
(The PROMPT operand on the PROFILE command must also be in
effect.)
NOPROMPT TSO/E commands in the CLIST may not prompt the terminal for
input.
SYMLIST ] NOSYMLIST
SYMLIST Each executable statement is displayed at the terminal before

it is scanned for symbolic substitution. Executable statements
include commands, subcommands, and CLIST statements.
NOSYMLIST Executable statements are not displayed at the terminal

before symbolic substitution.
LIST ] NOLIST
LIST Commands and subcommands are displayed at the terminal after

symbolic substitution but before execution.
NOLIST Commands and subcommands are not displayed at the terminal.
CONLIST ] NOCONLIST
CONLIST CLIST statements are displayed at the terminal after symbolic

substitution but before execution.
NOCONLIST CLIST statements are not displayed at the terminal after

symbolic substitution.
CAPS ] NOCAPS ] ASIS
CAPS Character strings are converted to uppercase letters before being

processed.
NOCAPS or ASIS Character strings are not converted to uppercase before

being processed.
MSG ] NOMSG
MSG Informational messages from commands and statements in the CLIST
are displayed at the terminal.
NOMSG Informational messages from commands and statements in the CLIST

are not displayed at the terminal.
FLUSH ] NOFLUSH
FLUSH The system can erase (flush) the queue of nested CLISTs called
the input stack unless NOFLUSH or MAIN is encountered. The system
normally flushes the stack when an execution error occurs.
NOFLUSH The system cannot flush the CLIST when an error occurs.
: Note: To protect a CLIST from being flushed, the CLIST must

: contain an error routine.
MAIN
This is the main CLIST in your TSO/E environment and cannot be deleted
by a stack flush request from the system. When MAIN is specified, the
NOFLUSH condition is assumed for this CLIST, regardless of whether or
not FLUSH was in effect. This operand is required for CLISTs
containing attention routines that do anything other than terminate
the CLIST.
END(string)
A character string recognized by the CLIST as a replacement for an END
statement that concludes a DO or SELECT statement, or a subprocedure.
string is 1-4 alphameric characters, beginning with an alphabetic
character.
13.5 DATA-ENDDATA Sequence
Use the DATA-ENDDATA sequence when you do not want a command or subcommand
to be interpreted as a CLIST statement. The CLIST views the group of
commands and subcommands in the DATA-ENDDATA sequence as data to be
ignored and passed to TSO/E for execution.
Do not include CLIST statements in a DATA-ENDDATA sequence because TSO/E

attempts to execute them as commands or subcommands.
Symbolic substitution is performed before execution of the group.
<-----------------]
>>--]--------]--DATA----]-commands----]-]--ENDDATA----------------------><
]-label:-] ]-subcommands-]
label
DATA-ENDDATA sequence. label is one-to-31 alphameric characters,
commands ] subcommands
The data to be ignored and passed to TSO/E for execution.
13.6 DATA PROMPT-ENDDATA Sequence
Use the DATA PROMPT-ENDDATA sequence to designate responses to prompts by

TSO/E commands or subcommands. An error condition (error code 968) occurs
unless the sequence is immediately preceded by a command or subcommand
issuing a prompt.
>>--]--------]--DATA PROMPT--responses--ENDDATA-------------------------><
]-label:-]
Note: When using the DATA PROMPT-ENDDATA sequence, the following rules
apply:
* The CLIST must allow prompting.

* Symbolic substitution is performed before a reply is sent.
13.7 DO Statement
Use the DO statement to execute sequences of commands, subcommands, and

statements (DO-sequences). You can use the DO statement to execute
DO-sequences once, repeatedly, and when certain conditions are true.
To execute a DO-sequence once, include only the DO and END statements.
To execute a DO-sequence repeatedly, include a variable with a starting

value, a TO value, and, optionally, a BY value.
To execute a DO-sequence conditionally, include a WHILE or UNTIL clause.

The WHILE clause contains a leading decision and executes while a
comparative expression is true, and the UNTIL clause contains a trailing
decision and executes until a comparative expression is true.
To execute a DO-sequence repeatedly and conditionally (compound DO), the

WHILE and/or UNTIL clauses must follow the from, TO, and optional BY
clauses.
The DO statement indicates the beginning of a DO-sequence. The END

statement concludes the DO-sequence. If you want to use the TSO/E END
command in a DO-sequence, you must redefine the END statement, using the
END operand of the CONTROL statement.
>>--]--------]--DO------------------------------------------------------->
]-label:-]
>--]---------------------------------------------------------]----------->
] ] ]-BY--1--------] ]
] ]-variable--=--from_expr.--TO--to_expr.--]--------------]-]
] ] ]-BY--by_expr.-] ]
]-WHILE--condition----------------------------------------]
]-UNTIL--condition----------------------------------------]
>--(DO-sequence)--]--------]--END---------------------------------------><
]-label:-]
label
DO statement. label is one-to-31 alphameric characters, beginning
variable
A symbolic variable that controls execution of the DO-sequence. With
each execution, the variable value increases or decreases by a certain
amount. When the value passes a certain limit, the CLIST stops
executing the DO-sequence and executes the next instruction after the
END statement.
from_expression
A decimal integer, or an expression that evaluates to a decimal
integer, forming the initial value of the DO variable.
to_expression
integer, forming the terminal value of the DO variable.
by_expression
integer, by which the DO variable increases or decreases each time the
DO-sequence executes.
condition
A comparative expression or a sequence of comparative expressions
sequenced by logical operators. The expression or expressions can
include character data, including characters of the double-byte
character set.
In the absence of a BY clause, the value of the DO variable increases by 1

with each execution of the DO sequence.
If the by-expression evaluates to a negative number or consists of a

number beginning with a minus sign, the DO variable decreases by that
amount.
If the statements in a DO-sequence modify a DO variable, the CLIST uses

the new value in determining whether to repeat the DO-sequence.
DO-sequences can contain nested DO statements.
13.8 END Statement
Use the END statement to mark the end of a DO-sequence, a SELECT

statement, or a subprocedure. The END statement must appear on a line by
itself following the DO-sequence, SELECT statement, or subprocedure.
>>--END-----------------------------------------------------------------><
The END statement is distinct from the TSO/E END command. If you use both
the END statement and END command in a CLIST, you must distinguish them by
redefining the END statement. Using the CONTROL statement, you can
redefine the END statement as follows:
CONTROL END(string)
where string is 1-4 alphameric characters, beginning with an alphabetic

character. You then use the string in place of END statements in the
CLIST.
13.9 ERROR Statement
Use the ERROR statement to set up an environment that checks for non-zero
return codes from commands, subcommands, and CLIST statements in the
currently executing CLIST. When an error code is detected, processing
continues at the ERROR routine active for the command, subcommand, or
CLIST statement that registered the error. If an ERROR routine is not
active, the CLIST either terminates or continues, depending on the
severity of the error.
The error exit must be protected from being flushed from the input stack
by the system. Stack flushing makes the error return codes unavailable.
Use the MAIN or NOFLUSH operands of the CONTROL statement to prevent stack
flushing.
When ERROR is entered with no operands, the CLIST displays the command,
: subcommand, or statement in the CLIST that ended in error. No explanatory
: CLIST ERROR messages are displayed. &LASTCC is reset to 0 and the CLIST
: continues with the next sequential statement or command.
If the LIST option was requested for the CLIST, the null ERROR statement
is ignored.
The ERROR statement must precede any statements that might cause a branch
to it.
>>--]--------]--ERROR--]--------]---------------------------------------><
]-label:-] ]-OFF----]
]-action-]
label
ERROR statement. label is one-to-31 alphameric characters, beginning
OFF ] action
OFF Any action previously set up by an ERROR statement is nullified.
action Any executable statement, commonly a DO-sequence constituting a

routine. The action may execute TSO/E commands, subcommands, and
CLIST statements.
Note: Coding ERROR OFF within the DO-sequence routine itself

prevents the routine from returning control to the CLIST.
13.10 EXIT Statement
Use the EXIT statement to return control to the program that called the
currently executing CLIST. The return code associated with this exit can
be specified by the user or allowed to default to the value in control
variable &LASTCC.
A CLIST that is called by another CLIST is said to be nested. Multiple

levels of nesting are allowed. The structure of the nesting is called the
hierarchy. You go "up" in the hierarchy when control passes back to the
calling CLIST. TSO/E itself is at the top of the hierarchy.
Entering EXIT causes control to go up one level. When EXIT is entered

with the QUIT operand, the system attempts to pass control upward to the
first CLIST encountered that has MAIN or NOFLUSH in effect (see "CONTROL
Statement" in topic 13.4). If no such CLIST is found, control passes to
TSO/E, which flushes all CLISTs from the input stack and passes control to
the terminal.
>>--]--------]--EXIT--]------------------]--]------]--------------------><
]-label:-] ]-CODE(expression)-] ]-QUIT-]
label
EXIT statement. label is one-to-31 alphameric characters, beginning
CODE (expression)
: A CLIST-defined return code. expression must be a positive integer,
: zero, or an expression that evaluates to a decimal integer. When CODE
is not specified, the system uses the contents of &LASTCC.
QUIT
Control is passed up the nested hierarchy until either a CLIST is
found with the MAIN or NOFLUSH option active or TSO/E receives
control.
13.11 GETFILE Statement
Use the GETFILE statement to read a record from a QSAM file opened by the
OPENFILE statement. One record is obtained by each execution of GETFILE.
After GETFILE executes, the file name variable contains the record
obtained. If you use GETFILE to read data from the terminal, the data is
translated to uppercase.
] Note: The GETFILE statement must be issued in the same CLIST as the
>>--]--------]--GETFILE--file_name--------------------------------------><
]-label:-]
label
GETFILE statement. label is one-to-31 alphameric characters,
file_name
The file name (ddname) assigned to the file (data set) when it was
allocated in the current session. Do not specify a symbolic variable
containing the file name.
13.12 GLOBAL Statement
Use the GLOBAL statement to share values between nested CLISTs. In the
: hierarchy of nested CLISTs, the highest-level CLIST must contain a GLOBAL
: statement with the maximum number of variables used throughout the nested
: chain. Lower-level CLISTs must include a GLOBAL statement if they intend
: to refer to the global variables defined in the highest-level CLIST.
Note: The GLOBAL statement cannot be used to give a REXX exec access to a
CLIST's global variables. CLIST variables cannot be accessed by REXX
execs.
The global variables are positional, and the order is defined by the
GLOBAL statement in the highest-level CLIST. All lower-level CLISTs that
reference this same set of variables must follow this order to reference
the same values. The variable names may be unique to the lower-level
CLISTs. This means that the Nth name on any level GLOBAL statement refers
to the same value, even though the symbolic name at each level may be
different. For example, if a nested CLIST references the fifth global
variable, then it must define five global variables. If it references the
second global variable, then it needs to define only two global variables.
Multiple GLOBAL statements are cumulative. For example, if a CLIST has a

GLOBAL statement that defines three variables followed by another GLOBAL
statement that defines two variables, then five variables have been
defined. The second GLOBAL statement defines the fourth and fifth
variables.
The GLOBAL statement must precede any statement that uses or defines its
variables.
<--------------]
>>--]--------]--GLOBAL--variable_1----]----------]-]--------------------><
]-label:-] ]-variable-]
label
GLOBAL statement. label is one-to-31 alphameric characters, beginning
variable_1 / variable
A symbolic variable name for this CLIST. The name refers to a
variable that is either being created by this GLOBAL statement or that
was created by a GLOBAL statement in the highest-level CLIST.
13.13 GOTO Statement
Use the GOTO statement to cause an unconditional branch within a CLIST.

Branching to another CLIST is not allowed.
>>--]--------]--GOTO--]-target----]-------------------------------------><
]-label:-] ]-&variable-]
label
GOTO statement. label is one-to-31 alphameric characters, beginning
target ] variable
target A label on a statement or command.
variable A symbolic variable that contains a valid label.
GOTO statements cannot branch:
* To another CLIST
* To a subprocedure's PROC statement
* From one subprocedure to another
* From a subprocedure to the CLIST's main procedure.
13.14 IF-THEN-ELSE Sequence
Use the IF-THEN-ELSE sequence to define a condition, test the truth of

that condition, and initiate an action based on the test results. Do not
code THEN and ELSE on the same logical line.
>>--]--------]--IF--logical_expression--THEN--]--------]----------------->
]-label:-] ]-action-]
>--]------------------]-------------------------------------------------><
]-ELSE-]--------]--]
]-action-]
label
IF-THEN-ELSE sequence. label is one-to-31 alphameric characters,
logical_expression
A comparative expression or a sequence of comparative expressions
sequenced by logical operators. The expression or expressions can
include character data, including characters of the double-byte
character set.
action
An executable command, subcommand, or CLIST statements. (Enclose an
action consisting of more than one statement in a DO-sequence.) The
THEN action is invoked if the logical expression is true. The ELSE
action is invoked if the logical expression is false. If a null THEN
or null ELSE statement is executed, control passes to the next
sequential statement after the IF-THEN-ELSE sequence.
The action must be on the same line as a THEN or ELSE clause, or be

joined to the line by a continuation character. For example, the
following are correct:
IF &FOOTPRINT = 0 THEN SET ECODE = 4
IF &FOOTPRINT = 0 THEN +
SET ECODE = 4
IF &FOOTPRINT = 0 THEN +
DO
SET ECODE = 4
.
.
.
END
13.15 LISTDSI Statement
Use the LISTDSI statement to obtain information about a data set that is
available on DASD. The LISTDSI statement can retrieve information about a
data set's allocation, protection, and directory, and store the
information in CLIST variables.
The LISTDSI statement does not support data that is on tape. The LISTDSI
statement supports generation data group (GDG) data sets, but does not
support relative GDG names.
The CLIST can use the LISTDSI information to determine whether the data
set is the right size or has the right organization or format for a given
task. It can also use the LISTDSI information as input to the ALLOCATE
command, to create a new data set using some attributes from the old data
set while modifying others.
If you use LISTDSI to retrieve information about a VSAM data set, the
] CLIST stores only the volume serial ID (in variable &SYSVOLUME), the
] generic device type (in variable &SYSUNIT), and the data set organization
(in variable &SYSDSORG). The CLIST sets all other LISTDSI variables to
question marks.
If you use LISTDSI to retrieve information about a multiple volume data

set, the CLIST stores information for the first volume only. Similarly,
if you specify a file name or the PREALLOC parameter and you have other
data sets allocated to the same file name, then the system might not
retrieve information for the data set you wanted.
: Note: LISTDSI considers file names in the form SYSnnnnn as

: system-generated file names. If LISTDSI is used to obtain information
: about a data set that was pre-allocated multiple times using a file name
: of the form SYSnnnnn, an existing file may be unintentionally freed.
: To suppress TSO/E messages issued by the LISTDSI statement, use the

: CONTROL NOMSG statement. For information about the CONTROL statement, see
: "CONTROL Statement" in topic 13.4.
] >>--]--------]--LISTDSI--]-data_set_name--]-------------------]-]-------->
] ]-label:-] ] ]-VOLUME(serial_id)-] ]
] ] ]-PREALLOC----------] ]
] ]-file_name--FILE----------------------]
] ]-NODIRECTORY-] ]-NOSMSINFO-]
>--]-DIRECTORY---]--]-----------]--]----------]-------------------------><
] ]-SMSINFO---] ]-RECALL---]
] ]-NORECALL-]
label
LISTDSI statement. label is one-to-31 alphameric characters,
data_set_name ] file_name
data_set_name The name of the data set about which you want to
retrieve information.
file_name The name of an allocated file (ddname) about which you want
to retrieve information.
VOLUME(serial_id) ] PREALLOC
VOLUME(serial_id) specifies the serial number of the volume where the

data set is located. If you do not specify either VOLUME or
PREALLOC, the system locates the data set through catalog search.
PREALLOC specifies that the location of the specified data set is

determined by allocating the data set, rather than through a
catalog search. PREALLOC allows data sets that have been
previously allocated to be located without searching a catalog and
allows unmounted volumes to be mounted.
] If you do not specify either VOLUME or PREALLOC, the system locates

] the data set through catalog search.
] If you specify a file_name, LISTDSI ignores the VOLUME and PREALLOC

] parameters.
FILE
specifies that you provided a file_name instead of a data_set_name.
If you do not specify FILE, LISTDSI assumes that you provided a data
set name.
DIRECTORY ] NODIRECTORY
DIRECTORY indicates that you want directory information for a

partitioned data set.
NODIRECTORY indicates that you do not want directory information for a

partitioned data set. If you do not require directory
information, NODIRECTORY can significantly speed up processing.
NODIRECTORY is the default.
] SMSINFO ] NOSMSINFO
] indicates whether you want SMS information about an SMS-managed data
] set, like the type of data set, the used space, the data -, storage -,
] and management class names. See also Figure 13-1.
] SMSINFO indicates that you want SMS information about data_set_name or

] file_name.
] If the specified data set is not managed by SMS, LISTDSI
] continues, but no SMS information is provided in the appropriate
] CLIST variables.
] Specify SMSINFO only if you want SMS information about a data set.
] NOSMSINFO (the default) significantly reduces the execution time
] of the LISTDSI statement.
] NOSMSINFO indicates that you do not want SMS information about the
] specified data set. NOSMSINFO is the default.
RECALL ] NORECALL
RECALL indicates that you want to recall a data set migrated by HSM.
The system recalls the data set regardless of its level of
migration or the type of device it has been migrated to.
NORECALL indicates that you do not want to recall a data set. If the
data set has been migrated, the system displays an error message.
] If you do not specify either RECALL or NORECALL, the system recalls

] the data set only if it has been migrated to a direct access storage
] device (DASD).
: The LISTDSI function issues message IKJ56709I if a syntactically invalid

: data set name is passed to the function. To prevent this message from
: being displayed, use CONTROL NOMSG.
: --------------------------------------------------------------------
: PROC 0
: SET DSNAME = ABCDEFGHIJ.XYZ /* Syntactically invalid name,
: /* because a qualifier is longer
: /* than 8 characters
: CONTROL NOMSG /* Set OFF to suppress any LISTDSI
: /* TSO/E messages
: LISTDSI &DSNAME /* Obtain data set information
: WRITE Return code from LISTDSI is ==> &LASTCC
: EXIT CODE(0)
: --------------------------------------------------------------------
CLIST Variables Set by LISTDSI
Figure 13-1 describes the contents of the CLIST variables set by LISTDSI.
For VSAM data sets, only the variables &SYSVOLUME, &SYSUNIT, and &SYSDSORG
are accurate; all other variables are set to question marks.
]------------------------------------------------------------------------]
] Figure 13-1. Variables Set by LISTDSI ]
]--------------------]---------------------------------------------------]
] Variable ] Contents ]
]--------------------]---------------------------------------------------]
] &SYSDSNAME ] Data set name ]
]--------------------]---------------------------------------------------]
] &SYSVOLUME ] Volume serial ID ]
]--------------------]---------------------------------------------------]
] ] &SYSUNIT ] Generic device type on which volume resides, for ]
] ] ] example, "3390". ]
]--------------------]---------------------------------------------------]
] &SYSDSORG ] Data set organization: ]
] ] ]
] ] PS Physical sequential ]
] ] PSU Physical sequential unmovable ]
] ] DA Direct organization ]
] ] DAU Direct organization unmovable ]
] ] IS Indexed sequential ]
] ] ISU Indexed sequential unmovable ]
] ] PO Partitioned organization ]
] ] POU Partitioned organization unmovable ]
] ] VS VSAM ]
] ] ??? Unknown ]
]--------------------]---------------------------------------------------]
: ] &SYSRECFM ] Record format; 1- to 6-character combination of ]
: ] ] the following: ]
] ] ]
: ] ] U Records of undefined length ]
: ] ] F Records of fixed length ]
: ] ] V Records of variable length ]
: ] ] T Records written with the track overflow ]
: ] ] feature of the device (3375, 3380, and ]
: ] ] 3390 do not support track overflow) ]
: ] ] B Records blocked ]
: ] ] S Records written as standard or spanned ]
: ] ] variable-length blocks ]
: ] ] A Records contain ASCII control characters ]
: ] ] M Records contain machine code control ]
: ] ] characters ]
: ] ] ?????? Unknown ]
]--------------------]---------------------------------------------------]
] &SYSLRECL ] Logical record length ]
]--------------------]---------------------------------------------------]
] &SYSBLKSIZE ] Block size ]
]--------------------]---------------------------------------------------]
] &SYSKEYLEN ] Key length ]
]--------------------]---------------------------------------------------]
] &SYSALLOC ] Allocation, in space units ]
]--------------------]---------------------------------------------------]
] ] &SYSUSED ] Allocation used, in space units. For a ]
] ] ] partitioned data set extended (PDSE) "N/A" will ]
] ] ] be returned; see the description of the ]
] ] ] &SYSUSEDPAGES for used space of a PDSE. ]
]--------------------]---------------------------------------------------]
] ] &SYSUSEDPAGES((1)) ] The used space of a partitioned data set extended ]
] ] ] (PDSE) in 4K pages. A value is returned only if ]
] ] ] the SMSINFO keyword operand is provided with the ]
] ] ] LISTDSI statement. ]
]--------------------]---------------------------------------------------]
] &SYSPRIMARY ] Primary allocation in space units ]
]--------------------]---------------------------------------------------]
] &SYSSECONDS ] Secondary allocation in space units ]
]--------------------]---------------------------------------------------]
] &SYSUNITS ] Space units: ]
] ] ]
] ] CYLINDER Space units in cylinders ]
] ] TRACK Space units in tracks ]
] ] BLOCK Space units in blocks ]
] ] ???????? Space units are unknown ]
]--------------------]---------------------------------------------------]
: ] &SYSEXTENTS ] Number of extents allocated ]
]--------------------]---------------------------------------------------]
] &SYSCREATE ] Creation date in Year/day format, for example: ]
] ] 1985/102. ]
]--------------------]---------------------------------------------------]
] &SYSREFDATE ] Last referenced date in Year/day format, for ]
] ] example: 1995/107. ]
] ] ] (Specifying DIRECTORY causes the date to be ]
] ] ] updated) ]
]--------------------]---------------------------------------------------]
] &SYSEXDATE ] Expiration date in Year/day format, for example: ]
] ] 1995/365. ]
]--------------------]---------------------------------------------------]
] &SYSPASSWORD ] Password indication: ]
] ] ]
] ] NONE No password protection ]
] ] READ Password required to read ]
] ] WRITE Password required to write ]
]--------------------]---------------------------------------------------]
] &SYSRACFA ] RACF indication: ]
] ] ]
] ] NONE No RACF protection ]
] ] GENERIC Generic profile covers this data set ]
] ] DISCRETE Discrete profile covers this data set ]
]--------------------]---------------------------------------------------]
] &SYSUPDATED ] Change indicator: ]
] ] ]
] ] YES Data set has been updated ]
] ] NO Data set has not been updated ]
]--------------------]---------------------------------------------------]
] &SYSTRKSCYL ] Tracks per cylinder for the unit identified in ]
] ] the &SYSUNIT variable ]
]--------------------]---------------------------------------------------]
] ] &SYSBLKSTRK ] Blocks of &SYSBLKSIZE per track for the unit ]
] ] ] identified in the &SYSUNIT variable ]
]--------------------]---------------------------------------------------]
] &SYSADIRBLK ] Directory blocks allocated - returned only for ]
] ] ] partitioned data sets when DIRECTORY is ]
] ] ] specified. For a partitioned data set extended ]
] ] ] (PDSE) "NO_LIM" will be returned because there is ]
] ] ] no static allocation for its directory. ]
]--------------------]---------------------------------------------------]
] &SYSUDIRBLK ] Directory blocks used - returned only for ]
] ] ] partitioned data sets when DIRECTORY is ]
] ] ] specified. For a partitioned data set extended ]
] ] ] (PDSE) "N/A" will be returned because it is not a ]
] ] ] static value. ]
]--------------------]---------------------------------------------------]
] &SYSMEMBERS ] Number of members - returned only for partitioned ]
] ] data sets when DIRECTORY is specified ]
]--------------------]---------------------------------------------------]
] &LASTCC ] LISTDSI return code ]
]--------------------]---------------------------------------------------]
] &SYSREASON ] LISTDSI reason code ]
]--------------------]---------------------------------------------------]
] &SYSMSGLVL1 ] First level message if an error occurred ]
]--------------------]---------------------------------------------------]
] &SYSMSGLVL2 ] Second level message if an error occurred ]
]--------------------]---------------------------------------------------]
] ] &SYSDSSMS((1)) ] Contains information about the type of a data ]
] ] ] set, provided by DFSMS/MVS. ]
] ] ]
] ] ] If the SMSINFO keyword operand on the LISTDSI ]
] ] ] statement is not specified, or SMS DSNTYPE ]
] ] ] information could not be retrieved, the &SYSDSSMS ]
] ] ] variable contains: ]
] ] ]
] ] ] SEQ for a sequential data set ]
] ] ] PDS for a partitioned data set ]
] ] ] PDSE for a partitioned data set extended. ]
] ] ]
] ] ] If the SMSINFO keyword operand on the LISTDSI ]
] ] ] statement is specified, and the data set is a ]
] ] ] PDSE, the &SYSDSSMS variable contains: ]
] ] ]
] ] ] LIBRARY for an empty PDSE ]
] ] ] PROGRAM_LIBRARY for a partitioned data set ]
] ] ] extended program library ]
] ] ] DATA_LIBRARY for a partitioned data set ]
] ] ] extended data library. ]
]--------------------]---------------------------------------------------]
] ] &SYSDATACLASS((1)) ] The SMS data class name - returned only if ]
] ] ] SMSINFO is specified on the LISTDSI statement and ]
] ] ] the data set is managed by SMS. ]
]--------------------]---------------------------------------------------]
] ] &SYSSTORCLASS((1)) ] The SMS storage class name - returned only if ]
]--------------------]---------------------------------------------------]
] ] &SYSMGMTCLASS((1)) ] The SMS management class name - returned only if ]
]--------------------]---------------------------------------------------]
] ] Note: ]
] ]
] ] 1. These variables, introduced with TSO/E 2.5, require either MVS/DFP ]
] ] 3.2 (or later) or DFSMS/MVS 1.1 (or later) to be active on your ]
] ] system. For data sets not managed by SMS these variables return a ]
] ] null string. ]
]------------------------------------------------------------------------]
Return Codes
Return codes from the LISTDSI statement appear in CLIST variable &LASTCC.
Error routines do not receive control when a CLIST receives a non-zero
return code from LISTDSI. Figure 13-2 lists the LISTDSI return codes and
their meanings.
]--------------------------------------------------------------------------]
] Figure 13-2. LISTDSI Return Codes ]
]---------------]----------------------------------------------------------]
] Return Code ] Meaning ]
]---------------]----------------------------------------------------------]
] 0 ] Processing successful ]
]---------------]----------------------------------------------------------]
] 4 ] Some data set information is unavailable. All data set ]
] ] information other than directory information can be ]
] ] considered valid. ]
]---------------]----------------------------------------------------------]
] 16 ] Processing unsuccessful. None of the CLIST variables ]
] ] can be considered valid. ]
]---------------]----------------------------------------------------------]
Reason Codes
Reason codes from the LISTDSI statement appear in CLIST variable

&SYSREASON. Figure 13-3 lists the LISTDSI reason codes and their
meanings.
]--------------------------------------------------------------------------]
] Figure 13-3. LISTDSI Reason Codes ]
]---------------]----------------------------------------------------------]
] Reason Code ] Meaning ]
]---------------]----------------------------------------------------------]
] 0 ] Normal completion ]
]---------------]----------------------------------------------------------]
] 1 ] Error parsing the statement. ]
]---------------]----------------------------------------------------------]
] 2 ] Dynamic allocation processing error (SVC 99 error). ]
]---------------]----------------------------------------------------------]
] 3 ] The data set is a type that cannot be processed. ]
]---------------]----------------------------------------------------------]
] 4 ] Error determining UNIT name (IEFEB4UV error). ]
]---------------]----------------------------------------------------------]
] 5 ] Data set not cataloged (LOCATE macro error). ]
]---------------]----------------------------------------------------------]
: ] 6 ] Error obtaining the data set attributes (OBTAIN macro ]
: ] ] error). ]
]---------------]----------------------------------------------------------]
] 7 ] Error finding device type (DEVTYPE macro error). ]
]---------------]----------------------------------------------------------]
] 8 ] The data set does not reside on a direct access device. ]
]---------------]----------------------------------------------------------]
] 9 ] DFHSM migrated the data set, NORECALL prevents ]
] ] retrieval. ]
]---------------]----------------------------------------------------------]
] 11 ] Directory information was requested, but you lack ]
] ] authority to access the data set. ]
]---------------]----------------------------------------------------------]
] 12 ] VSAM data sets are not supported. ]
]---------------]----------------------------------------------------------]
] 13 ] The data set could not be opened. ]
]---------------]----------------------------------------------------------]
] 14 ] Device type not found in unit control block (UCB) ]
] ] tables. ]
]---------------]----------------------------------------------------------]
] 17 ] System or user abend occurred. ]
]---------------]----------------------------------------------------------]
] 18 ] Partial data set information was obtained. ]
]---------------]----------------------------------------------------------]
] 19 ] Data set resides on multiple volumes. ]
]---------------]----------------------------------------------------------]
] 20 ] Device type not found in eligible device table (EDT). ]
]---------------]----------------------------------------------------------]
] 21 ] Catalog error trying to locate the data set. ]
]---------------]----------------------------------------------------------]
] 22 ] Volume not mounted (OBTAIN macro error). ]
]---------------]----------------------------------------------------------]
] 23 ] Permanent I/O error on volume (OBTAIN macro error). ]
]---------------]----------------------------------------------------------]
] 24 ] Data set not found by OBTAIN macro. ]
]---------------]----------------------------------------------------------]
] 25 ] Data set migrated to non-DASD device. ]
]---------------]----------------------------------------------------------]
] 27 ] No volume serial is allocated to the data set. ]
]---------------]----------------------------------------------------------]
] 28 ] ddname must be one to eight characters. ]
]---------------]----------------------------------------------------------]
] 29 ] Data set name or ddname must be specified. ]
]---------------]----------------------------------------------------------]
13.16 NGLOBAL Statement
Use the NGLOBAL statement to share values between subprocedures in a

CLIST.
The NGLOBAL (named global) statement defines variables by name. When you
define an NGLOBAL variable, other subprocedures in the same CLIST can
refer to it by name and modify its value. Other CLISTs cannot access or
modify an NGLOBAL variable.
There is no limit to the number of variables that can be defined on an

NGLOBAL statement. The NGLOBAL statement must precede any statement that
uses its variables.
<--------------]
>>--]--------]--NGLOBAL--variable_1----]----------]-]-------------------><
label
NGLOBAL statement. label is one-to-31 alphameric characters,
A symbolic variable name for this CLIST. The name refers to a
variable that is being defined by this NGLOBAL statement.
Note: Variables named on an NGLOBAL statement cannot appear on a PROC

statement.
13.17 OPENFILE Statement
Use the OPENFILE statement to open a QSAM file for I/O. The file must
have been allocated during the session and assigned a file name. Each
execution of OPENFILE can open only one file, and files cannot be open for
different members of the same PDS at the same time. The files must
represent data sets with logical record lengths no greater than 32767
bytes.
Note: The OPENFILE statement sets any I/O variables to nulls. Always
execute the OPENFILE statement before using any SET statements to create
I/O records.
Complete your file I/O on a specific file before changing from command to
subcommand mode and vice versa. Cross-mode file I/O is not supported and
causes unpredictable abnormal terminations.
Specify NOFLUSH for a CLIST that uses file I/O. (See the CONTROL
statement.) If a system action causes TSO/E to flush the input stack
because you did not specify NOFLUSH, a user may have to log off the system
to recover. The user will recognize the condition by receiving a message
similar to "FILE NOT FREED, DATA SET IS OPEN.".
]-INPUT--]
>>--]--------]--OPENFILE--]-file_name---------------]--]-OUTPUT-]-------><
]-label:-] ]-&symbolic_variable_name-] ]-UPDATE-]
label
OPENFILE statement. label is one-to-31 alphameric characters,
file_name ] symbolic_variable_name
file_name The file name (ddname) you assigned to the file (data set)
when allocating it in the current session.
symbolic_variable_name The symbolic variable to which you assigned

file_name.
INPUT ] OUTPUT ] UPDATE
INPUT Open the file for input.
OUTPUT Open the file for output.
UPDATE Open the file for updating in place; that is, the CLIST can
execute GETFILE and PUTFILE statements before closing the file.
13.18 PROC Statement
Use the PROC statement to:

* Define parameters to be passed on the EXEC command to the CLIST. In

this case PROC is optional, but if you use it, it must be the first
executable statement in the CLIST.
* Define a subprocedure and any parameters passed on the SYSCALL

statement to the subprocedure. A subprocedure must begin with a PROC
statement. In this case the PROC statement must have a label, and a
corresponding END statement to mark the end of the subprocedure.
<--------------------------]
>>--]--------]--PROC--positional_number----]----------------------]-]---->
]-label:-] ]-positional_parameter-]
<----------------------------------------------]
>----keyword_parameter-]-----------------------]--]--]-----]------------><
]-(-]---------------]-)-] ]-END-]
]-default_value-]
label
A name the CLIST can reference in a SYSCALL statement to pass control
to this PROC statement. Required on PROC statements that begin
subprocedures, label is one-to-31 alphameric characters, beginning
positional_number
The number of required positional parameters to be passed. Enter 1-5
decimal digits. If none, enter 0.
positional_parameter
A positional parameter passed to the CLIST or subprocedure.
A positional parameter name may be 1-252 alphameric characters in

length, beginning with an alphabetic character. Lowercase values are
changed to uppercase.
If the name of a positional parameter on the PROC statement is the

same as the name of a GLOBAL variable, an error occurs.
keyword_parameter
A keyword parameter passed to the CLIST or subprocedure.
A keyword parameter name can be 1-31 alphameric characters in length,

beginning with an alphabetic character, and cannot contain the
character underscore (_). Lowercase values are changed to uppercase.
default_value
The value assigned to the corresponding variable in the CLIST or
subprocedure if the user does not specify a value on the associated
keyword on the EXEC command or SYSCALL statement.
If the value is omitted (empty parentheses) the user may supply a

value on the associated keyword on the EXEC command or SYSCALL
statement.
Note: Symbolic substitution does not occur for default values of a

keyword parameter.
All parameters have an initial value at the time the CLIST or subprocedure
begins execution. Each parameter name becomes the name of a symbolic
variable that has the initial value of the associated parameter. The
values of passed parameters are in effect only while the CLIST or
subprocedure is active. Values passed in lowercase are converted to
uppercase by the exec command.
13.19 PUTFILE Statement
Use the PUTFILE statement to write a record to an open QSAM file. Each
execution of PUTFILE writes one record. Unless the user wants the same
record sent more than once, the file name variable must be assigned a
different record using an assignment statement before the next PUTFILE
statement is issued.
] Note: The PUTFILE statement must be issued in the same CLIST as the
>>--]--------]--PUTFILE--file_name--------------------------------------><
]-label:-]
label
PUTFILE statement. label is one-to-31 alphameric characters,
file_name
The file name (ddname) assigned to the file (data set) when it was
allocated in the current session. Do not specify a symbolic variable
containing the file name.
13.20 READ Statement
Use the READ statement to read input from the terminal and store it in
symbolic variables. These variables may be defined on the READ statement
or elsewhere in the CLIST. The READ statement is usually preceded by a
WRITE or WRITENR statement that requests the user to enter the expected
input at the terminal.
>>--]--------]--READ--]------------------------------]------------------><
]-label:-] ] <--------------] ]
]-variable_1---]----------]-]--]
]-variable-]
label
READ statement. label is one-to-31 alphameric characters, beginning
Any valid variable name. The variables are positional in that values
in the input data entered by the terminal user are stored sequentially
into the specified variables.
If the operand is omitted the input is stored in the &SYSDVAL control

variable.
13.21 READDVAL Statement
Use the READDVAL statement to assign the current contents of the &SYSDVAL
control variable to one or more specified symbolic variables.
The assignment is done sequentially to the variables in the order

specified; variables not assigned values default to null values. If there
are more values than variables, the excess values from &SYSDVAL are not
assigned.
<--------------]
>>--]--------]--READDVAL--variable_1----]----------]-]------------------><
label
provides a name the CLIST can reference in a GOTO statement to branch
to this READDVAL statement. label is one-to-31 alphameric characters,
Any valid variable name. A variable need not have been previously
defined.
13.22 RETURN Statement
Use the RETURN statement to:
* Return control from an error routine or an attention routine to the

statement following the one that ended in error or the one that was
interrupted by an attention.
* Provide a return code from a subprocedure. Control will pass to the

statement following the SYSCALL statement that called the
subprocedure. The return code is stored in the control variable
&LASTCC. (Note, however, that return codes from CLIST subprocedures
do not cause an error routine to receive control.)
RETURN is valid only when issued from a subprocedure, an activated error

routine, or an activated attention routine. If issued from any other
place, RETURN is treated as a no-operation.
>>--]--------]--RETURN--]------------------------]----------------------><
] ]-label:-] ]-CODE(-]------------]-)-]
] ]-expression-]
label
RETURN statement. label is one-to-31 alphameric characters, beginning
CODE
Subprocedures can issue a return code. Control will pass to the
statement following the SYSCALL statement that called the
subprocedure.
expression
A CLIST-defined return code. expression can be a character string, a
decimal integer, or an expression that evaluates to a decimal integer.
The expression is stored in the control variable &LASTCC. If CODE
appears without an expression, &LASTCC takes a null value.
13.23 SELECT Statement
Use the SELECT statement to conditionally perform one of several

alternative actions. There are two forms of the SELECT statement: the
simple SELECT and the compound SELECT.
Simple SELECT
In the simple SELECT statement, the CLIST tests one or more expressions.
When the CLIST finds an expression that evaluates to a true value, the
CLIST performs the associated action, then passes control to the END
statement. If none of the expressions are true, the CLIST performs the
action on the OTHERWISE clause, if any, or passes control to the END
statement.
<----------------------------------------]
>>--]--------]--SELECT----WHEN--(logical_expression)--]--------]-]------->
]-label:-] ]-action-]
>--]-------------------]--]--------]--END-------------------------------><
]-OTHERWISE--action-] ]-label:-]
label
SELECT statement. label is one-to-31 alphameric characters, beginning
logical_expression
A comparative expression, such as &A = 3 or &B ^&gtsym 10, that
evaluates to a true or false condition.
action
Any CLIST statement, TSO/E command, or DO sequence. A null action
passes control to the END statement. The action can include nested
IF, DO, and SELECT statements. Any statements in the action can have
labels, allowing GOTO statements to branch to them.
Compound SELECT
A compound SELECT statement includes an initial test expression. The

CLIST evaluates the test expression and compares its value to those of the
WHEN expressions.
In a compound SELECT statement, a WHEN expression can contain multiple

expressions separated by the logical operator ] (OR). WHEN expressions
can also include ranges of values, represented by a colon (:) between the
lowest and highest values of the range. For example, 3:5 represents 3, 4,
and 5.
When a test expression matches a value or falls within a range of values

in a WHEN expression, the CLIST performs the associated action and passes
control to the END statement. If no matches are found, the CLIST performs
the action on the OTHERWISE clause, if any, or passes control to the END
statement.
>>--]--------]--SELECT--test_expression---------------------------------->
]-label:-]
] <------------------------------------------------------------]
] >----WHEN--(--expression--]--------------------]--)--]--------]-]-------->
] ]--]-:--]-expression-] ]-action-]
] ]-]--]
] ]-OR-]
>--]-------------------]--]--------]--END-------------------------------><
]-OTHERWISE--action-] ]-label:-]
label
SELECT statement. label is one-to-31 alphameric characters, beginning
test_expression
A character string or a logical expression that results in a value to
be compared to the expressions in the WHEN clauses.
expression
A character string, a single logical expression, or a range such as
1:5. Values and ranges can be combined, for example: WHEN (&A-3 ] &B
] 4:6)
action
Any CLIST statement, TSO/E command, or DO sequence. A null action
passes control to the END statement. The action can include nested
IF, DO, and SELECT statements. Any statements in the action can have
labels of their own.
13.24 SET Statement
Use the SET statement to assign a value to a symbolic variable or a

control variable.
>>--]--------]--SET--]---]--]-symbolic_variable_name-]--]-=--]--value---><
] ]-label:-] ]-&-] ]-&control_variable_name-] ]-EQ-]
label
SET statement. label is one-to-31 alphameric characters, beginning
symbolic_variable_name ] control_variable_name
symbolic_variable_name The symbolic variable to which you are

assigning a value.
control_variable_name The control variable to which you are assigning

a value. (See Figure 5-2 in topic 5.1 for those control variables
that you can modify.)
EQ ] =
The operator 'equal'.
value
Any valid numeric value or character string.
13.25 SYSCALL Statement
Use the SYSCALL statement to pass control to a subprocedure. The SYSCALL

statement contains the name of the subprocedure and any parameters to be
passed. The name of the subprocedure must match the label on the PROC
statement that begins the subprocedure.
>>--]--------]--SYSCALL--procname--]--------------------------------]---><
]-label:-] ] <---------------] ]
]-parameter_1---]-----------]-]--]
]-parameter-]
label
SYSCALL statement. label is one-to-31 alphameric characters,
procname
The label of the PROC statement that begins the subprocedure.
parameter_1 / parameter
Any valid CLIST expression, including constants, symbolic variables,
built-in functions, and arithmetic expressions. All parameters are
separated by CLIST delimiters (blanks, commas, or tabs). For
information about how to pass a parameter that contains blanks, see
"Calling a Subprocedure" in topic 7.3.
If the parameter is the name of a variable that is referenced on a

SYSREF statement in the subprocedure, the variable name must not
include an ampersand on the SYSCALL statement.
The PROC statement of the subprocedure is responsible for defining

variables to receive the parameters.
SET &A = John

SET &B = AL
]--SYSCALL XYZ &A B /* pass variables to XYZ, omitting & from
] . <--------------] /* the variable name referenced on SYSREF
] WRITE &B ] /* result: GEORGE
] . ]
v . ]
XYZ: PROC 2 PARM1 PARM2 ] /* Subprocedure XYZ */
. ]
SYSREF &PARM2 ] /* indicate PARM2 holds a variable name
WRITE &PARM2 ] /* result: AL
SET &PARM2 = GEORGE ]
END--------------------]
13.26 SYSREF Statement
Use the SYSREF statement in a subprocedure to identify the names of

variables, passed from the caller, whose values the subprocedure can
reference and modify. When you assign a new value to a SYSREF variable,
the new value is retroactive; that is, the new value takes effect in the
caller as well as in the subprocedure.
On the SYSREF statement in the subprocedure, list the PROC statement

parameter that corresponds to the variable name that the caller passed.
The SYSREF statement must precede any subprocedure statement that uses its
variables.
>>--]--------]--SYSREF--]------------------------------]----------------><
]-label:-] ] <--------------] ]
]-variable_1---]----------]-]--]
]-variable-]
label
SYSREF statement. label is one-to-31 alphameric characters, beginning
The name of a parameter from the PROC statement. The parameters
correspond to variable names that were passed to the PROC statement.
Ampersands (&) are optional on the variable name.
In the following example, the subprocedure assigns a new value to the

variable whose name was passed (B). The new value (GEORGE) replaces the
variable's old value (AL) in the caller.
SET &A = John
SET &B = AL
]--SYSCALL XYZ &A B /* pass variables to XYZ, omitting & from
] . <--------------] /* the variable name referenced on SYSREF
] WRITE &A ] /* result: JOHN (original value)
] WRITE &B ] /* result: GEORGE (changed value)
v . ]
XYZ: PROC 2 PARM1 PARM2 ] /* Subprocedure XYZ */
. ]
SET &parm1 = Joe ] /* change value of &parm1
WRITE &parm1 ] /* result: JOE
SYSREF &PARM2 ] /* indicate PARM2 holds a variable name
WRITE &PARM2 ] /* result: AL
SET &PARM2 = GEORGE ] /* change value of SYSREF variable
END--------------------]
13.27 TERMIN and TERMING Statement
: Use the TERMIN or TERMING statement to pass control from the CLIST to the
: terminal user. You can also use TERMIN or TERMING to define the character
strings, including a null line, that a user enters to return control to
the CLIST. TERMIN is usually preceded by a WRITE statement that requests
the expected response from the terminal user.
: The TERMIN or TERMING statement ends a CLIST when you issue a CLIST in any
: of the following ways:
: * Under ISPF
: * In the background
: * From a REXX exec (a nested CLIST).
: Control returns to the CLIST at the statement after TERMIN or TERMING.

When control returns, &SYSDLM and &SYSDVAL have been set.
>>--]--------]--]-TERMIN--]--]--------------------------]---------------->
]-label:-] ]-TERMING-] ]-string_1-]------------]--]
] ]-user_input-] ]
]-,------------------------]
<----------------------------]
>----]------------------------]-]---------------------------------------><
]-string-]------------]--]
] ]-user_input-] ]
]-,----------------------]
label
TERMIN statement. label is one-to-31 alphameric characters, beginning
: TERMIN ] TERMING
: transfers control to the terminal and establishes a means for the user
: to return control to the CLIST.
: TERMIN A CLIST executed from the TERMIN is not considered nested

: within the CLIST that issued the TERMIN statement, which has the
: following effects:
: * Sharing GLOBAL variables - GLOBAL variables cannot be shared

: across the TERMIN. Global variable sharing between the CLIST
: executed from the TERMIN and the CLIST that issued the TERMIN
: is not allowed.
: * Variable access - variable access across the TERMIN cannot be

: communicated through the CLIST variable access routine
: IKJCT441.
] * Checking command output trapping (&SYSOUTTRAP) - IKJCT441 and

: IRXEXCOM do not recognize CLISTs or REXX execs on opposing
: sides of a TERMIN element.
: * CONTROL NOMSG statement - checking the NOMSG setting on

: opposing sides of a TERMIN element is not allowed.
: TERMING A CLIST executed from the TERMING is considered nested within

: the CLIST that issued the TERMING statement, which has the
: following effects:
: * Sharing GLOBAL variables - GLOBAL variables can be shared

: across the TERMING. Global variable sharing between the CLIST
: executed from the TERMING and the CLIST that issued the
: TERMING is allowed.
: * Variable access - variable access across the TERMING can be

: communicated through the CLIST variable access routine
: IKJCT441.
] * Checking command output trapping (&SYSOUTTRAP) - IKJCT441 and

: IRXEXCOM recognize CLISTs or REXX execs on opposing sides of a
: TERMING element.
: * CONTROL NOMSG statement - checking the NOMSG setting on

: opposing sides of a TERMING element is allowed.
string_1 / string
A character string that the terminal user enters to return control to
the CLIST. The &SYSDLM control variable contains a number
corresponding to the position of the string that the user entered (1
for stringâ1ã, 2 for stringâ2ã, etc.).
user_input
Additional input entered by the terminal user. The input is stored in
the &SYSDVAL control variable.
,
If you specify a comma in place of a string, the terminal user can
enter a null line (press the ENTER key) to return control to the
CLIST.
If no operands are specified the terminal user enters a null line to

return control to the CLIST.
13.28 WRITE and WRITENR Statements
Use the WRITE and WRITENR statements to define text and have it displayed
at the terminal. This text can be used for messages, information, or
prompting.
>>--]--------]--]-WRITE---]--text---------------------------------------><
]-label:-] ]-WRITENR-]
label
WRITE/WRITENR statement. label is one-to-31 alphameric characters,
WRITE ] WRITENR
WRITE The cursor moves to a new line after the text is displayed.
WRITENR The cursor does not move to a new line after the text is
displayed.
text
What is displayed at the terminal. You can enter any character
string, including symbolic variables. Unless you enclose an
arithmetic expression in an &EVAL built-in function, the WRITE/WRITENR
statement does not perform evaluation on the expression. The CLIST
also displays any comments on the same line as the WRITE/WRITENR
statement.
13.29 END Command
For information about the END command, see TSO/E V2 Command Reference,
SC28-1881.
13.30 EXEC Command
For a description of the EXEC command, see TSO/E V2 Command Reference

SC28-1881.
INDEX Index
v
]--------------------]
] Special Characters ]
]--------------------]
/ (division symbol)
as an arithmetic operator 3.4
// (remainder symbol)
* (multiplication symbol)
** (exponentiation symbol)
&LASTCC
See CLIST variable
&LASTCC control variable 5.10
&LENGTH built-in function 6.3
&MAXCC control variable 5.10
&NRSTR built-in function 6.5
&SUBSTR built-in function 6.7
&SYS4DATE control variable 5.2
&SYS4JDATE control variable 5.2
&SYS4SDATE control variable 5.2
&SYSABNCD control variable 5.11
&SYSABNRC control variable 5.11
&SYSADIRBLK
See CLIST variable
&SYSALLOC
See CLIST variable
&SYSAPPCLU control variable 5.5
&SYSASIS control variable 5.7
&SYSBLKSIZE
See CLIST variable
&SYSBLKSTRK
See CLIST variable
&SYSCAPS built-in function 6.9
&SYSCLENGTH built-in function 6.4
&SYSCLONE control variable 5.5
possibles uses 5.5
&SYSCONLIST control variable 5.7
&SYSCPU control variable 5.5
&SYSCREATE
See CLIST variable
&SYSCSUBSTR built-in function 6.8
&SYSDATACLASS
See CLIST variable
&SYSDATE control variable 5.2
&SYSDFP control variable 5.5
&SYSDLM control variable 5.8
&SYSDSN built-in function 6.11
&SYSDSNAME
See CLIST variable
&SYSDSORG
See CLIST variable
:exmp.
:xmp.
&SYSDSSMS
See CLIST variable
&SYSDVAL control variable 5.8
&SYSENV control variable 5.6
&SYSEXDATE
See CLIST variable
&SYSEXTENTS
See CLIST variable
&SYSFLUSH control variable 5.7
&SYSHSM control variable 5.5
&SYSICMD control variable 5.6
&SYSINDEX built-in function 6.12
&SYSISPF control variable 5.5
&SYSJDATE control variable 5.2
&SYSJES control variable 5.5
&SYSKEYLEN
See CLIST variable
&SYSLC built-in function 6.10
&SYSLIST control variable 5.7
&SYSLRACF control variable 5.5
&SYSLRECL
See CLIST variable
&SYSLTERM control variable 5.3
&SYSMEMBERS
See CLIST variable
&SYSMGMTCLASS
See CLIST variable
&SYSMSG control variable 5.7
&SYSMSGLVL1
See CLIST variable
&SYSMSGLVL2
See CLIST variable
&SYSMVS control variable 5.5
&SYSNAME control variable 5.5
possibles uses 5.5
&SYSNEST control variable 5.6
&SYSNODE control variable 5.5
&SYSNSUB built-in function 6.13
&SYSONEBYTE built-in function 6.14
&SYSOUTLINE control variable 5.9
&SYSOUTTRAP control variable 5.9
&SYSPASSWORD
See CLIST variable
&SYSPCMD control variable 5.6
&SYSPLEX control variable 5.5
possibles uses 5.5
&SYSPREF control variable 5.4
&SYSPRIMARY
See CLIST variable
&SYSPROC control variable 5.4
&SYSPROMPT control variable 5.7
&SYSRACF control variable 5.5
&SYSRACFA
See CLIST variable
&SYSREASON
:exmp.
:xmp.
See CLIST variable
&SYSRECFM
See CLIST variable
&SYSREFDATE
See CLIST variable
&SYSSCAN control variable 5.6
&SYSSCMD control variable 5.6
&SYSSDATE control variable 5.2
&SYSSECLAB control variable 5.5
&SYSSECONDS
See CLIST variable
&SYSSMFID control variable 5.5
&SYSSMS control variable 5.5
&SYSSRV control variable 5.5
&SYSSTIME control variable 5.2
&SYSSTORCLASS
See CLIST variable
&SYSSYMDEF control variable 5.5
&SYSSYMLIST control variable 5.7
&SYSTERMID control variable 5.3
&SYSTIME control variable 5.2
&SYSTRKSCYL
See CLIST variable
&SYSTSOE control variable 5.5
&SYSTWOBYTE built-in function 6.15
&SYSUDIRBLK
See CLIST variable
&SYSUID control variable 5.4
&SYSUNIT
See CLIST variable
&SYSUNITS
See CLIST variable
&SYSUPDATED
See CLIST variable
&SYSUSED
See CLIST variable
&SYSUSEDPAGES
See CLIST variable
&SYSVOLUME
See CLIST variable
&SYSWTERM control variable 5.3
&147 (logical AND symbol) 3.4
&DATATYPE built-in function 6.1
&EVAL built-in function 6.2
&STR built-in function 6.6
+ (plus sign)
- (minus sign)
< (less than symbol) 3.4
<= (less than or equal to) 3.4
= (equal sign) 3.4
> (greater than symbol) 3.4
>= (greater than or equal to) 3.4
^< (not less than) 3.4
:exmp.
:xmp.
^= (not equal sign) 3.4
^> (not greater than) 3.4
] (logical OR symbol) 3.4
v
]---]
] A ]
]---]
action
of an attention routine
attention interrupt 10.1
cancelling 10.1
protecting the input stack for 10.1
protecting using the MAIN operand of CONTROL 10.1
of an error routine
canceling 10.2
listing instruction causing error 10.2
protecting using MAIN or NOFLUSH operand of CONTROL 10.2
ALLOCATE CLIST
attention routine 10.1
allocating CLIST libraries
implicit execution 2.4
allocation information
retrieving with LISTDSI 5.12
alphameric character
definition of 3.2, 13.1
ALTLIB command
example 2.4
specifying alternative CLIST libraries with 2.4
using under ISPF 2.4
ampersand (&)
in the SET statement 4.2
meaning of, preceding a variable name 4.1
using double ampersands 4.3
AND
logical operator 3.4
APPC/MVS
finding name 5.5
application
CLIST 1.2
different languages
using CLIST to manage 1.2
full-screen
writing 12.15
arithmetic expression
creating from user supplied input 12.3
arithmetic operator 3.4
ASIS
CONTROL statement operand 5.7, 13.4
assigning value
to symbolic variable 4.2
attention facility for CLIST 10.1
:exmp.
:xmp.
attention handling CLIST 10.1
example 10.1
attention interrupt
cancelling action for 10.1
defining action 10.1
attention routine
cancelling 10.1
establishing 10.1
example 10.1
ATTN statement
creating a CLIST attention routine with 10.1
syntax 13.2
using in a subprocedure 7.3
attribute, data set
default 2.2
availability test
data set 6.11
v
]---]
] B ]
]---]
background
executing a CLIST 2.3
executing a job from a CLIST
example 12.9
tailoring a CLIST for background execution, using &SYSENV 5.6
base control program
finding level of 5.5
BCP
finding level of 5.5
branching within a CLIST
using GOTO statement 7.5
built-in function
&LENGTH 6.3
&NRSTR 6.5
&SUBSTR 6.7
&SYSCAPS 6.9
&SYSCLENGTH 6.4
&SYSCSUBSTR 6.8
&SYSDSN 6.11
&SYSINDEX 6.12
&SYSLC 6.10
&SYSNSUB 6.13
&SYSONEBYTE 6.14
&SYSTWOBYTE 6.15
&DATATYPE 6.1
&EVAL 6.2
&STR 6.6
:exmp.
:xmp.
overview 6.0
writing your own 6.0
BY expression
in an iterative DO loop 7.2
v
]---]
] C ]
]---]
CALC CLIST
adding front-end prompting to 12.4
creating arithmetic expression from input 12.3
CALCFTND CLIST 12.4
capital letter
converting from lowercase
with &SYSCAPS 6.9
with CONTROL CAPS 13.4
converting to lowercase
with &SYSLC 6.10
capitalization in a CLIST 3.2
CAPS
CONTROL statement operand 13.4
CASH CLIST 12.12
category of CLIST
managing applications written in other languages 1.2
performing routine tasks 1.2
self-contained applications 1.2
character set
double-byte 3.5
supported in CLIST 3.2
supported in I/O 9.1
CLIST
attention facility 10.1
data set
copying 2.2
creating 2.1, 2.2
default attributes 2.2
editing 2.2
debugging 11.0
error code 11.3
executing 2.3
language 1.0
library
allocating using ALTLIB 2.4
implicit execution 2.4
installation-defined 2.1
user-defined 2.1
statement
list of 3.1
writing your own 3.1
testing 11.0
CLIST variable
set by LISTDSI
:exmp.
:xmp.
&LASTCC 13.15
&SYDSORG 13.15
&SYSADIRBLK 13.15
&SYSALLOC 13.15
&SYSBLKSIZE 13.15
&SYSBLKSTRK 13.15
&SYSCREATE 13.15
&SYSDATACLASS 13.15
&SYSDSNAME 13.15
&SYSDSSMS 13.15
&SYSEXDATE 13.15
&SYSEXTENTS 13.15
&SYSKEYLEN 13.15
&SYSLRECL 13.15
&SYSMEMBERS 13.15
&SYSMGMTCLASS 13.15
&SYSMSGLVL1 13.15
&SYSMSGLVL2 13.15
&SYSPASSWORD 13.15
&SYSPRIMARY 13.15
&SYSRACFA 13.15
&SYSREASON 13.15
&SYSRECFM 13.15
&SYSREFDATE 13.15
&SYSSECONDS 13.15
&SYSSTORCLASS 13.15
&SYSTRKSCYL 13.15
&SYSUDIRBLK 13.15
&SYSUNIT 13.15
&SYSUNITS 13.15
&SYSUPDATED 13.15
&SYSUSED 13.15
&SYSUSEDPAGES 13.15
&SYSVOLUME 13.15
CLOSFILE statement
syntax 13.3
using 9.3
closing a file 9.3
code, error
list of 11.3
coding statements and commands 13.1
combining variable 4.3
command
installation-written
distinguishing from CLIST statement name 6.6
TSO/E
using in a CLIST 1.2, 3.3
comment, in a CLIST 3.2
comparative operator 3.4
compound DO sequence
using to create a loop 7.2
compound SELECT statement
using 13.23
compound variable 4.3
COMPRESS CLIST 12.11
:exmp.
:xmp.
compressing a data set 12.11
concatenating
CLIST data set to SYSPROC
sample CLIST for 12.14
CLIST data sets with ALTLIB 2.4
compound 4.3
data set for I/O 9.8
variable 4.3
continuation symbol 3.2
CONTROL statement
syntax 13.4
using for CLIST diagnosis 11.1
control variable
See variable
controlling
the display of messages 8.2
uppercase and lowercase
using &SYSLC and &SYSCAPS control variables 8.3
using CAPS operand of CONTROL 8.3
converting READ statement input
to lowercase character (&SYSLC) 6.10
to uppercase character (&SYSCAPS) 6.9
copying a CLIST
considerations 2.2
creating a CLIST
TSO/E EDIT and full-screen editor 2.2
v
]---]
] D ]
]---]
Data Facility Hierarchical Storage Manager (DFHSM)

See DFHSM (Data Facility Hierarchical Storage Manager)
DATA PROMPT-ENDDATA sequence
syntax 13.6
using to code responses to prompts 8.1
data set
allocating using ALTLIB
example 2.4
attribute
default 2.2
availability
checking with &SYSDSN 6.11
I/O
performing 9.0
information about attributes 13.15
name
determining qualification 12.8
performing substringing on 12.8
reading in a CLIST, precautions for 8.3
specifying on the EXEC command 2.3
:exmp.
:xmp.
DATA-ENDDATA sequence
syntax 13.5
using to distinguish a command from a statement 7.2
&DATATYPE built-in function 6.1
date formats, four-digit years
See SYS4DATE
See SYS4JDATE
See SYS4SDATE
date formats, two-digit years
See SYSDATE
See SYSJDATE
See SYSSDATE
date, obtaining the
in Julian form 5.2
in sortable form 5.2
in standard form 5.2
DBCS (double-byte character set)
CLIST support 3.5
combining variables containing DBCS data 4.3
converting DBCS data to EBCDIC, using &SYSONEBYTE 6.14
converting EBCDIC data to DBCS, using &SYSTWOBYTE 6.15
counting DBCS bytes with &LENGTH 6.3
counting DBCS characters with &SYSCLENGTH 6.4
defining a DBCS string as character data
using &STR 6.6
determining if a string contains DBCS data, using &DATATYPE 6.1
error code involving DBCS 11.3
including leading/trailing blanks/zeros 6.3
restriction on using DBCS data in CLIST
general 3.5
using &SYSINDEX 6.12
with EDIT command 2.2
subdividing strings containing DBCS characters
using &SUBSTR 6.7
using &SYSCSUBSTR 6.8
debugging a CLIST 11.0
defining
non-rescannable character string (&NRSTR) 6.5
real value (&STR) 6.6
substring (&SUBSTR) 6.7
substring (&SYSCSUBSTR) 6.8
symbolic variable 4.2
DELETEDS CLIST 12.2
delimiter
delimiter for a DBCS string in a CLIST 3.5
for CLIST statement 3.2
for the double-byte character set 3.5
period
used to distinguish variable from data 12.7
determining
an expression's data type (&DATATYPE) 6.1
an expression's length
in bytes (&LENGTH) 6.3
in characters (&SYSCLENGTH) 6.4
data set availability (&SYSDSN) 6.11
:exmp.
:xmp.
DFHSM (Data Facility Hierarchical Storage Manager)
determining level
using &SYSHSM 5.5
DFSMS/MVS
availability to CLISTs 5.5
diagnostic procedure
for a CLIST 11.0
dialog, ISPF
creating 8.5
sample 12.15
displaying
CLIST statement
after substitution, using &SYSCONLIST 5.7
before substitution, using &SYSSYMLIST 5.7
panel from a CLIST 1.2
TSO/E commands
after substitution, using &SYSLIST 5.7
distinguishing
END statement from END subcommand
in general 7.2
using the CONTROL statement 7.2
using the DATA-ENDDATA sequence 7.2
RACF SELECT subcommand from the SELECT statement 7.1
strings that match CLIST statement names 6.6
WHEN clause from WHEN command 7.1
DO statement
syntax 13.7
DO-END sequence
in an attention routine 10.1
using
in the IF-THEN-ELSE sequence 7.1
DO-UNTIL-END sequence
DO-WHILE-END sequence
double ampersands
preserving, with &NRSTR 6.5
use of 4.3
v
]---]
] E ]
]---]
EDIT command
creating a CLIST under 2.2
executing a CLIST under 2.3
editing a CLIST
TSO/E EDIT and full-screen editor 2.2
END command 7.4
END statement
distinguishing from END command or subcommand 7.2
syntax 13.8
end-of-file processing
:exmp.
:xmp.
example 10.2
performing 9.7
entry panel
PROFILE CLIST example 12.15
EQ (equal sign) 3.4
error
cancelling action for 10.2
code
list of 11.3
obtaining in a CLIST 11.3
condition
end-of-file processing 9.7
defining action for 10.2
protecting the input stack from 10.2
routine
cancelling 10.2
creating 10.2
end-of-file 9.7
sample CLIST 10.2
error message
CLIST error routine 11.3
getting help for 11.2
viewing at the terminal 11.1
ERROR statement
canceling error action using 10.2
listing instruction causing error 10.2
syntax 13.9
&EVAL built-in function 6.2
evaluation
order of 3.4
example of a CLIST
list of 12.0
executing a CLIST
explicitly 2.3
finding how a CLIST was executed 5.6
implicitly 2.3
in general 2.3
exit
installation
writing a built-in function 6.0
writing a CLIST 3.0
routine
establishing 10.1
EXIT statement 7.4
syntax 13.10
to exit a CLIST specifying a return code 7.4
to exit a CLIST without specifying a return code 7.4
exiting
CLIST using the END command 7.4
CLIST using the EXIT statement
specifying a return code 7.4
from a nested CLIST 7.4
:exmp.
:xmp.
EXPAND CLIST 12.16
explicit execution of a CLIST 2.3
expression
arithmetic 3.4
comparative 3.4
logical 3.4
simple 3.4
v
]---]
] F ]
]---]
file input/output
performing
closing a file 9.3
end-of-file processing 9.7
on a JCL statement 9.8
on concatenated data set 9.8
opening a file 9.2
significance of file name 9.2
using &SYSDVAL 12.13
using READDVAL 12.13
reading a record from a file 9.4
updating a file 9.6
writing a record to a file 9.5
file name
significance of in file I/O 9.2
FLUSH option of CONTROL statement 13.4
flushing the input stack
with &SYSFLUSH 5.7
footprint (flag)
setting
in a CLIST 10.1
testing
in an attention handling CLIST 10.1
forcing arithmetic evaluation 6.2
foreground
executing a CLIST 2.3
executing a job from a CLIST
example 12.9
tailoring a CLIST for foreground execution using &SYSENV 5.6
formatting in a CLIST 3.2
front-end prompting
adding to the CALC CLIST 12.4
example 12.4, 12.7
full-screen application
example 12.15
writing 12.15
fully-qualified data set name
processing
example 12.8
function
built-in
:exmp.
:xmp.
converting DBCS data to EBCDIC (&SYSONEBYTE) 6.14
converting EBCDIC data to DBCS (&SYSTWOBYTE) 6.15
converting READ input to lowercase (&SYSLC) 6.10
converting READ input to uppercase (&SYSCAPS) 6.9
defining a non-rescannable character string (&NRSTR) 6.5
defining a real value (&STR) 6.6
defining a substring (&SUBSTR) 6.7
defining a substring (&SYSCSUBSTR) 6.8
determining data set availability (&SYSDSN) 6.11
limiting symbolic substitution (&SYSNSUB) 6.13
locating strings within strings (&SYSINDEX) 6.12
overview 6.0
built-in function
determining an expression's length in bytes (&LENGTH) 6.3
determining data type (&DATATYPE) 6.1
forcing arithmetic evaluation (&EVAL) 6.2
function,
built-in 6.0
determining an expression's length in characters (&SYSCLENGTH) 6.4
v
]---]
] G ]
]---]
GE (greater than or equal to symbol) 3.4

GETFILE statement
syntax 13.11
using 9.4
GLOBAL statement
syntax 13.12
global variable
establishing 7.4
example 7.4
in error routine
protecting using the MAIN operand of CONTROL 10.2
GOTO statement
example 7.5
syntax 13.13
GT (greater than symbol) 3.4
v
]---]
] H ]
]---]
HOUSKPNG CLIST 10.1

hyphen
as continuation symbol 3.2
:exmp.
:xmp.
v
]---]
] I ]
]---]
I/O
performing file 9.0
IF-THEN-ELSE sequence
nesting 7.1
null ELSE format 7.1
null THEN format 7.1
standard format 7.1
syntax 13.14
using to make a decision 7.1
implicit execution
allocating a CLIST for 2.4
benefit of 2.1
of a CLIST 2.3
implicitly defining variable 4.2
input
obtaining from the terminal 8.1
input stack
protecting
for attention routine 10.1
for error routine 10.2
for nested CLISTs 7.4
using MAIN operand of CONTROL 10.1, 10.2
using NOFLUSH operand of CONTROL 10.2
input string
performing substringing on
example 12.8
installation exit
writing a built-in function 6.0
writing a CLIST 3.1
Interactive System Productivity Facility (ISPF)
See ISPF (Interactive System Productivity Facility)
intercepting
command output from a CLIST
example 12.14
command output from CLISTs
using &SYSOUTTRAP 5.9
interface to application
simplifying 12.12
interpretive language
advantage 1.0
introduction 1.0
ISPEXEC command of ISPF
using in a CLIST 12.15
ISPF (Interactive System Productivity Facility)
availability
determining with &SYSISPF 5.5
command, in a CLIST 2.2, 8.5
copying a CLIST under ISPF 2.2
:exmp.
:xmp.
creating and editing a CLIST under ISPF 2.2
dialog
example 12.15
writing 12.15
executing a CLIST under ISPF 2.3
panel, using with a CLIST 12.15
restriction for a CLIST
length of variable 4.1
trapping TSO/E command output under ISPF 5.9
using ALTLIB under 2.4
iterative DO sequence
v
]---]
] J ]
]---]
JCL (job control language)

including in a CLIST
example 12.7
precaution 3.3
protecting those containing /* 12.7
special consideration for performing I/O on 9.8
JES
finding level 5.5
finding name 5.5
finding network node name 5.5
job
foreground and background execution
example 12.9
jobcard information
verifying
example 12.7
v
]---]
] K ]
]---]
keyword parameter
on PROC statement
description 4.2
example 12.9
prompting with 8.1
v
]---]
] L ]
]---]
label 3.2, 13.1

:exmp.
:xmp.
&LASTCC control variable 5.10
LE (less than or equal to symbol) 3.4
&LENGTH built-in function 6.3
length of a CLIST statement 3.2
levels of searching
specifying with ALTLIB 2.4
list of CLIST error codes 11.3
list of sample CLISTs 12.0
LISTALC command
managing command output 12.14
LISTDSI statement
reason code 13.15
return code 13.15
sample CLIST 12.16
syntax 13.15
using to assign values to variables 5.12
variables set by 13.15
LISTER CLIST 12.1
LOG/LIST parameter
setting 12.15
loop, creating
using the compound DO sequence 7.2
using the DO-UNTIL-END sequence 7.2
using the DO-WHILE-END sequence 7.2
using the iterative DO sequence 7.2
lowercase letter
converting from uppercase
with &SYSLC 6.10
converting to uppercase
with &SYSCAPS 6.9
preserving
with &SYSASIS 5.7
with CONTROL NOCAPS 13.4
LT (less than symbol) 3.4
v
]---]
] M ]
]---]
MAIN operand of CONTROL

using to protect
global variable for attention routine 10.1
global variable for error routine 10.2
the input stack for attention routine 10.1
the input stack for error routine 10.2
managing command output
LISTALC command 12.14
&MAXCC control variable 5.10
message
controlling the display of
with &SYSMSG 5.7
:exmp.
:xmp.
with CONTROL MSG 8.2, 13.4
writing to the terminal
using WRITE and WRITENR 8.2
minus sign
as continuation symbol (hyphen) 3.2
MVS/DFP
finding the level installed 5.5
v
]---]
] N ]
]---]
NE (not equal sign) 3.4

nesting
CLIST
example 7.4
example - the SCRIPTN CLIST 12.6
protecting the input stack for nested CLISTs 5.7, 7.4
determining if CLISTs are nested 5.6
IF-THEN-ELSE Sequence 7.1
loop 7.2
nesting CLISTs
limitations with file i/o 9.0
variable 4.3
network node name
finding 5.5
NG (not greater than symbol) 3.4
NGLOBAL statement
syntax 13.16
NL (not less than symbol) 3.4
NOCAPS
CONTROL statement operand 13.4
NOFLUSH operand of CONTROL
using to protect the input stack
NOFLUSH option of CONTROL statement 13.4
&NRSTR built-in function 6.5
null
ELSE format 7.1
line
coding for use with DATA PROMPT-ENDDATA 8.1
issuing in an attention routine 10.1
THEN format 7.1
variable
creating 4.2
numeric value allowed in variable 3.4
:exmp.
:xmp.
v
]---]
] O ]
]---]
obtaining
current date and time 5.2
input from within a CLIST
using the DATA PROMPT-ENDDATA sequence 8.1
offset of a string within a string
finding, with &SYSINDEX 6.12
OPENFILE statement
syntax 13.17
using 9.0
opening a file 9.2
operator
arithmetic 3.4
comparative 3.4
logical 3.4
option
including in a CLIST
example 12.10
using TESTDYN 12.10
OR
in the SELECT statement 13.23
order of evaluation 3.4
organizing related activities 12.1
OUTPUT CLIST 12.6
output trapping
&SYSOUTLINE 5.9
&SYSOUTTRAP 5.9
example (the SPROC CLIST) 12.14
v
]---]
] P ]
]---]
panel, ISPF
displaying from a CLIST 1.2, 8.5
example 12.15
ISPF command in a CLIST 1.2
sample
XYZABC10 12.15
XYZABC20 12.15
XYZABC30 12.15
XYZABC40 12.15
parameter
defining on the PROC statement
keyword parameter 4.2, 13.18
positional parameter 4.2, 13.18
:exmp.
:xmp.
passing to a CLIST 2.3
parentheses
as arithmetic operator 3.4
defining as character data 6.6
passing control to the terminal
returning control after a TERMIN statement 8.4
TERMIN statement 8.4
percent sign (%)
using in implicit execution of a CLIST 2.3
performing file I/O
using &SYSDVAL 12.13
using READDVAL statement 12.13
period
used to distinguish variable from data
example 4.3, 12.7
PF key definition
setting 12.15
setting (1-12) 12.15
setting (13-24) 12.15
PHONE CLIST 12.13
plus sign
as continuation symbol 3.2
position of a string within a string
finding, with &SYSINDEX 6.12
positional parameter
on PROC statement
description 4.2
prompting with 8.1
preserving double ampersands
with &NRSTR 6.5
PROC statement
assigning value to variable with 4.2
defining parameter with 4.2
in a subprocedure 7.3
prompting with 8.1
syntax 13.18
PROFILE CLIST 12.15
prompting for input
coding response to prompt
using DATA PROMPT-ENDDATA sequence 8.1
controlling uppercase and lowercase 8.3
example 12.4, 12.7
methods 8.1
permitting from a CLIST
using &SYSPROMPT 5.7
precaution when reading fully-qualified data set name 8.3
significance of &SYSDLM control variable after a TERMIN statement 8.4
storing input in &SYSDVAL control variable 8.3
using statement
PROC 8.1
READ 8.3
READDVAL 8.3
TERMIN 8.4
:exmp.
:xmp.
WRITE 8.2
WRITENR 8.2
protecting
input stack
for attention routine 10.1
for nested CLISTs 7.4
using MAIN operand of CONTROL 10.1, 10.2
using NOFLUSH operand of CONTROL 10.2
JCL statement containing /*
example 12.7
PUTFILE statement
syntax 13.19
using 9.5
v
]---]
] R ]
]---]
RACF availability
determining with &SYSRACF 5.5
READ statement
defining variable with 4.2
syntax 13.20
using for prompting 8.3
READDVAL statement
syntax 13.21
using when performing file I/O 12.13
reading a record from a file 9.4
reading input from the terminal
precaution when reading fully-qualified data set name 8.3
storing input in &SYSDVAL control variable 8.3
to obtain value for PROC statement keyword 8.3
using the READ statement
controlling uppercase and lowercase 8.3
description 8.3
using the READDVAL statement 8.3
using the TERMIN statement
description 8.4
significance of &SYSDLM control variable 8.4
using the TERMING statement
returning control after a TERMING statement 8.4
significance of &SYSDLM control variable 8.4
reading input from within the CLIST
using the DATA PROMPT-ENDDATA sequence
example 8.1
reason code
set by LISTDSI statement 13.15
record
copying directly into variable using &SYSDVAL 12.13
performing file I/O consideration
:exmp.
:xmp.
concatenated data set 9.8
general 9.0
JCL statement 9.8
reading from a file 9.4
updating in a file 9.6
writing to a file 9.5
retroactive variable
defining in a subprocedure
using SYSREF 7.3
return code
from subprocedure 7.3
obtaining from a CLIST statement 11.3
RETURN statement
syntax 13.22
routine
attention 10.1
error 10.2
routine task
performing with CLIST 1.2
simplifying 12.2
RUNPRICE CLIST 12.9
v
]---]
] S ]
]---]
sample CLIST
adding
front-end prompting to the CALC CLIST 12.4
allowing
background execution of a CLIST 12.9
foreground execution of a CLIST 12.9
attention routine 10.1
background execution of a job 12.9
concatenating
data set to SYSPROC 12.14
creating
arithmetic expression from input 12.3
VIO data set 12.11
distinguishing
operator from an operand 12.10
variable from data 12.7
error routine 10.2
foreground execution of a job 12.9
full-screen application
writing 12.15
including
JCL statement 12.7
option 12.10
TSO/E command 12.1
initializing
:exmp.
:xmp.
system service 12.5
interface to application
simplifying 12.12
invoking
nested CLISTs to perform subtasks 12.6
system service 12.5
job card information
verifying 12.7
keyword
using to run foreground/background job 12.9
option
including 12.10
organizing
related activities 12.1
protecting
JCL statement containing /* 12.7
leading zeros 12.7
READDVAL statement
using when performing file I/O 12.13
routine task
simplifying 12.2
simplifying
interface to application 12.12
routine task 12.2
system-related task 12.11
substringing
avoiding when performing file I/O 12.13
performing on input string 12.8
system-related task
simplifying 12.11
TSO/E command
including 12.1
using
keyword to run foreground/background job 12.9
verifying
job card information 12.7
VIO data set
creating 12.11
writing
full-screen application 12.15
saving command output in a CLIST
example 12.14
SCRIPTD CLIST 12.6
SCRIPTDS CLIST 12.5
SCRIPTNEST CLIST 12.6
SELECT statement
distinguishing from the RACF SELECT subcommand 7.1
syntax 13.23
using to make a selection 7.1
selection menu
relevance to PROFILE CLIST 12.15
self-contained application 1.2
Session Manager
determining availability, with &SYSPROC 5.4
reformatting a screen with 5.3
:exmp.
:xmp.
SET statement
defining variable with 4.2
syntax 13.24
setting
LOG/LIST parameter 12.15
PF key definition 12.15
PF key definition (1-12) 12.15
PF key definition (13-24) 12.15
terminal characteristics 12.15
shift-in character, for DBCS string 3.5
shift-out character, for DBCS string 3.5
simple SELECT statement
syntax 13.23
simplifying
interface to application 12.12
process of invoking CASHFLOW 12.12
routine task 12.2
system-related task 12.11
SPROC CLIST 12.14
standard format for IF-THEN-ELSE sequence 7.1
&STR built-in function 6.6
string
performing substringing on input
example 12.8
structuring a CLIST
branching within a CLIST
using GOTO statement 7.5
consideration 7.0
exiting
CLIST using the END command 7.4
CLIST using the EXIT statement 7.4
from a nested CLIST 7.4
global symbolic variables
establishing 7.4
example 7.4
IF-THEN-ELSE sequence
nesting CLISTs
example 7.4
subprocedure 7.3
using a DO-group
consideration 7.2
distinguishing END statement from subcommand 7.2
the DO-END sequence 7.1
using SELECT statement
distinguishing a WHEN clause from a command 7.1
distinguishing END statement from subcommand 7.2
using the compound DO sequence 7.2
using the DO statement
nesting DO-loops 7.2
using the DO-UNTIL-END sequence 7.2
using the DO-WHILE-END sequence
example 7.2
using the IF-THEN-ELSE sequence
:exmp.
:xmp.
condition 7.1
nesting IF-THEN-ELSE 7.1
null ELSE format 7.1
standard format 7.1
using the iterative DO sequence 7.2
using the SELECT statement
with a test expression 7.1
without a test expression 7.1
subcommand
environment
effect on nested CLISTs 7.4
of the EDIT command
executing a CLIST with 2.3
using to modify a CLIST 2.2
of the TEST command
executing a CLIST with 2.3
SUBMIT * command
example 12.7
SUBMITDS CLIST 12.7
SUBMITFQ CLIST 12.8
subprocedure
calling, using SYSCALL 7.3
defining with the PROC statement 7.3
passing control to 7.3
returning information from
retroactive (SYSREF) variable 7.3
return code 7.3
sharing variables among
using the NGLOBAL statement 7.3
using SYSREF in 7.3
substitution, symbolic
See symbolic substitution
&SUBSTR built-in function 6.7
substringing
avoiding when performing file I/O 12.13
on input string
example 12.8
subtask
performing using nested CLISTs
OUTPUT 12.6
SCRIPTD 12.6
symbol
continuation 3.2
symbolic substitution
limiting
with &SYSCAN 5.6
with &SYSNSUB 6.13
with &NRSTR 6.5
of nested variables 4.3
of variable 4.1
symbolic variable
assigning value to 4.1
naming 4.1
value of 4.1
:exmp.
:xmp.
syntax
ATTN statement 13.2
CLOSFILE statement 13.3
CONTROL statement 13.4
DATA PROMPT-ENDDATA sequence 13.6
DATA-ENDDATA sequence 13.5
DO statement 13.7
END statement 13.8
ERROR statement 13.9
EXIT statement 13.10
GETFILE statement 13.11
GLOBAL statement 13.12
GOTO statement 13.13
IF-THEN-ELSE sequence 13.14
LISTDSI statement 13.15
NGLOBAL statement 13.16
OPENFILE statement 13.17
PROC statement 13.18
PUTFILE statement 13.19
READ statement 13.20
READDVAL statement 13.21
RETURN statement 13.22
SELECT statement 13.23
SET statement 13.24
SYSCALL statement 13.25
SYSREF statement 13.26
TERMIN statement 13.27
TERMING statement 13.27
WRITE statement 13.28
WRITENR statement 13.28
syntax diagram 13.1
syntax rule
CLIST
capitalization 3.2
comment 3.2
delimiter 3.2
formatting 3.2
label 3.2
length of a CLIST statement 3.2
continuation symbol 3.2
&SYS4DATE control variable 5.2
&SYS4JDATE control variable 5.2
&SYS4SDATE control variable 5.2
&SYSABNCD control variable 5.11
&SYSABNRC control variable 5.11
&SYSAPPCLU control variable 5.5
&SYSASIS control variable 5.7
SYSCALL statement
syntax 13.25
using to call a subprocedure 7.3
&SYSCAPS built-in function 6.9
&SYSCLENGTH built-in function 6.4
&SYSCLONE control variable 5.5
&SYSCONLIST control variable 5.7
&SYSCPU control variable 5.5
:exmp.
:xmp.
&SYSCSUBSTR built-in function 6.8
&SYSDATE control variable 5.2
&SYSDFP control variable 5.5
&SYSDLM control variable 5.8
&SYSDSN built-in function 6.11
&SYSDVAL control variable 5.8
&SYSENV control variable 5.6
&SYSFLUSH control variable 5.7
&SYSHSM control variable 5.5
&SYSICMD control variable 5.6
&SYSINDEX built-in function 6.12
&SYSISPF control variable 5.5
&SYSJDATE control variable 5.2
&SYSJES control variable 5.5
&SYSLC built-in function 6.10
&SYSLIST control variable 5.7
&SYSLRACF control variable 5.5
&SYSLTERM control variable 5.3
&SYSMSG control variable 5.7
&SYSMVS control variable 5.5
&SYSNAME control variable 5.5
&SYSNEST control variable 5.6
&SYSNODE control variable 5.5
&SYSNSUB built-in function 6.13
&SYSONEBYTE built-in function 6.14
&SYSOUTLINE control variable 5.9
&SYSOUTTRAP control variable 5.9
&SYSPCMD control variable 5.6
&SYSPLEX control variable 5.5
sysplex name
finding 5.5
&SYSPREF control variable 5.4
&SYSPROC control variable 5.4
&SYSPROMPT control variable 5.7
&SYSRACF control variable 5.5
SYSREF statement
syntax 13.26
&SYSSCAN control variable 5.6
&SYSSCMD control variable 5.6
&SYSSDATE control variable 5.2
&SYSSECLAB control variable 5.5
&SYSSMFID control variable 5.5
&SYSSMS control variable 5.5
&SYSSRV control variable 5.5
&SYSSTIME control variable 5.2
&SYSSYMDEF control variable 5.5
&SYSSYMLIST control variable 5.7
System Management Facilities
SMF ID 5.5
system name
finding 5.5
system service
initializing and invoking
example 12.5
:exmp.
:xmp.
system-related task
simplifying 12.11
&SYSTERMID control variable 5.3
&SYSTIME control variable 5.2
&SYSTSOE control variable 5.5
&SYSTWOBYTE built-in function 6.15
&SYSUID control variable 5.4
&SYSWTERM control variable 5.3
v
]---]
] T ]
]---]
TERMIN statement
passing control to the terminal 8.4
syntax 13.27
terminal
prompting for input from the 8.1
receiving response from the 8.3
writing a message to 8.2
terminal characteristics
setting 12.15
variables that describe 5.3
TERMING statement
syntax 13.27
TEST command
executing a CLIST under 2.3
test expression
using the SELECT statement with a 7.1
using the SELECT statement without a 7.1
TESTDYN CLIST 12.10
testing a CLIST 11.0
time of day
obtaining the 5.2
TO expression
translating READ statement input
to lowercase character (&SYSLC) 6.10
to uppercase character (&SYSCAPS) 6.9
trapping TSO/E command output
&SYSOUTLINE 5.9
&SYSOUTTRAP 5.9
example (the SPROC CLIST) 12.14
TSO/E
finding level installed 5.5
finding MVS symbolic name 5.5
finding MVS system symbol 5.5
finding MVS/DFP level 5.5
finding security level 5.5
finding terminal ID 5.3
TSO/E commands
prompting for input with 8.1
trapping output from
:exmp.
:xmp.
description 5.9
example 12.14
using in a CLIST 1.2, 3.3
TSO/E service facility
using to execute a CLIST from another language 2.3
TSOEXEC command 5.11
v
]---]
] U ]
]---]
understanding CLIST error code 11.3

updating a file 9.6
uppercase letter
converting from lowercase
with &SYSCAPS 6.9
converting to lowercase
with &SYSLC 6.10
v
]---]
] V ]
]---]
variable
assigning value
description 4.1
combining
containing DBCS data set 4.3
symbolic and character strings 4.3
control
&LASTCC 5.10
&MAXCC 5.10
&SYS4DATE 5.2
&SYS4JDATE 5.2
&SYS4SDATE 5.2
&SYSAPPCLU 5.5
&SYSASIS 5.7
&SYSCLONE 5.5
&SYSCONLIST 5.7
&SYSCPU 5.5
&SYSDATE 5.2
&SYSDFP 5.5
&SYSDLM 5.8
&SYSDVAL 5.8
&SYSENV 5.6
&SYSFLUSH 5.7
&SYSICMD 5.6
&SYSISPF 5.5
&SYSJDATE 5.2
&SYSJES 5.5
:exmp.
:xmp.
&SYSLIST 5.7
&SYSLRACF 5.5
&SYSLTERM 5.3
&SYSMSG 5.7
&SYSMVS 5.5
&SYSNAME 5.5
&SYSNEST 5.6
&SYSNODE 5.5
&SYSOUTLINE 5.9
&SYSOUTTRAP 5.9
&SYSPCMD 5.6
&SYSPLEX 5.5
&SYSPREF 5.4
&SYSPROC 5.4
&SYSPROMPT 5.7
&SYSRACF 5.5
&SYSSCAN 5.6
&SYSSCMD 5.6
&SYSSDATE 5.2
&SYSSECLAB 5.5
&SYSSMFID 5.5
&SYSSMS 5.5
&SYSSRV 5.5
&SYSSTIME 5.2
&SYSSYMDEF 5.5
&SYSSYMLIST 5.7
&SYSTERMID 5.3
&SYSTIME 5.2
&SYSTSOE 5.5
&SYSUID 5.4
&SYSWTERM 5.3
consideration for &SYSDATE and &SYSSDATE 5.2
describing terminal characteristics 5.3
description 5.0
for TSO/E command output trapping 5.9
modifiable 5.1
non-modifiable 5.1
related to input 5.8
related to return and reason codes 5.10
related to the CLIST 5.6
related to the CLIST CONTROL statement 5.7
related to the current date and time 5.2
related to the system 5.5
related to the user 5.4
related to TSOEXEC command 5.11
relationship between &SYSPCMD and &SYSSCMD 5.6
defining symbolic variable 4.2
GLOBAL 7.4
LISTDSI statement 13.15
naming
description 4.1
on PROC statement 4.1
nesting 4.3
NGLOBAL 7.3
:exmp.
:xmp.
related to the TSOEXEC command
&SYSABNCD 5.11
&SYSABNRC 5.11
subprocedure variable 7.3
symbolic substitution of 4.1, 4.3
using double ampersands with 4.3
value of 4.1
VIO data set
creating 12.11
v
]---]
] W ]
]---]
WHEN clause of SELECT statement

distinguishing from the WHEN command 7.1
WRITE statement
prompting with 4.2, 8.1
syntax 13.28
WRITENR statement
prompting with 8.1
syntax 13.28
writing
full-screen application 12.15
message to the terminal 8.2
record to a file 9.5
v
]---]
] Y ]
]---]
year formats, four-digit years

See SYS4DATE
See SYS4JDATE
See SYS4SDATE
year formats, two-digit years
See SYSDATE
See SYSJDATE
See SYSSDATE

CLIST

Uploaded by

Copyright:

Available Formats

CLIST

Uploaded by

Document Information

Original Description:

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

CLIST

Uploaded by

Copyright:

Available Formats

CONTENTS

About This Book PREFACE

Summary of Changes CHANGES

Topic 1. Introduction 1.0

Topic 2. Creating, Editing, and Executing CLISTs 2.0

Topic 3. Writing CLISTs - Syntax and Conventions 3.0

Topic 4. Using Symbolic Variables 4.0

Topic 5. Using Control Variables 5.0

Topic 6. Using Built-in Functions 6.0

Topic 7. Structuring CLISTs 7.0

Topic 8. Communicating with the Terminal User 8.0

Topic 9. Performing File I/O 9.0

Topic 10. Writing ATTN and ERROR Routines 10.0

Topic 11. Testing and Debugging CLISTs 11.0

Topic 12. Sample CLISTs 12.0

Topic 13. Reference 13.0

Communicating Your Comments to IBM BACK_1

Readers' Comments -- We'd Like to Hear from You COMMENTS

1-1. Sample CLIST Consisting of TSO/E Commands 1.2

FRONT_1.1 Programming Interface Information

Other company, product, and service names, which may be denoted by a

PREFACE About This Book

PREFACE.1 Who Should Use This Book

This book is intended for new and experienced CLIST programmers.

PREFACE.2 How This Book Is Organized

* Topic 1, "Introduction" describes the types of functions CLISTs

* Topic 2, "Creating, Editing, and Executing CLISTs" describes how

* Topic 3, "Writing CLISTs - Syntax and Conventions" describes the

* Topic 5, "Using Control Variables" describes how to use CLIST

* Topic 6, "Using Built-in Functions" describes how to use CLIST

* Topic 7, "Structuring CLISTs" describes how to use CLIST

* Topic 8, "Communicating with the Terminal User" describes how to

* Topic 9, "Performing File I/O" describes how to read and write

* Topic 10, "Writing ATTN and ERROR Routines" describes how to

* Topic 12, "Sample CLISTs" provides sample CLISTs that perform a

* Topic 13, "Reference" contains complete syntax descriptions of

PREFACE.3 Where to Find More Information

PREFACE.4 Referenced Program Products

* All occurrences of DFHSM refer to Data Facility Hierarchical

* All occurrences of ISPF refer to Interactive System Productivity

* All occurrences of ISPF/PDF refer to Interactive System

* All occurrences of RACF refer to Resource Access Control

CHANGES Summary of Changes

CHANGES.1 SC28-1876-04 for TSO/E Version 2 Release 5

* The SMSINFO keyword operand on the LISTDSI statement has been

* Information about CLIST data set attributes has been added to

* This revision also reflects the changes caused by miscellaneous

CHANGES.2 : Online Update SK2T-0710-05 for TSO/E Version 2 Release 2

CHANGES.3 : Online Update SK2T-0710-01 for TSO/E Version 2 Release 2

CHANGES.4 SC28-1876-03 for TSO/E Version 2 Release 2

CHANGES.5 SC28-1876-02 for TSO/E Version 2 Release 2

CHANGES.6 SC28-1876-01 for TSO/E Version 2 Release 1.1

* Some of the information from the topic "Characters Supported in

CHANGES.7 SC28-1876-00 for TSO/E Version 2 Release 1

* Information about the ATLIB command has been added to Topic 2.

* Examples of the EXEC command have been changed to include the

1.0 Topic 1. Introduction

Besides issuing TSO/E commands, CLISTs can perform more complex

The CLIST language is an interpretive language. Like programs in other high-