5 ISPF command tables

Before I can explain the functionality of the command table technology, I think it is important to explain the different methods of executing programs in a TSO/ISPF environment.

5.1 Execute programs in a TSOP/ISPF environment

Any programs that are available in a z/OS system are executable in a TSO/ISPF environment. There are two types of programs:

– Programs are executable directly in z/OS without any additional support. These are all compiled programs and z/OS utilities.

– Programs needing the assistance of an interpreter are all programs written in REXX or CLIST.

All programs are executable online and in batch. Programs written in REXX or CLIST need for an execution in batch, of course, the appropriate interpreter. When these programs use ISPF services, the ISPF environment must also be available. For means of explaining the entire complex of program execution under a number of conditions, I have developed two REXX programs. Both are very small. They take a parameter and print its content.

– TEST1: This program only needs the TSO environment.

– TEST2: This program additionally needs the ISPF environment.

Here the source code lists of both programs:

5.1.1 Online execution

For the online calling of a program, you do not know whether this is a procedure or a compiled program. Moreover, you do not have to worry about the program requiring ISPF services, because you are already working in ISPF. Nevertheless, you have to know if it is for the correct execution parameters needed.

5.1.2 Batch execution

To execute a REXX program in a batch job is not as easy as in the online environment because an appropriate JCL program is required which is to the batch system environment for execution submitted. This is first a difficult matter because you have to know how this JCL needs to be to work properly constructed. Having had this problem many times using TSO/ISPF, I developed two edit macros, which relieve me of all this work. These two edit macros are:

#TSOB to submit and execute REXX programs which only need the TSO environment.

#ISPFB to submit and execute REXX programs which additionally need the ISPF environment.

If a program requires input parameters, these can be when calling entered.

I have the two above-mentioned programs TEST1 and TEST2 each executed with the correct edit macro. I have added the resulted JCL programs below.

When running this program, the following list is printed. It can be in SDSF found.

5.2 Introduction to the ISPF command technology

Self-defined ISPF commands are the best way to facilitate the daily work with ISPF. Unfortunately, the most users do not have the skills to create command definitions. It is very cumbersome to install such commands. However, you should not despair now, because I will show you a silver bullet for defining your own ISPF commands in the following chapters. In addition, I hope you will say: It is quite simple.

As you may have already noticed, almost every ISPF screen has an upper left line that begins with Command ==> or option ==>. The line in which this input option is available, I will refer to in the following text as a Command Line. In this command line, you can always enter one or more ISPF commands. If you want to have several ISPF commands executed at once, then you have to separate the individual commands by the ISPF command delimiter character.

Behind Command ==> you can always enter two different types of commands:

1. ISPF Primary Commands: The commands are like a TSO, KEYLIST, KEYS, DSLIST, = 3.4, ISPFWORK etc. The brochure z/OS ISPF User's Guide Volume I contains a description of the ISPF Primary Commands. You will also find these commands in the ISPF help system.

2. User Commands: The ISPF user has created these commands.

Which user commands do you now have available?

You can easily determine:

Enter the ISPF menu 3.9 and you receive the following POP UP Panel:

This panel covers two purposes simultaneously:

1. It serves as an entry screen for displaying or modifying individual command tables. Behind Application ID is the name of an application ID entered whose command table is displayed. Therefore, if we no press ENTER in the above panel, the command table ISRCMDS appears.

2. It displays in the Command Search Order column, which command table levels are used and the order in which the command tables are searched (top to bottom).

As we see, we can define user commands in four different levels (and thus in four different command tables). These levels are:

We see that only the application level and the system level have a table prefix entry, and thus only these two levels are usable. It becomes obvious from the statement in the screen above that the commands in the two tables ISRCMDS and ISPCMDS are now used.

5.2.1 The member ISPCONF

I already mentioned several times in this book the fact that the ISPF system programmer department customizes some definitions and options within your ISPF. Of course, there must be a location defining these options. It is a member named ISPCONF. This member contains these options. It is located in a system library and maintained by the ISPF system programmers department. I recommend asking your ISPF system programmers for this member and having a look at it. Most entries are so meaningful that you can easily grasp their meaning.

Here is an excerpt from the Member ISPCONF that contains some interesting values:

In our example above, we see that only the application and the system level are usable. This also means that only two command tables can be active simultaneously. The following definition line defines the search order:

SITE_COMMAND_TABLE_SEARCH_ORDER

If some commands are defined with the same name in both tables and if the option BEFORE is set only, the command in the application table is found. If you want to delve deeper into the topic ISPF customization, then I recommend the brochure ISPF Planning and Customizing. Here a short excerpt from this book concerning the above entry:

SITE_COMMAND_TABLE_SEARCH_ORDER

Determines whether the site-wide command tables are before or after the default ISP command table searched. Valid values are AFTER and BEFORE.

The default is BEFORE.

Depending on this setting, the search order will be:

Search Order = BEFORE	Search Order = AFTER
1. Application	1. Application
2.USER (1 to 3)	2. USER (1 to 3)
3.SITE (1 to 3)	3. System
4System	4. SITE (1 to 3)

5.2.2 Datasets for command tables

Where are the command tables located?

We have already seen in the establishment of ISPF that some files must be present when starting ISPF. One of these files is the file with the DD name ISPTLIB. When you start an application, ISPF searches in this data set the command table member that belongs to this application.

What are the names of the command table members assembled?

The name of the command table member is formed using the first three characters from the name of the application ID expanded with the string CMDS. Looking at the panel of the command table utility above, we see the entries ISR and then ISP in the command search order column. Thus, we assume to find in the ISPTLIB chain two members with the name ISRCMDS and ISPCMDS.

Let us now check whether these members exist:

We use the program DDLIST and search for the members ISRCMDS and ISPCMDS one after the other. I have conducted these searches in my ISPF.

After completing these two searches, following display appears:

However, why did the ISPF user put his own commands just in the Member ISPCMDS and not in the Member ISRCMDS? The following text answers this question:

– The commands in ISRCMDS are only available as long as the application ISR active is because this command table is an application command table. Once a new application such as SDSF opens with the application ID ISF, these commands are available in ISFCMDS and not in the table ISRCMDS.

– The Table ISPCMDS, as seen above, is on the ISPF system level. This means that the commands are always available regardless of which application opens.

– Of course you can prove the Table ISRCMDS with own commands. However, you have to remember that these commands always disappear when you activate another ISPF application.

Let us now look at the member list of ISPTABL library:

As you can see, this ISPF user has changed and written back only two command tables. These are in gray highlighted. We remember: The name of the command table member will assembled using the characters of the application ID expanded with the string CMDS. Therefore, if you want to see which applications command tables already exists, then look at the files that are associated with ISPTLIB for members with the suffix CMDS.

5.2.3 Creating your own ISPF commands

Let us now again turn to the panel of the command table utility using ISPF selection 3.9.

With the above screen displayed, we simply press ENTER to see what happens:

We then get the following screen, which contains the entries to the current ISP command table:

If we look at this panel, the shaded text is conspicuous. This text tells us that it will not be so easy to create own ISPF commands because we cannot directly modify the contents of our table ISPCMDS and then save the changes.

We try it again now with the table for the application ISF (SDSF), being certain that at this time the table ISFCMDS of our SDSF is not open in any other ISPF logical screen.

Here we are now getting a very different picture than for the table ISPCMDS. The reason is that we currently do not have the application SDSF open anywhere in this ISPF. Therefore, the table ISFCMDS is available for update. Thus, you could now enter your own commands or change the existing one. However, they were available only in the SDSF application and the benefit for our ultimate goal, namely own commands available under the application ID ISP (and thus for all levels of ISPF), is unfortunately nothing.

How can we change the ISP command table ISPCMDS?

If you can only use the standard facilities of ISPF, perform the following steps:

1. First, look whether in your file that is associated with ISPTABL the member ISPCMDS is already present there. If not, then look using the DDLIST utility in the file chain of ISPTLIB and then copy the member ISPCMDS into the data set that is associated with ISPTABL. If you do not have ISPTABL allocated, you cannot change any command tables!

2. Next, create via menu 3.4/M in the ISPTABL data set (which you can also call directly into the DDLIST display with the input m) a copy of ISPCMDS named XXXCMDS.

3. Then go to the ISPF menu 3.9, enter XXX as an application ID and press ENTER.

4. Now the contents of the current ISPCMDS table appear (the contents you copied to the member XXXCMDS) with the ability to make updates.

5. Perform your intended updates and exit the panel with the PF3 key. The member XXXCMDS is now in your ISPTABL data set and has the content you would like to have inside the member ISPCMDS.

6. Copy the member XXXCMDS as member ISPCMDS in the ISPTABL data set using the REPLACE option.

7. Now leave the ISPF and start using the TSO command ISPF again. If the TSO READY prompt does not appear immediately when you leave ISPF perform a new TSO+ISPF logon.

8. In the future, you can always make changes in the XXXCMDS member and then copy this member to ISPCMDS. Remember: The new or changed commands are not available until you perform a new start of ISPF or a new LOGON.

Your originally created commands in the members XXXCMDS are now under the Application ID ISP and thus throughout ISPF available.

Although this is a lot of work, it is worth doing!

5.3 Program SICMD

It would be nice if there were a tool that allows you to always create ISPF commands to be done regardless of whether the concerning application is currently active or not. I developed such a tool a long time ago for my own use. This tool is available under the name SICMD in the SMART ISPF utilities as REXX procedure. The description of this program is in the general descriptions of SMART ISPF utilities.

Installation:

Copy the REXX program SICMD from the SMART ISPF utility collection file in your file for executable REXX procedures.

Execution:

Enter TSO SICMD ISP in the ISPF command line. The SICMD application starts and displays the working panel to change the ISPF command table ISPCMDS. The content on your display may be different!

5.3.1 Edit ISPF commands using SICMD

5.3.1.1 The panel ISPUCMX

The command table utility panel ISPUCMX appears when you enter one of the action characters S, R, I or U in column C on panel SICMD.

The following display shows the panel ISPUCMX called to update the ISPF command ++. I use this command for the quick call of my mostly used Personal Data Set Lists.

This is a standard panel of ISPF designed to administer ISPF command tables. In the panel ISPUCMX, each input field is sensitive for HELP. If you put the cursor in one of those fields and press PF1, you will get dedicated help information concerning this field.

5.3.1.2 Description of input fields for panel ISPUCMX

Each entry for an ISPF command consists of four elements:

1. Verb The command name: Up to 8 characters long. This name is mandatory.

2. Trunc Indication of a minimum length of the entered command.

3. Action The actual statement what ISPF should execute (max. 240 characters).

4. Description  A description text (max. 80 characters).

Example:

The entering of ++hugo in the ISPF command line displays the DSLIST HUGO. As we see in the command definition above, a minimum abbreviation of two characters is necessary to execute this command. Therefore, it is sufficient to enter the two characters ++ to execute the command.

In this case, if we display the SWAP LIST panel, the name HUGO appears in the NAME column in the SWAP LIST panel.

5.3.2 Display the list of all standard ISPF commands

As I mentioned above, you should avoid designing an original ISPF command as your own command. Always when a new release of ISPF appears, new commands can possible be added. Therefore, you should be able to get a list of all current available standard ISPF commands. In an earlier chapter, I explained the display of all ISPF commands. My tip you here again is to get a list of all commands:

1. In the ISPF Primary Option Menu press PF1 to call the ISPF help system.

2. Enter the following command: i;i;i8. A panel displaying all current available standard ISPF commands appears.

5.3.3 Define the call of SICMD as command

Of course, we can define the call for the REXX procedure SICMD as ISPF command. This entry must look like this:

As you can see, the call to the procedure SICMD is expandable by adding a parameter represented by the ISPF system variable &ZPARM. This parameter may be an APPLID. If there is no parameter specified, then the program sets the APPLID automatically to ISP.

5.3.4 Generating a list of commands

With the program SICMD, you can generate a list of commands from the currently edited ISPF command table.

Simply enter in the command line the SAVELIST command and press ENTER.

This command creates a file that contains the commands contained in the command table, each in a record of a sequential data set. This file can then be to the PC transferred, edited with a word processor and printed.

The data set name of the output file will as follows composed: userid.tablename.LIST

Two examples of the generated files:

	→ Command list of the application ISF (SDSF)
	→ Command list of the application ISP.

Example of a SAVELIST call:

If you enter SAVELIST and press ENTER, SICMD creates the output data set and the name appears in a small frame at the bottom of the screen.

Screen 5.8: Display a list of all ISPF user commands