Introduction to

CLIST

Objectives
Understand CLIST programs and
procedures
Create & Execute new CLIST programs
Use In-Built functions
Understanding and practising the
Sample programs

Contents
What is CLIST?
Usage and Advantages
CLIST Statement Structures
Variables, Operators and Expressions
Creation & Execution
PROC Statement
In-built functions
Control Statements
Error handling

What is CLIST?
C-List stands for Command List
A CLIST is an online file containing
statements that can be executed in TSO in
the interactive mode
It is a set of TSO commands,
subcommands and CLIST statements that
have been arranged in a executable
sequence in a dataset

Contd
High Level Interpretive Language

CLISTs are not compiled like COBOL

programs, they are interpreted.

Foreground counter part of JCL

Developed by IBM

Usage of CLIST
Simple execution of Multiple operations
Conditional execution of operations
Repetitive execution of same operations
Execution with parameter and variables
Interaction with end users
Simple arithmetic and logical operations
Error and interrupt detection

Advantages
minimizes typing and hence the typing
errors
lengthy commands can be stored and
executed when required
reduces the risk of executing commands
out of sequence

Contd..
Offers lot of flexibility
Interaction with Terminal User
Tolerance of errors and error
handling capacity
Write and Execute - need not
compile for load module creation

CLIST Statements
Each line in a CLIST procedure is a
statement
All CLIST statements must begin with
either a CLIST command or TSO
or subcommand

Statement structure
WRITENR

ENTER NAME OF MONTH

COMMAND

SET

OPERAND

&A = (( 4 + &B) / &C)

COMMAND

IF
COMMAND

OPERAND

&A=7 , THEN GOTO LABEL1

OPERAND

COMMAND

COMMAND

OPERAND

OPERAND

Syntax rules
Separators (space, comma and TAB)
Continuation Symbols ( + , -)
Uppercase letters
Comments /* This is a comment
Any TSO/CLIST commands can be labeled.
Labels can consists of :
Alphanumeric characters(A-Z,0-9,#,$,@,-)
Must begin with alphabet
Ex:
label1: IF A=

Variables
Two kinds of variables

User-defined
System-defined

Usually the variables are prefixed by &

Rules of Naming

The 1st character must be one of :A-Z, a-z,_,#,$,@

Others can include 0-9
252 characters maximum
It cant be CLIST word or Operator such as EQ,NE..
On PROC statements :
must begin with A-Z caps only
keyword variables cant contain(_) or be longer than 31

Defining and initializing symbolic

variables
To define variables and assign specific
values

Use SET(control variables & built-in functions

can also be used with SET)
Use READ to get Users response
Use PROC statement to get values from the
parameters passed to the CLIST

Expression
Is a string in a CLIST statement that contains

one or more variables

character strings
and/ or arithmetic, comparative and logical operators

A space preceding and following an operator may be

optional
A space is mandatory between letter operators
IF &A = &B OR &A < &C GOTO LABEL1
mandatory

optional

Arithmetic operators
+ Addition
- Subtraction
* Multiplication
/ Division
** Exponentiation
// Remainder

Priority of operators

Exponentiation(**) and remainder(//)

Multiplication(*) and division(/)
Addition(+) and subtraction(-)
Comparison
Logical AND
Logical OR

Creation of CLIST
CLIST Dataset Characteristics

can be a sequential Dataset

or a member of a partitioned Dataset

Attributes of the PDS containing CLISTs :

RECFM = FB
LRECL = 80
BLKSIZE = 3120

Execution of CLIST
EXPLICIT EXECUTION

Initiate the CLIST by issuing TSO Command

EXEC or EX
followed by the dataset name of the CLIST file
and parameter values that are assigned to
variables, if any specified on the initial PROC
statement in the CLIST.
FORMAT: TSO EXEC dsname parameters
Eg: TSO EXEC N010060.CLIST.LIB(MYCLIST

Execution of CLIST
IMPLICIT EXECUTION

refers to executing a CLIST when the EXEC

command is implied.
eg: MYCLIST

Can be used only when the CLIST is a

member within a users command procedure
library which is allocated to the SYSPROC
library.
ALLOC F(SYSPROC) DA(userid.clist.lib SYS1.CLIST
PUBLIC.CLIST)

Defining Variables
To define variables and assign specific
values

Use SET
Use READ to get Users response
Use PROC statement to get values from the
parameters passed to the CLIST
eg: SET NAME = AETNA (no quotes)
SET CI = &P * &N * &R

PROC Statement
Values can be passed in the EXEC
statement
All the values passed in the exec
statements should be declared in PROC
statement.
For this both Positional and key word
parameters can be used.

Positional parameters
EXEC (TEST) 100 ABC
PROC 2 NUMB SEQ
2 -- Number of Positional parameters
NUMB 100
SEQ ABC
A positional parameter cannot accept a null
value for a variable and it will prompt the user to
enter a valid value for the variable

Keyword parameters
EXEC NAME(RAM) AGE(28)
PROC NAME(AAA) AGE(00)
Name = Ram
Age =28
Default values for name and age are AAA
and 00 respectively
A keyword parameter can be set to null by
setting the variable with a blank bracket()
either in PROC or EXEC

Terminal I/O Statement

WRITE text

send text to terminal with Carriage Return

WRITENR text

send text to terminal without CR

READ variables

reads values from the terminal into the

variables listed

Sample CLIST
WRITE A TRIAL CLIST
WRITE ENTER YOUR FIRST NAME
READ NAME
WRITE YOUR NAME IS &NAME
WRITE ENTER YOUR AGE
READ
WRITE &SYSDVAL IS YOUR AGE

WRITE Statement displays the

text on the screen with carriage
return
READ Statement gets the input
from the user
NAME is a user defined variable
&SYSDVAL is a system defined
variable

More about System Variables

Information about terminal I/O :
&SYSDVAL - information entered by the user.

Information about procedures execution

&LASTCC - CC returned by last TSO/CLIST

&MAXCC - highest CC encountered

&SYSICMD - member name if invoked implicitly else blank
&SYSPCMD - name of recently executed TSO command
&SYSSCMD - name of recently executed TSO subcommand
&SYSNEST - YES if invoked by other procedure else NO

Contd
Information about User :

&SYSUID - the user-id of current user

&SYSPROC - name of the log-on procedure
&SYSPREF - the default prefix added to
data set names for the current user

Date & Time

&SYSDATE - system date in mm/dd/yy format

&SYSTIME - system time in hh:mm:ss format

Built-in Functions
These are some built in functions which will
perform the predefined functions when given the
required parameters

&LENGTH (expression) - returns length of exp.

&DATATYPE (expression) - returns data type of the
expression (NUM/CHAR)
&SYSDSN (dsn) - returns OK if dsn exists & available
&SUBSTR (start: end, string) - extracts a sub-string
from a string ( end is optional)

Sample - 1
WRITE ENTER THE STRING
READ &NAME
WRITE ENTER THE NUMBER OF CHARACTERS TO
EXTRACT
READ &NUM
WRITE NO OF CHAR IN GIVEN STRING IS
&LENGTH(&NAME)
WRITE THE EXTRACTED STRING IS
&SUBSTR(1:&NUM,&NAME)
WRITE THE DATATYPE OF THIS STRING IS
&DATATYPE(&SUBSTR(1:&NUM,&NAME))

What is the output? If Name = Infosys and num = 2

Output is ..
The number of characters in the given is
7
The extracted string is IN

Start = 1 gives the starting position of

the extraction
End = 2 gives the ending position of
the extraction

The Data type of the string is CHAR

Sample - 2
WRITE ENTER THE DSN NAME THAT IS TO BE
CHECKED
READ &DSN
SET RES = OK
IF &SYSDSN(&DSN) EQ &RES THEN +
WRITE YES, THE DSN EXISTS
ELSE +
WRITE NO, THE DSN DOESN'T EXIST
This is to check whether the entered dsn name exists or
not

Nested CLISTS
A CLIST may have an EXEC
statement to execute another
CLIST. This subordinate CLIST
can also include EXEC statement
to invoke CLISTS on an even
lower level. These are referred to
as Nested CLISTS

More about Nested CLISTs

Used in performing hierarchical functions.
Nesting can simplify the test procedures
and enhances the potential for flexibility.
The command procedure invoked by the
user in either explicit or implicit EXEC
mode is the highest-level procedure in this
hierarchy.

/* MAIN PGM
GLOBAL VAR1 VAR2 VAR3
WRITE IN MAIN PROGRAM
WRITE ENTER THE FIRST NUMBER
READ VAR1
EXEC 'G21198.TEST.SRCLIB(LINK1)'
SET &VAR3 = &VAR1 + &VAR2
WRITE IN MAIN PROGRAM
WRITE THE RESULT IS &VAR3
/* LINK PGM
GLOBAL VAR1 VAR3
WRITE IN LINK1
WRITE ENTER THE SECOND NUMBER
READ VAR3
EXIT

First CLIST calls the second one

The variables declared as global can be
shared between the CLISTS
They are positional
But the names of the variables are
immaterial

IF Condition.
IF <cond> THEN <action> +
ELSE <action>

THEN must appear on the same logical line of IF

only one statement after THEN and ELSE

eg:

IF AGE = 18 THEN WRITE ELIGIBLE +

ELSE WRITE NOT ELIGIBLE

DO END Loop
Collect CLIST statements into a group of
logically related operations.
Format :DO [ variable = term1 TO term2 BY term3 ]
[WHILE condition ]
[UNTIL condition ]

END

WRITE ENTER 3 NUMBERS

READ NUM1
READ NUM2
READ NUM3
IF &NUM1 > &NUM2 && &NUM1 > &NUM3 THEN +
DO
WRITE NUM1 IS THE GREATEST OF THE THREE.
WRITE THANKS FOR YOUR COOPERATION
END
ELSE +
IF &NUM2 > &NUM1 AND &NUM2 > &NUM3 THEN +
DO
WRITE NUM2 IS THE GREATEST OF THE THREE.
WRITE THANKS FOR YOUR COOPERATION
END
ELSE +
DO
WRITE NUM3 IS THE GREATES OF THE THREE.
WRITE THANKS FOR YOUR COOPERATION
END

&& and AND goes alike

Since IF THEN ELSE loop can support
only one statement each, a DO loop can
be used as shown

WRITE DO LOOP
SET I = 1
DO WHILE &I LE 4
WRITE WHILE
SET &I = &I + 1
END
SET I = 1
DO UNTIL &I = 4
WRITE UNTIL
SET &I = &I + 1
END
DO &I = 1 TO 4 BY 1
WRITE INCREMENT
END

DO WHILE --- The loop executes when

when the conditions
becomes TRUE
DO UNTIL --- The loop executes when
when the conditions
becomes FALSE

SELECT-END Loop
To test multiple conditions
executes the actions specified in the first
occurrence of a WHEN clause whose condition is
true.
Format :SELECT [ expression ]
WHEN ( condition1 ) +
action
WHEN ( condition2 ) +
action
OTHERWISE +
action
END

Example
WRITE ENTER CHOICE
READ C
SELECT (&C)
WHEN(y) WRITE YES
WHEN(n) WRITE NO
OTHERWISE WRITE INVALID
END
& in the select statement is a must. And in WHEN
clause no need for quotes even for characters

JCL and CLIST

//G21190J JOB (JOB1),NOTIFY=G21190,CLASS=A
//STEP1 EXEC PGM=IEFBR14
//DD1 DD DSN=G21190.PDS.NEW,SPACE=(TRK,(1,1,1)),
//
DCB=(RECFM=FB,BLKSIZE=800,LRECL=80),
//

DISP=(NEW,CATLG)

EQUIVALENT CLIST:
ALLOC DA(&SYSPREF.PDS.NEW') RECFM(F B) TR DIR(1) +

LRECL(80) BLK(800) SP(1 1) NEW CATALOG

CLIST a list of TSO commands

EDIT 'G21198.TEST.SRCLIB(FSTJCL)' OLD CNTL
C'USERID' 'G21198' ALL
SUBMIT
END SAVE
LISTCAT
All the userid in the above pds will be changed to
g21198

Error handling
ERROR DO
IF &LASTCC < 4 THEN RETURN
ELSE +
DO
WRITE THERE IS AN ERROR
RETURN
END
END
SET &T = name
WRITE THE VALUE OF T IS &T
SET &T = &T + 1
WRITE THE PROGRAM CONTINUES WITH EXECUTION
WRITE THE VALUE OF T IS &T

RETURN is used only in ERROR routines.

Processing returns to the next statement
following the one where an interrupt was
issued.
EXIT statement ends a main or nested
CLIST.
Processing returns to the next higher level
CLIST or TSO.

Reference
Charles H. Rider , TSO/E CLIST The
Complete Tutorial and Desk Reference,
1992, QED Information Sciences, Inc.