History of TSO: Part One
by Jim Moore
Whats in a name? Or more accurately, where many people own individual time whats in an acronym? Repeat after me: shares of a property. I wonder if real estate Plenty! In the mixed-up, crazy world of soft- sales people also refer to these as a TSO? ware jargon, acronyms are the names. It matters not. The context here is the vener- Heres a quick acronym question: What un- able old MVS (pardon me for using the most derlying words does TSO, the acronym, rep- simplistic name but I dont need another trip resent? Heres the quick answer: Time-Shar- to the acronym vault) software system ing Option. known as TSO Time-Sharing Option.
Lets analyze these three words separately, Thats my context and Im sticking to it! Fall 2003 shall we? The Birth of a Name
TSO Assistance for Assistance the MVS Professional TSO Time A temporal, somewhat ephemeral Have you ever noticed that when something concept measured in ticks of a clock, life- new comes along, the initial name that is times or even vast, incomprehensibly long given to it speaks volumes about the pithy In This Issue periods covering billions of years. essence of the thing? I have.
Sharing Sharing is a good thing. Didnt Sometimes these seminal names stick, some- History of TSO: Part One your mom teach you that? times they dont. For instance, do you call by Jim Moore your car a horseless carriage? Or do you Option Something that isnt mandatory. refer to a modern airplane as a heavier than Or, that thing that a car salesperson will air machine? REXX TCP/IP Sockets ALWAYS try to get you to purchase: Would by Mike Shaw you like the extended-warranty option? No? Me neither. But these terms were ubiq- uitous just over 100 years ago. They do an Why Develop TSO The phrase time-sharing option has yet excellent job of describing something new Command Processors? another meaning: Think vacation condos in the context of their current time. To a by Steve Myers ...continued on page 3
To Address or Not to Chicago-Soft Announces Address and Comments (Style vs. Performance) The FutureFuture ofof ISPF...TODAY!ISPF...TODAY! by Lionel Dyck ISPF-Plus brings a modern-age graphical interface to ISPF that works within Windows Explorer. With its Windows/web look and feel, ISPF-Plus provides A TSO/E Command easy-to-use, point-and-click technology to perform tasks previously available Trapper only in a traditional 3270 format, and limited to those users familiar with the by Jim Moore cryptic, command-line driven green screen technology.
A 21st Century z/OS ISPF ISPF-Plus benefits all TSO/ISPF users Environment Easy to learn and use by Jim Moore Saves keystrokes and multi-screen requirements Extensive fly-over and context-sensitive help Single desktop & workspace access to all applications: mainframe & non-mainframe & the internet Plus a whole lot more!
For more information about ISPF-Plus give us a call at 603-643-4002, email [email protected] or visit us on-line at www.chicago-soft.com/ispfplus www.tsotimes.com REXX TCP/IP Sockets by Mike Shaw Did you know that REXX for TSO/E includes a complete set of ISPF Edit to view a copy of the HTTP servers access-log file. functions that implement TCP/IP socket calls? OK, maybe you did When IPLOOKUP starts, it extracts the log-file line that the cursor know, but have you had a chance to use them? is on and pulls the IP address out of that line and saves it in a REXX variable named data. Once the IP address is extracted and I recently needed to use the REXX TCP/IP socket functions. I was checked for reasonableness, IPLOOKUP uses various REXX TCP/ in the process of analyzing the access logs produced by the IBM IP socket calls to establish a TCP/IP connection. HTTP server under z/OS. The HTTP server produces several logs whenever it receives a request to serve a web page to a client. One The main TCP/IP call of interest is the statement that looks like log records accesses, one log records errors, another log documents this: Common Gateway Interface (CGI) errors, and so on. lastrc = Socket(GETHOSTBYADDR,data) One log of particular interest is the HTTP server access log, usu- ally found in the this statement uses the IP address stored in the REXX data vari- able as an argument to the REXX TCP/IP socket function called /web/httpd1/logs/httpd-log GETHOSTBYADDR. This function accepts an IP address and re- turns the name of the host associated with that IP address. The or returned host name is then displayed in a one-line message by the IPLOOKUP macro through the use of the ISPF SETMSG service. /usr/lpp/internet/server_roots/logs/httpd-log If a non-zero return code is passed back from any REXX TCP/IP socket function call, an error message is displayed and the edit directories on the UNIX System Services (USS) side of z/OS and macro terminates execution. OS/390 systems. The actual log location is specified using the AccessLog directive in the HTTP server configuration file Its not fancy, but this macro provides a quick way to determine the (httpd.conf). host name associated with a given IP address. When you are re- viewing HTTP server logs, who issued that request? is a ques- Here is an example of what the HTTP server access log contains: tion that comes up frequently. The IPLOOKUP macro will help you answer that question quickly, and also gives you a
9.3.7.140 - - [06/Jun/2001:14:26:27 +0500] GET / HTTP/1.1 401 247 9.3.7.140 - rmoles [06/Jun/2001:14:26:31 +0500] GET / HTTP/1.1 200 2621 9.3.7.140 - rmoles [06/Jun/2001:14:26:34 +0500] GET /Admin/lgmast.gif HTTP/1. 9.3.7.140 - rmoles [06/Jun/2001:14:27:21 +0500] GET /favicon.ico HTTP/1.1 40 9.3.7.140 - - [06/Jun/2001:14:28:57 +0500] GET / HTTP/1.1 401 247 9.3.7.140 - - [06/Jun/2001:14:29:14 +0500] GET / HTTP/1.1 403 693 9.3.7.140 - - [06/Jun/2001:14:29:37 +0500] GET / HTTP/1.1 401 247 9.3.7.140 - webadm [06/Jun/2001:14:29:47 +0500] GET / HTTP/1.1 200 2621 9.3.7.140 - webadm [06/Jun/2001:14:29:48 +0500] GET /Admin/lgmast.gif HTTP/1.
simple overview on how to use the TSO/E REXX TCP/IP socket The first field in each log-file record is the Internet Protocol (IP) functions. address for the client (i.e., web browser) that issued the request. The IP address, rather than the actual host name, is saved in the More information on TSO/E REXX TCP/IP sockets can be found log-file entry to identify that entry and to speed up execution of the on the Internet by using Google to search on these arguments: IBM HTTP server. The IP number provides the IP address of the system REXX SOCKET on which the requesting client/browser was executing. The source code for the IPLOOKUP Edit Macro is available for If you want to know what the actual name of that host system is, download at www.tsotimes.com/currentarticles.html you have to decode the IP address by using the services of a Do- main Name Server (DNS).
I wanted to find out what the actual host name was for the IP ad- dress in certain log entries that were of interest to me, so I created Mike Shaw is a senior software developer in the MVS/Quick- an ISPF edit macro, written in REXX, that performs that function. Ref product support group at Chicago-Soft. Mike has over 27 years of MVS experience as a Systems Programmer and Sys- The edit macro (I call it IPLOOKUP) is invoked while I am using tem Software Developer. 2 History of TSO: Part One
...continued from page 1 population thoroughly accustomed to the idea of horses pulling TSS (Time-Sharing System) was an attempt to do everything that four-wheeled carriages, the name horseless carriage made per- Multics did, but better. IBM knew this project was strategically fect sense. important and put a lot of resources into it. Hundreds of program- mers. The result was a system that was bloated and unstable. The Today, if you called a car a horseless carriage, people would think first release took over ten minutes from power-up to the first login you were a kook. Especially your local mechanic! prompt, but usually crashed within 10 minutes after that. Eventu- ally, IBM killed the project. 2 The Birth of TSO Can we apply this same clear birth-of-a-name logic to TSO? Yes, A fascinating piece of TSO-related lore can be found in a piece of but just as with the car/horseless carriage example, we will have to software that went by the name of MTS, or Michigan Time-Shar- roll back the clock a bit to gain a more balanced, historical per- ing System (also known as the Michigan Terminal System). There spective. Not quite as far back, though. are some interesting articles written about MTS on the Web. Here is a succinct description of it: Lets set the dial on the way back machine to the room-filling, monolithic, single-user computer era of the late 1960s, early 1970s. The Michigan Time-Sharing System was started in 1966 to exploit a modified 360/65 which was to be built specifically for this project. I dont want to shortchange all the rich historical details involved By the time it was delivered in 1967, others had heard about the here but I am space constrained. Refer to the Internet links that machine, and over 100 units had been ordered. The history of the accompany this issue for some fabulous histories of early time shar- MTS project is told in these 3 articles publiched [sic] by Univer- ing environments. sity of Michigan in 1996, when the last MTS machine was turned off.3 What I took away from reading all of this historical material is that in many ways computers of 1960s vintage were a lot like personal Wrap It Up, Ill Take It! computers of the 1980s. That is, they were single-user, non-shar- I didnt really write much about our loyal old pal TSO, did I? Noth- able, one-thing-at-a-time type of computers. And huge, as well as ing about ISPF either. OK, Ill admit it. Thats the hook! Read the hugely expensive! conclusion of the first part of this TSO essay on the Internet. Point your browser to: www.tsotimes.com/currentarticles.html THE issue of 1960s computing was: How can we do more than one thing at a time on these behemoths? Or stated another way: How to share the time and multi-process to get more bang for the buck 1 The Evolution of the Unix Time-sharing System By Dennis M. Ritchie out of these monsters? Web Link: http://cm.bell-labs.com/cm/cs/who/dmr/hist.html
2 Computer History - IBM 360/370/3090/390 TSS/360 Sub-Heading This is a strange concept to us today. Here in the 21st century, highly Web Link: http://www.beagle-ears.com/lars/engineer/comphist/ibm360.htm shared computing (especially mainframe and Unix) environments are taken for granted. 3 Computer History - IBM 360/370/3090/390 MTS Michigan Time-Sharing Sub-Heading Historical slants - Multics, TSS and MTS Web Link: http://www.beagle-ears.com/lars/engineer/comphist/ibm360.htm IBM was the dominant computer maker of the 1960s but there were a number of other players in the time-sharing game. One major player was AT&T, or more specifically, their Bell Labs R&D divi- sion. They too were busily trying to solve the time-slicing, multi- user problem with their 1960s-vintage Multics operating system. TSO Times is published by Chicago-Soft, LTD., which develops and Multics was a very early, experimental time-sharing system devel- markets corporate productivity and management software for main- oped by Bell Labs. It was never commercially released but was, in frame, Windows and web-based systems. Intended as a forum for the fact, the inspiration for Unix. Quoting Dennis M. Ritchie: exchange of technical information of interest to TSO and ISPF users, its content will be mostly technical, with some promotional materials.
Although it was not until well into 1970 that Brian Kernighan All inquiries concerning subscriptions, requests and change of address suggested the name Unix, in a somewhat treacherous pun on should be sent to Chicago-Soft, LTD, ATTN: TSO Times, One Maple Multics, the operating system we know today was born. 1 Street, Hanover, NH 03755, TEL: 603-643-4002, FAX: 603-643-4571, email: [email protected]
On IBM machines of the 1960s something called TSS was a kind Additional information can be found at www.tsotimes.com. of pre-cursor to what is now known as TSO. TSS, or Time-Sharing Chicago-Soft, LTD information can be found at www.chicago-soft.com System, was an IBM boondoggle from the get-go. Consider this: Copyright © 2003 Chicago-Soft, LTD All rights reserved. All trademarks are property of their respective holders. 3 Why Develop TSO Command Processors? by Steve Myers TSO command processor programs - also sets and call batch programs. Some CLISTs The command line is unnatural. The com- called prompters - are small programs run also perform some fairly serious process- mand line a TSO user would expect would in line mode TSO that perform whatever ing, but this processing is mostly setup pro- be: functions their authors need. Although com- cessing for another program. LIBRPRT dsn(member) mand processor programs are written in not FLIBPRT is a CLIST that prints a member Assembler, they are surprisingly easy to LIBRPRT dsn member of a CA-ADR Librarian master file that write. contains an archive of Assembler listings. It damages the existing environment. It frees Even though command processors are fairly It is a shell script that calls a personal pro- up data sets allocated with the SYSPRINT, easy to write, they are certainly more diffi- gram called FLIBGET, which copies a SYSUT1, SYSUT2 and SYSIN DD names. cult than REXX or CLIST. When trying to member of a CA-ADR Librarian data set Certainly it makes a good guess about real- determine whether it is worth writing a com- to a "regular" partitioned data set. Then locating SYSPRINT and SYSIN, but it's not mand processor in Assembler, first analyze FLIBPRT calls another CLIST, PRT4UP, quite the same. what you are doing when you write a REXX which actually prints the data-set member or CLIST program. Then determine if you to a fixed destination using fixed attributes. It allocates a temporary data set with a per- can improve your system by writing a com- Refer to Figure 1. manent name. To make sure it has a "fresh" mand processor. data set, it deletes an old version of the tem- The CLIST is fine if it is run just a few times porary data set. Most REXX or CLIST programs are really a day. However, if it is run hundreds of times shell programs that ultimately allocate data a day it presents quite a few problems. It does an unnecessary amount of work. An Assembler command processor would sim- ply allocate the CA-ADR Librarian mas- Figure 1 The FLIBPRT CLIST source code ter, the output destination attributes, and the PROC 2 LIBRDSN LIBRMEMB SYSOUT output data set, and then copy the CONTROL LIST member. CONTROL NOMSG FREE F(SYSPRINT SYSUT1 SYSUT2 SYSIN) Would the FLIBPRT CLIST be a good can- CONTROL MSG didate for translation to an Assembler TSO LISTDSI &LIBRDSN command prompter? It very well could be. SET RC = &LASTCC IF &RC ¬= 0 THEN + This article is continued on-line at WRITE &LIBRDSN DOES NOT EXIST www.tsotimes.com/currentarticles.html ELSE + DO Steve Myers has been programming LISTDSI LIBRPRT.TEMP since 1965 and writing TSO command SET RC = &LASTCC processors since the very beginning of IF &RC = 0 THEN + TSO. DO CONTROL NOMSG DEL LIBRPRT.TEMP CONTROL MSG END ALLOC F(SYSPRINT)DA(*) ALLOC F(SYSUT1) SHR DSN(&LIBRDSN) ALLOC F(SYSUT2) DA(LIBRPRT.TEMP) SP(2 1) CYL REC(V B M) DIR(1) + LRECL(255) CALL *(FLIBGET) &LIBRMEMB SET RC = &LASTCC FREE FILE(SYSPRINT SYSUT1 SYSUT2) IF &RC = 0 THEN + IF &SYSDSN(LIBRPRT.TEMP(&LIBRMEMB)) = OK THEN + PRT4UP LIBRPRT.TEMP(&LIBRMEMB) ELSE + WRITE MEMBER &LIBRMEMB NOT COPIED TO TEMPORARY DATA SET BY FLIBGET CONTROL NOMSG DEL LIBRPRT.TEMP CONTROL MSG END ALLOC F(SYSPRINT)DA(*) ALLOC F(SYSIN)DA(*)
4 To Address or Not To Address and Comments (Style vs. Performance) by Lionel Dyck When writing an ISPF application in REXX there are two camps between the same REXX coded both ways. when it comes to the use of the ADDRESS ISPEXEC statement. Camp one claims that you should use it on every statement that The TSO REXX FAQ (http://www.uberfish.freeserve.co.uk/Com- invokes an ISPF service, while camp two claims that you should puters/rexxfaq.html) suggests that, for performance reasons, camp only use it to set up the addressing environment for the ISPF ser- two is the proper camp to be in. Interestingly, when I asked IBM vices and then return to ADDRESS TSO when the ISPF services ISPF Level 2 this question they referred me to this FAQ, so it would are completed. seem that IBM agrees with their conclusion again based solely on performance. Why the two camps? One could reply that there are only two camps because there isnt another option, since we all know that program- The choice is yours to make as you are the artist/programmer and ming is an art and artists all have their own opinions. you have your own style. I hope this article has given you food for thought in deciding which camp you want to remain in (or join). Here are two examples: As long as we are on the topic of performance characteristics of your REXX program, take a look at comments. Here are two ex- /* REXX with Address ISPEXEC on every call of an amples: ISPF service */ arg argument Address ISPExec Vget (zapplid) /* REXX example with each line a complete comment */ Address ISPExec TBCreate table names(zapplid) /* */ NoWrite Replace /* this REXX program has a number of comment lines*/ Address ISPExec TBAdd table /* where each line is a complete comment. */ Address ISPExec TBEnd table /* REXX example with one long comment * * * * this REXX program has one very long comment * /* REXX with Address ISPEXEC once */ * with several lines. The first line starts the * arg argument * comment and the last line ends the comment. */ Address ISPExec Vget (zapplid) TBCreate table names(zapplid) NoWrite Replace This is another stylistic issue for the artist/programmer; however, TBAdd table there is actually less system overhead using the second example TBEnd table with the single long comment. Decide which style you prefer, these are only examples. The key is that when each record is a self con- The serious answer is that it depends. tained comment (begins with /* and ends with */) the REXX inter- preter closes out the comment processing upon scanning the */ and The reasons to code ADDRESS ISPEXEC on every statement that begins to look for other REXX keywords or functions. With the invokes an ISPF service are: multi-line comment the REXX interpreter continues to scan for the final */ and, thus, there is less overhead. 1. It improves the documentation, as you know explicitly when you are calling an ISPF service To time your REXX programs with different coding options you 2. You wont forget to set the correct addressing environ- can use a simple REXX program that I call TIMER. It is available ment by coding it on every statement calling an ISPF ser- for download at www.tsotimes.com/currentarticles.html vice Lionel B. Dyck has been in data processing since 1972. The reasons to not code ADDRESS ISPEXEC on every statement Over the years, he has developed many TSO/ISPF tools to but to code it on its own statement just before invoking the ISPF simplify repetitive or complex tasks. Many of Lionels tools services and then code ADDRESS TSO when the ISPF services can be found on the old SHARE tools tape, the CBT Tape, are complete are: and also at his web site: http://www.lbdsoftware.com
1. It saves the overhead of setting up and releasing the ISPEXEC addressing environment FREE SUBSCRIPTION 2. It is a more efficient way of coding Was this issue of the TSO Times mailed directly to you? If not, would you like to receive your own copy? Which is correct? The answer is that both are. The additional over- head in using the ADDRESS ISPEXEC on every statement calling If so, please visit www.tsotimes.com/subscribe.html an ISPF service is so small that you would have to run the REXX and fill out our on-line subscription form to start exec several thousand times just to see a measurable difference receiving your own copy. Its that easy! 5 A TSO/E Command Trapper by Jim Moore
TSO/E commands certainly provide a lot of help, meaningful in- If the return code from the command is zero or any formation and every-day utility. They just dont do this in a user- positive number, use LMINIT, LMOPEN and an initial friendly way. Most TSO/E commands are line-mode oriented due LMPUT to write the command string as the first record to TSOs paper-based history. in the file.
Good news! It isnt too hard to intercept most TSO/E line-mode 4. Then, using the SAVE.0 entry as the top of stack messages, store them in a REXX-indexed variable and then trans- variable, loop through the entire OUTTRAPed data fer them to a file to be browsed, viewed or edited. area, incrementing a variable each time, setting another variable equal to that indexed entry, and then finishing Interpretive REXX and the OUTTRAP Function by using LMPUT to transfer that variable to the file. The simple ISPF dialog available for download at www.tsotimes.com/currentarticles.html consists of a single panel 5. Finally, an LMCLOSE is issued to flush all values to and a REXX Exec. The panel provides the input field where the disk and the file is either browsed, viewed or edited, TSO/E trapped command is entered, as well as a one-byte selec- depending upon what was selected at the initially tion field that determines if the output is eventually browsed, viewed displayed panel. On a PF3 press, loop back to point 2 or edited. above and await further commands.
A great feature of any interpretive language is that a variable that If, after the command is issued (in point 3 above) and a negative contains a command string can be passed through to the command return code is issued, this indicates that the string that was passed processor and executed. Coupled with the screen-redirecting through is not even a valid TSO/E command. In this case, the ISPF OUTTRAP function, this forms the basis of the TSO/E Command SETMSG service is used and the panel is re-displayed with an er- Trapper. ror message.
OUTTRAP Restrictions Conclusion Not all output of TSO/E commands can be trapped with the REXX Try out the TSO/E command Trapper on a line-mode oriented TSO/ OUTTRAP function. Whether or not OUTTRAP can successfully E help command. For example: HELP ALTLIB or HELP LISTCAT. re-direct screen output depends entirely upon how the command Youll see the advantage immediately. does its line-mode output. A screen-captured example as well as the downloadable source code OUTTRAP will not trap any line-mode output produced by the for the TSO Command Trapper are available on-line at following: www.tsotimes.com/currentarticles.html
· TPUT · WTO macro · messages issued by TSO/E REXX (that is, messages beginning with IRX) MVS/Quick-Ref · messages issued by TRACE output. The #1 Programmer’s Choice ISPF LM (Library Management) Services and the TSO Allo- cate/Free Commands MVS/Quick-Ref is an on-line quick reference tool for users The ISPF LM services, coupled with the native TSO/E Allocate of the MVS operating system. It has the ability to pop-up and Free commands, round out the REXX Exec. Here is a basic over an active ISPF application and give you a quick answer overview of the process: to an MVS-related question and then go away without af- fecting the active application. 1. Create a random DD name and use it in a TSO Allocate command that doesnt use a data-set name. This creates Instant access to over 27 million lines of MVS/OS/ a reusable pool of allocated space that the command 390 reference information. trapper will write to. It has the disposition of NEW,DELETE so that when it is freed, it is deleted. Why do you need MVS/Quick-Ref? It saves you time and money! 2. In a pop-up window, display the panel that allows TSO/E command entry. If the user presses PF3 at the For more information or to order panel, exit and free the pool allocation. a FREE trial, give us a call at 603-643-4002 or visit us on-line at 3. Otherwise, set the OUTTRAP and issue the command. www.chicago-soft.com 6 A 21st Century z/OS ISPF Environment by Jim Moore Have you been keeping track of all the latest IBM advances in Conclusion ISPF configuration? Do you know that many of these advances It is important to remember that there really are two types of ISPF make your job easier, make the ISPF environment more flexible customization being applied at a z/OS site: System-wide values and enhance the long-term maintainability of your sites ISPF in- and user-specific values. stallation? In general, system-wide values are ones that are read in and ap- They truly do all of these things, but in many cases some of the plied by ISPF when the initial sub-task is ATTACHed from TSO most useful customizations to ISPF are being routinely ignored by Ready mode. These types of values will then remain active for the many MVS installations. Part of the reason for this can be found by duration of any and all additional ISPF sub-tasks (split screens). examining the IBM-supplied defaults that are shipped with ISPF. Examples of these types of values are the size of the RETRIEVE stack, maximum number of split screens, and the declaration of the This article will discuss ISPF install time configuration. In the on- SITE and/or USER command tables. line portion of this article, several important customizable items and their IBM default settings will be compared to possible alter- User-specific values relate to the many different settings of the native settings. Knowing your choices and knowing the benefits boilerplate ISPF user profile (ISPSPROF) and the many initial that can be derived from a few minor adjustments to the IBM de- default settings for rows in the Edit Profile table (ISREDIT). faults will result in a 21st Century z/OS ISPF environment. Read more about a 21st Century z/OS ISPF environment in the con- Why OS/390 V2R8 Was Important to ISPF Configuration tinuation of this article at www.tsotimes.com/currentarticles.html. One of the biggest changes ever to ISPF customization appeared in Here, IBM default options for several key ISPF customization items OS/390 V2R8. This change (more like a complete overhaul) ad- are compared to alternate settings. Some recommendations are pre- dressed the fundamental procedures that are used to apply ISPF sented and discussed. customization.
Prior to Release 8, ISPF customization was implemented through the use of a number of Assembler language source tables. The most important of these tables was the PDF configuration table known as ISRCONFG (CSECT ISRCONFG, member name ISRCNFIG in ISP.SISPSAMP). Another table for ISPF, known as ISPDFLTS (CSECT ISPDFLTS, member name ISPDFLTA in ISP.SISPSAMP) Jim Moore is the Editor of the TSO Times. also needed to be examined and modified. These Assembler lan- guage tables had to be carefully hand edited, assembled/linked and then tested by the ISPF installer (typically, via an ISPLLIB alloca- tion) to ensure that all settings were working as desired. Finally, TSO Times Advertising the finished load modules had to be placed into the ISPF LPALIB as an SMP/E usermod. Rates Full Page (7 1/2 x 10) $500 This procedure, while not particularly difficult for an experienced 1/2 Vertical (3 1/2 x 10) $400 systems programmer familiar with Assembler, was retired in OS/ 1/2 Horizontal (7 1/2 x 5) $400 390 V2R8. It was replaced with a keyword driven file that is cre- 1/4 Vertical (3 1/2 x 4 3/4) $150 ated by a standard ISPF dialog within ISPF itself. This is in keep- Business Card (3 1/2 x 2) $75 ing with IBMs direction of simplifying the administration of ev- Please submit your ad in one of the following PC-compat- erything in their flagship mainframe operating systems. All of the ible digital formats: Illustrator, Photoshop, PageMaker or values that used be spread across a number of Assembler tables are Freehand. Images/graphics should be saved in one of the now consolidated into a single keyword-driven file. following formats: .eps, .tif, .jpg, .bmp, or .wmf and have a minimum resolution of 300 dpi/ppi when scanned or scaled. ISPF Customization Changes You may send your ad on a cd-rom, floppy or Iomega ZIP Beginning with Release 8, all tables (ISRCONFG and ISPDFLTS disc to Chicago-Soft, LTD, ATTN: TSO Times, One Maple being the major ones) were combined into a single entity known as Street, Hanover, NH 03755 or by email to the ISPF Configuration Table. But this combining of tables was [email protected]. only one part of the overhaul. The big change was the fact that the configuration tables went from being generated by way of a some- The TSO Times has a circulation of 25,000 people. what cryptic, error-prone (hand-editing, assembly, etc.) process to being generated by a simple-to-understand, keyword-driven flat file. Publication Schedule Also, an ISPF dialog was provided by IBM to make the creation of Fall 2003/ Winter 2003 / Spring 2004 /Summer 2004 the keyword customization file even easier. 7 What You See is Not What You Get
by Mark Zelden
Most people who have worked on OS/390 As a consultant who moves from site to site or z/OS for any length of time have prob- frequently, I found a simple way to deter- ably run into various out of storage abends mine what region size I was actually getting (x0A, x78, etc.) at one time or another. The after IEALIMIT/IEFUSI exits (possibly) fix may be as simple as increasing the RE- made their changes. The answer was in a TSOTSO GION size in the JCL for a batch job, or control block called the Local Data Area logging on to TSO with a larger region size. (LDA) which is documented in the MVS Data Areas manual and is mapped by the If there is no IEALIMIT or IEFUSI exit in IHALDA macro. I wrote a small REXX rou- place on the system, then the defaults for tine called REXXSTOR to display the re- TimesTimes the REGION parameter documented in the quested and actual region size values from MVS JCL Reference apply. Even the docu- the LDA for both below the line and above mented behavior for actual “region below” the line virtual storage. It also shows the and “region above” can be confusing for amount of storage used, but this may only Spring 2004 some. For example, if you specify be beneficial if invoked from an interactive REGION=20M the default extended region TSO or Unix System Services (OMVS) ses-
TSO Assistance for the MVS Professional TSO size will be 32M, not 20M. Please see the sion. MVS JCL Reference for more detail on the defaults. Then there is Unix System Ser- By running the exec from TSO, Unix Sys- vices, also referred to as OS/390 Unix or z/ tem Services (or even a OS/390 web server) In This Issue OS Unix, which takes its default region size and in batch with various region sizes speci- from the MAXASSIZE setting specified in fied in the JCL, I could see what effect the BPXPRMxx member of the system IEFUSI had on the region size. Region Size: What You See PARMLIB concatenation. is Not What You Get The REXXSTOR source code and sample by Mark Zelden The problem is that most shops use an JCL to run it in batch are available for IEFUSI exit to modify the defaults and un- download at www.tsotimes.com/ less the rules of the exit are clearly docu- currentarticles.html. Random ISPF Tricks mented, you may not know what to expect. by Lionel B. Dyck It is also up to the system programmer to Mark Zelden is an independent contractor decide whether to invoke the IEFUSI exit with many years of development experience. for batch jobs, TSO users, started tasks and His work has involved all manner of systems Chicago-Soft Joins Unix System Services. work, databases and troubleshooting. Cornerstone Systems TechPartner by Steve Caplan
History of TSO: Part Three by Jim Moore
Dyanmic Allocation - The MVS Way by Steve Myers
REXX Comparison Tool by Yash Pal Samnani
Windows Keyboard Shortcuts
www.tsotimes.com Random ISPF Tricks by Lionel Dyck You can use whatever name you like but these work. For this months article I am going to document some little known features of ISPF (based on ISPF under z/OS 1.3). Then tell your users that they can, from any ISPF command ISRDTLCV line enter BPDF data.set.name, EPDF data.set.name or VPDF data.set.name to directly enter ISPF Browse, Edit or View on This handy REXX program is provided in the ISPF REXX the specified data set. The ISREPDF program has other op- library (ISP.SISPEXEC) as a tool for converting an ISPF tions which you might find useful and for those you’ll need to panel that has been created using DTL so that you can make browse the supplied source code. updates to the panel without knowing DTL. A prime example of when to use this tool is when you want to make an update 3.4 and DSLIST to ISR@PRIM to add some local installation menu options. When in ISPF 3.4 or when using the DSLIST command the To use ISRDTLCV, first get into ISPF Edit on a copy of result is the same, program ISRDSLST is executed. This re- ISR@PRIM, and then execute this tool which is an ISPF Edit sults in a list of data sets that match your selection criteria. By macro. The result will be that all the hexadecimal codes in the this point in ISPF life nearly every ISPF user knows one or panel will be converted to something that you can actually both of these options. What they may not know is that when edit and see, and which are valid in the panel. in the data set list there are several primary commands which ISPLIBD can be used to make life easier, among them are: On rare occasions, more so if you develop ISPF dialogs, you CONFIRM which can be used to turn on or turn off confirma- may have a need to see what the current set of libraries are tion when a data set is deleted. To enable confirmations enter that have been allocated via LIBDEF. This command will do CONFIRM ON and to disable enter CONFIRM OFF on the that by simply entering ISPLIBD on any ISPF command line. ISPF DSLIST command line. If you are interested in only a specific library you can enter ISPLIBD library (e.g. ISPLIBD ISPPLIB). DSLSET can be used to bring up a popup panel where you ISRONLY can change the default behavior of the DSLIST. Provided in the ISPF Samples library (ISP.SISPSAMP) this EXCLUDE can be used to hide data sets with a specified char- handy REXX program should be copied into a library in your acter string. Use the ALL option if you want more than just SYSPROC or SYSEXEC concatenation, typically under the the first occurrence to be hidden. name ONLY. Then whenever you are in ISPF Edit just type in the ISPF command line ONLY xxxx to display only those records with the string xxxx. The parameters for ISRONLY ...continued on next page and the format of the string are the same as for the FIND command with the exception that FIRST, LAST, NEXT, and PREV are not supported. MVS/Quick-Ref™ One side note that most users of this command are unaware of is that while processing sequence numbers are turned off and The #1 Programmer’s Choice then turned back on when the command completes. The sequence numbers are not removed when numbers are off, MVS/Quick-Ref is an on-line quick reference tool for users they just become part of the data for this short period of time. of the MVS operating system. It has the ability to “pop-up” over an active ISPF application and give you a quick answer ISRBPDF and ISREPDF to an MVS-related question and then go away without af- These two samples are provided in the ISPF REXX library fecting the active application. (ISP.SISPEXEC) and are very helpful if you want to provide a fast path command to ISPF Browse and ISPF Edit. To use Instant access to over 27 million lines of MVS/OS/ these you must first Alias, Copy, or Rename these to drop the 390 reference information. ISR and then update your ISPF Site command table (or ISPCMDS if you don’t have a Site command table, which you should) with these entries: Why do you need MVS/Quick-Ref? It saves you time and money! BPDF 2 SELECT CMD(%BPDF &ZPARM) EPDF 2 SELECT CMD(%EPDF &ZPARM) For more information or to order VPDF 2 SELECT CMD(%EPDF &ZPARM VIEW) a FREE trial, give us a call at 603-643-4002 or visit us on-line at www.chicago-soft.com 2 Random ISPF Tricks Chicago-Soft Joins Cornerstone
...continued from previous page Systems TechPartner
by Steve Caplan MEMBER followed by a member name or member name pattern can be used to find all data sets in the list (X for only excluded, Chicago-Soft, Ltd, has entered into an agreement with Corner- NX for only those not excluded). Data sets which are migrated stone Systems, Inc., of Irvine, California, to participate in their will not be searched unless you use options RECALL1 for data newly formed TechPartner program. The TechPartner program sets migrated to DISK or RECALL2 for all migrated data sets. provides select “best of breed” software, preloaded for easy evalu- This is really handy but don’t be fooled into thinking you can ation, on zFrame™ S/390 servers from Cornerstone Systems. It’s enter a B (to browse) the member of the data set as a B will in- the S/390 version of “bundled” software. voke ISPF Browse on the entire member list (this might be a good requirement to submit to IBM to allow the B (or whatever Cornerstone customers purchasing a zFrame™ S/390 server, run- command) to operate on the member or members found by the ning OS390/zOS, will find Chicago-Soft’s flagship product, MVS/ MEMBER command). Quick-Ref, already installed on their system. MVS/Quick-Ref is the premier online documentation program for MVS, OS/390 SAVE will save the current list of data sets to a data set which can and z/OS. All that will be required to begin a free trial evaluation then be processed or printed. will be an evaluation code zap, available from Chicago-Soft Cornerstone customers who purchase MVS/Quick-Ref through RESET will undo the EXCLUDE. this program will receive special TechPartner discount pricing from Chicago-Soft. SRCHFOR will invoke the ISPF SuperC utility to search all of the non-migrated data sets. After entering SRCHFOR on the ISPF Cornerstone Systems, founded in 1990, is a “Tier 1” IBM Pre- DSLIST command line you will be presented with a panel where mier Business Partner. They are authorized and trained in the you can enter the search arguments and select various search cri- sale and support of the IBM eServer Systems products, including teria such as only search online data sets. IBM’s zSeries (s/390), pSeries (RS/6000) and xSeries (Netfinity) processor lines, Enterprise Storage Server (“Shark”) disk sub- There are a lot of ‘hidden’ capabilities within ISPF which you systems, Storage Area Networks (SAN) and Virtual Tape Servers can find by reading the tutorials or (gasp) reading the documen- (VTS). In addition to sales, implementation and support of these tation. systems, Cornerstone provides a variety of services in the OS/ 390, VM, z/OS, Linux on 390, AIX, HP-UX, Linux and Solaris This column in TSO Times is for your education and enjoyment. operating systems and environments. Their services include If you have questions about anything in TSO or ISPF send them everything from complete systems outsourcing and back up, to [email protected] and we will address as many as enterprise network security, to application development. we can each month (and if there are no questions then we will be creative and write something that you will find worthwhile). More information about the Cornerstone Systems and the TechPartner program is available on their website: http:// Lionel B. Dyck has been in data processing since 1972. www.csihome.com Over the years, he has developed many TSO/ISPF tools to simplify repetitive or complex tasks. Many of Lionel’s tools can be found on the old SHARE tools tape, the CBT Tape, Steve Caplan is Vice President of Strategic Partnering for and also at his web site: http://www.lbdsoftware.com Chicago-Soft, Ltd.
TSO Times is published by Chicago-Soft, LTD., which develops and markets corporate productivity and management software for main- frame, Windows and web-based systems. Intended as a forum for the exchange of technical information of interest to TSO and ISPF users, it’s content will be mostly technical, with some promotional materials.
All inquiries concerning subscriptions, requests and change of address should be sent to Chicago-Soft, LTD, ATTN: TSO Times, One Maple Street, Hanover, NH 03755, TEL: 603-643-4002, FAX: 603-643-4571, email: [email protected]
Additional information can be found at www.tsotimes.com. Chicago-Soft, LTD information can be found at www.chicago-soft.com
Copyright © 2003 Chicago-Soft, LTD All rights reserved. All trademarks are property of their respective holders.
3 The History of TSO ~ Part Three by Jim Moore
I received my first computerized “instant message” sometime in the summer of 1976. I was busily writing code one morning on a What’s an AID key? pin-feed, paper-based, 300 baud DEC Writer (with a bi-directional This is an IBM term that combines the word “attention” and the print head!) when suddenly, after I pressed ENTER, a message acronym “ID”, or attention identifier. Examples of AID keys printed out. would be ENTER, CLEAR, PA1, PA2 and all of the function keys. These keys were part of the hardware of the 3270 series I turned to my co-worker (Eric McConney, an early mentor of terminals. An AID key requests the attention of whatever under- mine) who was working next to me in the bullpen and asked him: lying operating system is being communicated with on a 3270 system. When you press an AID key, it becomes the first com- “Eric, what the heck is this? Where did this message come from?” ponent in the 3270 data stream. It describes what action caused the data stream to be sent. The most frequently pressed AID key He leaned over, looked at the printed message and said: is ENTER, especially in TSO/ISPF.
“Someone up on Chicago Avenue is asking if you want to go to Conversational, Again the ball game tonight. Just reply back and ask who they are.” Getting a TSO session to remain active on the operating system’s chain of jobs, waking up and performing work only upon the press “How?” I asked Eric. of an AID key, was the real breakthrough for those long-ago IBM developers of TSO. The swap-in, swap-out (or wake up, go to sleep) After a quick lesson from Eric in the use of the TSO SEND com- nature of a TSU is what allowed a true “sharing of the time” be- mand, I instant messaged the sender back in reply. tween multiple, signed-on users.
It turned out that the person sending me the message had mixed TSO retains this exact characteristic to this day. What must al- up my TSO-id with a similar one. Alas, no White Sox game for ways be remembered is that even in a swapped-out state, any re- me that night but that didn’t matter much to me. I was far more sources held by a TSO session (such as allocated files, memory intrigued with the message sending concept. Ball games come and even the occupied slot in the Address Space Vector Table, or and ball games go on a daily basis. But this instant, textual com- ASVT) remain held even when the TSU address space is in a munication technique was something brand-new to me back then swapped-out state. and I was spellbound by it. What a great new toy! I know I’ve said this before, but it certainly bears repeating: This TSO as Networking Software is what is meant by the term conversational. As long as the TSU In Part Two of this series, I mentioned that an important feature of address space is logged-on, it will hold on to something. mainframe TSO is its networking capability. Considering the humble TSO SEND command is one way to put TSO’s networking capabil- SEND Command Revisited ity into perspective. The only conceptual difference between some- Consider the earlier SEND command scenario. thing like the TSO SEND command and Internet instant messaging is the number of people that can send and receive messages. I was logged on to TSO, typing code in an editor but not pressing an AID key. Some other TSO user on the network typed in a SEND With mainframe TSO, the network consists of currently logged command with a message routed to my TSO session. on TSU address spaces plus any operator consoles. With Internet ...continued on page 7 IM, the network is vast, world-wide and far-flung. But in con- cept, both work quite similarly—instant textual communication Why ISPF uses the semi-colon as the default com- across some kind of network of logged-on users. mand stacking character A unique key on older IBM terminals was known as the Field It is the polling done by the Terminal Controlling Address Space Mark key. It was purely a terminal type key and had no equiva- (TCAS) on an MVS LPAR that allows for instant messaging via lent EBCDIC (hex) representation. When pressed, the screen the SEND command. This polling is the same mechanism that image of it looked like a semi-colon with a short, horizontal bar recognizes a press of an AID key (See Sidebar One) by a TSU. above it. It was not an AID key. Once a key press is detected, the TSU address space is swapped- in, made active and the requested processing is done. In line-mode (Ready-mode) TSO, the Field Mark key could be When the requested processing has finished, the entire TSU ad- used to “stack up” a string of commands and invoke them all dress space is swapped-out. Think of all the times that you have with one press of the ENTER key (one swap-in). When ISPF been in ISPF edit, looking at program code, JCL or other data. As added command stacking capability, it must have seemed natu- long as an AID key has not been pressed, your underlying TSO ral to the IBM developers to allude to the Field Mark and use session is in a dormant state, or as it is more commonly known, the semi-colon as the default dividing character for an ISPF com- swapped-out. mand stack. 4 Dynamic Allocation ~ The MVS Way
Steve Myers
The first TSO release in 1971 provided a limited form of • S99VERB - The type of allocation request dynamic allocation. It is still there and it still works. A separate o S99VRBAL - A “regular” allocation request article, available on the TSO Times web site discusses TSO o S99VRBUN - An unallocate (free) request dynamic allocation. It is easier to use, particularly for reentrant o S99VRBCC - A concatenation request programs, than MVS dynamic allocation, but it can only be used o S99VRBDC - A de-concatenation request in a TSO environment. o S99VRBRI - A remove-in-use request o S99VRBDN - A DD name allocation request. One of the big changes in the first MVS release MVS was the intro- This is really a request to take an existing alloca- duction of dynamic allocation. However, MVS dynamic allocation tion and increase the in-use count works differently than TSO dynamic allocation. MVS is much more o S99VRBIN – An information request from an powerful and much more extendable than TSO dynamic allocation, existing allocation but power comes with a cost in complexity. It is also more difficult to use, particularly for reentrant programs. • S99FLAG1 o S99FLG11 - Miscellaneous flags. They only need Table 1 shows a complete dynamic allocation request. to be present for full allocation requests. Some of them are: S99NOCNV - Make sure a new alloca- tion is used, rather than an existing al- location. S99NOMNT - Do not allow a volume mount. This is more useful for batch than TSO, since most TSO profiles for- bid a volume mount anyway. S99NOMIG - Do not recall a data set from archival storage to complete an allocation. o S99FLG12 - No bits for us peons are present.
• S99RSC o S99ERROR - An error code o S99INFO - Additional information to document the error code.
Everyone using dynamic allocation must be familiar with two IBM • S99TXTPP - The address of the text unit pointer list. macros in SYS1.MACLIB. The IEFZB4D0 - believe me, you’ll memorize this crazy name - macro defines the symbols for the • S99S99X - The address of the request block extension. definition of the request block pointer, the request block, the text • S99FLAG2 - Flags us peons can’t use. unit pointer list, and the text units. IEFZB4D0 also defines the symbols for a data area called the request block extension, which we will not discuss. The IEFZB4D2 macro defines the symbol names used in the text units. The Text Unit Pointer List
The text unit pointer list just points to each text unit. The last entry The Request Block Pointer has the high order bit set. It is a list of addresses.
The request block pointer - ARBPTR in our example - is real simple. ...continued on page 7 It contains the address of the request block, and the high order bit must be set on. FREE SUBSCRIPTION The Request Block Was this issue of the TSO Times mailed directly to The request block is a 20-byte data area that tells about the re- you? If not, would you like to receive your own quest. The first 4 bytes are flag bytes. copy? If so, please visit www.tsotimes.com/ subscribe.html and fill out our on-line subscription S99RBLN - The length of the request block. The example • form to start receiving your own copy. It’s that easy! shows the correct way to specify the field. 5 REXX Comparison Tool (CA) by Yash Pal Samnani
Comparison of old and new source code is essential to ascertain whether the changes done to programs (JCL/ Control Proc/ Figure 2 - Command ===> CA member name Copybooks) are in sync or not. When using the IBM provided COM- PARE command, this often requires long comparison commands Entering the CA macro with a trailing member name such as COMP < pds (member name)>. This problem of typing long comparison commands is compounded by the use of different pro- If the member exists in the production library, then the compari- duction library names. All of this extra typing consumes time through- son will be done. Otherwise, the message ‘Attempt failed! Ei- out the process of coding and testing the programs. ther the component is not available in the Production Library OR the component being compared is other than Proc, Source, My focus was to eliminate the wasted typing time. If this waste Control Proc or Copy Book’ will be displayed in a pop-up mes- could be avoided, programmers would be more efficient. I pro- sage window. pose a solution that will save users a lot of time and increase their List of possible message for different components displayed productivity. The solution is the use of a REXX edit macro (named on top left hand size of the panel CA) that contains a list of all the libraries that could ever be used to compare changed components against. That is, the list consists of the baseline component libraries divided by type. Determining Mismatch found - Progam: Source compared! which library to compare against is handled by logic in the CA Proc: PROC compared! REXX edit macro. The tool automatically recognizes the compo- Control Proc: compared! nent being compared. There is no need to specify whether the source Copy Book: Copy Book is a program, proc, control proc or a copybook. compared! Assume that the following production libraries are installed at a site. No mismatch found Progam: Files are same! Each and every time the CA macro is executed, these libraries (or Proc: Files are same! additional ones, if desired) will be compared at the member level: Control Proc: Files are same! Copy Book: Files are same! BOXA.PROD.TECH.SRCE BOXA.PROD.TECH.PROC Yash Pal Samnani is a computer programmer who develops BOXA.PROD.TECH.CTLPROC ISPF productivity aids for himself and co-workers. BOXA.PROD.TECH.COPYLIB Windows Keyboard Shortcuts When you type CA, the member name (that needs comparison) is automatically picked up from the dataset being edited and is Here is a table of some of the most useful Windows keyboard searched sequentially in production (or any other pre-defined li- shortcuts. With minimal practice, you can use these shortcuts to braries). These libraries could be source, proc, control proc or work faster and relieve stress on your mouse hand. In the table, copybook library. Wherever the member is found, it is compared “WK” indicates the “Windows Key”, the key with the small and the comparison is displayed. Microsoft Windows logo on it.
The comparison results will be fine even if the production library Keyboard What it does Where Used has a member in proc and source with the same name. This is F5 Same as Refresh Any Internet browser achieved by additional logic that uses the presence of keywords like IDENTIFICATION, ENVIRONMENT in the source to deter- Ctrl-C Copy text to clipboard Anywhere in Windows mine what type of member is being edited. Ctrl-V Paste text from clipboard Anywhere in Windows Ctrl-X Cut text to clipboard Anywhere in Windows Figure 1 - Command ===> CA WK-M Minimize all Windows Anywhere in Windows Entering the CA edit macro without a member name. WK-R Invoke Windows Run Anywhere in Windows WK-E Invoke Windows Explorer Anywhere in Windows This is also helpful to mainframe shops that use the version control WK-D Minimize/Undo Minimize Anywhere in Windows software named Changeman. Type CA on the command line and WK-F Invoke Find Files Dialog Anywhere in Windows press enter. Even though Changeman provides this feature as a part of its software, CA will still be effective. One exception: In the WK Pop-up the Start Menu Anywhere in Windows case of Changeman, if the component is a control proc or a copybook WK-Tab Move between open apps Anywhere in Windows then a member name is required. There is no need to specify the Alt-F4 Close an open window Anywhere in Windows member name in case the component being compared is a pro- gram or a proc. For more Windows keyboard shortcuts, read the Windows Help text, accessible by pressing WK-F1! 6 Dynamic Allocation ~ The MVS Way History of TSO ~ Part 3 continued from page 5 continued from page 4 When the message sender pressed ENTER, his TSO address space The Text Units was swapped in, the SEND command invoked and then swapped The text units, taken together, describe the allocation in detail. right back out again. Some text units provide information for dynamic allocation. Most text units are an exact equivalent of a JCL parameter. Other text The message, routed to me, was placed in a temporary holding units request information from dynamic allocation. As such, they area of the broadcast dataset. The message did not immediately do not have a JCL equivalent. appear on my terminal. The IEFZB4D2 defines symbols for all the key names used by dynamic allocation. USE THEM! The first byte of each key name Only when I pressed the ENTER key and in so doing, swap my is D. The second and third bytes are a copy of the last two bytes of TSO address space in, did I see the message. Additionally, any the symbolic dynamic allocation request verb used in the request pending changes that I had made to the code I was working on block. All the key names for full allocation, S99VRBAL, start with were also updated in memory. DAL. The remaining 5 bytes are suggestive of the function. For example, DALDSNAM means you are specifying a data set name. By the time I began reading the “take me out to the ballgame” All text units start as 2 half-word data areas. The first two bytes message that suddenly appeared on my DEC Writer, my TSO ses- contain the IBM-defined text unit key. The second two bytes are sion had already reverted to a dormant, swapped-out condition. the number of parameters that follow. Conclusion Each parameter contains a two-byte length field followed by the Even back in the old days of TSO, there were methods for getting parameter. more bang for the buck when a TSO session was swapped in. Re- Here are four text units taken from the online example program: fer to Sidebar Two for an interesting historical connection between • AL2(DALDSNAM,1,44),CL44' ‘ - This text unit speci- ISPF and TSO. fies a data set name. It has one parameter that contains 44 bytes, followed by the 44-byte parameter area. The final part of this four-part series is online at www.tsotimes.com/currentarticles.html • AL2(DALSTATS,1,1),AL1(X’08') - This text unit defines the allocation status. X’08' is DISP=SHR. Unfortunately there are no formally defined symbolic equates for this data area. However, IKJDAPB08 - one of the macros used Jim Moore is the Editor of the TSO Times. with TSO dynamic allocation defines an equivalent field and it provides equates that are identical to DALSTATS.
• AL2(DALRTDDN,1,8),CL8' ‘ - This key requests dy- namic allocation to return the length and text of the DD name assigned to the allocation. The DD name does not TSO Times Advertising have to be 8 bytes. Dynamic allocation will update the length field with the actual length. Rates Full Page (7 1/2” x 10”) $500 • AL2(DALRTORG,1,2),AL2(0) - This key requests dy- 1/2 Vertical (3 1/2” x 10”) $400 namic allocation to return the DSORG of the data set it 1/2 Horizontal (7 1/2” x 5”) $400 allocated. The data it returns is the same as DCBDSORG 1/4 Vertical (3 1/2” x 4 3/4”) $150 or DS1DSORG. The real reason to use this key is be- Business Card (3 1/2” x 2”) $75 cause dynamic allocation has to obtain this key from the VTOC entry for the data set. If the data set is cataloged, Please submit your ad in one of the following PC-compat- but it does not exist on the volume, dynamic allocation ible digital formats: Illustrator, Photoshop, PageMaker or will fail the request. This is better than getting an S213 Freehand. Images/graphics should be saved in one of the ABEND when you OPEN the data set! following formats: .eps, .tif, .jpg, .bmp, or .wmf and have a minimum resolution of 300 dpi/ppi when scanned or scaled. The sample TSO command for this article is DYNALLOC.ASM. You may send your ad on a cd-rom, floppy or Iomega ZIP As written, DYNALLOC.ASM does not apply the normal conven- disc to Chicago-Soft, LTD, ATTN: TSO Times, One Maple tion of inserting the current prefix into the data set name if the data Street, Hanover, NH 03755 or by email to set name in the command line is not enclosed in quotes. What change [email protected]. would you make to the command so that this could be done? The TSO Times has a circulation of 25,000 people. Publication Schedule Steve Myers has been programming since 1965 and writing TSO command processors since the very beginning of TSO. Spring 2004 / Fall 2004 / Spring 2005 / Fall 2005 7 What’s New in TSO/ISPF?
Do the programmers and users of TSO/ Jim Moore tosses out what he calls a ISPF that work in your data center get the “training dialog” - an Assembler/REXX highest and best use out of the TSO/ISPF combination named SHOWDSNS that software they use every day? Are they allows for an interactive browse of the aware of the huge number of improve- TIOT, similar to DDLIST. TSOTSO ments, enhancements and new features that have been added to the TSO/ISPF As you read these articles, ask yourself: environment over the last several years? Can I incorporate any of these new and improved techniques in my day-to-day New utilities, commands, dialog services, work? Do I need to know more about how TiTimesmes improved methods of working and much these enhancements will make my job more have poured out of the ISPF easier? developers at IBM recently. All of these great additions, coupled with the old Use these three simple steps: Fall 2004 stand-bys, make some form of training almost a requirement. • Discover TSO Assistance for the MVS Professional TSO • Experiment In this issue of The TSO Times, there is a • Incorporate bit of a training focus. Steve Comstock of In This Issue The Trainer’s Friend writes about what he If you need more help, contact the training calls Guerilla ISPF Training and Oliva professionals who can answer all of your Carmandi of MVS Training contributes on questions and cut through all of the the topic as well. befuddlement. What’s New in TSO/ISPF?
Five 3270 Emulator Tips Five 3270 Emulator Tips If you still work on an actual 3270 terminal, these tips won’t have much value for you. Guerilla ISPF Training But if you use any one of the many 3270-emulator packages (Reflection, Extra!, Rumba, by Steve Comstock Vista, etc.) to work on a mainframe, they might come in handy. 1. Learn to use BOTH cursors available to you – the mainframe cursor as well as The SHOWDSNS Dialog the “toothpick, I-beam” mouse cursor. Rolling and then left-clicking the mouse by Jim Moore is a much faster method to get to an insert point on the screen than tabbing or using the arrow keys.
Are You Getting Quality 2. If your emulator supports the “left double-click to highlight text” Windows Training? standard (Reflection does), always use this method to highlight short strings (like dataset names) as opposed to “swiping”. Follow on with the keyboard by Olivia Carmandi shortcut CTRL-C to Copy the highlighted text to the clipboard.
Working With Packed 3. Test to see if your emulator supports the Cut Text (CTRL-X) function. The better Decimal Data in REXX ones do and are sensitive enough to know when the highlighted text can truly be “cut”. That is, in an environment like ISPF edit, a good emulator will in fact by Steve Comstock remove highlighted text in response to a CTRL-X. In environments like ISPF Browse, they will not. They WILL place the highlighted text on the clipboard as The Power of DDLIST if you had requested a Copy (CTRL-C) in this situation.
by Jim Moore 4. In ISPF Edit, if your emulated terminal has Insert On and you want to Paste a piece of text (CTRL-V) from the clipboard, will your emulator insert the pasted text? Good emulators will – right-shifting the existing text to accommodate the pasted text (NULLS ON must be set in ISPF Edit profile) coming from the clipboard.
5. In ISPF edit, issue the HILITE command and activate the Colors drop-down. ...continued on page 6 www.tsotimes.com Guerrilla ISPF Training by Steve Comstock
For most z/OS applications programmers, ISPF is their window • Tab to action bar choices - With this de-selected, the terminal into the mainframe. It is the tool for writing and editing code, Home key sends the cursor to the command line (if the JCL and control statements. It is the mechanism for submitting command line is at the top of the panel). jobs and examining the output. It is the center for utility work such as copying files for test, backing up data (and restoring it • Always show split line - The split line is a line of dots when when necessary), for renaming files, even for getting into z/OS you have the screen split. Removing this line gives you one UNIX. more line of screen real estate to work with.
It would make sense to ensure ISPF users are up-to-date on the latest features of ISPF - that they are as efficient and effective as Technique 2 -Multiple split screens possible when using this powerful tool. Over the last ten years or so, ISPF has undergone tremendous changes - both in interface Most students know about split screens and command stacking design and changes in commands with enhancements to capa- but ISPF has extended screen splits from a maximum of two bilities that vastly improve what was available before. screens to a maximum of 32 (although the default is normally eight). Each screen is called a logical screen. Normally, you Yet management refuses to recognize that some organized can only see one at a time, although the Split command can training to update their peoples’ skills in ISPF would bring allow you to see part of each of two screens at one time. The enormous returns on a small investment. “They already know following commands are of enormous benefit in becoming that,” is a common management mantra. more productive.
Not in my experience. • Start [option] - Start a new screen - better than the Split command since you can specify a starting option We offer several courses for ISPF skills, yet we rarely are able to and the new screen is a whole screen, not dependent sell them to customers. Which is a shame because these classes upon where the cursor is positioned. Note that the improve developers’ skills and effectiveness in a short period of Split command can also split more than two screens if time. you type Split New as an ISPF command. All logical screens are numbered, beginning with “1”. You can Because we believe so strongly in the need for the content in assign a name to a screen using the Scrname command. these courses to be disseminated, we have started including Some variations: fragments from these courses when we teach other classes. In this article, I will outline the techniques we most often add to ...continued on next page other classes based on what we observe about the students’ skills and knowledge of ISPF. Since this training is not scheduled, requested, nor paid for, I call it Guerrilla Training. ™ Some of these techniques have been included in various articles, MVS/Quick-Ref but I believe this is the first time they have been pulled together The #1 Programmer’s Choice with the intent of placing them into class material (or used for “brown bag” lunch technical sessions or other informal settings). MVS/Quick-Ref is an on-line quick reference tool for users Technique 1- Settings of the MVS operating system. It has the ability to “pop-up” over an active ISPF application and give you a quick answer The changes from ISPF V3R5 to V4R1 (around 1996-1997) to an MVS-related question and then go away without af- introduced a major change to the user interface. A lot of the fecting the active application. IBM-supplied defaults were not the most user-friendly and I see a lot of people working with these in effect simply because they Instant access to over 27 million lines of MVS/OS/ are not aware of alternatives. So the first thing to do is to select 390 reference information. ISPF Option 0 (zero) or from a command line issue the Settings command (it has no operands). In either case, you will see a Why do you need MVS/Quick-Ref? panel like the one shown in Figure 1. On this panel, I direct the It saves you time and money! students to at least remove the “/” from these options: For more information or to order • Command line at bottom - This is a personal preference item a FREE trial, give us a call at but most people seem to prefer the line near the top. 603-643-4002 or visit us on-line at www.chicago-soft.com 2 Guerrilla ISPF Training ...continued from previous page
1. Scrname on - Causes the name you assign to a • Start SDSF - This will start a third screen, running SDSF. screen to display in the upper left-hand corner of • Scrname SDSF Perm - This assigns a name of SDSF to the screen. This is optional. this third screen. • Enter the ST (Status) command to watch jobs. Note that 2. Scrname name [perm] - Name is your choice. It this and the previous two steps depend upon the product must be 2-8 alphanumeric characters the first of you use to view job output and what command or option which is not numeric and not one of: NEXT, you use to start that product. This example uses the PREV, LIST, OFF, ON. The perm parameter will IBM-supplied product named SDSF but there are others. keep the name tied to the logical screen even if • Swap JCL;Sub;Swap SDSF - Go back to the JCL screen, you change the screen content. submit the job and return to the SDSF screen
Finally, you get from logical screen to logical screen by using the When your job has finished you can look at the output. If you Swap command. There are several variations: see you need to make a change, swap back to the CODE screen and make your changes, then issue: • Swap next - Swap to the next logical screen. • Swap prev - Swap to the previous logical screen. • Save;Swap JCL;Sub;Swap SDSF;End - This saves your • Swap n - Swap to screen number n. code changes, swaps to the screen with your JCL, • Swap name - Swap to the screen with name name. submits the job, swaps to SDSF and then closes the job • Swap list - Show a pop-up list of all screens currently output you were looking at previously. established. From this pop-up you can choose a screen or even start a new screen. Walking through this scenario, especially drawing pictures of the screens on a white board or flip chart, really brings it home to Typically, I recommend that students change their function key students how more than two logical screens can improve their assignments so that PF9 is assigned to Swap Next (although effectiveness (although I do find some people resist this - they some people prefer Swap List). Note that you may have to set still prefer to stay working with one, or at most, two screens). this in multiple screens, since each screen may have a separate Keylist associated with it. Once you set the PF9 values on all of Technique 3 - Command Retrieval your screens, the setting will be remembered across logons. As always in ISPF, you must make sure you exit ISPF cleanly The final topic I usually squeeze in when doing Guerrilla though, instead of timing out, for the settings to be remembered. Training is how to keep from re-typing long command strings. Most students are aware of two ways: Multiple Screen Scenario 1) Assign a string to a function key Suppose you start out with your first screen and you have some 2) Assign Retrieve to a function key (usually PF12) maintenance to do on a program. You might issue the following sequence of commands: But there is another, relatively new technique that can also be very helpful- The RETP command. Issue this command (or press • Scrname On - This will cause the screen name to display a function key assigned to this command) and you will see a in the upper left-hand corner. pop-up list of the last several commands (the number depends on • Scrname CODE Perm - This assigns a name of CODE to this first screen. ...continued on next page • Option 3.4 - Specify high level qualifier(s) you want and press
My overall design goal when writing the SHOWDSNS dialog back in the early 1990s was simple: Write an Assem- bler ISPF dialog function that transferred the contents of the TIOT into a standard ISPF table. Once that was done, a REXX (or CLIST or COBOL or C or whatever) function could handle all of the interactive portions of displaying the table, allowing line commands and all that other good stuff.
Further, isolating the table creation logic into an Assembler program that had no real human interface allows for a good deal of reuse. If you fiddle around with the dialog, I bet you can think of a few other uses for the table of TSO-allocated datasets that the Assembler program creates.
I decided to use SVC 99 with Verb Code 7, all in conjunc- tion with the DINRELNO text unit to access each entry in the TIOT. Why did I choose this method?
Long Term Support If I directly accessed the TIOT, walking memory and address pointers, it might be possible that IBM would eventually change something in the TIOT layout or the addresses that point to the TIOT. In fact, they did exactly that recently with the SWA=ABOVE parameter.
By using SVC 99, I was able to use the same method that IBM themselves uses and I never have to worry much about memory layout changes.
Curiosity I had noticed the DINRELNO text unit over the years and Steve Comstock has many years of mainframe experience. He had always wondered: Of what use would a relative request is President of The Trainer’s Friend, Inc. for information be? To clarify, DINRELNO allows you to (www.trainersfriend.com) which offers many training courses request information about the “nth allocation” (the 10th, in TSO/ISPF - both usage and dialog manager development. 21st, 45th, etc). How would I, as a programmer, know in advance which relative “slot” a particular allocation took up in the TIOT? ...continued on next page 4 The SHOWDSNS Dialog Are You Getting Quality Training?
...continued from previous page I wouldn’t unless I had already accessed it and examined it. Olivia Carmandi, President and Founder of MVS-Training Inc. However, it dawned on me that the real purpose of DINRELNO wants you to consider these points with regard to training: was to start a counter at 1, retrieve the information about the 1st allocation and then add 1 to the counter and continue retrieving • Evaluate the course materials – They should be this way until “End-of-TIOT”. And that’s exactly the technique written and have detailed text related to the course – used - a serial access through the TIOT extracting the required not just pictures and graphics. information about each allocation in turn. • Consider the style of training – It should be adaptive, participation-oriented and have as its main objective, improved job skills. Not just raw knowledge. REXX • Always verify the training specialist’s service – Call I chose REXX as the language for the interface portion of the previous companies that the trainer has taught at and SHOWDSNS dialog. Why? Ease of coding, pure and simple. I ask for an objective analysis of their skills. DO NOT like coding complex interface code in Assembler. Plus, • Realize that this analysis is necessary – If you don’t one of the greatest things about the TSO/ISPF environment is verify the trainer, who will? the fact that you can mix-and-match just about any languages that you want. Here’s Olivia’s Quality Training Checklist:
Conclusion What do training sessions provide? The entire SHOWDSNS dialog consists of : ____ Verify that the training manual contains substantial, • One Assembler program useful information. • One REXX EXEC • Three panels ____ How often do training material updates occur?
No messages, skeletons or saved tables. ____ At least 60% doing practical tasks—not all theory?
SHOWDSNS is a good example or learning dialog because it ____ Are there written learning checks every dozen pages to demonstrates some useful techniques. These are: reinforce the learning process?
• Creating a table in one function (program) but _____ (Team Challenges) where participants perform tasks displaying (or accessing) it in another. they’d do on their job. • Passing variables between function pools by way of the shared pool. _____ Can the training be tailored to your site’s needs? • Using multiple languages - Assembler and REXX • Doing “file-less” programming. That is, no files are opened, read, written or closed in SHOWDSNS. Call a telephone reference and ask:
The entire dialog is posted at The TSO Times web site in _____ Does training vendor work with client to help analyze IEBUPDTE format. There is also a small slide show there as their training needs? well that shows how the screens look. Download it and try it out. _____ Does trainer adapt when necessary?
Jim Moore is the Editor of The TSO Times and has been known _____ How did the trainer reply to participant’s questions? to write a few ISPF dialogs and edit macros. _____ Did trainer exhibit practical experience? FREE _____ What happens when the training is over?
SUBSCRIPTION Can you quantitatively measure the success of the training process? Are you reading this thanks to a friend or colleague? You can sign up for your own _____ Does training include before and after questions? subscription by visiting www.tsotimes.com/ subscribe.html and fill out our on-line _____ Ask to see past participant evaluations. subscription form. _____ Give daily evaluations, review them with management, and adapt accordingly. 5 Working With Packed Decimal Data in REXX by Steve Comstock Although all the REXX documents tell you that REXX deals tions. To account for the two decimal places, we divide by 100: with all data as “typeless character strings”, REXX is really quite aware of numeric data, and can even be used to process records un_price = un_price/100 containing numeric data, including packed decimal numeric fields. Then we can calculate the amount as: In this article an example is shown of working with a file that contains [at least] one packed decimal field. The presumption is amt = qty * un_price that you know how to read and write records, using record I/O (EXECIO) or stream I/O (linein, charin, linout, charout, and so Finally, we can display this amount in a formatted way using the on), so the mechanics of locating or updating records will not be FORMAT built in function: covered. Instead, the processing of numeric fields will be explained. say qty desc ‘@ $’ || format(un_price,,2) ‘ = $’ || format(amt,,2) Another assumption made is that the reader is aware that packed decimal data is numeric data stored as two decimal digits (0-9) and the user will see: per byte, except the right most byte, which contains a digit (0-9) and a sign (X’A’-X’F’). Further, recall that hex values A, C, E, 12 Blue Wombats @ $47.25 = $567.00 and F represent positive numbers while hex B and D represent negative numbers. If you like to reduce the number of lines of code, you can combine many of these steps into just a few, so the above could be: Suppose there is an inventory file with 100 byte records and that locations 35-39 contain the unit price for an item, in dollars and un_price = substr(c2x(substr(inrecord,4,5)),1,9)/100 cents. For example, if the field contains x’000004725C’ this amt = qty * un_price represents a price of $47.25. say qty desc ‘@ $’ || format(un_price,,2) ‘ = $’ || format(amt,,2)
Now suppose we are running an ISPF dialog driven by a REXX Conclusion exec that takes online orders and a customer puts in a request to Look for an article online at www.tsotimes.com that explains how buy some quantity of a particular item, say 12 Blue Wombats. to work with binary data in REXX. The concepts are similar. We need to calculate the total price, so we need to multiply the quantity being ordered by the unit price (then, of course, figure Steve Comstock has many years of mainframe experience. He is applicable taxes and handling and shipping charges). Assume the president of The Trainer’s Friend, Inc. - wwwtrainersfriend.com quantity ordered is in the REXX variable QTY, and the item - which offers many training courses in TSO/ISPF – both usage description is in a field called DESC. and dialog manager development.
Further, assume we are able to locate the relevant inventory record and read it into a variable called “inrecord”. The next step we must take is convert the data in positions 35-39 to REXX type numeric data. Five 3270 Emulator Tips Use the Built-In Functions ...continued from page 1 The tool to use here is the REXX built-in function C2X (“Charac- Select 1, Overtype Color. Set it to pink. End the ter-to-Hex”). This function takes any string as input and returns a HILITE dialog. Now, copy and paste some text into character string that represents the hexadecimal digits. For example, C2X(‘A’) returns the characters C1 since a character A is X’C1'. If your edit session’s data. Is the pasted text pink? That’s you take a hex string as input, you get the hex characters as a right, a Windows clipboard paste is considered an character string for output. In our case, we can code: “Overtype”.
un_price = C2X(substr(inrecord,35,5) These are just five simple tips for exploiting the features of your emulator software in conjunction with the older 3270-screen This ends up with un_price containing the character string model. There are many more things that can make you more ‘000004725C’. Since we are only dealing with positive numbers productive if you stop to consider the possibilities. In general, here, we can actually delete the last character, by: learn to mix mouse movements and keystrokes, developing fluid hand movement between the two devices. Use one hand for the un_price = substr(un_price,1,9) mouse and the opposite hand for the keyboard. Doing so might even help prevent repetitive stress injury, also known as “carpal Now un_price has a numeric value, so we can do numeric calcula- tunnel syndrome”.
6 The Power of DDLIST by Jim Moore along. I’d love to see CUSTOM include the ISPF Configuration Who needs an interactive, scrollable list of their TSO session Table settings that apply globally across an entire site. allocations? Need it or not, DDLIST is much more than just a list of allocated datasets. CLIST, as a command (as opposed to the language) will create a simple CLIST consisting of TSO ALLOC statements that will Here’s a list of the powerful primary commands available in allow you to easily tailor your logon concatenations. Try it. DDLIST at the z/OS V1R4 level: Try the other commands after a brief read about them in the Apf Browse Con CList COUnt CUstom tutorial. DUPlicates Enq EXclude Find Locate LOAD LONg LPa Member MList Only Parmlib I’ve saved the best for last and the best, in my opinion is the Reset Select Short BROWSE command.
This isn’t a dataset browse. It is a memory browse. There is so What a list it is! much functionality to the BROWSE command, that I cannot cover it entirely in the small amount of space allotted here. The APF, PARMLIB and LPA commands (and LINKLIST, which curiously, is not documented but works) all create pseudo-DD When it comes to testing, learning and examining memory on a names that show the APF (Authorized Program Facility), z/OS machine, the BROWSE command of DDLIST is a clear PARMLIB, LPA (Link Pack Area) and LINKLIST concatenations. window into the innards. Start with a simple BROWSE of the Prefixed Save Area (PSA, DSECT IHAPSA) and follow along. Once issued, these pseudo-DD names can be drilled through with the Member command to find member names, Located like any •Invoke DDLIST other DD name and individual libraries in the concatenation can •Type Browse 0. be browsed, viewed or edited with line commands. Handy indeed. Note that the dot after the zero is required (“Browse 0.”). Now, Need a quick snapshot of any enqueue contention on a system? find various addresses that are anchored in the PSA by using the Issue the CON (Contention) command. IHAPSA DSECT and see where they lead. Try the PSATNEW field at offset +21C (decimal 540). One of my favorite DDLIST commands is ENQ. It allows any TSO/ISPF user to really delve into the various and sundry Just point the cursor at the fullword address at +21C, type (or enqueues that are issued in a complex z/OS environment – by RETRIEVE) the BROWSE command and press enter. major/minor name, by job name, by just about any criterion that you can think of. You are now at your TSO Session’s TCB (Task Control Block, DSECT IKJTCB). I wrote a column about the ENQ DDLIST command back in March 2003 for NaSPA (Network and Systems Professionals Can you see how this powerful command might come in handy Association). Have a look at this column at http:// when debugging and investigating things? www.naspa.com/PDF/2003/0303/T0303006.pdf to see how ENQ can be used when testing complex applications; particularly Conclusion ISPF dialogs that issue operating system enqueues. There are also a number of line commands available in the DDLIST utility. I didn’t cover them because they are related to About now, you might be asking yourself: What do all of these the initial screen of allocated datasets. They are all explained in things have to do with my TSO session’s dataset allocations? the tutorial. The answer is: Not much, but who cares? Run with it! I find it fascinating how the DDLIST tool has just morphed into Need to know if an executable program is available on the z/OS a powerful system-wide workbench with it’s ultra-slick set of search path? Try issuing the LOAD or SELECT commands. Try: primary commands. Some have little to do with “dataset alloca- LOAD IEFBR14 just to get a feel for how these commands work. tions” but who cares? Read the tutorial (by pressing your HELP PF Key) to find out the difference between LOAD and SELECT. Can you say: For me, DDLIST has become an indispensable tool in ISPF. I CSVQUERY? hang out there almost as much as places like Option 3.4 (DSLIST). Try it and see if you can exploit it yourself. I’m still not 100% sure what the values shown by the CUSTOM command are. Here’s what the tutorial says about CUSTOM: Jim Moore is the editor of The TSO Times and wants to say that • Show the values in ISPTCM and some ISPF configurations. his upcoming November 2004 Working Smarter column for Technical Support (NaSPA) magazine is entirely devoted to the I’ll tell you what, when I figure it out, I’ll be sure to pass it Browse command of DDLIST. 7 WORKING SMAR T E R Cook Me up a Batch of EDITs: Part I
BY JIM MOORE
hat if I told you that you have a powerful batch utility on contain your initial edit macro as a member. SYSTSIN, as shown in your MVS machine that you probably didn’t even know Fig u r e 1, issues the ISPSTAR T. SYSTSPRT is for TSO messages . W about? Would you believe me? Would you be intrigued? Believe me, you have one! You use it every single day. It’s called BATCHEDT: A GENERIC CLIST the ISREDIT program, or Option 2 of ISPF.Your old pal the ISPF Figure 2 shows the six-line CLIST that you need to launch a editor can be invoked in batch mode to great effect. This is the first batch edit. This CLIST can be used for all of your batch editing. of a two-part series that will explore some of the ways that you can That’s what I mean by generic. It expects a parameter: the initial exploit the ISPF editor in batch mode. edit macro name. Note also that the LMINIT service is used to acquire an ISPF dataid. A dataid is an internal name for an external BATCH EDIT: STUNNINGLY SIMPLE DD name.The EDIT service of ISPF requires the use of a dataid. I The r e is no function in the realm of computer programming that is chose to use the DDNAME version of LMINIT since I have com- mo r e ad hoc than raw editing. Think of all the times that you have plete control over the batch IKJEFT01 JCL. The DDNAME, gone into program s , JC L , tex t , or what e ver , and done a quick cha n g e EDIT0001, is where I have the dataset allocated with DISP=OLD. to accomplish something. It takes up a large portion of your time. How This is the dataset that will be edited in batch. could something such as editing be canned into a batc h type function? The answer is simple:Your gar den vari e t y , ever y day editing can never ISPSTARTING AN EDIT be batc hed up. However , ce r tain repe at a ble , pre d i c t a ble functions can The ISPSTART at SYSTSIN uses the CMD keyword since be easily “p r ogram m e d ” into the editor. The methods to accomplish BATCHEDT is a CLIST.The name of the initial edit macro to be this are stunningly simple. used immediately follows the BATCHEDT CLIST name. Use a NEWAPPL of ISP and you’ll inherit all of the IBM defaults for THE INITIAL EDIT MACRO profiles and command tables. These defaults should be stored in the This is really the heart and soul of the trick that is batch editing. PDS at ISPTLIB. Finally, the BDISPMAX parameter is set to a IBM introduced the initial edit macro concept long ago. An initial very high value.When ISPF is started in batch there are several macro gets control after the data has been loaded into memory but b at ch - o n ly para m e t e rs that can be used. Th ey all begin with the has yet to be displayed. Because of the point in time that initial l e tter B. BDISPMAX sets the maximum number of batch displays. ma c r os get contro l ,t h e re are a few ISREDIT functions that they can’t issue. However, as this series will show, there are many things that THE NULL MACRO can be done to any dataset by using an initial edit macro. I will not If you have coded these simple components, code one more: the cover all restrictions on initial edit macros except where necessary. NULL macro. Choose your SYSPROC PDS and add a member to Instead, I will show you how to perform powerful transformations it called NULL. It should contain only two lines, as fol l ow s : of data using initial edit macros in batch TSO/ISPF edit. ISREDIT MACRO ISREDIT MEND IKJEFT01: THE TSO TMP The Time-Sharing Option Terminal Monitor Program (what a mouthful!) is IKJEFT01. This is the PGM= name for your batch Figure 1: Batch TSO/ISPF JCL edit. If you are using TSO in batch for DB2 or other functions, you //BATCHEDT EXEC PGM=IKJEFT01 should already have JCL samples. To pull off a batch edit, you will //EDIT0001 DD DSN=&SYSUID..LISTCAT,DISP=OLD //SYSPROC DD DSN=any.PDS,DISP=SHR also need to invoke this program. Hard-code your ISPF allocations. //ISPPLIB DD DSN=SYS1.ISPPLIB,DISP=SHR Refer to Figure 1 for sample JCL. Note how ISPPROF is really a //ISPMLIB DD DSN=SYS1.ISPMLIB,DISP=SHR //ISPSLIB DD DSN=SYS1.ISPSLIB,DISP=SHR (NEW,DELETE) type dataset. Also, ISPLIST and ISPLOG are //ISPTLIB DD DSN=SYS1.ISPTLIB,DISP=SHR DUMMY’d out — no elaborate concatenations are needed. Use //ISPLIST DD DUMMY //ISPLOG DD DUMMY only your IBM base libraries such as SYS1.ISPPLIB, or whatever //ISPROF DD UNIT=SYSDA, SPACE (TRK,(15,1,5)). you call them. Keep your JCL as simple as possible. Code only // LRECL=80,RECFM=FB,DSORG=PO //SYSTSPRT DD SYSOUT=* required ISPF DD names. //SYSTSIN DD * The only SYS-type DD names of nati ve TSO that you will need are ISPSTART CMD(%BATCHEDT IMACRO) NEWAPPL(ISP) BDISPMAX(9999) SY S P RO C , SY S T S P R T, and SYSTSIN. The PDS at SYSPROC will http://www.naspa.net May ‘97 TECHNICAL SUPPORT Figure 2: BATCHEDT CLIST to Launch a Batch Edit ISPF — REXX, CO B O L , BA L ,C / 3 7 0 ,C L I S T, PL/1 — choose you r wea pon! Edit macros can also use any of these languages. I have used PROC 1 MACNAME SET &DDNAME = &STR(DDNAME) them all exc e pt PL/1. Edit macros must be implicitly invoke d . ISPEXEC LMINIT DATAID(&DDNAME) DDNAME(EDIT0001) Fu rt h e r , if they are link-edited load modules, their name must be pre- ISPEXEC EDIT DATAID(&DDNAME) MACRO(&MACNAME) ISPEXEC LMFREE(&DATAID) ceded by an excl a m a tion point. Most edit macro authors cho o s e EXT REXX or CLIST because of their interpre t i ve natu r e. I norma l l y use REXX or BAL. REXX is powerful enough, has excellent bui l t - i n That’s it. The MACRO declarative sets up the edit macro environ- fu n c t i o n s , and most importa n t l y, can deal with non-prin t a ble hexa - ment. It is required for all edit macros. The MEND (Macro END) decimal data. BAL can also be used to grea t effec t , es p e c i a l l y in wha t ends the macro. You are now ready to run a batch edit. Simply do is called ISPEXEC mode. Using this ver sion of the ISPLINK call, the following: you essentially code your ISPF service calls just as you do in an inter- pre t i ve language. If I had to choose a favor ite language for day- t o - d a y 1. Add a real dataset at the DD name EDIT0001. edit macro writ i n g , it would be REXX. If I needed a low- l e vel BAL 2. Add the word NULL after the BATCHEDT in the ISPSTART type function, I’ d use the SELECT service from within the REXX at SYSTSIN. ma c r o. Whi c h brings me to this tantalizing conclu s i o n : You can also 3. Add your SYSPROC dataset. in vok e standard ISPF service calls from within edit macros. This is 4. Submit the job. po werful stuff! OK, I didn’t have the room this month to really give you some WOW, WHAT HAPPENED? good examples. If you use edit macros, you should have some good No t h i n g . Whoop-de-doo! The purpose of this little exer cise is not ideas already. ts to do anything real fan c y. Rath e r , I’m just trying to wor k the kinks out of the process — you know, JCL errors , misspelled names, and such. NaSPA member Jim Moore is the president of Concentrated Logic Corporation, a We’ re almost rea d y to do some real wor k. But firs t , I’ d like to men- Glendale Heights, Ill.-based software development firm specializing in TSO/ISPF/PDF tion a few things about choosing a language for edit macro writ i n g . and database design. He can reached at [email protected].
ISPF: ALL THINGS TO ALL LANGUAGES ©1997 Technical Enterprises, Inc. Reprinted with permission One of my favor ite things about the ISPF envi r onment is that ever y of Technical Support magazine. For subscription information, co m m e r cial programming language that IBM sells is supported in email [email protected] or call 414-768-8000, Ext. 116.
TECHNICAL SUPPORT May ‘97 http://www.naspa.net WORKING SMAR T E R Cook Me up a Batch of EDITs: Part II
BY JIM MOORE
ast month’s column examined the simple ◆ Edit macros must be invoked implicitly, most useful options for macro testing are components re q u i red to develop a or, in other words, by their member Option 8, Breakpoint, and Option 3, Lbatch edit. This month, I will present names at SYSPROC or SYSEXEC. I Variables. You can adjust (qualify), some practical uses for batch edit macros, use the AL TLIB command to activate an add, or temporarily disable breakpoints as well as recommend several techniques app l i c a tion level search. I do this from from a breakpoint. Neat! The variable for testing batch or interactive edit macros. within the Dialog Test option by issuing: option is useful for examining error messages and other dialog variables DIALOG TEST IS ALSO MACRO TEST TSO ALTLIB ACT APPL(CLIST) DA(some.PDS) that your macro may be manipulating. Let me start with testing. Option 7 of ISPF is ve ry useful for setting up a test Ev en if you are using REXX, as long as you ◆ Use the C (CANCEL) option only if e nv i ronment for edit macro deve l o p m e n t . ha ve included a comment with the wor d you have detected a loop or other time- The fo l l owing steps serve as a useful REXX in it in the fir st line, this will wor k fin e . consuming condition. The CANCEL outline of how to proceed with edit option drops you totally out of Dialog m a c ro testing: ◆ If you plan to use the edit macro in batc h Test. You will then have to repeat all of as an initial edit macro, enter its name your test setup work and begin again. 1. Navigate to 7.8, the BREAKPOINT in the INITIAL MACRO ===> field. di a l o g. In the fir st row, for the SERVI C E , Coupled with the breakpoint, this will ◆ Sit in split screen with your REXX enter ISREDIT. For WHEN, enter an A help you debug certain macro services or CLIST edit macro up in edit on the (AFTER). This is sufficient to get starte d . th a t are not allowed in initial edit macros . second logical screen. Make changes Be aware that you can qualify your These for b i d den services usually perta i n and issue SAVEs as you debug.Your breakpoint in a number of ways. Read to scrolling, such as UP or DOWN. changes won’t take effect until the how by pressing PF1. macro ends and is re-executed. ◆ If you are unfamiliar with the break- 2. Issue an =1 from the 7.8 dialog. This point display, it may take a little get t i n g BATCH MACROS IDEAS will take you to the dialog that allows used to. To proceed through a successful H ave you ever ran a utility such as you to launch your test function. macro call, you must enter the letter G IDCAMS or SuperC (ISRSUPC) in batch Note that Dialog Test sets its entry (Go) and press enter. I suggest starting mode and deliberate l y wrote the SYSPRINT menu as &ZPRIM = YES. So, issuing with a simple edit macro that has mini- to DASD so that you could edit it? This is =1 means th a t you jump to the dialog mal looping. If a severe error occurs, whe r e batc h edit macros can rea l l y be useful. th a t has been assigned the number 1 you’ll get the flowerbox error issued by The beauty of edit macros is that most of fr om the prim a r y menu of Dialog Test, ISPF whe n e ver register 15 is 8 or great e r the programming that you are doing uses not ISPF browse. and CONTROL ERRORS CANCEL ordinary, every day edit commands such as is active. Note: Since you are in test F I N D, C H A N G E , E X C L U D E , e t c. Oh, 3. Finally, from Option 1 of Dialog Test, mode, you will be given the option of there are some specialized services that can tab down to the field called PGM ==> continuing. Try continuing.Your macro only be invoked from macros, but 70 per- and enter ISREDIT. code needs to be corrected but maybe cent to 80 percent of the macro code will you can get by the error.When a macro be writing garden variety edit commands. Press enter.You should see the familiar ends with an error, a short message will Space does not permit me to show elabo- ISPF edit entry panel. Even though the edit display in the upper right-hand corner rate code examples. Instead, I will just list a en t r y panel looks like it always does, since you of the edit session’s screen. few batch edit macros that I have written in ha ve set a global breakpoint for all ISREDIT a problem/solution format. Hopefully, you macro service calls,you’re positioned to test ◆ At a breakpoint, all of the menu options will be able to see the utility in these and your macro. A few points to note: of Dialog Test are available to you. The find your own uses. http://www.naspa.net June ‘97 TECHNICAL SUPPORT Problem 1: 80-byte object code written P ro blem 3: M a ny, m a ny datasets in CORRECTION TO LAST MONTH’S COLUMN to one big flat file. From a minimum of one a certain High-Level Qualifier, usually an In last month’s column, the NULL to a maximum of hundreds of individual ex-employee’s TSO-id, have been migrated m a c ro presented contained two ove rs i g h t s : object decks, all concatenated together in by DFHSM. Short of doing an: HRECALL one big file. tsoid, which would restore more than need- 1 . Name the macro something other than Solution 1: A REXX batc h edit macro ed and hog a lot of cartridge slots, how can NULL such as XNULL or ZNULL. whi c h divides each object deck with an we selectively HRECALL a subset of the 2 . The macro should be coded as fo l l ow s : IE B UPDTE card: ./ ADD MEMBE R = m e m - migrated datasets? na m e . ISPF table services and REXX parsi n g Solution 3: Get a 3.4 list up of the HLQ / * R E X X * / also wer e invol v ed to capt u r e the entry point and type HRECALL in front of the first ISREDIT “M AC RO ” CSECT name. IEWL SYSLIN syntax DSN you want restored.Then, type an ISREDIT “ M E N D ” (N AME loadname(R)) is ad ded to the table equal sign (=) in front of all subsequent ISREDIT “ C A N C E L” and later as an IEBUPDTE member. After an ones. What, no edit macro! Yeah, that’s IE B UPDTE run fol l o wed by a link/bind, right, no edit macro. Although, IDCAMS S o rry for any inconveinence this may ever y object deck is prop e r ly linked no LISTCAT on the HLQ followed by a batch h ave caused. ts ma tter how many or how few there are. edit macro looking for MIGRAT or ARCHIV could have done it for you also. Problem 2: Need to find which load This last example illustrates that there is modules in a large load library contain cer- definitely more than one way to skin a cat. tain statically linked CSECTS.The search It doesn’t make a lot of sense to write an must make sure that the module is truly edit macro if its not reusable.While I’ve linked inside the larger load module mem- been touting the simplicity and ease of pro- ber.That is, we are not interested in weak, gramming for edit macros, they still take unresolved references or label definitions some time to write. that may appear in the ESD or elsewhere. If you want to use the ISPF edit NaSPA member Jim Moore is the president of These will show up as hits in a string-only p rogram in bat ch , yo u ’ll have to write edit Concentrated Logic Corporation, a Glendale Heights, scan of the load library. m a c ros. Furt h e r, t h ey have to be valid Ill.-based software development firm specializing in Solution 2: A batch edit macro which initial edit macros. Test your macros TSO/ISPF/PDF and database design. He can reached expects the SYSPRINT output of SuperC t h o ro u g h ly. Th e re is nothing wo rse than a at [email protected]. (ISRSUPC). ISRSUPC is the progra m looping edit macro. Macros used in bat ch t h at is behind 3.12, 3.13 and 3.14 of ISPF. should always include the MEND ©1997 Technical Enterprises, Inc. Reprinted Run a bat ch 3.14 scan of the load libra ry d e cl a rat ive. A l s o , d o n ’t fo rget to put with permission of Technical Support maga- looking for the CSECT names. The edit in a SAVE or END! Read the IBM zine. For subscription information, email m a c ro will cre ate AMBLIST syntax fro m documentation on edit macros. It is avail- [email protected] or call 414-768-8000, the found stri n g s , if any. The A M B L I S T able in paper format, in MVS/Quick-Ref Ext. 116. utility will reveal the internals of the load f rom Chicago-Soft Ltd. , and of cours e, module in gre at detail. Ti p : If you get too B o o k - M a n ager from IBM. The ISPF mu ch AMBLIST output, w rite another edit t u t o rial doesn’t re a l ly explain edit macro s m a c ro wh i ch looks for only wh at you are ve ry well. Use the tutorial to learn ab o u t i n t e rested in. D i a l og Test.
TECHNICAL SUPPORT June ‘97 http://www.naspa.net