15The SMART ISPF utilities
Since the early 1980ies, I have been working with ISPF. Over the time, I often missed some practical functions in ISPF. In the early 1980ies, no internet was available. Therefore, it was very difficult to find appropriate functions to fulfil my needs. In this situation, 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.
15.1Naming conventions
All programs are written in REXX language. 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).
15.2The 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 ISPF 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 is made to load the panels:
To decide whether the panels are to be loaded dynamically, the variable DYNPAN from the ISPF profile will be 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 ISPF utilities, you must edit the program SPROFVAR, the values contained therein, customize them and run the edit macro ##. This edit macro is executable without having to load the ISPF profile variables for the SMART ISPF utilities. See the following excerpt from program SPROFVAR:
See also the description of the installation process on page 286.
15.3List of executable programs
The following table shows all programs and their functions:
Table 15.1: List of the SMART ISPF utilities programs
15.4Program descriptions
This chapter contains individual descriptions of the programs of SMART ISPF utilities. Most programs include extensive help descriptions displayable using the PF1 key. When calling up some programs, a question mark can be entered as parameter. 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.
15.4.1Edit macro ## – Execute a currently edited REXX procedure
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 ISPF utilities. Help display with ## ?
15.4.2Edit macro #ALTXT – Realign line parts
Edit macro to realign line parts within given columns. Help display with #ALTXT ?
15.4.3Edit macro #EDMEM – Edit of a member
Edit of a member which name is the first word in a line of a data set currently being edited.
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 occurs as first word. No further help available.
Note:
For an optimal use of this macro, its call should be set on a PF key. E.g. PF22.
15.4.4Edit macro #IMACROA – General ISPF edit macro
General ISPF edit macro. Whenever you start an edit session, this macro will execute, regardless of whether an initial macro is defined for this data set 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 following panel:
No further help available.
Screen 15.1: Set activation of #IMACROA
15.4.5Edit macro #IMACRO1 – Initial edit macro
Initial macro to insert DOC: lines into edited members of partitioned data sets (PDS).
When starting an edit session of a PDS member and no DOC lines are found in the edited member within the first 20 lines, this macro then displays a panel that offers the opportunity to insert DOC lines at the beginning of the member currently being edited.
Help can be displayed via PF1 when the panel IMACRO11 appears. The following screen shows an example for inserting DOC and REM lines into a member.
Screen 15.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. The following screen shows the resulting contents of the new member after ENTER is pressed:
15.4.6Edit macro #IMACRO2 – Edit session end macro
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.
15.4.7Edit macro #ISPFB – Submit an ISPF batch job
Edit macro to submit a batch job to execute the REXX procedure currently being edited within an ISPF environment. When the macro is called, a parameter text can be added in the call statement. This text is as a parameter transferred to the executed REXX procedure. Help display with #ISPFB ?
15.4.8Edit macro #LCH – Perform long edit change commands
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...
15.4.9Edit macro #SPLJ – SPLIT and JOIN lines
This macro performs SPLIT and JOIN operations within an edit session.
Functional description:
When this macro is called, 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 are moved 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.
15.4.10Edit macro #SSS – Clear SCHFOR lists
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.
15.4.11Edit macro #SSSCH – Mass update of members
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 be used, when a super search list is displayed in edit session, to restore the displayed lines back into the members in which the searched lines were found. There is no other help available.
Remarks:
You can remove rows and members from the data set currently being edited. If you delete a member, all lines belonging to this member must also be deleted bulky. 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 be used when the lines are written back to the member. 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 before calling #SSSCH.
15.4.12Edit macro #SU – Submit JCL without a JOB statement
Submit a JCL that does not contain a JOB statement. Parameters: MSGLEVEL 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 the 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 inserted in the submitted job stream.
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 not always do this, 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.
15.4.13Edit macro #TSOB – Submit a TSO batch job
Edit macro to submit a batch job which executes the REXX procedure currently being edited within a TSO batch environment. A parameter text can be added to the macro call. This text is transferred to the executed REXX procedure.
Attention:
This macro does not save the source code of the data set currently being edited. Hence, the UNDO status of the edit session is not changed by this macro.
Remarks:
To avoid the SAVE command, the currently edited REXX procedure is stored to a work data set. The batch job will use this work data set 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.
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 data set and submits the job from this member by using the command: "SUBMIT '"workfile"(JOB)'". In this case, the lines of the member JOB will not be transferred to uppercase.
Help is available with #TSOB ?
15.4.14Edit macro #VERASE – Erase ISPF profile variables
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.
15.4.15Program SCURSOR – Calling a data set from an ISPF screen
With this program you can call a data set 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 program a PF KEY with TSO %SCURSOR. If you have positioned the cursor at any position within a DSN and then pushed the PF key a panel appears to offer a range of access possibilities to the data set. There are some restrictions for displaying GDGs and VSAM data sets.
This function can be used in many displays. Some examples:
–In an EDIT panel
–In a BROWSE panel
–In the SDSF display
–In a data set display
–In a POPUP panel
See the selection panel below:
Screen 15.3: SCURSOR selection panel
15.4.16Program 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 be 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 is found and there are more than five lines following the last found DOC: line without a DOC: the scan of this member ends.
15.4.17Program SLE – Display last edited data sets
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 15.1: Description of SLE functionality
The following screen shows the above-mentioned input fields:
Screen 15.4: SLE working panel
Remark:
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.
Tip:
Insert the following command in the ISPF command table to call the last edit function very fast when you type in SL in the ISPF command line.
_ SLE 2 SELECT CMD(%SLE)
REXX SLE CALL THE LAST EDIT FUNCTION
15.4.18SLOGDSN – Data member containing DSNs for logon
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 members 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 member SLOGDSN BEFORE the previously existing DSNs in each affected DSN chain. DDs that are not found in the existing allocations will additionally allocated.
Program 15.1: Member SLOGDSN
15.4.19Program SLOGON – Personal logon procedure
This is a personal logon procedure. It works as follows:
1.It reads all existing allocations of the TSO user and caches them.
2.It reads the control member SLOGDSN containing the DSNs that must allocated before the already existing DSNs. The new DSN chains are assembled in such a way 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 be 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 section 15.6.2 Installation on page 286.
Note:
If SLOGDSN contains DSNs of not existing data sets, a warning message is displayed during SLOGON, but the logon process continues anyway. This ensures that the logon process is successfully performed and a working user environment is created. This is a very important advantage of the procedure SLOGON.
15.4.20Program SPROFEDT – Store users ISPF profile variables
Execute program SPROFVAR to store users ISPF profile environment variables into ISPF Profile. This program is called by ISPF command SPROFVAR.
15.4.21SPROFVAR – Load user ISPF variables
SPROFVAR defines and stores variables 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!
15.4.22Program SSC – Super clone for data sets 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 model data set 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 continuously writes the members into the sequential data set.
–Only the following data set types can be processed with this program: Generally data sets on DASD and Sequential, PDS, PDSE and VSAM.
Note:
A sequential data set cannot be copied into a PDS member.
Screen 15.5: SSC working screen
Remark:
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.
15.4.23 Program SSS – Perform a Super-Search
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 15.6: SSS input panel
Remarks:
–The program SSS calls the ISPF standard super search utility ISRSUPC to perform the search.
–The standard ISPF help facility for super search appears when PF1 is pressed on the SSS screen.
–SSS saves the entered search parameters in lines 1 to 10 automatically in the ISPF profile and redisplays them at the next call of SSS.
–The edit macro #SSS removes unnecessary output contents from the standard output list of the search before the list appears on the screen. The macro #SSS is indicated as initial macro when the editor is invoked for displaying the search results.
SSS special update function:
SSS stores the optimized search results into a temporary data set and then displays this data set in the editor. This data set can be edited by using the normal editor functions. If individual lines of the data set are changed, these changes can restored into the individual members using the edit macro #SSSCH. See description of #SSSCH on page 264. This is one of the most important advantages of the program SSS.
15.5Programming aids
This chapter includes program elements which are intended for programmers who develop programs using the REXX language. The following table shows these edit macros, programs and subroutines, which are contained in the programming aid package.
Table 15.2: Programming aids Program Function
| Program | Function | |
| #C | This edit macro compiles the REXX program currently being edited and executes the compiled program immediately after the compile. One parameter can be added in the #c call statement. This parameter string will be passed to the compiled program to be used at execution time. To get an online tutorial description enter: #c ? | |
| #RO | Online compile of the REXX program currently being edited. This procedure can be called as an edit macro or in front of a member name in a DSLIST/M display panel. Parms: When #RO is used as a macro additional compiler options may be passed as parameters. | |
| #RC | Use this procedure to assemble and submit a batch job to compile a REXX procedure. | |
| #RCLOAD | Assembly and SUBMIT a job to compile a REXX procedure and generate a LOAD module or a CALL module. | |
| #IE | Edit macro to insert in an application program the call lines to the internal ISPF_ERROR subroutine. The inserted statements calls the ISPF error handling subroutine ISPF_ERROR in case an error appears. See the next row in this table. | |
| ISPFERR | ISPF error handling routine This subroutine is called when a call to an ISPF service function ends with an error. | |
| #PAN | The screen whose program code is currently being edited will be displayed immediately. | |
| DAYDIFF | Calculates the number of days between two DATE values. DATE values are entered in the form dd.mm.yyyy. | |
| ENDDAY | Calculates the target date for a period of days starting at a given date plus or minus a number of days. | |
| JULDATE | This subroutine calculates for a standard date the JULDATE or vise versa. | |
| LEAPYEAR | Calculates whether the entered year is a leap year or not. This function returns a 1 if the entered year is a leap year, otherwise it returns 0. Caution: No plausibility checking of the entered year parameter is performed. | |
| SCHANGE | This REXX subroutine performs changes in any strings. See section 4.6.3 SCHANGE – Change of texts on page 86. | |
| SDYNPAN | This program converts the source code of an ISPF panel so that the code can be embedded in a REXX procedure to be dynamically loaded from there into a temporary ISPPLIB for execution. |
15.5.1Edit macro #C – Compile and execute a REXX program
If the REXX compiler is available in your installation of z/OS systems, you can use this macro to compile your REXX programs very easily.
Program description:
Edit macro #c:
Edit macro to compile and execute the REXX procedure currently being edited. After the characters #c you can enter a string, which will be passed as parameter to the program for execution.
Examples:
Attention:
The entered parameter string MUST NOT contain the ISPF delimiter character. This character is used for ISPF command stacking and your parameter will possibly be truncated at the delimiter character position.
The ISPF delimiter character can be found in ISPF menu 0 in the line Command delimiter.
Processing flow:
The REXX program currently being edited is written to a work data set. This data set is used for input to the REXXCOMP program. If compilation is successful, the CEXEC module is written to the online work data set with DDNAME ##DD. If the ##DD data set is not allocated, it will be allocated. If the compilation ends with a RC > 0, the compiler listing is immediately browsed. The compiled program will be executed using the ISPF SELECT CMD service.
Remark:
Because the REXX program currently being edited is not stored to its data set for the purpose of compilation, the UNDO command can still be used.
15.5.2Edit macro #RO – Online compile of a REXX program
This procedure can be called as an edit macro or in front of a member name in a DSLIST/M display panel. If called as an edit macro the following rules exist.
1.The source code currently being edited is stored into a temporary data set and the compiler uses this data set as SYSIN file. When using this technique, the editors save command will not be performed and the change status of the edited file remains unchanged. Hence, the UNDO command can still be used in the editor.
2.After #RO the user can add some additional parameters which will be transferred to REXX compiler as compiler options.
3.If the REXX source code contains TRACE statements, the compiler produces no XREF listing and the compilers output list will be written to a data set.
If called in front of a member name in a DSLIST/M display:
1.The compiler reads the REXX source from this member.
2.No additional compiler options may be set. This is bacause at this point parameters cannot be added to the procedure call statement.
3.If the REXX source code contains TRACE statements, NO CEXEC output is produced and the compile ends with an error.
The name of the output data set for the CEXEC code is set up as follows: The last qualifier of the input DSN is substituted by CEXEC
Example: Input DSN→ LANZ.LOGON.REXX
Output DSN→ LANZ.LOGON.CEXEC
15.5.3Edit macro #RC – Compile a REXX procedure with a batch job
Functional description:
Use this procedure to assemble and submit a batch job to compile a REXX procedure. This procedure can be called as follows:
1.As an edit macro. In this case will the currently being edited REXX procedure be saved and the batch job to compile the REXX procedure will submitted.
2.In a DSLIST/M in front of a REXX procedure member.
3.In a DSLIST/M display in the command line to compile all or a selected number of members, e.g.: sei ab* #rc --> all members which names are beginning with characters ab are compiled. At this type of call no NOTIFY=userid() parameter is inserted into the JOB statement.
The name of the output data set for the CEXEC code is set up as follows: The last qualifier of the input DSN is substituted by CEXEC
Example: Input DSN→ LANZ.LOGON.REXX
Output DSN→ LANZ.LOGON.CEXEC
15.5.4Edit macro #RCLOAD – Produce a load or a call module
Assembly and SUBMIT a job to compile a REXX procedure and generate a load module or a CALL module. This procedure can only be called as edit macro. Parms: none
Attention:
There are two things necessary in order to use this macro:
1.The REXX compiler REXXCOMP must be available in your system. You can check this using the DDLIST utility.
2.The REXXCL jcl procedure must be available in your system. Ask your system programming department where it is.
Two different types of load modules can be generated:
1.A load module that can be executed in a batch job using the EXEC PGM=name statement. This type is called EXEC type. In this case the following comment line must be found in the source code: /* STUB: MVS */
2.A load module which was added to a Function Package Lib needs to be called with a CALL command. (CALL type). In this case the following comment line must be found in the source code: /* STUB: EFPL */
After generating the load module of this call type, it has to be implemented in a Function Package. See the corresponding manual TSO/E REXX Reference.
If you try to execute such a program directly, then the CALL ends with a return code 0C4. This means the program ends with a hard crash.
Link library:
If STUB: MVS is set, a file in the source code needs to be defined to where the load module is to be written. This load library is named by a comment line in the source code which is structured as follows:
/* LNK: DSN of the load library */
Example:
/* LNK: PEVX.LANZ.LOAD*/
If no such row is found, then NO compile is performed.
15.5.5Edit macro #IE – Insert a call to ISPF_ERROR
Preface:
I have been looking for a method a long time to report errors when executing ISPF services elegantly and detailed. I think I have now found this method. This method consists of two parts which must be inserted into each program:
First part of error handling:
After each call to an ISPF service function, the return code RC will be checked. If this code signals an error, the error handling subroutine ISPF_ERROR will be called. The parameters in this call statement contain all information to report the error in detail.
After each call to an ISPF service, the following five lines of code are inserted:
The five lines must be manually inserted in the source code of a program as follows:
1.Enter #IE in the ISPF command line or program a PF key with #IE.
2.Move the cursor to the line containing the call to an ISPF service.
3.Press enter or the appropriate PF key which contains the command #IE. The above mentioned five lines will be inserted immediately behind the ISPF command line.
Description of the lines:
Lines 1 and 5 contain comments and are self-explanatory.
| Line | Explanation |
| 2 | The RC returned by the ISPF service is passed as first parameter. Depending on the RC that was returned by the ISPF service, a call will be executed to the error handling subroutine ISPF_ERROR. |
| 3 | This line is passed as the second parameter to the subroutine ISPF_ERROR. It contains the original ISPF command line without the variables contained in the command line being resolved. This text is used by the subroutine ISPF_ERROR to find the original command line in the source code of the program by using the REXX command SOURCELINE(). |
| 4 | This line is passed to ISPF_ERROR as third parameter. It contains the original ISPF command line with the variables contained in the command line being resolved. |
These three parameters are used by the subroutine ISPF_ERRROR to print a comprehensive error report.
Second part of error handling:
Insert the source code of the subroutine ISPF_ERROR manually into each program that contains calls to ISPF_ERROR. This is necessary because an externally called subroutine does not know the source code of the calling program. Therefore, the command SOURCELINE is not applicable to determine the line number of the line in the source code at which the error occurs.
Note:
In large programs, it can happen that a certain ISPF command line at several points occurs with the same content. In such a case, it is important to know the number of the program line in which the error occurred.
Example:
When using this method, errors in executing ISPF services are displayed as follows:
I replaced in the above example the contents of the variable DATASET by the text faked DSN to manually enforce the error. The statement where the error occurs is in line number 284 in the source code of the program.
15.5.6Subroutine ISPF_ERROR – Display ISPF error messages
I described above how the call to the subroutine ISPF_ERROR is performed. To complete the method, here is the source code of the subroutine ISPF_ERROR:
Program 15.2: ISPF_ERROR subroutine
15.5.7Edit macro #PAN – Execute a panel source code
When developing ISPF panels it is very tedious to test this using the ISPF menu 7.2. Therefore, I wrote the macro #PAN to test a panel which source code is currently being edited. Please read the comment lines at the beginning of the source code. It will describe how to use the macro.
Program 15.3: Edit macro #PAN to test macros directly
15.5.8Subroutine DAYDIFF – Calculate number of days
Please see the source code to recognize the function of this subroutine.
Program 15.4: Subroutine DAYDIFF
The following call to DAYDIFF returns 365:
say daydiff(15.05.2015 15.05.2014)
15.5.9Subroutine ENDDAY – Calculate a target date
Please see the source code to recognize the function of this subroutine.
Program 15.5: Subroutine ENDDAY
15.5.10Subroutine JULDATE – Translate a date to Julian and vise versa
Please see the source code to recognize the function of this subroutine.
Program 15.6: Subroutine JULDATE
15.5.11Subroutine Return – LEAPYEAR the leap year information
Please see the source code to recognize the function of this subroutine.
Program 15.7: REXX function LEAPYEAR
15.5.12REXX subroutine SCHANGE – REXX change function
Please see the source code to recognize the function of this subroutine.
Program 15.8: REXX subroutine SCHANGE
15.5.13Program SDYNPAN – Convert a panel source code
To save space, I will refrain from the expressions of the entire source code. The comment lines at the beginning of the program include a detailed description of the function. The source code of SDYNPAN is very long. Therefore, only the functional description of the program is inserted below.
Program 15.9: Program SDYNPAN
Remark:
I used this program to convert all panels of the SMART ISPF utilities to load them dynamically when a program is started, which contains panels.
15.6Installation 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:
Note:
The REXX procedures of the SMART ISPF utilities contain all required panel definitions in their source code. Therefore, you do not have to transfer the panels to your ISPPLIB. The installation program SPROFVAR that stores the ISPF environment variables in the ISPF PROFILE POOL, contains the variable dynpan. If you set dynpan to YES before you execute SPROFVAR, then the REXX procedures uses imbedded panels when executed.
15.6.1Download and unzip
Perform the following steps to install the SMART ISPF utilities:
1.Download the SMART ISPF utilities ZIP file from the DeGruyter website www.degruyter.com.
2.Unzip the file to a folder in your PC. After unzipping, the following data sets are in the folder:
| REXX | The REXX program package. |
| PANELS | The ISPF panel package. |
| SHOSTUNP | REXX program to unpack REXX programs and ISPF PANELS into their libraries on z/OS host. |
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/ 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 15.7: Examples of unpacking SMART ISPF utilities members
Note:
The last three lines in the above panel show the commands automatically executed under TSO while the upload was running.
15.6.2Installation
For the installation of the SMART ISPF utilities, multiple scenarios concerning your TSO/ISPF user environment are possible:
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 ISPF utilities. However, 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 only available in the logical screen in which the ALTLIB command was executed. See the description of the ALTLIB command below.
15.6.3ALTLIB 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 be 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 using 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 be 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.
To execute the ALTLIB command, enter the following command 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.
Recommendation:
Program a PF key with this ALTLIB call. When you open a new logical screen in ISPF, then you can execute the command immediately by pressing the PF key.
Example:
The following screen shows the assignment of keys PF18 and PF19 for execution of the ALTLIB command.
Screen 15.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:
I used DDLIST to find the DDNAME SYS00278 and found it in the following screen:
Remarks concerning the ALTLIB command:
–ALTLIB commands can occur in a stacked manner.
–Only the procedures of the first level in a chain of stacked ALTLIB chains are reachable.
–Use the command altlib deact application(exec) to remove the top level of the chain.
Example:
I pressed PF18 four times and then I pressed PF19. The following chain appears:
Note:
The command ALTLIB DISPLAY shows in opposition to the command ISPLIBD only the DD names of the allocated data sets. If you want to see the corresponding DSNs, you can view them with the utility DDLIST as shown below.
15.6.4Make the SMART ISPF utilities ready to run
Before you can use the SMART ISPF 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 section 15.6.2 Installation on page 286.
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 ISPF utilities.
The following profile variables are important to have appropriate values:
Conclusion:
After having performed all mentioned steps above, the SMART ISPF utilities should work fine and I wish you much success with it.