GERMAN I TSO CLIST & ISPF Using TSO Clists and ISPF for Generating SAS® Programs Hallett German, GTE LABORATORIES Inc. INTRODUCTION variable, and executes a clist. TSO Clists (pronounced SEE-LISTS) and ISPF­ based applications are frequently presented at A Clist dataset is either sequential or partitioned SUGI. However, many users do not have a good using a record format of fixed block or variable understanding of these products to fully appreciate blocked (FB or VB). Clist datasets are allocated to a these talks. The Interface section of NESUG 89 concatenation named SYSPROC using a TSO attempts to relieve this by reviewing popular ALLOCATE command such as the example below: interpreted command languages and how they can be used to build SAS applications. al/oc f(sysproc) da(my.clist­ The following outline is followed: 'sys1.cl/sf) shr reuse I. Introduction A. What are Clists? The above example concatenates 1. Allocating Clists two datasets. The 2. Clist Components personal clist dataset is placed first so your clists will 3. Clist Limitations execute before a system clist of the same name. 4. Clist Uses Ideally, datasets in the concatenation should be the 5. Clist Internals record format and block size. Otherwise use the B. What is ISPF? BLKSIZE operand of ALLOCATE or place the 1. ISPF Components dataset with the largest blocksize first. 2. Invoking ISPF Dialog C. File I/0 Operations To execute 1. Clist QSAM Facility a clist from the READY prompt enter: 2. ISPF Skeletons. 3. PDF Edit Macros. exec 'hhg1.my.c/ist(test)' or exec runit.clist D. The Future of Clists 1. Why REXX? The first form is fully-qualified (with userid) and is for 2. REXX versus Clists. a partitioned dataset. The second form is not fully­ The paper will attempt to present the major concepts qualified and is for a sequential dataset. See the of these areas so you can have a good foundation to references for other forms and considerations when look at IBM documentation or SUGI talks and build invoking clists. Note TSO/E Version 2 sites can also real-world examples. Those wanting a more specify a CLIST operand to differentiate a clist from comprehensive version on this topic, see my a REXX exec. (Such as exec mylib.clist clist.) forthcoming book on TSO/E Clists. Clist Components What are Cllsts? The following are the major components of the clist language and the corresponding statements * Trace facility Allocating Clists - CONTROL What follows is a brief introduction to clists. * File Operations A CLIST is - OPENFILE, CLOSFILE a sequential or partitioned dataset - GETFILE, PUTFILE member with executable TSO commands and clist statements. The CLIST LANGUAGE is a high-level * Terminal Operations interpretative symbolic programming language made - READ, READDVAL up of clist statements. This definition means that - WRITE, WRITENR clist statements 1) use English-like commands, 2) - TERMIN has an interpreter which during two phases, checks - DATA-ENDDATA for syntax, performs symbolic substitution on each * Exception Handling 67 GERMAN I TSO CLIST & ISPF 1 - ATTN, ERROR Clist Internals - CONTROL, RETURN Many problems clist users have are a result of not - EXIT understanding how clist internals work. The EXEC interpreter processes clist In two distinct phases. Built-in Functions * Here is a summary - 15 of them of some of what happens. This is based on reverse engineering and not on any IBM * System Variables documentation: - 37 of them Phase 1: Startup Tasks (17 used by TSO/E REXX} - Check if dataset exists - Is it a clist or REXX exec? * Clist Symbolic Variables - How clist invoked? - SET, LISTDSI, PROC - EXEC operands valid? - Case of parameters? * Clist Flow Control - Syntax of TSO and clist - DO-UNTIL-END statements - DO-WHILE-END Any mentioned dataset exist? - IF-THEN-ELSE - SELECT-END - Iterative DO Phase 2: Execute Clist Compound DO Are there any nested symbolic variables ? * Calling other clists - Are there system variables or - SYSCALL built-in functions? - EXEC Is there the need for another - GLOBAL, NGLOBAL symbolic substitution scan? - SYSREF Are there any TSO statements to process? - Execute the clist and TSO Clist Limitations connnands? The clist language does have its limitations, some of - Get the return code. which are listed. 1) Clists cannot directly read - Perform error or attention routines. character data. You need a built-in function to do this. 2) Clists cannot easily parse character strings. So phase 1 reads each clist statement and checks 3) Clists values cannot be decimals. 4) Clists allow its syntax and phase 2 performs symbolic for some sloppy programming practices. 5) Clists substitution and executes the clist. We will go back lack the processing speed of an interpreted program. to looking at clists after a brief introduction to ISPF. Clist Uses What Is ISPF? There are four types of clist uses: Utility Clists do system tasks. ISPF components Application Clists are self-contained ISPF or Interactive System Productivity Facility applications which may be full-screen. allows programmers to quickly develop interactive applications. Features include data entry validation, Front-End Clists access other help screens, tutorials, dynamic program creation, languages. and simple database transactions. To build full­ Clist and other languages such as screen applications or DIALOGS requires using REXX, Edit Macros, Session Manager. ISPF Dialog Manager services including: Clists are the gateway to building many ad-hoc * Display Services oversees the input/output processing and production applications because of Its ties of full-screen PANELS. to many languages and environments. * Table Services coordinate the adding, modifying, deleting, and saving data into a two dimensional array or TABLE. 68 GERMAN I TSO CLIST & ISPF * Variable Services manages Method 1: Clist QSAM Facility user-generated and system variables An important part of clist processing is creating and between and within dialogs. modifying small datasets using the Queued Sequential Access Method or QSAM. QSAM is * File Tailoring (Skeleton) Services generates programs used for foreground ideal for clists because: or background (batch) processing. * It reads datasets sequentially, so keys (unique record identifers) are not needed. This is great for * Message and Other Services controls small datasets but may mean reading the entire the dialog's help and tutorial panels dataset just to access the last record - bad for large and also processes any dialog messages. datasets. * QSAM is device and mode independent. QSAM runs in either interactive or batch TSO. This also Invoking an ISPF dialog means that QSAM does not need compiling or To invoke an ISPF dialog requires two steps: 1) recompiling - great for interpreted languages. allocating the appropriate dataset and 2) invoking the dialog. Here is a brief look at each. To reinforce the above, here are some rough benchmarks for ao byte records. To allocate an ISPF library is nearly identical to allocating the SYSPROC datasets for clist shown Records Time in Seconds earlier. Here is a simple allocation: 1 < 1 10 < 1 100 < 1 free f(sysproc ispplib ispmlib ispsllb) 500 < 1 alloc f(sysproc) da(.. ) shr reuse /*Ciists*/ 1000 2 a/lac f(ispplib) da(.. ) shr reuse /*Panels*/ 5000 8 10000 17 alloc f(ispmlib) da(.. ) shr reuse /*Messages*/ 50000 86 alloc f(ispslib) da(.. ) shr reuse /*Skeletons*/ ISPF Version 2 Release 3 and later users can also A good rule of thumb for the clist QSAM facility is: If use the LIBDDEF command. The following clist more than 5000 records, send a message to the sequence will correct invoke an ISPF application users that processing may take some time. read regardless if invoked from TSO or ISPF: and write from a dataset. Read from !! dataset. IF &SYSISPF NE ACTIVE THEN DO ISPSTARTPANEL(A10P) NEWAPPL(AP1) 1. error routine 2. FREE F(ddn) END 3. ALLOC F(ddn) DA(dsn) SHR ELSE DO 4. OPENFILE ddn INPUT ISPEXEC SELECT PANEL(A 10P) NEWAPPL(AP1) or END 4. OPENFILE ddn 5. GETFILE ddn 6. SET &symvar = &ddn Note ISPF statements start with ISPEXEC amd edit 7. CLOSFILE ddn macro statements start with ISREDIT. 8. FREE F(ddn) Write to !! dataset File 1/0 Operations 1. error routine We will briefly look at three different ways to create 2. FREE F(ddn) 3. ALLOC F(ddn) DA(dsn) OLD and modify a SAS program using dynamic symbolic 4A. OPENFILE ddn OUTPUT substitution. These are 1) the Clist QSAM facility, 2) (Use with 5A.) The ISPF file tailoring (skeletons) facility, and 3) or ISPF/PDF edit macros. 4B. OPENFILE ddn UPDATE (Use with 5B.) SA. SET &ddn = &symvar 69 GERMAN I TSO CLIST & ISPF 5B. GETFILE ddn Input Records 6. PUTFILE &ddn Input records may contain: 7. CLOSFILE ddn B. FREE f(ddn) 1) Symbolic variables which translate to no larger than the output record. An ampersand followed by a Here are some things to consider when reading or blank will not process. writing to a dataset 2) Special characters - use two to produce one. 1. Include error routines or IF &LASTCC - .. THEN... These include & (for SAS macros), I, and I· Failure to do this means opened files. Some possible routines are 1) unexpected end of file, 2) 3) A Question mark in the last column continues an dataset not found, 3) unable to open or close input line. dataset. And 4) Writing to a read-ready dataset or reading from a write-ready dataset. 4)Skeleton Statements: 2. The INPUT operand is optional when reading from )BLANK num. -- Adds num blank lines a dataset. to the output record. )CM text -- Adds a comment to your 3. GETFILE reads a record and assigns it to a output file. symbolic variable with the DO-UNTIL. )ENDSEL -- Ends a )SEL block. 4. To ''freeze" the current record, assign it to another symbolic variable.