CLIST- Advanced

Production CLISTs need more than WRITE and IF: they trap errors instead of dying mid-run, share data between nested CLISTs, live in managed SYSPROC libraries, and cooperate with REXX and ISPF. This module puts those pieces together in one complete utility CLIST.

ERROR handling

• The ERROR statement sets a trap that runs when a TSO command invoked by the CLIST fails.
• ERROR DO ... END runs your own cleanup block: log the failure, then EXIT with a code.
• ERROR RETURN sends control back to the calling CLIST or TSO.
• ERROR EXIT CODE(n) ends the CLIST at once with return code n.
• ERROR OFF disables the trap again. Code the ERROR statement before the risky commands.

GLOBAL and NGLOBAL variables

• Normally each CLIST has its own private variables. GLOBAL &V1 &V2 shares the listed variables with every CLIST it calls, down the whole chain.
• Code GLOBAL right after PROC, before any statement that uses the shared variables.
• Every CLIST in the chain that touches the shared variables should declare the same GLOBAL statement.
• NGLOBAL &V1 removes a variable from the shared pool again.
• Use GLOBAL for a small set of control values (like &HLQ or &DEBUG); pass everything else as PROC arguments.

SYSPROC and CLIST libraries

• SYSPROC is the ddname whose concatenated PDSs TSO searches for the %member form and for nested EXEC calls.
• Your logon procedure allocates the system CLIST libraries to SYSPROC automatically.
• Add your own library for the session with: ALLOC F(SYSPROC) DA('USER1.CLIST') SHR.
• After that, %PAYRPT JAN finds member PAYRPT in your PDS without any quoted dataset name.
• Keep production CLISTs in a shared team PDS allocated to SYSPROC by the logon proc, not by personal ALLOCs.

Calling CLISTs from REXX

• A REXX exec can run any CLIST through the TSO command environment with EXEC.
• ADDRESS TSO "EXEC 'USER1.CLIST(ARCHDSN)' 'USER1.DATA'" runs the CLIST and waits for it.
• After the call, the REXX special variable RC holds the CLIST's return code (from EXIT CODE(n)).
• CLISTs can also call REXX execs the same way, so mixed-language toolchains are common.

Calling CLISTs from ISPF

• From any ISPF command line (including option 6), %ARCHDSN USER1.DATA runs the CLIST under ISPF.
• Inside a panel's )PROC section, SELECT CMD(%ARCHDSN USER1.DATA) runs the CLIST when the panel processes.
• A CLIST can call ISPF dialog services directly: ISPEXEC DISPLAY PANEL(MYPANEL) shows a panel, ISPEXEC VGET/VPUT move variables between the CLIST and the ISPF shared pool.
• ISPF services need an ISPF session: they fail if the CLIST runs in batch TMP without ISPF started.

Complete utility CLIST: ARCHDSN

ARCHDSN archives a dataset by renaming it with a date stamp. It validates the input with &SYSDSN, builds YYMMDD from &SYSDATE with &SUBSTR, traps errors, and returns a meaningful code. Save it as member ARCHDSN and run %ARCHDSN USER1.DATA.