Module 2: CLIST Variables

CLIST- Variables

CLIST variables are called symbolic variables and always begin with an ampersand, like &NAME or &DSN. Before TSO executes any statement, it scans the line and replaces every symbolic variable with its current value. Understanding exactly when this substitution happens is the key to writing correct CLISTs.

Symbolic variables and SET

Variable names start with & followed by letters, digits, or @ # $, up to 31 characters.
SET &NAME = value assigns a value. The & on the left side is optional: SET NAME = JOHN works too.
PROC arguments arrive as symbolic variables automatically: PROC 1 DSN makes &DSN available.
READ &VAR stores terminal input into a symbolic variable.
Variables are untyped: everything is a character string until &EVAL or &DATATYPE treats it as a number.

SET &NAME = JOHN
SET &AGE = 30
SET CITY = LONDON /* & on the left is optional */
WRITE &NAME LIVES IN &CITY AND IS &AGE

How symbolic substitution works

Substitution happens before the statement runs, on every statement, every time.
Quotes do NOT stop substitution: WRITE "&NAME" still prints the value of &NAME.
A period ends the variable name and stays in the output: &DSN.BKUP becomes USER1.DATA.BKUP.
Two variables side by side concatenate: SET &FULL = &FIRST&LAST gives JOHNSMITH.
To glue a variable to following text, use the dot: &DSN.D&STAMP becomes USER1.DATA.D261008.

SET &DSN = USER1.DATA
SET &STAMP = 261008
SET &NEW = &DSN.D&STAMP
WRITE &NEW /* displays: USER1.DATA.D261008 */

&STR - controlling substitution

&STR(string) stores the string exactly as written, without substituting variables or evaluating expressions inside it.
Use &STR when the value contains blanks, parentheses, commas, or ampersands you want kept literally.
Without &STR, SET &MSG = HELLO WORLD only keeps HELLO; &STR keeps the whole phrase.
&STR also protects operators: SET &EXPR = &STR(2 + 3) stores the text "2 + 3", not 5.

SET &A = 10
SET &B = &STR(&A + 5) /* &B is the literal text: &A + 5 */
SET &MSG = &STR(HELLO WORLD) /* keeps the blank */
WRITE &B
WRITE &MSG

&EVAL - arithmetic evaluation

&EVAL(expression) computes an arithmetic result. SET &C = 2 + 3 stores text; SET &C = &EVAL(2 + 3) stores 5.
Supported operators: + - * / and parentheses for grouping.
Division of integers truncates toward zero: &EVAL(7 / 2) gives 3.
Always &EVAL user input before numeric comparison, or "9" will compare larger than "10" as text.

SET &PRICE = 100
SET &QTY = 3
SET &TOTAL = &EVAL(&PRICE * &QTY)
WRITE TOTAL = &TOTAL /* displays: TOTAL = 300 */
SET &HALF = &EVAL(&TOTAL / 2)
WRITE HALF = &HALF /* displays: HALF = 150 */

String functions: &SUBSTR, &LENGTH, &DATATYPE

&SUBSTR(start:end:string) extracts characters; positions start at 1 and both ends are inclusive.
&LENGTH(string) returns the number of characters in the string.
&DATATYPE(string) returns NUM if the string is numeric, CHAR otherwise.
&SYSDATE holds MM/DD/YY, so &SUBSTR(7:8:&SYSDATE) pulls out the two-digit year.

SET &D = &SYSDATE /* e.g. 10/08/26 */
SET &YY = &SUBSTR(7:8:&D) /* 26 */
SET &MM = &SUBSTR(1:2:&D) /* 10 */
SET &N = &LENGTH(&D) /* 8 */
IF &DATATYPE(&YY) = NUM THEN WRITE YEAR IS NUMERIC

System symbolic variables

TSO provides read-only system variables: &SYSUID (your userid), &SYSDATE (MM/DD/YY), &SYSTIME (HH:MM:SS).
&LASTCC holds the return code of the most recently executed TSO command. Save it immediately: it changes after every command.
&MAXCC holds the highest return code seen so far in this CLIST run.
&SYSDSN('dsname') is a built-in function returning OK if the dataset exists, or an error message if not.

WRITE USERID = &SYSUID DATE = &SYSDATE TIME = &SYSTIME
LISTDS 'USER1.DATA'
SET &RC = &LASTCC
IF &RC = 0 THEN WRITE DATASET LISTED OK
IF &SYSDSN('USER1.DATA') = OK THEN WRITE DATASET EXISTS

Backward

Forward

Let's understand Mainframe