3 The TSO/ISPF logon process
Before we can work with ISPF on our z/OS, we have to run through some steps:
1. We call the 3270 emulation software on our PC.
2. The 3270 emulation software connects to a Mainframe Session Manager.
3. The session manager offers some systems to which we have access.
4. We select a path to a TSO on that z/OS we want to logon.
5. The TSO start handler assembles the start job for our TSO user and submits it. The name of the start job is the TSO user ID. The JCL EXEC statement contains the name of the started task of the LOGON procedure. JES2 finds the task in one of the SYSPROC chains.
6. JES2 starts the logon job. The TSO processor IKJEFT01 is loaded.
7. TSO processes the logon procedure.
8. The logon procedure starts ISPF.
Steps 1 to 4 may differ from installation to installation in a z/OS computing center. However, steps 5 to 8 are always the same. The most elegant way to come into an ISPF on a z/OS operating system is the Host on Demand (HOD) system offered by IBM.
The ISPF logon procedures differ from company to company. I describe here only the general steps. The most important element of an ISPF logon process is the logon procedure:
3.1 The logon procedure
The system programmers department designs and installs the start process of TSO/ISPF. An important element within this process is the logon procedure. It starts automatically when a user logs on.
The LOGON procedure…
– uses programs developed in CLIST or REXX language.
– allocates all necessary basic data sets to run ISPF and those for all subsystems that can run under ISPF’s control (SDSF, GDDM and others).
– calls ISPF
Your own LOGON procedure:
In the most z/OS computing centers is it possible to use an own by the user developed logon procedure. To do this the user must be able to develop programs in REXX or CLIST. Volume 2 ISPF Application Programmer's Guide explains this technique in detail.
When ISPF ends, the logon procedure continues with the statements following the ISPF start statement. Two things can happen:
– The logon procedure performs a TSO LOGOFF command. In this case, the user falls back to the session manager.
– The logon procedure ends without a TSO LOGOFF command. In this case the TSO READY PROMPT appears and the user gets the chance to call an own logon procedure or enter some other TSO commands. See the following examples.
Example 1: Call an own LOGON procedure:
The LOGON procedure has ended without a TSO LOGOFF. Therefore, the user is able to call his own LOGON procedure.
Example 2: Logon to another TSO user ID:
The current TSO user is left and a LOGON to user2 starts: (of course, the same user may repeat its logon here)
When a user enters a LOGON command like this, the standard TSO logon panel appears and the user has to enter the necessary values for the new called TSO user.
3.2 TSO start and the user logon process in detail
In this chapter, I will explain how the logon process works in detail and what resources and requirements are necessary. As I mentioned above, the most important thing to logon to TSO/ISPF is the logon procedure.
Where do we find the name of the logon procedure?
There are two locations where we can find the name of the logon procedure:
The first available location is the ISPF primary option menu:
Screen 3.1: ISPF primary option menu showing the TSO logon procedure name
As can be seen in the above screen, the TSO logon procedures name is XYZLOGON:
The second location is the TSO Logon Panel:
When the session manager controls the logon process, the TSO/E Logon Panel does not appear and the previous logon procedure is used. Therefore, we do not see this panel during a logon process. To achieve the display of this panel, we leave ISPF in a normal way. Then, when the TSO READY screen displays, we enter a logon userid command (e.g. logon xyz0001) and the TSO/E logon panel appears:
This panel contains many empty lines. I removed these lines to save space.
Screen 3.2: TSO/E logon screen showing the TSO logon procedure name
The Procedure ===> XYZLOGON field contains the TSO logon procedure name. When the user presses the ENTER key, the logon process continues.
The logon process step by step:
1. The start processor for TSO users assembles a start job for the user and submits it to JES2.
2. Example with parameter values from the above logon panel:
JCL 3.1: JCL to start a TSO user
3. The system searches the SYSPROC chain of the z/OS system for the member XYZLOGON. This member contains a Started Task JCL to start the TSO user XYZ0001. In this case, we assume the member XYZLOGON stays in TSO.PROCLIB.
 |
Note: When JES2 starts during the IPL process of z/OS the system builds the SYSPROC chain. Below you see an example of a JCL procedure to start JES2: |
JCL 3.2: JES2 start job
4. JES2 starts the task XYZLOGON (see the JCL below).
JCL 3.3: TSO user start procedure
5. The program IKJEFT01 (it is the TSO processor) searches in its SYSPROC chain the member named in the parm field of the EXEC statement. This is the Logon Procedure written in CLIST or REXX.
6. The logon procedure XYZLOGON runs and ISPF starts.
3.3 ISPF start
Hereafter I give information about prerequisites and preparations to start ISPF. Additionally I will explain several possibilities to start ISPF online.
3.3.1 Necessary ISPF libraries
For a start, each TSO user (like each BATCH job) has access to all programs found in systems LINKLIB library chain.
This ability does not fulfill the requirements of TSO and least of all for ISPF. TSO is able to run procedures and programs found in SYSPROC or SYSEXEC allocation. However, this is nowhere near enough for ISPF. This system needs many additional allocations to start and run in a usable manner. All necessary data sets must be previously allocated, before ISPF can start. Why is this necessary?
– ISPF is in contrast to TSO panel driven. Therefore, ISPF needs the DD allocation for ISPPLIB. The ISPPLIB chain contains the basic panels for ISPF itself as well as the panels for the ISPF subsystems (SDSF, GDDM …) and user application panels.
– Applications may produce messages embedded in panels. The library ISPMLIB contains these message definitions.
– Many ISPF applications use ISPF tables. These tables are stored in the ISPTLIB library.
– The skeleton library ISPSLIB is necessary when applications use the skeleton method.
– To execute procedures ISPF needs the allocation of SYSEXEC or SYSPROC (or both).
– When an application and ISPF itself ends, ISPF writes the Profile Pool Variables back into the profile data set. Therefore, ISPF needs the allocation of DD for ISPPROF.
All libraries except ISPPROF and ISPTABL are normally concatenated data sets and ISPF opens all when started.
|
Remark: When the ISPF is already running, more LIBRARIES may be temporarily allocated and deallocated. The commands to do this are LIBDEF and ALTLIB. |
Table 3.1: All mandatory library allocations to start ISPF
|
Remark: |
3.3.2 Display currently existing library structures
The currently existing library structures can as follows displayed:
– The command ISPLIBD is to display the currently allocated ISPF libraries used. Enter this command in the ISPF command line. After enter the following screen is displayed:
Screen 3.3: Display existing ISPF library allocations
– The command TSO ALTLIB DISPLAY is to display the currently existing ALTLIB allocation used. This command is in the ISPF command line entered. After enter the following screen is displayed:
Screen 3.4: Display existing ALTLIB allocation
3.3.3 ISPF table service data sets
The above table contains the ISPTLIB allocation. This DD is used to READ ISPF tables. The allocation of ISPTLIB normally contains a chain of data sets. Nevertheless, it is impossible to write tables back to a chain of data sets. To WRITE a table a DD definition containing only ONE data set must exist. Therefore, another DD name called ISPTABL allocates the table output data set.
To read and write tables the following method is used:
– There is a table output data set allocated using the DD name ISPTABL containing only ONE data set.
– This data set is the first one in the ISPTLIB chain.
The following excerpt from a DDLIST utility display shows the allocations of ISPTLIB and ISPTABL:
|
Remark: To start ISPF, an allocation of ISPTABL is not necessary, but the ISPTLIB allocation is mandatory. |
3.3.4 The user profile library ISPPROF
To start ISPF the user profile library is mandatory. This means, an allocation of ISPPROF must exist. When first starting ISPF, the user profile library may be empty, but the allocation ISPPROF must exist. ISPF uses the profile library to store information from session to session. This data set is a PDSE with the following allocation values:
RECFM=FB, LRECL=80, BLKSIZE=27920
ISPF creates the members in an empty ISPPROF library when ISPF or an application starts the first time. ISPF updates the members each time when an application or ISPF ends.
Table 3.2: Important members in ISPPROF library
Screen 3.5: ISPF profile data set information panel
 |
Warning: |
The logon procedure allocates the data set for the ISPF profile. See the following excerpt from a CLIST logon procedure:
Program 3.1: CLIST logon procedure
3.3.5 Contents of ISPF profile library
The ISPF profile library contains the following value types:
– ISPF system variables.
– Variables of ISPF applications.
– User variables.
The values are stored in application dependent members. ISPF builds the member names automatically.
The type of each ISPF variable is character string. The length of each variable can be up to 32760 bytes.
|
Remark: When ISPF itself or an application in ISPF starts, all ISPF variables are loaded from the ISPPROF library into the virtual storage. They stay there until the application or ISPF ends. When the application ends, ISPF writes all the application variables back to the appropriate member. When an application ends with a severe error, there is no chance to write the variables back. Therefore, all changes of variables are lost. The same happens for variables of all running ISPF applications when ISPF itself ends with a severe error or when an operator cancels ISPF or the TSO user. When ISPF or an application after a demolition starts again, the variables stored last are loaded. |
3.3.6 The ISPF start command
There are three TSO commands to start ISPF:
1. ISPSTART
2. ISPF
3. PDF
Each of these commands is usable to start ISPF. If one of these commands is without any parameters used, the default options are in effect. The Table 3.3 on page 38 shows all three ISPF start commands and their default options.
Table 3.3: ISPF start commands
| Command | Default option | Used ISPF applid |
| ISPSTART | PANEL(ISP@MSTR) | ISP |
| ISPF | PANEL(ISP@PRIM) NEWAPPL(ISR) | ISR |
| PANEL(ISP@PRIM) NEWAPPL(ISR) | ISR |
There are many options available when one of these commands is used. You can find these options in the manual ISPF Dialog Developer’s Guide and Reference in chapter 2: Controlling ISPF Sessions.
3.3.7 The initial logon procedure XYZLOGON
After we are familiar with how TSO/ISPF starts, we shall look how the logon procedure works.
ISPF user start sequence:
1. First, the logon procedure checks the availability of an ISPPROF data set.
2. If this data set exists, the procedure allocates ISPPROF.
3. If the data set does not exist, the procedure creates the data set and allocates it as ISPPROF.
|
Caution: |
We used the procedure language REXX to develop the procedure XYZLOGON. Sometimes CLIST may also be used. If you are not familiar with one of these languages, I added some explanations below the figure. These explanations should help you to understand the most important statements. The line numbers are normally not part of the statements. I added these line numbers only for the explanation of their contents for you.
Program 3.2: Logon procedure XYZLOGON
The following table contains descriptions for some lines in the above procedure:
| Lines | Description |
| 6–8 | Set contents of variables lpar, user, pdsn |
| 12 | Check whether the data set for ISPPLIB is available. |
| If yes, allocate it. | |
| 13–15 | If no, create and allocate it. |
| 22 | Check whether a private logon procedure is available. If yes, then call it up. |
| 23 | If there is no private logon procedure, then call ISPF immediately. |
3.3.8 Rules how a logon procedure may end
Each logon procedure stays active in background as long as ISPF is running. When ISPF quits, the control comes back into the logon procedure behind the ISPF call command.
Depending on the exit programming of one of the procedures, the following happens:
– If the general logon procedure XYZLOGON or the private logon procedure performs a TSO LOGOFF command after the ISPF call statement, the TSO user becomes throwing back to the session manager and he has no chance to get a TSO READY prompt panel.
– If the private logon procedure AND the general logon procedure are both ending without performing a TSO LOGOFF the user gets a TSO READY prompt.
3.3.9 The private logon procedure SLOGON
An own logon procedure is necessary if you plan to do the following:
– Develop own ISPF applications.
– Use ISPF applications frequently which executing elements are not contained in the standard ISPF libraries.
– Modify existing ISPF applications.
First, you have to investigate which TSO environment is available in your z/OS system. The questions are:
1. Is there a standard way available to use an own logon procedure?
Do the following if such an environment is available:
Look into the standard logon procedure for installing your own logon procedure and what name you has to use. In our example above XYZLOGON is the name of the standard logon procedure and the name of your private logon procedure member must be SLOGON in the data set 
. The ISPF Primary Option Menu contains the name of the standard logon procedure. If you do not know where the standard logon procedure resides, ask your system programmer.
Copy the standard logon procedure under the new name SLOGON into the data set and modify it as necessary.
2. When you leave ISPF, do you get the TSO READY PROMPT?
You can enter the command exec 
to start your own Logon Procedure after ISPF quits.
3. When you leave ISPF, do you fall back to the session manager?
If this happens, you have no chance to use a private logon procedure. The only chance to use your own logon procedure is to ask your system programmers whether they are willing to install a special logon environment for you.
A possible circumvention in this situation may be the use of ISPFs LIBDEF commands in all your own application procedures. To reach your procedures, you must use the ALTLIB command first.
Rules to develop your own logon procedure:
– Write the logon procedure in CLIST or REXX. Other languages are not useable.
– You are free in designing the procedure.
– The procedure must call ISPF. Use one of the ISPF start commands shown above in Table 3.3 on page 38.
 |
Recommendation: If you plan on developing own ISPF applications, you should install a test and a production logical level for each ISPF library. This would especially useful if there are several users working on the same project. The first logical levelcontains your own programming elements and the second logical levelis the group one. |
3.3.10 Example of a LOGON procedure
|
Remark: This logon procedure uses the CONCATD command to allocate private libraries. This command is able to position additional data sets BEFORE the existing one in a DD element. See the description of CONCATD in the section 10.1 The TSO command CONCATD on page 179. |
Program 3.3: LOGON procedure example
3.4 The SLOGON procedure of the SMART ISPF utilities
On the previous pages, you learned a lot concerning logon procedures. You are now aware how important a reliable private logon procedure is. All procedures we discussed have a weakness: If the name of one of the data sets in the systems logon procedure has changed, your private logon procedure fails with the error Data set not found. Therefore, I wrote a special logon procedure, which avoids this chink.
Requirements for such a procedure:
Persons without REXX knowledge should be able to use the procedure.
– The existing data set chains must be conserved and new added data sets must be before the origin ones for each affected DD allocation positioned.
– If an additionally to allocate data set is not found, the procedure must display an error message and continue the allocation with the available data sets.
– The CONCATD command is not necessary.
The SLOGON procedure of the SMART ISPF utilities fulfills all these requirements.
Functions of the SLOGON procedure of the SMART ISPF utilities:
1. Read all existing DD together with their allocated data sets and save all.
2. Read a control file containing data set names that should allocated BEFORE the current ones for each DD element.
3. Assemble a complete new data set allocation structure.
4. Allocate this structure using the TSO ALLOC command with REUSE option.
5. Call ISPF.
|
Caution: This logon procedure can never be under control of ISPF executed because the affected libraries are OPEN when ISPF is running. |
3.4.1 Install the SLOGON procedure
First, edit the control member SLOGDSN. You can copy the example member shown below from the SMART ISPF utility data set.
3.4.1.1 The control member SLOGDSN
The logon procedure reads the control member SLOGDSN. It must reside in the same data set where the logon procedure is. The control member contains DD names and DSNs designed to allocate in front of existing allocations in the DSN chain for the relevant DD element. This method avoids the necessity to insert the variable DDNAMES and DSNs into the logon procedure itself. The logon procedure therefore always remains unchanged.
Figure 3.1: SLOGDSN control member example
3.4.1.2 Install the SMART ISPF utilities logon procedure
There are two logon scenarios possible:
Scenario 1:
There is an environment available to install an own logon procedure as described in the section 3.3.9 The initial logon procedure XYZLOGON on page 40.
1. Identify the data set to which you must the LOGON procedure copy and copy it.
2. Copy the SMART ISPF utilities SLOGDSN member into the same data set as the LOGON procedure.
3. Modify this member as needed for your requirements.
4. Perform a new logon.
5. Use the DDLIST utility to check whether the allocations are correct.
Scenario 2:
There is NO environment available to install an own logon procedure as described in the section 3.3.9 The initial logon procedure XYZLOGON on page 40. However, you get the TSO READY PROMPT when you leave ISPF.
1. Copy the SMART ISPF utilities logon procedure SLOGON and the SLOGDSN member into a PDS/PDSE of your choice. The PDS/PDSE must have a LRECL=80. e.g. userid.REXX
2. Modify the member SLOGDSN as needed for your requirements.
3. Leave ISPF.
4. At the TSO READY PROMPT enter the command: exec 'userid.REXX(SLOGON) '.
5. The logon procedure runs and ISPF starts again. During running, the logon procedure displays an echo print of all allocations as well as error messages that are eventually appearing.
6. Use the DDLIST utility to check whether the allocations are correct.
The figure Screentext 3.1 on page 45 shows an excerpt of a DDLIST printout when the above SLOGDSN control member is during a logon used. All additionally assigned allocations are in gray.
Screentext 3.1: Allocated ISPF libraries
See also the chapter 11.5 Installation of SMART ISPF utilities on page 203.