GERMAN I TSO CLIST & ISPF

Using TSO and ISPF for Generating SAS® Programs

Hallett German, GTE LABORATORIES Inc.

INTRODUCTION variable, and executes a . 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 . 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 ? 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 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 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. ) IM skeletoname options -- Nests up to three skeletons. 5. Use OPENFILE..OUTPUT to create a new Options dataset record and OPENFILE .. UPDATE to modify include NT an existing record. (include file but no 6. To do a PUTFILE ori an OUTPUT dataset, assign additional translating the entered record to a symbolic variable with the same name as ddn. and OPT Use the &STR function to retain (process blanks. For an UPDATE dataset, GETFILE retrieves even if the the record to modify use a DO-WHILE or DO-UNTIL if skeleton does not 7. Do a PUTFILE to only one PDS member. exist.) )SEL condition -- Conditionally include 8. Note GETFILE and PUTFILE always convert text input records until to upper case. finding and )ENDSEL. Condition may use ANDs,ORs, and most relational operators. You may nest Method 2: ISPF Skeletons up to 8 )SEL-)ENDSEL blocks ISPF provides the file tailoring facility for creating Use any other customized sequential files. This includes creating skeleton statement output files based on symbolic variable values and in this block. any needed symbolic substitution. To produce an output file, an ISPF dialog (application) needs the )SET dialogvar = value -- Assigns a following. 1) A Skeleton (INPUT FILE) composed of value to a INPUT RECORDS used to create OUTPUT dialog RECORDS and SKELETON STATEMENTS. 2) "FT" variable DIALOG MANAGER STATEMENTS. which uses The "FT" prefix no notes file tailoring services are to be used. Let us ampersand. briefly look at each of these: You can assign a

70 GERMAN I TSO CLIST & ISPF

nearly or more clist-like statements performing some infinite specified edit task. usually repetitively. These clist number of statements reside as a member of a partitioned values with dataset part of the SYSPROC concatenation. You one )SET. You may also can also create edit macros with REXX or languages perform like C or (called PROGRAM MACROS.) mathematical Space does not permit a discussion of initial and operations. recovery macros, and program macros.

To invoke an edit macro, do any of the following: "FT'' Dialog Manager Statements 1. Type in the macro name at the Here is a typical framework of creating an output INITIAL MACRO==-> area dataset with skeletons. of the Edit-Entry panel (PDF option 2.) 1. ISPEXEC FTOPEN TEMP 2. ISPEXEC FTINCL MYSKEL 2. Place in a clist: 3. ISPEXEC FTCLOSE ALLOC F(fnm) DSN(dsn) SHR 4. ISPEXEC VGET (ZTEMPF) ISPEXEC EDIT DATASET(dsn) MACRO(mnm) 5. ALLOC DD(MYCOPY) DA('&ZTEMPF') SHR ISPEXEC EDIT DATASET(dsn) MACRO(mnm) 6. ALLOC DD(PERMl) DA(PERM.DATA) NEW .. 3 . In the COfJKiTAND -==> part of the 7. COPY '&ZTEMPF' PERM.DATA EDIT screen. This is what is happening above: Macro statements always begin with ISREDIT. A macro starts with an ISREDIT statement such as Statement 1: Opens a temporary sequential dataset ISREDIT MACRO (LASTNAME). The edit macro is because of the TEMP operand. ISPF assigns the defined with one symbolic variable (always in system variable &ZTEMPF the eight character name parentheses.) If the macro Is named NAMECHG, of the dataset. then you could enter NAMECHG GERMAN at the COMMAND ===> prompt. This assigns the value of Statement 2: Include and process the skeleton GERMAN to &LASTNAME. Additional variables (as MYSKEL (or any other skeleton name). The name well as default values) can be assigned as well. An used must be a member of a partitioned dataset in important point is these variables are positional and the ISPSLIB concatenation. Note placing NOFT after the edit macro does not check if user-entered values the skeleton name just copies the file without any are out of order. One of these statements usually end a macro: symbolic substitution. A &LASTCC of 8 means the skeleton does not exist. 1. EXIT CODE(&MAXCC)

Statement 3: Closes the file. Use the NOREPL 2. ISREDIT END -- saves dataset. operand stops any overwriting of existing output files. 3. ISREDIT MEND -- batch only. 4. ISREDIT CANCEL Statement 4: Retrieve the name of the temporary file from shared variable pool. Use this to submit this dataset as a JCL job. An important concept of both PDF EDIT and Edit macros is labels. Labels are markers showing the Statements 5-7. Statement 5 allocates the temporary relative position of a line. So you can perform an edit output file which is copied to a permanent dataset in operation without actually knowing the line number. statement 7. Statement 6 allocates the permanent Valid label names start with a period and then have output file. up to fi11e alphabetical characters. System labels start witrl .Z and cannot be changed by an edit macro. These are: Method 3: ISPF/PDF Edit Macros .ZCSR -- Current cursor position PDF Edit macros have been available since ISPF Version 2 Release 1. An EDIT MACRO is an .ZDEST -- The "to" line in edit ISPF/PDF primary edit command consisting of one operations.

71 GERMAN I TSO CLIST & ISPF

.ZFIRST -- Relative top of file. 1. REXX can process a greater variety of data (including decimal integers.) It also generally doesn't . ZFRANGE Start of range . need built-in functions to do this. . ZLRANGE End of range . 2. REXX has superior string manipulation and . ZLAST Relative end of file . parsing features, and stronger flow control structures. A common sequence is doing a FIND on a string assigning the value of .ZCSR to a user label and The Clist language can only work in the TSO then perform a DELETE or another EDIT operation. 3. address space of MVS and cannot be easily ported to any operating systems. The following clist statements are commonly used with Edit macros: Because Chapman Gleason's paper at NESUG '89 CONTROL LIST CONLIST will more than cover "What is REXX", the remainder of the paper compares the clist and REXX Clist Labels languages. (See the table on the next page.) Keep the following in mind when converting from Clists to SET (do math operations) REXXexecs: Flow Control Structures -Programmers who take advantage of (IF-THEN,DO-WHILE ... ) features in TSO/E Version 1 Release 4 and later will EXIT, IF &LASTCC have an easier time converting.

WRITE &LASTCC -- debugging. - Watch out for GOTOS in clists.

Built-in Functions - Convert clists that can take (&DATATYPE, &STR ... ) immediate advantage of REXX: o Those with string manipulation. Also other ISPF services: o A multiple clist which should VGET/VPUT -- pass values be a subprogram. between clist o Sequences that do date or time and macro math. (only way!) o Sequences which convert a whole number to a decimal. Skeletons to build macros! o Using character instead of symbol for relational operators. Message services This concludes what has been a quick look at many important areas of clist and ISPF processing. I hope you can now better understand past and future talks REXX: The Next Command Language on this subject. Generation

REFERENCES: WhyREXX? All references can be found at the end of the In 1987, IBM announced their computers would appropriate chapters of TSO!E Clists: Main Streets adhere to a set of procedures and standards called and Back Roads to be soon published by Van System Administration Architecture or SAA. An Nostrand Reinhold. To get a copy of the overheads important part of SAA was selecting a subset of of the talk or other information please contact: REXX (REstructured eXtended eXecutor) as the Hallett German SAA Programming Language (or SAA/PL.) For MVS GTE Laboratories users, this meant that REXX can run in the TSO and 40 Sylvan Road non-TSO areas. It is clear that REXX, not clist, is the Waltham, Ma 02254 focus of future IBM developments. This is probably 617-466-2290 why REXX was selected over clists:

72 GERMAN I TSO CLIST & ISPF

Feature REXX Clist

System Design 1 phase interpreter 2 phase interpreter

More flow control structures.

Statements in any Statements case. upper case.

Variables and More data types. Operators

More powerful Character operators. equivalents of relational operators.

Stack Operations Easy manipulation No easy manipulation

Built-in Functions 60+ Functions 15 functions

Trace Facility Slightly more powerful.

Subprograms Internal/external Internal only subprograms and subprograms. functions.

SAS® is a registered trademark of the SAS Institute Inc., Cary, North Carolina.

73