7Introduction to ISPF programming

In the preceding chapters, I you with the operation of ISPF. Likewise, I familiarized you with the programming language REXX. Now that you have the necessary knowledge in REXX programming, I will show you how to create ISPF applications.

7.1Programming languages useable in ISPF

The following programming languages can be used to create ISPF applications:

– Assembler

– REXX

– CLIST

– PL/I

– COBOL

– VS FORTRAN

– C

– PASCAL

– APL2

I marked REXX in the above table. In this book, I will only use REXX as programming language to develop ISPF applications. From the above mentioned languages, REXX is the easiest to use, the fastest and most elegant language. REXX requires the least effort to create ISPF applications.

7.27

ISPF is a dialog-oriented online system while CICS and IMS are transaction-oriented online systems in z/OS MVS. Dialogue oriented means in this context that an online program remains in memory as long as the user works in dialogue with it. This has the advantage that you as a programmer of online applications in ISPF do not have to worry about subsequent transactions, storage of data between transactions, etc. At delivery, a toolbox with all the tools needed for programming applications running in ISPF is already included. These tools are described in the following IBM brochures:

ISPF Dialog Developer's Guide and Reference

and

ISPF Services Guide

There are essentially tools for creating or editing the following items:

– Data sets

– Panels

– Messages

– Skeletons

– Tables

– Variables

We will discuss in detail all of these elements during the further course of the book. For each of the above elements I will give you below a brief introduction followed by examples for each element.

Data sets

REXX normally processes only sequential data sets. This may also involve members of a PDS. There are also functions for editing directories of PDS. VSAM and other types of data sets can be processed with special access programs. For processing DB2 tables See following URL: http://mainframe-tips-and-tricks.blogspot.de/2011/12/sample-db2-rexx-program.html and http://www-01.ibm.com/support/knowledgecenter/SSEPEK_11.0.0/com.ibm.db2z11.doc.apsg/src/tpc/db2z_codesqlstaterexx.dita

Panels

Panels are created using the ISPF editor. They consists of two parts: The first part defines the representation on the screen. The other part performs a certain plausibility check and defines for which fields help panels are available.

Messages

ISPF provides a very simple and user-friendly way to define messages and output them as required. The messages can be outputted from programs and from panels.

Skeletons

Skeletons define a mask for creating data sets, where the variables which are defined in the skeletons will be replaced automatically by the contents of the variables of the same name in the REXX procedure. Skeletons are mostly used for creating JCL lines. The ISPF editor is used to generate skeletons. When a REXX program calls a skeleton, then all variables in the skeleton are replaced by the values that are defined in the REXX program with the same name.

Tables

Tables are by programs created and edited using appropriate ISPF functions. Tables consists of a special ISPF data type. They can only be stored as members in special ISPF table datasets of type PDS. Since they are interspersed with ISPF control data, their content can be viewed with edit and browse.

Variables

Variables play a major role in ISPF. ISPF itself contains a large amount of variables that can be used in some ISPF elements such as panels, messages and programs. ISPF differentiates between system variables, normally starting with Z and user variables that can be anything called. The name must not be longer than eight characters. A table of system variables is found in Appendix D of the IBM manual ISPF Dialog Developer's Guide and Reference found.

Conclusion

Now having introduced you to the theoretical programming elements, I want to look at some examples from my practice. The examples are purposely from practice, because I do not want to bore you with simple things. I ask for your understanding that I cannot explain the commands and procedures for each example in detail as this go too far. All the different elements in the examples are anyway discussed in more detail later in the book.

7.37

7.3.1Example for use of ISPF panels

The program SSS belongs to the SMART ISPF utilities. It is called in front of the name of a data set to perform a SUPER SEARCH in a DSLIST panel. The panel SSSP1 shown below is used by the REXX procedure SSS to read in the text to be searched for.

Program 7.1: Panel definition of panel SSSpl

The variables SSP1 to SSp14 that contain the search texts are written into the ISPF profile and are again read before the panel is recalled. Therefore, I do not have to reenter the search text on every call to SSS. Reading and writing of the variables using VGET and VPUT could also be performed in the panel, but I decided to do this in the SSS procedure. Here is the excerpt from the REXX procedure SSS which calls the panel SSSP1:

7.3.2Example for use of skeletons

Skeletons are mostly used to assemble extensive job streams. For such an application, I have taken the following example.

Function:

In a large job step must be commands inserted which perform BIND PACKAGE for DB2. Since this job must be created for different LPARs, all values that relate to the individual LPARs are kept variable.

Here first the skeleton member. The variables in skeletons always begin with an ampersand (&) character. The association of variables with text or other variables will done by a period (.). Since points must separate the individual qualifiers of DSNs, you will have to use two points when creating DSNs by linking variables in skeletons.

JCL 7.3: Skeleton VINTPAC

In the following part of the program variables are defined that are needed in the skeleton VINTPAC to produce the job step. When the statement ISPEXEC FTINCL VINTPAC is executed, the skeleton variables are replaced by the actual values.

Here is the created step in which the variables with real values have been replaced:

JCL 7.4: Job step build by skeleton VINTPAC

This is a complex example from practice. Try to understand the process. All important places are grayed out. We will deal in a later chapter in detail concerning the use of skeletons.

7.3.3Example for use of tables

ISPF tables are data objects that are normally processed within programs using ISPF. ISPF tables can be viewed and manipulated directly using the ISPF option 7.4. This tool is actually only useful for testing purposes.

Example:

As an example, I want to take the table that is used in the program SLE of the SMART ISPF utilities. It contains the names of the recently edited data sets, along with other information such as date and time of use. First, here is the program section of the edit macro #IMACRO2 that is called when an edit session ends. Here, the Table $SLETAB is opened and the DSN of recently edited data set is inserted in the table. When a member of a PDS was edited the member name will be inserted in the DSN. If the table does not exist, it is created and written after processing into the ISPF library ISPPROF. The following part of the program SLE shows the insertion of a DSN in the table $SLETAB.

Screentext 7.1: Program part from SLE – Insert a DSN into table $SLETAB

Here is the part in the program SLE which displays the panel SLEP1 containing the contents of table $SLETAB.

Moreover, here the panel:

Screen 7.1: Panel SLEP1 displayed by the program SLE

When I put the cursor in front of a DSN positioned in this display, I can enter selections for edit, view, browse etc. This panel appears again at the end of each action and I can make a new selection. A detailed description of the application is in section 12.5 Example of working with tables on page 218.

7.3.4Example for use of ISPF variables

There are two types of ISPF variables:

– System variables

– User variables

System variables are, as its name implies, created and managed by ISPF. You can use them in all ISPF functions. In some, you can change the content. See ZEDLMSG above. Some system variables are assigned to specific ISPF services. Since I have used in the shown examples so far some variables of both types, I will refrain from further examples. However, I want to show you how you can view the currently defined variables and their contents in your ISPF. To do this, I proceed as follows: I choose the ISPF option 7.3 and get the following panel, which is showed shortened below:

Screen 7.2: ISPF variables display using ISPF menu 7.3

If permitted by ISPF, you can change the contents of variables, delete them entirely or create new variables in this panel. I grayed some of the Z-variable. These contain values that are often needed in daily operations. To get the contents of ISPF variables, read them using the command:

"ISPEXEC VGET (ZDATESTD ZACCTNUM ZAPPLID ZDAY ZDAYOFWK ZJDATE ZJ4DATE", "ZDATE ZDATEF ZTIME ZTIMEL)"

7.3.5Example for data processing with TSO and ISPF

For the processing of data sets, you have two options in an ISPF environment and in the use of the language REXX:

– Use the REXX command EXECIO that only needs the support of TSO.

– Use ISPF data set management services. Then you additionally need ISPF data set services.

This distinction is important because it decides whether the procedure to perform I/O operations requires only the TSO level or additionally the ISPF level. This definition is particularly important too, when the intention is to use the procedure in batch jobs. The ISPF environment is in the first case not required but always in the second. This is important for preparation of the batch jobs, as we can see in the chapter 6 Execute REXX programs on page 105.

Example of data set processing with TSO and ISPF:

To explain the difference between I/O operations using the TSO command EXECIO and the ISPF LM services I wrote two programs, which each perform the same work. They read a flight log and summarize the number of flights conducted and hours of flight time for each aircraft type found in the records. Here the source code of both programs:

Program 7.2: IOEXMPL1 – Read records using EXECIO of TSO

Program 7.3: IOEXMPL2 – Read records using LM services of ISPF

These both programs produce exactly the same result. I have grayed the statements used for each I/O method. It is obvious that the method with EXECIO by far requires the lower programming costs. The actually necessary error query and error analysis after each ISPF command has been deliberately omitted to improve clarity of the code.

7.3.6Output of messages with ISPF

For the issuance of messages in the ISPF, a standard procedure is available. In its use, ISPF system variables will be filled with contents. A standard ISPF service dis- plays these special variables on the screen. This service is only usable for outputting messages online on a screen. It is not usable to print the messages in a batch job. If a REXX procedure shall be run online as well as in batch the output of messages must be controlled accordingly. See section 9.1.2 Output of error messages on page 178. The following excerpt from the Appendix D Dialog variables of the IBM manual ISPF Dialog Developer's Guide and Reference shows the ISPF system variables concerning error messages:

Table 7.1: ISPF system variables concerning error messages

Variable	Length	Description
ZERRALRM	Char 3	The value is set to YES if an alarm was specified in the message definition otherwise, the value NO. Set when ISPF services issue a return code of 8 or greater.
ZERRHM	Char 8	The name of a Help panel, if one was specified in the message definition. Set when ISPF services issue a return code of 8 or greater.
ZERRLM	Char 512	Long-message text in which variables have been resolved. Set when ISPF services issue a return code of 8 or greater.
ZERRMSG	Char 8	Message ID. Set when ISPF services issue a return code of 8 or greater.
ZERRSM	Char 24	Short-message text in which variables have been resolved. Set when ISPF services issue a return code of 8 or greater.

How messages are displayed?

ISPF offers a standard method to display messages when a program runs online. These messages are displayed on the ISPF screen. The ISPF service SETMSG is used to display the messages. The SETMSG service expects the error messages in the two special variables:

ZEDSMSG

ZEDLMSG

S and L stand for SHORT and LONG. This means that you can put a message up to 24 characters in ZEDSMSG and in ZEDLMSG a long message up to 512 characters. See Screentext 7.1: Program part from SLE – Insert a DSN into table $SLETAB on page 115.

The ISPF service SETMSG writes the error message texts contained in ZEDSMSG and ZEDLMSG on the currently displayed screen. However, the following rules are to be considered:

– If the variable ZEDSMSG contains a text, then initially only this text is displayed on the right top corner of the screen and nothing else happens. First, when the user presses PF1, then the related ZEDLMSG message will also be displayed on the bottom of the screen.

– If the variable ZEDSMSG contains nothing, only the ZEDLMSG message is immediately displayed on the bottom of the screen.

Example:

Program example:

The following program shows two typical applications of the ISPF message services:

– In the first use of the service are the names of data sets, which have an ENQ reservation displayed. The function QUERYENQ detects such ENQs. These are the statements 202 to 212.

– The second application displays an error message when a data set should be edited for which the editor is unable to edit.

Screentext 7.2: Example of the ISPF messages service

There are two possible messages displayed:

1. An attempt was made to edit an ENQUED data set.

2. This error message is self-explanatory.

7.4LIBDEF – Dynamic linking of ISPF libraries

We have already discussed the ISPF libraries earlier in this book. And we have also seen that some library chains must be assigned before ISPF starts. However, if you want to run an application of ISPF objects stored in own ISPF libraries; you have to copy all these objects in the appropriate permanently assigned libraries. As this would be very costly and impractical, ISPF contains a command to allocate additional libraries dynamically before the existing permanently allocated libraries. This is the LIBDEF service.

Function:

Allocate additional data sets to the existing ISPF libraries dynamically and remove such assignments again.

With these options, you can define how the LIBDEF chains shall be arranged.

Program 7.4: LIBDEF example

Use the ISPF command ISPLIBD to display the current LIBDEF assignment. See the following screen. It shows the currently assigned LIBDEFs within this logical ISPF screen.

Screen 7.3: ISPLIBD – Display the current active LIBDEF assignment

7.5ALTLIB – Dynamic linking of EXEC libraries

With LIBDEF, only ISPF libraries can be set before the default associated libraries. However, when a REXX program executes, the system searches for the program only in the libraries that are allocated under SYSEXEC or SYSPROC. With the ALTLIB command other data sets can dynamically be assigned before the SYSEXEC and SYSPROC libraries. The ALTLIB command has to be executed as a TSO command. As we will see below, the ALTLIB command works slightly different in an ISPF environment as in a pure TSO environment.

The ALTLIB command can achieve the following:

– Define alternative libraries for procedures calls.

– Define the user, application and system-level libraries that are used for searching programs.

– Exclude one or more libraries level from the search.

– Reset the search order to the system level.

– View the current search order.

Normally, the TSO is set so that when a procedure is called, then the SYSEXEC library is first searched and afterwards the program is searched in the SYSPROC library. This is of course only valid if both library types are assigned.

The command TSO ALTLIB DISPLAY displays the current ALTLIB setting:

Example:

Current search order (by DDNAME) is:

System-level EXE CDDNAME=SYSEXEC

System-level CLIST DDNAME=SYSPROC

7.5.1Search sequence in the procedures libraries

The following table shows the search order for procedures libraries. The corresponding DD names will also displayed. These DD names can either be created dynamically with the ALLOCATE command or have been created even by the login procedure.

Table 7.2: Search sequence in the procedures libraries

Example 1:

Temporary activation of a library for executing a REXX procedure from that data set.

"ALTLIB ACTIVATE APPLICATION(EXEC) DDNAME(##DD)"

"ISPEXEC SELECT CMD(%"mem strip(pp)")"

"ALTLIB RESET"

Here is the data set that is already allocated under the DD name ##DD, provided for the call of the procedure named in the SELECT statement.

Example 2:

Disable the CLIST system level.

TSO ALTLIB DEACTIVATE SYSTEM(CLIST)

When I now execute the command TSO ALTLIB DISPLAY, the following display occurs:

Current search order (by DDNAME) is: System-level EXECDDNAME=SYSEXEC

This means that procedures in the SYSPROC allocation will not be found regardless whether the allocation exists or not.

Example 3:

I have written a small REXX procedure that executes some ALTLIB commands.

Program 7.5: ALTLIB1: Example of the application of the command ALTLIB

When the procedure executes, the following display appears:

7.5.2The ALTLIB command in ISPF

As long as ALTLIB commands are used only under TSO, the once by ALTLIB set search sequences remain active until they are changed with another ALTLIB command. On the other hand, when the ALTLIB command is called under the ISPF environment, this rule changes as follows:

Rules when ALTLIB is used in the ISPF environment:

– If you use ALTLIB while ISPF is active, you can issue this command on the application level. Libraries that are allocated by a running application remain active as long as this application is running. When the application ends, the state is the same as before calling the application.

– When an application is started in the ISPF split screen mode which settles ALTLIB commands, then their defined search order applies only to this split screen panel.

– Libraries that are allocated at the start of an application in the ISPF will not be deactivated by the NEWAPPL and PASSLIB parameters in the SELECT command.

– If an application is launched while NEWAPPL is specified, but not PASSLIB, you will not have all LIBDEF and ALTLIB pre-allocated libraries in this application available. They are only available again when this application ends.

– If an application is started using NEWAPPL and PASSLIB, then all library allocations previously created with LIBDEF and ALTLIB remain active. However, LIBDEF and ALTLIB allocations that are made in this application are only active as long as the application is running.

– If neither NEWAPPL nor PASSLIB are specified when starting an application, then all previously with LIBDEF and ALTLIB created allocations are active in this application. Any changes made using LIBDEF and ALTLIB in this application remain active even after the end of the application.

– ALTLIB allocations that were made before starting of ISPF are unknown after the call to ISPF.

7.5.3Stacking of the APPLICATION level ALTLIBs

If multiple ALTLIB commands are issued on the APPLICATION level within an ap- plication, they will be stacked up to a depth of eight levels. This stacking takes place so that always the last created allocation is at the top.

Example: stacking APPLICATION Level ALTLIBs.

Program 7.6: Stacking ALTLIB commands

Here is the output that generates the above procedure:

As you can see, only the DD names of allocated data sets are displayed. If you want to see the associated DSNs, you can view them using the ISPF command DDLIST.

7.5.4The QUIET operand of the ALTLIB DISPLAY command

If you use the ALTLIB DISPLAY command in ISPF, you can specify the QUIET option. This option ensures that the ALTLIB DISPLAY command output information will not be outputted via SYSTSPRT but rather written in ISPF variables in the SHARED pool. You can then use these ISPF variables to use the information contained therein in the program.

The following ISPF variables will be filled:

– IKJADM contains the number of rows that were written in ISPF variables.

– The variables IKJADM1 to IKJADM99 contain the individual lines. The following example shows how you can use these service in a program:

Program 7.7: ALTLIB3 – Using of ALTLIB DISPLAY QUIET command

I ran the program. It produces the following output: