11 The SMART ISPF utilities

Since the early 1980ies, I have been working with ISPF. Over time, I often missed some practical functions in ISPF. In the early 1980ies, there was no internet available. Therefore, it was very difficult to find appropriate functions to fulfil my needs. Therefore, I began to develop these functions from time to time myself. Now a whole series of programs have accumulated that I use in my daily work in ISPF. They are all REXX programs in which I very often use the functions provided by ISPF. Often there are functions consisting of one program only. Sometimes it happens, however, that in order to fulfill the functions, more programs have to work together. Although there are many utilities for ISPF available on the internet, I think that my programs so far are still unique.

In my two books on Smart Practices for ISPF, I make the SMART ISPF utilities available for you to download, so that these utilities provide good services.

11.1 Naming conventions

All programs are in REXX language written. There are generally two types of programs:

Edit macros:

These program names all begin with character # (hash). Using these names rule, the macros are easily distinguishable from the other programs.

Direct executable:

These program names all begin with character S (stands for smart).

11.2 The dynamic panel concept

All panels of SMART ISPF utilities are embedded in the programs REXX code and are automatically loaded in a temporary ISPPLIB of DD Name $$DYNPAN when a program executes.

This technique has the advantage that you do not need a separate ISPPLIB version of ISPF panels to run SMART utilities. Another advantage of this procedure is that REXX programs using ISPF panels are easily distributable because the simultaneous distribution of a panel data set is not necessary.

The following excerpt from a program of the SMART ISPF utilities shows the part where the decision made is to load the panels:

To decide whether the panels are to be loaded dynamically, will the variable DYNPAN from the ISPF profile read in. The program SPROFVAR loads this variable together with other variables needed by some SMART utility programs.

Urgent recommendation: Before you can use the SMART utilities, you must edit the program SPROFVAR, the values contained therein, customize and run it using the edit macro ##. This program is executable without having to load the ISPF profile variables for the SMART utilities.

See the following excerpt from program SPROFVAR:

See also the description of the installation process on page 204.

11.3 List of programs

The following table shows all programs and their functions:

Table 11.1: List of SMART utility programs

Name	Usage	Description
##	stand alone	Edit macro to execute acurrently edited REXX procedure immediately.
#ALTXT	stand alone	Realign documentation text within given borders.
#EDMEM	stand alone	Edit of a member which name is the first name in a line of anedited list.
#IMACROA	assist SLE>	General ISPF edit macro. Automatically executed by ISPF when an edit session starts even if no initial macro is set for the edited data set.
#IMACRO1	assist SDOC	Initial macro to insert DOC: lines into edited data sets.
#IMACRO2	assist SLE	This macro inserts the DSN of an edited data set into the table $SLETAB.
#ISPFB	stand alone	Edit macro to submit a batch job to execute the current edited REXX procedure within an ISPF environment.
#LCH	stand alone	Perform edit change with long parameter texts.
#SSS	assist SSS	Purge unnecessary parts of a SRCHFOR list.
#SSSCH	assist SSS	This macro can be used when a super search list is displayed in edit, to restore the displayed lines back into the members in which the searched lines were found.
#SPLJ	stand alone	This macro performs SPLIT and JOIN operations within an edit session.
#SU	stand alone	Submit a JCL that does not contain a JOB statement.
#TSOB	stand alone	Edit macro to submit a batch job that executes the currently edited REXX procedure within a TSO environment.
#VERASE	stand alone	Erase an ISPF variable from the profile and the shared pool.
SCURSOR	stand alone	Access to a data set by EDIT, VIEW, BROWSE, MEMLIST or DSINFO. The DSN must appear on an ISPF panel.
SDOC	stand alone	This program reads all members of a PDS and produces the $DOC member in the same PDS.
SHOSTPAC	stand alone	This program packs all members of a PDS into one member of name $PACKED.
SHOSTUNP	stand alone	Unpack a $PCPACK file coming as an upload from a PC which was originally packed at a z/OS by the REXX program SHOSTPAC.
SICMD	stand alone	Maintaining ISPF command tables.
SIDCAMS	stand alone	Produce an IDCAMS LISTCAT of a data set and Browse the list. Call in front of a DSN in a DSLIST display.
SJOBSUFF	function	Provide job suffix character for dynamic job assembly.
SLE	stand alone	Display recently edited data sets.
SLIBOFF	stand alone	Reset a LIBDEF.
SLISTC	stand alone	Produce an IDCAMS LISTCAT of a data set and browse the list. Call in front of a DSN in a DSLIST display.
SLISTRAC	stand alone	Produce a RACF LISTDSD of a data set and browse the list. Call in front of a DSN in a DSLIST display.
SLOGON	stand alone	SMART user logon procedure.
SPROFEDT	stand alone	Execute program SPROFVAR to store users ISPF profile environment variables into ISPF profile.
SPROFVAR	stand alone	Store the user's environment variables into ISPF profile.
SSC	stand alone	SMART super clone function for data sets.
SSC01	assist SSC	Messages for panel SSCPP01 called by function SSC.
SSS	stand alone	Perform a super-search operation by entering SSS in front of a DSN in a DSLIST panel.

11.4 Program descriptions

This chapter contains individual descriptions of the programs of SMART utilities. Most programs include extensive help descriptions displayable using the PF1 key. When calling up some programs, a question mark can be as parameter entered. In this case, the program will not run with its functionality. It will only display a description of its functions in a help panel. The following description of the programs points out the possibility of displaying a help panel using a question mark. Therefore, the following description of the programs is only a short one to show the basic function.

11.4.1 Edit macro ##

Edit macro to execute a currently edited REXX procedure. After typing ##, enter a parameter string which is transferred to the REXX program for execution. This program is executable without having to load the ISPF profile variables for the SMART utilities.

Help display with ## ?

11.4.2 Edit macro #ALTXT

Edit Macro to realign line parts within given column.

Help display with #ALTXT ?

11.4.3 Edit macro #EDMEM

Edit of a member which name is the first word in a line of an edited data set.

Description:

The edited list can come from following sources:

– A list output of the procedure SSS and processed by the #SSS macro.

– A list output produced by ISPF function SRCHFOR in the resulting display list.

– The member $DOC from a PDS.

At call, the cursor must be in a line in which the member name as first word occurs. No further help available.

Note: For an optimal use of this macro, its call should be set on a PF key. E.g. PF22.

11.4.4 Edit macro #IMACROA

General ISPF edit macro. Whenever you start an edit session, this macro will execute, regardless of whether an initial macro is for this file defined or not.

Activating of this macro:

1. Start an edit session in an ISPF environment.

2.  Enter in line command ===> EDITSET or EDSET

3.  Make the necessary entries in the appearing panel. See the following panel:

No further help available.

screen 11.1: Set activation of #IMACROA

11.4.5 Edit macro #IMACRO1

Initial macro to insert DOC: lines into edited members of partitioned data sets (PDS).

When starting an edit session of a PDS member and in the edited member are no DOC lines found within the first 20 lines, this macro displays then a panel that offers the opportunity to insert DOC lines at the beginning of the member, which is edited.

Help can be via PF1 displayed when the panel IMACRO11 appears. The following screen shows an example for inserting DOC and REM lines into a member.

Screen 11.2:Panel IMACRO11 for edit macro #IMACRO1

The greyed fields show the standard options inserted here by #IMACRO1 depending on LLQ. These options are changeable to fulfil user’s needs.

The following screen shows the resulting contents of the new member after ENTER is pressed:

11.4.6 Edit macro #IMACRO2

This macro inserts the DSN of an edited data set into the table $SLETAB. This macro is executed when an edit session ends in which the macro #IMACRO1 was executed.

No further help available.

11.4.7 Edit macro #ISPFB

Edit macro to submit a batch job to execute the current edited REXX procedure within an ISPF environment.

When the macro is called, a parameter text can be added in the call statement. This text is to the executed REXX procedure as a parameter transferred. Help display with #ISPFB ?

11.4.8 Edit macro #LCH

Perform edit change with long parameter texts.

Function:

When the Command ===> line in the normal edit panel is too short to contain the whole CHANGE command, you can use this program to solve the problem. This program opens a panel for input of two lines each with max 70 characters. The first line is the SEARCH argument for the change and the second line is the replacement value.

Additionally, you can enter parameters for the CHANGE in a third line.E.g. 1, ALL, WORD…

11.4.9 Edit macro #SPLJ

This macro performs SPLIT and JOIN operations within an edit session.

Functional description:

When this macro is called, the further processing of the position of the cursor depends on the following:

 1. If the cursor is within a line and after this position, characters are on the line, these characters move to a new line after the current one. This is the split function.

2. If after the position of the cursor only blanks are on the line, the line after the current line moves to the current line after the cursors position. This is the join function.

There is no other help available.

11.4.10 Edit macro #SSS

Remove unnecessary parts from SCHFOR list.

Functional description:

Delete all unnecessary lines from a list produced by the Super Search Function of ISPF. The procedure SSS calls this macro as initial macro. If you have performed a manual search, you can also use this macro to revise the list output.

There is no other help available.

11.4.11 Edit macro #SSSCH

This macro offers a very smart functionality: When you have performed a super search and you make some changes in the edited list you can write back the displayed lines completely to its members. With this possibility, you can perform mass changes on many members in one step.

Purpose:

This macro can when a super search list is in edit displayed be used to restore the displayed lines back into the members in which the searched lines where found.

There is no other help available.

Remarks: You can remove rows and members from the edited file. If you delete a member, all lines belonging to this member must also be bulk deleted. New rows cannot be inserted because the row numbers, which are included in the displayed list, contain the relative position of these lines in the member. These line numbers will used when the lines will be back to the member written. The existing lines with the same number will be overwritten. If you do not want to write back changes in individual lines, you can of course delete these lines.

11.4.12 Edit macro #SU

Submit a JCL not containing a JOB statement.

Parameters: MSHLEVEL in the form: 0,0 / 1,0 / 2,0 / 0,1 / 1,1 / 2,1. This MSGLEVEL is in the JOB statement set.

Function description:

The program assembles the job statement using user-defined variables from ISPF profile pool.

Use the program SPROFVAR to store these variables into the ISPF profile pool.

#SU is usable at following positions:

As an edit macro.

In front of a member in a DSLIST/M display.

Special function:

EXCLUDED lines of the edited data set are NOT in the submitted job stream inserted.

Attention: Due to using the TSO SUBMIT command, all lines of the edited data set are translated to UPPER CASE during SUBMIT. This is a regular effect of SUBMIT.

Author’s remark: During my years of consultant activity, I always had all my job statements adapted to varying conditions in the data centers. To have to do this not always I developed the REXX program SPROFVAR. There, I have all the values that apply to a data center inserted as variables and stored them in the ISPF profile. When I installed the SMART ISPF utilities at a new customer, I adapted and executed only the member SPROFVAR. In all the jobs I had to run at the customer's site, I was able to leave the job statement and start jobs with #SU.

No further help available.

11.4.13 Edit macro #TSOB

Edit macro to submit a batch job, which executes the currently edited REXX procedure within a TSO batch environment. A parameter text can be to the macro call added. This text is to the executed REXX procedure transferred.

Attention: This macro does not save the source code of the edited file.

Hence, the UNDO status of the edit session is by this macro not changed.

Remark: To avoid the SAVE command, the currently edited REXX procedure is stored to a work file. The batch job will use this work file to execute the REXX procedure.

The description of the 'SUBMIT *' command in the manual TSO/E Command Reference contains the following note: The SUBMIT command converts all characters of the job stream to uppercase before the stream is submitted to the system.

Note: To avoid setting all JCL lines in uppercase by command 'SUBMIT *' and thus also the line which contains the parameter text, this procedure writes the job stream to member JOB into a work file and submits the job from this member by using the command: "SUBMIT '"workfile"(JOB)'". In this case, the lines of the members JOB will not be transferred to uppercase.

Help is available with #TSOB ?

11.4.14 Edit macro #VERASE

With this edit macro, you can delete an ISPF variable from the profile and the shared pool. At call, you can enter only one variable name.

11.4.15 Program SCURSOR

With this program you can call a file which name is somewhere in an ISPF screen. When calling a small panel appears which allows you to select the type of file processing.

Description:

If a DSN of a data set appears on any ISPF screen, you can get access to this data set by positioning the cursor within the DSN and call SCURSOR. For a comfortable use of this function, I recommend to set a PF KEY to 'TSO %SCURSOR'. If you have positioned the cursor at any position within a DSN and then push the PF key a panel appears to offer you a range of access possibilities to the data set.

There are some restrictions for displaying GDGs and VSAM data sets.

This function can be in many displays used. Some examples:

–  In an EDIT Panel

–  In a BROWSE Panel

–  In the SDSF display

–  In someone data set display

–  In a POPUP panel

See the selection panel below:

Screen 11.3: SCURSOR selection panel

11.4.16 Program SDOC

Produce documentation members.

This program reads all members of a PDS and produces the $DOC member in the same PDS.

Function:

The program scans all members of the PDS for lines with keyword DOC: as the second word in a line. Only the first 200 lines in each member will scanned. When during this scan no DOC: lines are found, then only the member name will be stored in the output. When the first DOC: line found is and there are more than five lines following the last found DOC: line without a DOC: the scan of this member ends.

11.4.17 Program SLE

Purpose:

The program starts by input of SLE in the ISPF command line. It displays an ISPF table containing names of recently edited data sets. The program displays the ISPF table $SLETAB. The EDIT initial macro #IMACRO2 updates this table with DSNs of recently edited data sets. The display panel offers the ability to perform some functions on the data sets displayed. See the help panels available in the programs screen.

Smart Last Edit offers the following functions:

Screentext 11.1: Description of SLE functionality

The following screen shows the above-mentioned input fields:

Screen 11.4: SLE working panel

Remarks: Help screens are available for all greyed fields. Position the cursor in such a field and press PF1 to display the help. The general help screen appears, when the cursor is on any other position on the screen and PF1 is pressed.

11.4.18 Data member SLOGDSN

The member SLOGDSN contains DD names and the corresponding DSNs. The logon procedure SLOGON reads this member, looks for the already existing allocations by the same DDs and assembles a new structure in which the member referred to in SLOGDSN DSNs are respectively arranged in front of the existing DSNs of each affected DD. The program SLOGON then allocates this new structure using the REUSE option. This technique ensures that the DSNs specified by the user allocates in the file SLOGDSN BEFORE the previously existing DSNs in each affected DSN chain. DDs, which are not found in the existing allocations, will be allocated additionally.

Program 11.1: Member SLOGDSN

11.4.19 Program SLOGON

This is a personal logon procedure. It works as follows:

1.  It reads all existing allocations of the TSO user and caches them all.

2.  It reads the control file SLOGDSN containing the DSNs that must allocated before the already existing DSNs. The new DSN chains are in such a way assembled that the DSNs read from the member SLOGDSN stay before the existing DSNs.

3.  When in the member SLOGDSN new DDs and their DSNs are contained that are not present in the previous allocations, these chains will added to the allocation stream.

4.  SLOGON now performs the new allocations using the new allocation stream and the TSO ALLOC option REUSE. The REUSE option replaces the old allocations.

For installing this logon procedure, see the section 11.5.2 Installation on page 204.

Note: If SLOGDSN contains DSNs of not existing data sets, a message displays during SLOGON, but the logon process continues anyway. This ensures that the logon process successfully implemented will and a working user environment created is. This is a very important advantage of the procedure SLOGON.

11.4.20 Program SPROFEDT

Execute program SPROFVAR to store users ISPF profile environment variables into ISPF Profile. This program is by ISPF command SPROFVAR called.

11.4.21 ISPF variables load member SPROFVAR

SPROFVAR defines and stores variable needed by the SMART ISPF utilities in the ISPF profile pool. Several SMART utility programs use these profile variables. The PF keys are also set.

Each user can add his own profile variables as needed!

11.4.22 Program SSC

Purpose:

This program uses a model data set to perform some functions on this data set or to create a new data set based on the model data set.

Smart Super Clone offers the following functions:

Allocate a new data set with the same or different attributes as the model data set has with optionally copying the data.

Restructure the model data set. Some attributes may be changed.

Copy the data models into another data set. The target data set must exist. During this operation, the data set attributes cannot be changed.

The source data set can be a PDS and the target data set can be sequential. In this case, the program writes the members continuously into the sequential data set. Only the following types of data sets can be with this program used: Generally data sets on DASD and Sequential, PDS, PDSE and VSAM.

Screen 11.5: SSC working screen

Remarks: Help screens are available for all greyed fields. Position the cursor in such a field and press PF1 to display the help. The general help screen appears, when the cursor is on any other position on the screen when PF1 is pressed.

11.4.23 Program SSS

Purpose:

Perform a Super-Search operation by entering SSS in front of a DSN in a DSLIST panel.

Two types of calling SSS (Smart Super Search) are available:

Enter SSS <search string> in a line in front of a DSN on a DSLIST panel. The search operation then performs with only one string. Enter the search string without quotes and it can only consist of one word.

Enter SSS in front of a DSN on a DSLIST panel. In this case, the panel SSSP1 appears. This panel allows the input of many search terms.

Screen 11.6: SSS input panel

11.5 Installation of SMART ISPF utilities

To use the smart utilities, you must install them in your TSO/ISPF system. Before you start transferring programs and panels, you need to make an important decision:

11.5.1 Download and unzip

Perform the following steps to install the SMART utilities:

1.  Download the SMART ISPF utilities ZIP file from the De Gruyter website www.degruyter.com.

2.  Unzip the file to a folder in your PC. After unzipping the following data sets are in the folder:

The two files REXX and PANELS contain all procedures and all panels of the SMART ISPF utilities in packed form. After transferring into the appropriate libraries on the z/OS/ISPF system, they must be unpacked using the REXX program SHOSTUNP. This REXX program is the only program that is usable to unpack the data sets because the packed data sets have a proprietary format.

Upload and unpack the members to z/OS host:

1.  Use the 3270 emulation software you have on your PC to upload the three members to the z/OS host into a PDS or PDS-E with RECFM=FB and LRECL=80.

2.  Then use the program SHOSTUNP to extract the packed members into the appropriate libraries. Use the Command Shell (Menu 6) of ISPF to execute the program SHOSTUNP. The following screen shows these commands:

Screen 11.7: Examples of unpack SMART ISPF utilities members

11.5.2 Installation

For the installation of the SMART utilities, multiple scenarios concerning your TSO/ISPF user environment are possible: See chapter 3 The TSO/ISPF logon process on page 29.

1. You still have an own ISPF library environment with an own logon procedure. This is the ideal case. You can copy the REXX procedures of the SMART ISPF utilities directly into your SYSEXEC or SYSPROC library and unpack them there. If you want to use a panel library for the panels, you can copy the panels to the ISPPLIB chain. Additionally, you can decide whether you want to use the SLOGON procedure of the SMART ISPF utilities together with the member SLOGDSN to make your logon process more variable and convenient.

2. You get the TSO READY prompt when you leave ISPF.

In this case, you can call the logon procedure SLOGON at the READY PROMPT using the command EX 'dsn(SLOGON)'. First, you must only adjust the member SLOGDSN so that there the correct data set names are included.

3. Your TSO user is completely logged off when you leave ISPF and you have no chance to start an own logon procedure.

In this case, you can still use the SMART utilities. However, the installation of the call environment is somewhat more complex. You can use the command ALTLIB. While there is a restriction that makes the process somewhat inconvenient: If you have performed an ALTLIB command, the calling environment thus created is always available only in the logical screen in which the ALTLIB command was executed. See the description of the ALTLIB command below.

11.5.3 ALTLIB command

Excerpt from the IBM manual TSO-E Reference concerning ALTLIB:

Use the ALTLIB command to:

–  Define alternative application-level libraries of REXX execs or CLISTs.

–  Indicate that user-, application-, and system-level libraries of REXX execs and CLISTs will searched.

–  Exclude one or more library levels (user, application, system) from being searched.

–  Reset the search order to the system level.

–  Obtain a display of the search order that is in effect.

Using ALTLIB in ISPF:

When you use ALTLIB when ISPF is active, you can define the libraries (user, application, and system) that are active for each application. Libraries that you define while running an application are in effect only while that application has control. When the application completes, the previous libraries (user, application, and system) will automatically reactivated.

If you are in split-screen mode in ISPF and you issue the ALTLIB command from a one-screen session, the changes affect only that screen session. The ALTLIB search order is not valid across split screens.

Execute the ALTLIB command in the following way:

Type in an ISPF command line:

TSO ALTLIB ACT APPLICATION(EXEC) DSNAME('dsn')

dsn is the data set where your REXX procedures reside. If you have installed the REXX procedures of SMART ISPF utilities into this dsn, the utilities are also executable.

Example:

The following screen shows the assignment of keys PF18 and PF19 for the execution of the ALTLIB command.

Screen 11.8: PF key setting to execute ALTLIB

The command ALTLIB DISPLAY shows the current ALTLIB chain. After pressing PF18 and then PF19 the following display appears:

Screen 11.9: PF key settings to use the ALTLIB command

I used DDLIST to find the DDNAME SYS00278 and found it in the following screen:

Example:

I pressed PF18 four times and then I pressed PF19. The following chain appears:

11.5.4 Make the SMART ISPF utilities ready to run

Before you can use the SMART utilities, there are still some steps necessary:

1. If you can fully use an own logon procedure, you must adapt the members SLOGON and SLOGDSN and perhaps copy the procedure SLOGON into an appropriate library. See the section 11.5.2 Installation on page 204.

2. Edit the member SPROFVAR, perform the necessary changes and execute it using the edit macro ##. This program is executable without having to load the ISPF profile variables for the SMART utilities.

The following profile variables are important to have appropriate values: