A Few Good TSO Commands

A Few Good TSO Commands

Introduction fo lesser-known useful commands like CMDE, ZEXPAND, ISRDDN, REFLIST, TSO PROFILE, SEND.  Explains difference in TSO READY vs ISPF commands..

Learning more TSO Commands is like expanding your vocabulary.  You can manage to use TSO/ISPF knowing very little about it, but it’s like speaking a language – You feel more comfortable using the language when you know more words.

As with previous posts: If you already know everything, move along, this is not the article you’re looking for; Just keep on Googling.

Also note that some of the features discussed in these pages came in with release level 2.1 of z/OS (V2R1), and if you have an older version – Version  1.13 (V1R13) for example – You won’t have the newest stuff until your site converts to Version 2.  Additional new stuff comes in at 2.2 and so on, but 2.1 was a pivotal release with more and better enhancements than most new releases.  Most of the stuff discussed in this article  has been around for a long time (like SEND and ISRDDN), but some is new, like ZEXPAND.

You pick up more vocabulary as you go along; Words change, usage changes, usage varies from one place to another, you can make up new words.  There are a couple of EXEC languages you can use to make up your own TSO commands easily: REXX, which you may know from other platforms, and an older CLIST (Comand List) language which consists basically of putting any set of ordinary TSO commands together into an executable file, though some additional niceties such as IF and DO logic are available.  You can also put sets of ISPF edit commands together into an executable file, called an Edit macro.

Adding your own commands would be a digression from today’s topic, though, which is to show you a few handy TSO commands you can use right now to expand your comfort zone.

We will also discuss usage quirks such as TSO READY mode (line mode) vs full screen mode, the meaning of the three-asterisk line, and the use of PA2 to redisplay a garbled screen.

CMDE might be the best TSO/ISPF command you probably never heard of.  You’ve noticed that the ISPF command line varies in length from one screen to another, and quite often the line is too short for you to enter some long command you want to type?  Just type CMDE on the command line, press Enter, and voila! You get an extended command line, in the form of a popup screen with a command line so long your typing can wrap to multiple lines.  The popup goes away by itself after you use it.

ZEXPAND is a variation on CMDE.   When in ISPF Edit, you might want to enter an extra-long Edit subcommand — Maybe you want to do a Find or a Change using a long text string.  For Edit subcommands you need to use ZEXPAND rather than CMDE.  Also the method for using ZEXPAND is a bit more awkward: You type ZEXPAND to get the popup with the long command line, then you enter your lengthy edit subcommand, then you press F3; when the popup goes away and you see the regular Edit screen again, you press Enter from there to get the long command to execute.  Cumbersome but effective I guess.

If you have never felt you needed a longer command line, keep reading, you might change your mind.

You want to use Instant Messaging from one TSO session to another? Then you want the SEND command.  Yes, before cell phones were invented, TSO users could text each other using SEND.  The syntax is:

TSO  SEND  'Your message enclosed in quotes ',U(Anybody)

Be sure you include that last part, the comma followed by the U (which stands for USER, meaning TSO Userid), followed by the TSO userid of your intended recipient enclosed in parentheses.  With the above example, you send a message to somebody who has the Userid “ANYBODY”.  If you forget that part, or make some syntax error that causes it to be discarded, then the message goes to the default destination: the main operations console; Generally it will then also appear in the System Log (where it will be viewable to everyone who looks at SDSF LOG).

What syntax error could one possibly make? you might ask.  A common error is to try to enclose an apostrophe within the quoted string.  That apostrophe then becomes the termination of the string.  The string, thus terminated, and not being followed immediately by ,USER(Whoever) . . . Well, it goes to the default destination (the main operations console, and thence to the aforementioned System Log).  Can you include an apostrophe in your message?  Yes, if you code it as two consecutive apostrophes:

TSO   SEND   'Isn"’t that nice?',USER(Someone)

When using this type of TSO command, in general the comma can be replaced with a space – they’re interchangeable (in TSO) in most such cases.

Also note, if you didn’t already know it, that two consecutive apostrophes can be used in many places within z/OS to represent one single apostrophe within a quoted string; It can be done to include an apostrophe within a PARM string in JCL, for example.

When you use SEND, the message recipient does not actually see your message until they press Enter (or some F-key, or the screen clear key, and so on).  So if they are just sitting there staring at something on the screen, they won’t get it until they do something to wake up the screen.

Want to send somebody an entire dataset?  Sort of like appending a photo to a cell phone text message, right?  The TRANSMIT command, aka XMIT, does that.  To pick up the dataset you sent, the recipient uses the RECEIVE command.   Yes it works for Library datasets too.  Yes it can send the dataset to a TSO user on another z/OS system as long as the two systems are connected to each other.  In fact you can XMIT your Library to a flat file, download the flat file to your PC in binary format, and email the file if you want.  For that matter, you can also send emails directly from the mainframe – but we’re getting ahead of ourselves.  That would all be beyond the scope of the present very basic article.  Now that you know it is possible, you can look it up elsewhere using Google, of course, if you're super-interested in it; and it might make a good topic for a future article here; but for now let’s get back to today’s simpler theme – a few good TSO commands.

 Why do you say “TSO” before the “SEND”?

 In the Microsoft PC world, before there was Windows, there was DOS.  You can still open a DOS window on your PC and enter DOS line commands.  Analogously, under TSO, before there was ISPF, there was TSO READY mode.  So ISPF is kind of like Windows:  It’s a full-screen interface that was overlaid onto a previously existing line-mode system.  Yup.

There were a lot of TSO commands in the pre-ISPF world, and, like the PC DOS commands, they are still there.  When you enter the word “TSO” on the ISPF command line, the rest of the line is passed across to the underlying TSO READY-mode line-oriented handler.  If you use ISPF Option 6, it’s like opening a DOS window on the PC, and everything you enter within ISPF Option 6 is passed directly to the TSO READY-mode handler; but if you just want to enter one or two line commands, then you don’t need to go to Option 6 – you can just preface what you say with the word TSO on the command line on any ISPF screen.

Another little quirk you should know about TSO READY mode, that is, line mode:  When TSO writes to your screen in line mode, it puts three asterisks at the bottom of whatever it writes.  You are supposed to press enter at that point, after you finish reading the screen.  When you press enter – or an F-key, or clear, etc. – TSO interprets that as a signal for it to move ahead to the next bunch of data it wants to display, if any, or to return to full-screen mode if it has no further lines to display.  If you type anything on the line with the three asterisks, whatever you say will be thrown away, discarded, ignored.

Any input from you on the three-asterisk line is just taken as an indication that you have finished reading the lines and are ready for the next display.  The actual content of what you enter vanishes, uninterpreted and unseen.

What if you realize you have unwittingly become trapped in some process that is going to produce way more lines of data than you want to sit through, and you just want to cancel out of it somehow?  Usually the PA1 key, the ATTN key, or a Break key will do it, provided your emulator offers you such a key.

If the screen now looks wonky, press PA2  to restore the full screen display as it was before you got it messed up.  This works whether the screen was messed up by the line mode display or some other method.  For example, when in ordinary full screen mode, if you press the CLEAR key accidentally,  how do you get your original screen back?  Just press PA2.  Or suppose, in Edit mode, you overtype some stuff you didn’t mean to change?  Press PA2 and the screen goes back to the way it was before.

What other TSO READY mode commands are there for you to use?  You might be amazed.  All of the IDCAMS commands, for starters, as well as the DFHSM data set migration, recall, and recovery commands.  Yes, you can enter things like:

TSO DEFINE CLUSTER(etc.etc.)

on the ISPF command line, provided you get the syntax right.

You also have available the DELETE and RENAME commands.

Besides deleting and renaming datasets, these can be used to delete and rename individual members of libraries if you get the syntax right and have enough confidence to try it.

The penalty for getting the DELETE syntax wrong can, unfortunately, result in your deleting an entire dataset accidentally, so DELETE is not really something you usually want to do as a freehand command entry.

HDELETE can be used to delete a migrated dataset without first recalling it.  That can be useful, and usually runs faster than other methods.

RENAME can provide a handy way to assign an alias name to a library member – You just add the operand “ALIAS” on the TSO RENAME (at the end of the line).

Where are you supposed to get the syntax for this kind of stuff? From the TSO HELP of course.

Yes, there is a  HELP for the line-oriented commands, and it is, of course, accessed by entering TSO HELP followed by the name of the command you want help with, for example:

TSO HELP RENAME

However, I don’t usually do that.  All of the basic TSO READY mode HELP text from IBM is contained in a library named ‘SYS1.HELP’, and personally I just go and use ISPF browse to look at ‘SYS1.HELP’ – It’s a lot easier to read that way, because you can page up and down in full screen mode; also because looking at the member list will give you hints about what might be the name of the command you’re looking for, in case you don’t remember exactly.  (Was it HRECALL that I wanted, or HRECOVER??? For example.)  Moreover, there are a bunch of useful HELP members that don’t correspond exactly to the name of the command: For example, the DEFCL member tells you about DEFINE CLUSTER, and the DEFGDG member tells you about DEFINE GDG (Generation Data Group).

The TSO HELP members have, alas, a peculiar syntax you need to know.  Think of it like reading stock market quotes or the Racing Form or a Recipe book: First you have to know how to read it, but that isn’t hard to learn.  For the HELP members, you need to know that they show the syntax using this convention:

Anything that is shown unquoted in UPPER CASE LETTERS, you type it exactly as they show it.

Anything they show 'enclosed in single quotes', you replace with your own information.  As a variation, Occasionally they indicate this by using Lower Case Letters rather than (or in addition to) single quotes.  (In general, single quotes means paired apostrophes.)

Example: If they say

TRACKS('PRIMARY' 'SECONDARY')

Or

TRACKS(primary secondary)

In both cases you type the word TRACKS and the parentheses as shown, but you replace the words primary and secondary with data of your own choosing, such as:

TRACKS(15  45)

When using TSO READY mode commands, you can usually replace a space with a comma, at your discretion.  The following is equivalent to the above:

TRACKS(15,45)

But wait, you may say: SOMETIMES you actually need to enter your own data, AND you need to enclose it in single quotes.  MOSTLY the HELP text will represent this situation by the use of double apostrophes, like so:

DATA("STRING")

The above means you would be expected to supply something like this:

DATA(‘My text string goes here’)

For another example of that, the SEND command – with which you are now already familiar – shows this in the HELP member:

SEND  "TEXT"  USER('USERID LIST')

Which, as you now know, means you would actually enter something like this (from an ISPF command line, where you need to prepend the word TSO):

TSO SEND ‘Are you still using that data set? ’,USER(someguy)

Another Syntax item you want to know is that a vertical bar is used to mean “OR”.  Hence, if the HELP tells you that you have this option available (from the text in the DEFCL help member):

INDEXED | NONINDEXED | NUMBERED

That means that you can choose any one of the three choices shown, but only one.  (Many options you can leave off and allow them to assume their default values – most of the defaults are reasonable for obscure parameters you never heard of – but Indexing is not an example of something you want to leave to chance.)

Typically each HELP member is organized so that first it shows the complete syntax of the command, with all the options, and after that it tells you which options are actually required and what all the defaults are, and then the final section gives you a short explanation of each separate operand.

If you browse the members of ‘SYS1.HELP’ you will find descriptions of some commands you are probably not authorized to use. You probably don’t want to experiment willy-nilly with commands you can guess are probably going to be blocked (e.g., OPERATOR and ACCOUNT and some of the RACxxxx stuff).  Authorization violations, however innocent, may be logged someplace, and you don’t really want to be asked to explain things for which the only explanation you can offer is, uh, just playing around I guess.  The mood could vary depending on where you are, of course, but these days I’d lean toward the side of caution. Worse, some commands might NOT be blocked when they ought to be, and you could accidentally cause trouble that you don’t yet know how to fix.  So by all means read through the HELP text for anything that sounds like it could be interesting and useful, but don’t actually try to use anything you aren’t sure is safe.

Oh, and ‘SYS1.HELP’ does not contain HELP members for all possible TSO commands, just the basic ones provided by IBM – which is still a lot of commands.

Among these, then, what other TSO READY mode commands might be useful, you wonder?  I’m thinking you should know about PROFILE.

TSO PROFILE

Yes, there is a PROFILE command for the underlying TSO, apart from ISPF profiles and the myriad other profiles.  Most of the TSO PROFILE operands are well and truly useless these days, but there are a few useful ones.  First, PREFIX.  You can say things like:

TSO PROFILE PREFIX(AltName)

TSO PROFILE NOPREFIX

TSO PROFILE PREFIX(MyOwnID)

The PREFIX default is your own TSO Userid.  What does that mean?  It means that anyplace you enter a dataset name in TSO without enclosing it in quotes, TSO prefixes the DSN (Data Set Name) you enter with your TSO userid.  That’s what usually happens, right?  You go to ISPF option 2 and enter something like TEST.DATA and you end up editing DSN=YourOwn.TEST.DATA, and that suits most people most of the time.

If you say TSO PROFILE NOPREFIX on the command line and press enter, then TSO will stop prepending your userid for you.  Thereafter you would have to type YOUROWN.TEST.DATA rather than just TEST.DATA – and that wouldn’t be great if you really use your own datasets most of the time.  On some projects, however, you might use a lot of shared datasets, and that means you have to put quotes around the dataset names all the time, and maybe you get tired of doing that.  In that situation, people sometimes use TSO PROFILE NOPREFIX, or, more rarely, people set the PREFIX to whatever name qualifier is used by the project.

Also handy is TSO PROFILE MSGID which will get TSO to prefix an identifying message number, such as IKJ1234E, when TSO issues messages.  (This is different from the message identifier that you can set within ISPF option zero, which tells ISPF to do basically the same thing with ISPF-generated messages.)  Why do you want that message number?  So that when something goes wrong you can look the error message up with Google (or the search engine of your choice).

PAUSE is a TSO PROFILE operand that lets you get a little more information sometimes.  If you turn on TSO PROFILE PAUSE, then sometimes when a process fails and displays an error message it will just wait after the message, giving you a chance to enter a question mark (?) to request additional error information (if any happens to be available).  It doesn’t tell you to enter the question mark, it just sits there waiting for you to do something.  If you just press enter, then the failing process will just continue with the normal path of its failure.  . . . Except sometimes pressing enter will be interpreted as requesting an abend dump to be produced.  If you press the enter key just after, or during, a failure, and your TSO session seems to hang for a minute, it probably took an abend dump during that minute.

Commence Short digression about dumps produced under TSO:

Let’s follow this digression real quickly.  Dump creation depends not just on your settings and responses, but also on various other settings, some specific to you or to a product, some system-wide. In general if your TSO session seems to hang for a long minute right after a failure, it probably used that time to take a dump.  Sometimes you might want the dump, if only to give it to someone else to look at.  The surprise is that you might also want to find the dumps you don’t want, so you can delete them.

To find the dump, go into SDSF, assuming you use SDSF, which most places do, especially most JES2 places.  However, if your z/OS system uses JES3 instead of JES2, then you may have some other SDSF-like product instead of SDSF, and in that case you can ask somebody at your site what they use to look at sysout. This discussion is going to assume JES2 for simplicity, or at least for reduced complexity.

So, to find a dump created by your TSO session, go to SDSF (or a reasonable facsimile thereof).  On the command line first enter something like “OWNER myTsoID”, substituting, of course, your own TSO userid for “myTsoID”.  After that, enter “DA”, for “Display Active”.  It should show a job list consisting mainly of your TSO userid.  Yes, your TSO session runs like a job, with JCL and everything.

Put a question mark (?) to the left of your userid.  This lists the various sysout files associated with your TSO session.  The first three at the top contain your TSO session JCL and a bunch of messages similar to what you see at the top of any batch job.  After that, there may be other files in the list.

Possibly there is a CEEDUMP or SYSABEND or SYSUDUMP or something else that looks like a dump.  If so, that is probably where your dump is.  If you want to keep it to give to somebody, you can copy it into a dataset the same way you would any sysout file, that is, you type XD in the command entry column to the left of the sysout you want to save.  When you press enter, you will be presented with a screen that lets you provide a dataset name where you want it to save the dump.  So, do that if you want.

A dump in your sysout will probably go away when you logoff, or else it will stay in your output queue for a few days and then eventually go away if you don’t purge it first.  It is possible to fill up the spool by producing a large number of these dumps – I joke not – So you might want to purge it from your sysout queue if you find that you are creating a lot of them and they’re big and they aren’t going away quickly by themselves.

If you did not find a dump in your sysout, then, if a dump was produced, it probably went into a dataset.  That might be a very large disk dataset filling up space you could use for something else.  So, look through the system-generated messages that are near the top of your sysout file for your TSO session.  Do a FIND for “dump” (yes, just like in Edit).  Maybe the messages will say the dump was suppressed.  Maybe they will say it went into a dataset with a name like SYS1.DUMP01, in which case, unless you want to send somebody a copy of it, you don’t care, because (a) that isn’t your own disk space it’s using, and (b) those SYS1 dump datasets get reused in a loop by new dumps, so your dump didn’t cause any additional use of disk space.  However, there is another possibility, which is especially likely if you are running with IBM Language Environment, and that possibility is that a very large dump dataset has been created using your TSO userid for the first part of its dataset name, and hence using up disk space that you could perhaps use more beneficially for something else.  Moreover, it will create a new such dump dataset the next time it encounters a similar abend, and another one the time after that.  Each will have the time and date of the occurrence woven into the dataset name.  These can use enormous amounts of disk space during the testing phase of a project.  Again, I joke not.  As a humorous aside, note that these datasets, if left lying around, probably get backed up to tape by automatic backup procedures, hence cramming up lots of backup tapes and possibly annoying the people in charge of that.  Okay, it’s only a little bit funny.

So, find every occurrence of “dump” in your TSO session messages, looking for any of them that say something like “a dump has been taken to YourUserId.Dnnnnnn.Tnnnnnn.YourUserId” – the format of this can vary, but you should be able to spot them.  If you actually want to find the dump to give to somebody who has requested that you get a dump for them, well, there it is.  Send them an email.  Otherwise go to ISPF 3.4 and delete the dump dataset and all its similarly unwanted cousins.

For extra credit and additional disk space reclamation, do an ISPF 3.4 on the TSO userid of everybody else involved in the testing phase of your project, find their presumably unwanted and unnoticed dump datasets, and enquire politely as to whether they really are keeping them on purpose, or maybe they want to delete them to free up disk space for the project?  Again, it’s only a little bit funny, but you really can claw back loads of disk space this way under some conditions.

If you just want more disk space for your own immediate use and you don’t much feel like talking to your co-workers about it, then type HMIG to the left of their dump datasets while you are in ISPF 3.4 on their dataset lists.  This might (or might not) result in said datasets being migrated off disk to tape (Migration can fail for various reasons, for example the system might not be willing to migrate a dataset if that dataset hasn’t been backed up yet).  Most often this works, though; usually you can HMIG the large datasets of other users without ticking off the security system.

End of digression about dumps produced under TSO.

Another operand a bit similar to PAUSE is PROMPT, which allows failing EXECs to stop and prompt you to enter information that might allow the failing process to correct itself and continue. The opposite setting of this operand, TSO PROFILE NOPROMPT, can be useful if you have a habit of becoming trapped in long verbose EXEC failures that keep prompting you to answer dumb questions when all you really want is to exit.

VARSTORAGE(HIGH) is an offbeat TSO PROFILE operand that I like personally.  It influences the allocation of some of the invisible variables created by EXEC files, so they go into storage (memory) with 31-bit addresses (where there is more room) rather than 24-bit memory (which is a much smaller area).  EXEC files are used a lot behind the scenes in ISPF, and a lot of ISPF-based applications create a lot of big variables and use a lot of memory, so this has the potential to be more useful than it might sound.

You can string multiple operands together on one TSO PROFILE command, for example:

TSO PROFILE MSGID PAUSE PROMPT VARSTORAGE(HIGH)

Finally, TSO PROFILE NOINTERCOM will block receipt of messages that other TSO users might try to send you using TSO SEND.  (It does not prevent operations, or the system itself, from sending you messages.)  You would say TSO PROFILE INTERCOM to turn it back on.

TSO PROFILE with no operands will cause all of your current TSO PROFILE settings to be displayed.

Although the execution of TSO READY mode commands is handled by the line-oriented handler, that does not mean that the commands, once invoked, need to stay in line mode.

In fact a lot of them will go immediately into full-screen mode.  A good example is ISRDDN.  You can invoke ISRDDN via the TSO-prefix route by saying, unsurprisingly, TSO ISRDDN on any ISPF command line.  That brings up a full-screen interface program.  You can also invoke the same command directly from ISPF by using the command name DDLIST unprefixed by the word “TSO”.

If you have never used this command (TSO ISRDDN aka DDLIST), you definitely want to try using it.  It gives you a full screen display listing the datasets that are allocated to your TSO session, and lets you do a lot of stuff with them.

There is a column that allows you to enter a single-letter command against any dataset in the list.  Among these commands is E for edit, which invokes the ISPF editor.  If you have several library datasets concatenated onto one ddname, and you put the E against the top of that concatenated list, then you are placed into edit with a composite member list which is a merge of all the libraries allocated to that ddname.

So if you are trying to find out where a particular ISPF screen or a particular EXEC is coming from, this greatly facilitates the search.  You can Edit or Browse an entire concatenation as you would a single dataset.  The main ddname for EXEC members is SYSPROC, and the main ddname for ISPF screens is ISPPLIB.  There are also other ddnames used under various conditions – For example, any particular product might use some ddname of its own for its own ISPF screens and another for its EXEC members.

Incidentally, the main ddname for the TSO HELP text members is SYSHELP, so if you use the ISRDDN tool to browse that ddname you will find even more members than you would by just browsing ‘SYS1.HELP’ as previously suggested.  Doing this has the same appeal as reading a dictionary or an encyclopedia.  It’s a good way to learn stuff, if you like that kind of thing.  Note that not all HELP members correspond to actual commands – Somebody might have deleted a TSO command but forgotten to delete its HELP member.  Similarly, not all TSO commands have HELP members to describe them – somebody might add a command but not write a HELP for it.  The stuff from IBM is kept up to date pretty well, though.

Besides these single-letter commands aimed at the datasets, you can enter primary commands on the main command entry line, including but not limited to some good search commands.  Saying MEMBER XXX tells it to search the directory lists of all of the libraries in the entire dataset list to find member named XXX, for example, and it highlights when multiple datasets contain the same member name.

Invoke TSO ISRDDN (or DDLIST) and, once in, type HELP on the main command entry line.  There is an extensive (and fairly readable) HELP text covering a lot of useful subcommands, including an ENQ enquiry to find out who is using a particular dataset, an APF enquiry to find out what libraries are in the currently active APF-authorized library list, and much more. This is one of the most useful commands out there.  Try it, you’ll like it.

Okay, you’re happy enough to get a list of the datasets you have allocated right now; but suppose you want to know what datasets you had allocated yesterday? Or, recently, anyway.  No problem, you want REFLIST:

REFLIST

The display you get from REFLIST will look a lot like the ISPF 3.4 DSLIST, but it will contain the names of the datasets you referenced most recently.  On the command line within the REFLIST display, you can enter SORT REFERRED to get them arranged in order of use, SORT NAME to get them arranged in alphabetical order, and so on, the same as in the ISPF 3.4 display.  You can use F11 and F10 to scroll right and left to get additional information about the datasets (space used, attributes, and so on).

Well, Enough for now.

Until next time, then.

[This post revised March 10th to add ZEXPAND and PA2, and the note about z/OS V2R1.  Revised again 25 April with minor corrections.]

 

3 comments on “A Few Good TSO Commands

  1. Originally there were only CLISTS and they had to reside in SYSPROC. Later REXX support was added, and REXX execs can also be in SYSPROC, but the SYSEXEC ddname was added to support separation of REXX execs. A REXX member can reside either in the original SYSPROC or in SYSEXEC. It is also possible to put both CLIST and REXX members in any ddname you want if you use ALTLIB. In addition, some software products contrive to use alternate ddnames they make up arbitrarily and then fetch from those ddnames. But I stand by the statement that the main ddname is the original ddname and that is SYSPROC. The other ddname you like, SYSEXEC, is purely optional and unnecessary, and isn't made for CLISTS. If you just have a SYSPROC and nothing else you'll be fine, you can put REXX and CLIST members both into SYSPROC. Also SYSPROC is required by ISPF under TSO.

  2. You said: "… The main ddname for EXEC members is SYSPROC …"
    That is not entirely true. If you place EXECs in //SYSPROC, it might be. EXECs can also be placed in //SYSEXEC, though.
    (CLISTs, OTOH, can be placed only in //SYSPROC.)

Comments are closed.