Module 3: CLIST Control Statements

CLIST- Control Statements

Control statements decide which lines run and how often: IF-THEN-ELSE for decisions, DO WHILE and DO UNTIL for loops, SELECT for multi-way branches, and GOTO for jumps. Together with EXIT and RETURN they turn a flat list of TSO commands into a real program.

IF-THEN-ELSE

IF condition THEN statement runs the statement only when the condition is true.
Add ELSE statement for the false path. ELSE always pairs with the nearest unmatched IF.
For multiple statements in a branch, wrap them in DO ... END and continue the IF line with +.
Comparison operators: = (equal), < (less than), > (greater than), <= and >=.

IF &CHOICE = 1 THEN WRITE YOU PICKED ONE
ELSE WRITE YOU PICKED SOMETHING ELSE

IF &RC = 0 THEN +
DO
WRITE BACKUP COMPLETED
END
ELSE +
DO
WRITE BACKUP FAILED, RC = &RC
EXIT CODE(8)
END

DO WHILE and DO UNTIL loops

DO WHILE condition ... END repeats while the condition is true. The test happens before each pass, so the loop may run zero times.
DO UNTIL condition ... END repeats until the condition becomes true. The test happens after each pass, so the loop always runs at least once.
DO loops can be nested, but every DO needs its matching END.
Always change the loop variable inside the loop, or it will never end.

SET &I = 1
DO WHILE &I <= 5
WRITE COUNT = &I
SET &I = &EVAL(&I + 1)
END

SET &TRIES = 0
DO UNTIL &TRIES = 3
READ &PW PROMPT(ENTER PASSWORD:)
SET &TRIES = &EVAL(&TRIES + 1)
END

SELECT-WHEN-OTHERWISE

SELECT tests a list of WHEN conditions from top to bottom and runs the first one that is true.
Each WHEN condition is written in parentheses: WHEN (&C = 1).
OTHERWISE catches everything that matched nothing. Without it, no match means nothing happens.
The block ends with END. SELECT is cleaner than a long chain of IF-ELSE statements.

SELECT
WHEN (&DAY = MON) WRITE START OF THE WEEK
WHEN (&DAY = FRI) WRITE WEEKEND IS NEAR
OTHERWISE WRITE JUST ANOTHER WEEKDAY
END

GOTO and labels

GOTO -name jumps to the label -name: elsewhere in the CLIST. Labels begin with a hyphen and end with a colon.
CLIST labels look different from REXX labels (REXX uses name: with no hyphen).
Use GOTO for simple loops and for skipping to cleanup code at the end.
Prefer DO WHILE and SELECT for new code; reserve GOTO for error exits and retries.

SET &N = 0
-TOP: SET &N = &EVAL(&N + 1)
WRITE N = &N
IF &N < 3 THEN GOTO -TOP
WRITE LOOP FINISHED

EXIT and RETURN

EXIT ends the CLIST immediately and returns to the caller (TSO READY or the calling CLIST).
EXIT CODE(n) ends the CLIST and passes return code n back. The caller sees it in &LASTCC.
RETURN also goes back to the caller, but is meant for returning from a called routine rather than ending everything.
Reaching the last line of the member is the same as EXIT with no code.

IF &SYSDSN('&DSN') = OK THEN WRITE EXISTS
ELSE +
DO
WRITE NOT FOUND
EXIT CODE(4)
END
WRITE CONTINUING...

Putting it together: a menu CLIST

This complete example combines READ, SELECT, GOTO, and EXIT into a small menu that loops until the user picks option 3.

/* MENU: simple option menu */
PROC 0
CONTROL NOMSG
-MENU: WRITE
WRITE 1 - LIST YOUR DATASETS
WRITE 2 - SHOW DATE AND TIME
WRITE 3 - EXIT
WRITENR ENTER CHOICE (1-3):
READ &C
SELECT
WHEN (&C = 1) LISTDS
WHEN (&C = 2) WRITE &SYSDATE &SYSTIME
WHEN (&C = 3) GOTO -DONE
OTHERWISE WRITE INVALID CHOICE - TRY AGAIN
END
GOTO -MENU
-DONE: WRITE GOODBYE
EXIT

Backward

Forward

Let's understand Mainframe