ISPF 101: Introduction to Panels,

Messages and Variables

Clive Nealon
IBM Global Services Australia
SHARE 98, Winter 2002
[email protected]

SHARE 98
®
 SHARE Nashville - ISPF Project Grid ®

IBM Software Solutions

8:00am 9:30am 11:00am 1:30pm 3:00pm 4:30pm 6:00pm

2600 90 mins
ISPF and
Sunday SCLM Suite
March 3 Open / Reqs
Review ¤

2400 2601 ¤ 0001 2602 ¡ 2603 ¡ 2604 ¡ 2608 ¡L

MVS Program ISPF and SCLM General ISPF 101: ISPF 102: ISPF 103: ISPF laboratory
Monday Opening Suite Trends Session Introduction to Introduction to Introduction to
March 4 and Directions Panels and Skeletons and ISPF Dialogs
Messages Tables

2634 ¤ 2635 ¤ 2636 ¤ 2637 ¤ 2638 ¤L 2632 ¡

Tuesday IBM’s SCLM Suite SCLM Suite SCLM Suite SCLM Suite Dynamic ISPF
March 5 SCLM Suite 101: Intro. to 102: SCLM 103: SCLM 104: Laboratory
Library Mgmt in Action Admin.

2639 ¤ 2640 ¤ 2644 ¤

Wednesday SCLM Suite SCLM Suite SCLM Suite
March 6 User Session and InfoMan User Group
Integration
Story
2625 ¡ 2627 ¡ 2605 ¡ 2646 ¡ 2649 90 mins
ISPF Hidden ISPF ISPF ISPF One Hour ISPF and
Thursday Treasures Panel Behind the – Two Topics SCLM Suite
March 7 Processing Scenes Reqs & Close
¤
ISPF and SCLM Suite sessions are in Ryman Chambers A/B/C,
except labs (marked L), which are in Presidential Chamber B.
¡ Attendance counts towards ISPF certification only
¤ Attendance counts towards ISPF and SCLM Suite certification
© COPYRIGHT IBM CORPORATION 2002 IBM SOFTWARE SHARE 98, Winter 2002
Agenda ®

IBM Software Solutions

ISPF Overview
What ISPF Does
Where to store the parts of a 'dialog'

ISPF Variables
Pools
Services

Messages

Panels

© COPYRIGHT IBM CORPORATION 2002 IBM SOFTWARE SHARE 98, Winter 2002
What ISPF Does ®

IBM Software Solutions

ISPF is the interface between your program and

the user on TSO.

1. Present a screen to the user (called a Panel)

2. Get user input (into one or more variables)
3. Process the input.
4. Set messages and respond to the user.

© COPYRIGHT IBM CORPORATION 2002 IBM SOFTWARE SHARE 98, Winter 2002
Parts of an ISPF Dialog ®

IBM Software Solutions

Panels - Define the image on the screen. They

can also provide some basic application logic.

Messages - Provide simple feedback to the

user.

Skeletons - Provide a basic mechanism for

formatting data to an output file. Usually used to
generate JCL or listings.

© COPYRIGHT IBM CORPORATION 2002 IBM SOFTWARE SHARE 98, Winter 2002
Parts of an ISPF Dialog ®

IBM Software Solutions

Tables - Provide a means of storing data.

Intended for relatively small amounts of data
(Not meant to be a database)

Images (GUI only)

© COPYRIGHT IBM CORPORATION 2002 IBM SOFTWARE SHARE 98, Winter 2002
Parts of an ISPF Dialog ®

IBM Software Solutions

And of course...

Your program - Can be REXX, CLIST, Compiled

language (COBOL, PL/I, ASSEMBLER, etc.), or APL.

Any language which can use 'standard linkage

conventions' will work.

All ISPF services are called through ISPEXEC and

ISPLINK

© COPYRIGHT IBM CORPORATION 2002 IBM SOFTWARE SHARE 98, Winter 2002
Parts of an ISPF Dialog ®

IBM Software Solutions

ISPF parts live in PDSes allocated to specific DD

names. Each part is a member of a PDS.

ISPxLIB
where 'x' defines the type of the part...

© COPYRIGHT IBM CORPORATION 2002 IBM SOFTWARE SHARE 98, Winter 2002
Parts of an ISPF Dialog ®

IBM Software Solutions

ISPPLIB - Panels
ISPMLIB - Messages
ISPSLIB - Skeletons

ISPTLIB - Tables
ISPPROF - Tables These have special
properties
ISPTABL - Tables

ISPILIB - Images

© COPYRIGHT IBM CORPORATION 2002 IBM SOFTWARE SHARE 98, Winter 2002
Parts of an ISPF Dialog ®

IBM Software Solutions

REXX programs reside in SYSPROC or

SYSEXEC.

CLISTs reside in SYSPROC.

Load modules are in ISPLLIB, STEPLIB, Linklist,

LPA, or other places.

ISPF does not control these libraries.

© COPYRIGHT IBM CORPORATION 2002 IBM SOFTWARE SHARE 98, Winter 2002
Parts of an ISPF Dialog ®

IBM Software Solutions

There are other DD names that may be needed.

There are other ways to dynamically allocate

parts of a dialog (LIBDEF, ALTLIB, TSOLIB, and
other dynamic allocation products and service).
Tip: Use the TSO ISRDDN command to find parts (there is a help
panel - F1)

Tip: Use existing parts as examples. Especially panels.

© COPYRIGHT IBM CORPORATION 2002 IBM SOFTWARE SHARE 98, Winter 2002
ISPF Variables ®

IBM Software Solutions

ISPF Dialogs rely on variables

Names are 8 characters.

Many formats...
FIXED (numeric)
CHAR (character)
...
USER (you decide)

© COPYRIGHT IBM CORPORATION 2002 IBM SOFTWARE SHARE 98, Winter 2002
ISPF Variables ®

IBM Software Solutions

Names starting with Z are reserved by ISPF.

Examples:
&Z = null (used for testing for empty variables)
&ZUSER = userid
&ZTIME = current time
&ZSCREEN = split screen number
&ZWIDTH = screen width
Tip: In panels, messages and skeletons, variables are
usually represented with an ampersand prefix.

© COPYRIGHT IBM CORPORATION 2002 IBM SOFTWARE SHARE 98, Winter 2002
ISPF Variables ®

IBM Software Solutions

In REXX or CLIST, ISPF uses the REXX/CLIST

variables (you don't need to do anything
special).

Only those with names of 8 characters or less.

Stem variables are not allowed as ISPF
variables.

© COPYRIGHT IBM CORPORATION 2002 IBM SOFTWARE SHARE 98, Winter 2002
ISPF Variables ®

IBM Software Solutions

Compiled programs use local storage as a

location for ISPF variables.

VDEFINE - Associate program storage with a

name.

VDELETE - Remove the association.

It is VERY IMPORTANT to have one VDELETE

for each VDEFINE.

© COPYRIGHT IBM CORPORATION 2002 IBM SOFTWARE SHARE 98, Winter 2002
ISPF Variables ®

IBM Software Solutions

... other services using the variable...

Creates ISPF variable MYVAR1 over program variable pgmvar.

© COPYRIGHT IBM CORPORATION 2002 IBM SOFTWARE SHARE 98, Winter 2002
ISPF Variable Pools ®

IBM Software Solutions

Variables pools define sharing and persistence

of variables.

Function pool - known only to your program

Shared pool - Can be shared between programs within

an application (without sharing storage)

Profile pool - Can be shared between programs and

saved across ISPF sessions. (Saved in DD name
ISPPROF).

© COPYRIGHT IBM CORPORATION 2002 IBM SOFTWARE SHARE 98, Winter 2002
ISPF Variable Pools ®

IBM Software Solutions

Variable Services:

VGET - copy a variable from shared or profile

pool.

VPUT - Copy a variable to shared or profile pool.

VCOPY - Copy variable contents from any pool.

VREPLACE - Create an 'implicit' variable from
data at any storage location.

© COPYRIGHT IBM CORPORATION 2002 IBM SOFTWARE SHARE 98, Winter 2002
ISPF Variables ®

IBM Software Solutions

VGET and VPUT assume you did a VDEFINE or

are using REXX or CLIST.

VCOPY and VREPLACE just copy data from

and to storage but do not require the actual
storage association (VDEFINE).
These two are not available in REXX or CLIST.

© COPYRIGHT IBM CORPORATION 2002 IBM SOFTWARE SHARE 98, Winter 2002
ISPF Messages ®

IBM Software Solutions

Messages are named:

ppppnnns

Prefix: one to five alphabetic characters

(A-Z, #, $, or @)
Number: three numeric characters (0-9)
Suffix (optional): one alphabetic character.

Examples:
ISRE016, EXIT532G, SK@949A
© COPYRIGHT IBM CORPORATION 2002 IBM SOFTWARE SHARE 98, Winter 2002
ISPF Messages ®

IBM Software Solutions

Message member names are determined by

truncating the message ID after the second digit
of the number.

Example:

Member GTE08 may contain messages

GTE080 through GTE089Z

© COPYRIGHT IBM CORPORATION 2002 IBM SOFTWARE SHARE 98, Winter 2002
ISPF Messages ®

IBM Software Solutions

Messages are used by the following services:

SETMSG - Show a message on the next display.

DISPLAY - Show a message as part of

displaying a panel.

TBDISPL - Show a message as part of

displaying a table.

LOG - Write a message to the ISPF log.

© COPYRIGHT IBM CORPORATION 2002 IBM SOFTWARE SHARE 98, Winter 2002
ISPF Messages ®

IBM Software Solutions

You can also read a message into a program

with the GETMSG service.

This is an easy way to get simple national

language translation capability for small amounts
of translatable data.

© COPYRIGHT IBM CORPORATION 2002 IBM SOFTWARE SHARE 98, Winter 2002
ISPF Messages ®

IBM Software Solutions

ISPF Messages have:

Short message:
Up to 24 characters

Long message:
Up to 512 characters
Tip: Use the long message to tell how to fix the
problem, not just to tell what went wrong.

Attributes: Alarm, associated help panel, severity of message,

etc..

© COPYRIGHT IBM CORPORATION 2002 IBM SOFTWARE SHARE 98, Winter 2002
ISPF Messages ®

IBM Software Solutions

Continuation

Continue long messages with a

SPACE-PLUS after the line to be continued.

'This is line one followed by ' +

'line two.'

© COPYRIGHT IBM CORPORATION 2002 IBM SOFTWARE SHARE 98, Winter 2002
ISPF Messages - Example ®

IBM Software Solutions

NEXT000 'No matching names'

'There were no data set names matching the specified' +
'pattern (&pattern).

NEXT001 ' '

'The name &nextname was retrieved using pattern "&PATTERN".'

NEXT002 'No more names'

'There were no additional ' +
'data set names matching the specified pattern (&pattern).'

Note that NEXT001 has no short message.

© COPYRIGHT IBM CORPORATION 2002 IBM SOFTWARE SHARE 98, Winter 2002
ISPF Messages ®

IBM Software Solutions

Examples:

ISPEXEC SETMSG MSG(EJG331)

ISPEXEC DISPLAY PANEL(MYPAN) MSG(EED001)

ISPEXEC LOG MSG(EJD331L)

© COPYRIGHT IBM CORPORATION 2002 IBM SOFTWARE SHARE 98, Winter 2002
ISPF Panels - Overview ®

IBM Software Solutions

Panels define what your users will see on the

screen.

Output fields
Input fields
Colors
Variables displayed or used for input

Panel logic provides some 'smarts'

© COPYRIGHT IBM CORPORATION 2002 IBM SOFTWARE SHARE 98, Winter 2002
ISPF Panels - Four types of panels ®

IBM Software Solutions

Selection panel

Can invoke programs, TSO commands, or other

selection panels. Usually used for primary panels.

Invoked via ISPEXEC SELECT service

&ZSEL))
(Always have an assignment to &ZSEL

ISPEXEC SELECT PANEL(ISR@PRIM)

© COPYRIGHT IBM CORPORATION 2002 IBM SOFTWARE SHARE 98, Winter 2002
ISPF Panels - Four types of panels ®

IBM Software Solutions

Display panels

Used for basic input and output operations.

An example is the Option 2 edit input panel.

Displayed via the DISPLAY service

ISPEXEC DISPLAY PANEL(EDITINP)

© COPYRIGHT IBM CORPORATION 2002 IBM SOFTWARE SHARE 98, Winter 2002
ISPF Panels - Four types of panels ®

IBM Software Solutions

Table Display Panels

Used to display formatted ISPF Tables.

An example is the Option 3.9 display (Command

tables).

Displayed via the TBDISPL service

ISPEXEC TBDISPL TABLE(MYTABLE) PANEL(MYTBPANL)

© COPYRIGHT IBM CORPORATION 2002 IBM SOFTWARE SHARE 98, Winter 2002
ISPF Panels - Four types of panels ®

IBM Software Solutions

Tutorial Panels

Used to display Help panels.

Displayed when the HELP key is pressed. Specified in

Panels or on Messages.

Basically the same as Display panels with a few extra

keywords.

Tip: You can view a specific help panel by typing TUTOR panel
on any ISPF command line.
© COPYRIGHT IBM CORPORATION 2002 IBM SOFTWARE SHARE 98, Winter 2002
ISPF Panels ®

IBM Software Solutions

Panels reside in DD name ISPPLIB

Each panel is a member.

Services use the member name to refer to the

panel.

Input on panels ends up in ISPF Variables.

© COPYRIGHT IBM CORPORATION 2002 IBM SOFTWARE SHARE 98, Winter 2002
ISPF Panels - The basic sections ®

IBM Software Solutions

Panels have several sections:

)ATTR
Defines attribute bytes, e.g. input, output,
colors

)BODY
Defines what the panel will look like

)INIT, )REINIT
)INIT )REINIT, )PROC
Panel Logic (simple setup, verifications, etc.)
)END
Defines the end of the panel definition (required)
© COPYRIGHT IBM CORPORATION 2002 IBM SOFTWARE SHARE 98, Winter 2002
ISPF Panels - )ATTR ®

IBM Software Solutions

The )ATTR section defines Attribute bytes

Attribute bytes, used in the )BODY section,

indicate what follows:

# TYPE(TEXT) COLOR(RED)
means text following this byte is red.

@ TYPE(INPUT) CAPS(ON)
means an input field is beginning and the
field will translate input to upper case.
© COPYRIGHT IBM CORPORATION 2002 IBM SOFTWARE SHARE 98, Winter 2002
ISPF Panels - )ATTR ®

IBM Software Solutions

Many different TYPEs:

TYPE(TEXT) - Text follows - may include

variables, e.g.: Hello &ZUSER
TYPE(INPUT) - Input field
TYPE(OUTPUT) - Output field (variable name)

CUA Types define colors based on the field type,

such as panel title or normal entry field.

© COPYRIGHT IBM CORPORATION 2002 IBM SOFTWARE SHARE 98, Winter 2002
ISPF Panels - )BODY ®

IBM Software Solutions

The )BODY section is the 'WYSIWYG' section.

(what you see is what you get)

Use attribute bytes, plain text and variables.

)ATTR
% type(text) intens(high)
%, + and _ are preset by ISPF.
+ type(text) intens(low) They are shown here as an
_ type(input) example only.
)BODY
%------- Panel Title -----
%Command ===>_MYVAR %
)END This indicates the beginning of
an input field. What the user
types will be stored in variable
MYVAR.
© COPYRIGHT IBM CORPORATION 2002 IBM SOFTWARE SHARE 98, Winter 2002
ISPF Panels - Panel Logic ®

IBM Software Solutions

Use Panel Logic in the )INIT, )REINIT and )PROC

sections:

)INIT section - Run before panel display

)REINIT section - run before redisplay (usually

before an error message set in the )PROC section is
shown).

)PROC section - Run after the panel is displayed.

Usually contains field verifications.

© COPYRIGHT IBM CORPORATION 2002 IBM SOFTWARE SHARE 98, Winter 2002
ISPF Panels - Panel Logic ®

IBM Software Solutions

Assignment statement

&MYVAR = &ZUSER

&MYVAR = 'Johnny is a &NICEGUY'

&CURSLOC = .CURSOR
(Control variables are special panel variables)

&ZSEL = TRANS(&COM 1,'CMD(A)' 2,&MYVAR)

© COPYRIGHT IBM CORPORATION 2002 IBM SOFTWARE SHARE 98, Winter 2002
ISPF Panels ®

IBM Software Solutions

Some control variables

.CURSOR - Field name where cursor is.

.CSRPOS - Cursor offset into field.
.HELP - Help panel associated with this panel
.MSG - Next message to display
.RESP - User or simulated response - END or ENTER.
.TRAIL - What remained after a TRUNC() operation
(TRUNC is a common function to pull options of the command
line).

© COPYRIGHT IBM CORPORATION 2002 IBM SOFTWARE SHARE 98, Winter 2002
ISPF Panels ®

IBM Software Solutions

IF - ELSE

Indentation sensitive
Comments use /* */

IF (&A = 1,2,3) /* if a is 1, 2 or 3 */
&B = 2
.MSG = XGG001 Clause on same or next line(s)

ELSE &B = 4 /* can be on same line as else */

&C= 'This is outside of the IF/ELSE logic */

© COPYRIGHT IBM CORPORATION 2002 IBM SOFTWARE SHARE 98, Winter 2002
ISPF Panels ®

IBM Software Solutions

IF - ELSE

The expression can include

Simple comparison : IF (&A = 3)

List if comparisons : IF (&A NE 4,5,6)

Use of control variables: IF (.MSG = &Z)

Imbedded verify: IF (VER (&DSN,NB))

© COPYRIGHT IBM CORPORATION 2002 IBM SOFTWARE SHARE 98, Winter 2002
ISPF Panels ®

IBM Software Solutions

IF - ELSE
= or EQ Equal
¬= or NE Not equal
> or GT Greater than
< or LT Less than
>= or GE Greater than or equal
<= or LE Less than or equal
¬> or NG Not greater than
¬< or NL Not less than

Tip: Panel language does not do math

eg : IF (&A=&C+1)

© COPYRIGHT IBM CORPORATION 2002 IBM SOFTWARE SHARE 98, Winter 2002
ISPF Panels ®

IBM Software Solutions

VER - The VERIFY statement

Used to Verify input fields:

VER (&A, NB,RANGE,6,19)

VER (&A,NB)

VER (&A,LIST,4,7,JOE,MARY, MSG=XYZ001)

VER (&PROJECT,DSNAME)
© COPYRIGHT IBM CORPORATION 2002 IBM SOFTWARE SHARE 98, Winter 2002
ISPF Panels ®

IBM Software Solutions

VER (variable [NONBL] keyword [,MSG=value])

Keywords:
ALPHA LEN,relational-operator,expected-length

ALPHAB LIST,value1[value2...]
BIT LISTV,varlist
DBCS LISTVX,varlist
DSNAME LISTX,value1,value2,...
EBCDIC MIX
ENUM NAME
FILEID NUM
HEX PICT,string
INCLUDE[IMBLK] value1[,value2] RANGE,lower,upper

© COPYRIGHT IBM CORPORATION 2002 IBM SOFTWARE SHARE 98, Winter 2002
ISPF Panels ®

IBM Software Solutions

)BODY
% Sample panel
%Command ===>_ZCMD +
+
+ Project%===>_PRJXXX + _Z%Show Dates
+ Group %===>_G1 +
+ Type %===>_TYPENAME+
+ Member %===>_MEMNAME +

)INIT
&ZCMD = &Z /* blank out command line */
.ZVARS ='(SHOWDATE)' /* Z used for long names */
VGET (PRJXXX G1 TYPENAME MEMNAME showdate) SHARED
IF (&SHOWDATE NE &Z) &SHOWDATE = '/'
IF (.MSG EQ &Z) .CURSOR = MEMNAME /*set cursor */
)REINIT
REFRESH (*)
)PROC
IF (&SHOWDATE NE &Z) &SHOWDATE = '/'
VER (&PRJXXX ,NB,NAME)
VER (&G1 ,NB,NAME)
VER (&TYPENAME,NB,NAME)
VER (&MEMNAME ,NB,NAME)
VPUT (PRJXXX G1 TYPENAME MEMNAME SHOWDATE) SHARED
)END

© COPYRIGHT IBM CORPORATION 2002 IBM SOFTWARE SHARE 98, Winter 2002
ISPF Panels ®

IBM Software Solutions

© COPYRIGHT IBM CORPORATION 2002 IBM SOFTWARE SHARE 98, Winter 2002
ISPF Panels - Testing ®

IBM Software Solutions

Use Dialog Test

Option 7.2 - displays panels and messages

Start ISPF in TEST mode from the TSO READY prompt

to insure that you get the latest copy of each panel.

ISPF TEST

© COPYRIGHT IBM CORPORATION 2002 IBM SOFTWARE SHARE 98, Winter 2002
More information ®

IBM Software Solutions

ISPF Dialog Developers Guide and Reference

Use ISRDDN to find existing panels

Use the ISRDTLCV edit macro to make DTL

generated panels more readable.

Copy, Steal, Modify, Change, Pillage, ...

© COPYRIGHT IBM CORPORATION 2002 IBM SOFTWARE SHARE 98, Winter 2002
Internet Resources... ®

IBM Software Solutions

List Servers:
ISPF-L list server
send note to [email protected] with
SUBSCRIBE ISPF-L yourname
in the body of the note

ISPF-L is shadowed as newsgroup bit.listserv.ispf-l but you must be subscribed to post

to the newsgroup.

IBM-MAIN list server

send note to [email protected] with
SUBSCRIBE IBM-MAIN yourname
in the body of the note.

Search for listserver information at http://www.lsoft.com

© COPYRIGHT IBM CORPORATION 2002 IBM SOFTWARE SHARE 98, Winter 2002
Internet Resources... ®

IBM Software Solutions

Newsgroups:
On news.software.ibm.com

ISPF newsgroup
ibm.software.ispf

SCLM newsgroup
ibm.software.sclm

© COPYRIGHT IBM CORPORATION 2002 IBM SOFTWARE SHARE 98, Winter 2002
Internet Resources... ®

IBM Software Solutions

Useful Web Sites:

http://www.software.ibm.com/ad/ispf
ISPF home page (not very active)

http://www.redbooks.ibm.com
Redbooks produced for ISPF and SCLM

http://somebody.home.mindspring.com
OS/390 and ISPF Tools and toys (lots of ISPF extensions, some samples)
maintained by Doug Nadel

http://www.cbttape.org
The CBT tape, maintained by Sam Golob

http://planetmvs.com
A good starting point for everything OS/390...
maintained by Dave Alcock

© COPYRIGHT IBM CORPORATION 2002 IBM SOFTWARE SHARE 98, Winter 2002