introduction to panels, messages and variables

®®®®

ISPF 101: Introduction to Panels, Messages and Variables

SHARE 98

Clive NealonIBM Global Services Australia

SHARE 98, Winter [email protected]

IBM Software Solutions

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

®®®®SHARE Nashville - ISPF Project Grid

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

SundayMarch 3

2600 90 minsISPF and SCLM SuiteOpen / ReqsReview �

MondayMarch 4

2400MVS ProgramOpening

2601 �ISPF and SCLM Suite Trendsand Directions

0001General Session

2602 �ISPF 101:Introduction to Panels and Messages

2603 �ISPF 102:Introduction to Skeletons and Tables

2604 �ISPF 103:Introduction toISPF Dialogs

2608 �LISPF laboratory

TuesdayMarch 5

2634 �IBM�s SCLM Suite

2635 �SCLM Suite101: Intro. to Library Mgmt

2636 �SCLM Suite102: SCLM in Action

2637 �SCLM Suite103: SCLM Admin.

2638 �LSCLM Suite104: Laboratory

2632 �Dynamic ISPF

WednesdayMarch 6

2639 �SCLM Suite User Session

2640 �SCLM Suite and InfoMan Integration Story

2644 �SCLM SuiteUser Group

ThursdayMarch 7

2625 �ISPF Hidden Treasures

2627 �ISPF Panel Processing

2605 �ISPF Behind the Scenes

2646 �ISPF One Hour � Two Topics

2649 90 minsISPF and SCLM Suite 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



®®®®

ISPF OverviewISPF OverviewWhat ISPF DoesWhat ISPF DoesWhere to store the parts of a 'dialog'Where to store the parts of a 'dialog'

ISPF VariablesISPF VariablesPoolsPoolsServicesServices

MessagesMessages

PanelsPanels

Agenda



®®®®What ISPF Does

ISPF is the interface between your program and ISPF is the interface between your program and the user on TSO.the user on TSO.

1.1. Present a screen to the user (called a Panel)Present a screen to the user (called a Panel)2.2. Get user input (into one or more variables)Get user input (into one or more variables)3.3. Process the input.Process the input.4.4. Set messages and respond to the user.Set messages and respond to the user.



®®®®Parts of an ISPF Dialog

PanelsPanels - Define the image on the screen. They - Define the image on the screen. They can also provide some basic application logic.can also provide some basic application logic.

MessagesMessages - Provide simple feedback to the - Provide simple feedback to the user.user.

SkeletonsSkeletons - Provide a basic mechanism for - Provide a basic mechanism for formatting data to an output file. Usually used to formatting data to an output file. Usually used to generate JCL or listings.generate JCL or listings.




TablesTables - Provide a means of storing data. - Provide a means of storing data. Intended for relatively small amounts of data Intended for relatively small amounts of data (Not meant to be a database)(Not meant to be a database)

ImagesImages (GUI only) (GUI only)



®®®®

And of course...And of course...

Your programYour program - - Can be REXX, CLIST, Compiled Can be REXX, CLIST, Compiled language (COBOL, PL/I, ASSEMBLER, etc.), or APL. language (COBOL, PL/I, ASSEMBLER, etc.), or APL.

Any language which can use 'standard linkage Any language which can use 'standard linkage conventions' will work.conventions' will work.

AllAll ISPF services are called through ISPF services are called through ISPEXECISPEXEC and and ISPLINKISPLINK

Parts of an ISPF Dialog




ISPF parts live in PDSes allocated to specific DD ISPF parts live in PDSes allocated to specific DD names. Each part is a member of a PDS.names. Each part is a member of a PDS.

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




ISPPLIB - PanelsISPPLIB - PanelsISPMLIB - MessagesISPMLIB - MessagesISPSLIB - SkeletonsISPSLIB - Skeletons

ISPTLIB - TablesISPTLIB - TablesISPPROF - TablesISPPROF - TablesISPTABL - TablesISPTABL - Tables

ISPILIB - ImagesISPILIB - Images

These have special properties




REXX programs reside in SYSPROC or REXX programs reside in SYSPROC or SYSEXEC.SYSEXEC.

CLISTs reside in SYSPROC.CLISTs reside in SYSPROC.

Load modules are in ISPLLIB, STEPLIB, Linklist, Load modules are in ISPLLIB, STEPLIB, Linklist, LPA, or other places.LPA, or other places.

ISPF does not control these libraries.ISPF does not control these libraries.




There are other DD names that may be needed.There are other DD names that may be needed.

There are other ways to dynamically allocate There are other ways to dynamically allocate parts of a dialog (LIBDEF, ALTLIB, TSOLIB, and parts of a dialog (LIBDEF, ALTLIB, TSOLIB, and other dynamic allocation products and service).other dynamic allocation products and service).

Tip: Use the Tip: Use the TSO ISRDDNTSO ISRDDN command to find parts (there is a help command to find parts (there is a help panel - F1)panel - F1)

Tip: Use existing parts as examples. Especially panels.Tip: Use existing parts as examples. Especially panels.



®®®®ISPF Variables

ISPF Dialogs rely on variablesISPF Dialogs rely on variables

Names are 8 characters.Names are 8 characters.

Many formats... Many formats... FIXEDFIXED (numeric)(numeric)CHARCHAR (character)(character)......USERUSER (you decide)(you decide)




Names starting with Z are reserved by ISPF.Names starting with Z are reserved by ISPF.

Examples:Examples:&Z = null &Z = null (used for testing for empty variables)(used for testing for empty variables)

&ZUSER = userid&ZUSER = userid&ZTIME = current time&ZTIME = current time&ZSCREEN = split screen number&ZSCREEN = split screen number&ZWIDTH = screen width&ZWIDTH = screen width

Tip: In panels, messages and skeletons, variables are Tip: In panels, messages and skeletons, variables are usually represented with an ampersand prefix.usually represented with an ampersand prefix.




In REXX or CLIST, ISPF uses the REXX/CLIST In REXX or CLIST, ISPF uses the REXX/CLIST variables (you don't need to do anything variables (you don't need to do anything special).special).

Only those with names of 8 characters or less.Only those with names of 8 characters or less.Stem variables are not allowed as ISPF Stem variables are not allowed as ISPF variables.variables.




Compiled programs use local storage as a Compiled programs use local storage as a location for ISPF variables.location for ISPF variables.

VDEFINEVDEFINE - Associate program storage with a - Associate program storage with a name.name.

VDELETEVDELETE - Remove the association. - Remove the association.

It is It is VERY IMPORTANTVERY IMPORTANT to have one VDELETE to have one VDELETE for each VDEFINE.for each VDEFINE.




Creates ISPF variable MYVAR1 over program variable pgmvar.Creates ISPF variable MYVAR1 over program variable pgmvar.

... other services using the variable...



®®®®

Variables pools define sharing and persistence Variables pools define sharing and persistence of variables.of variables.

Function poolFunction pool - known only to your program- known only to your program

Shared poolShared pool - Can be shared between programs within - Can be shared between programs within an application (without sharing storage)an application (without sharing storage)

Profile poolProfile pool - Can be shared between programs and - Can be shared between programs and saved across ISPF sessions. (Saved in DD name saved across ISPF sessions. (Saved in DD name ISPPROF).ISPPROF).

ISPF Variable Pools



®®®®ISPF Variable Pools

Variable Services:Variable Services:

VGETVGET - copy a variable - copy a variable fromfrom shared or profile shared or profile pool.pool.

VPUTVPUT - Copy a variable - Copy a variable toto shared or profile pool. shared or profile pool.

VCOPYVCOPY - Copy variable contents from any pool. - Copy variable contents from any pool.VREPLACEVREPLACE - Create an 'implicit' variable from - Create an 'implicit' variable from data at any storage location.data at any storage location.




VGETVGET and and VPUTVPUT assume you did a VDEFINE or assume you did a VDEFINE or are using REXX or CLIST.are using REXX or CLIST.

VCOPYVCOPY and and VREPLACEVREPLACE just copy data from just copy data from and to storage but do not require the actual and to storage but do not require the actual storage association (VDEFINE). storage association (VDEFINE).

These two are not available in REXX or CLIST. These two are not available in REXX or CLIST.



®®®®ISPF Messages

Messages are named:Messages are named:

ppppnnnsppppnnns

� Prefix: one to five alphabetic characters � Prefix: one to five alphabetic characters (A-Z, #, $, or @) (A-Z, #, $, or @)

� Number: three numeric characters (0-9) � Number: three numeric characters (0-9) � Suffix (optional): one alphabetic character. � Suffix (optional): one alphabetic character.

Examples:Examples: ISRE016, EXIT532G, SK@949AISRE016, EXIT532G, SK@949A




Message member names are determined by Message member names are determined by truncating the message ID after the second digit truncating the message ID after the second digit of the number.of the number.

Example:Example:

Member Member GTE08GTE08 may contain messages may contain messages GTE08GTE080 through 0 through GTE08GTE089Z9Z




Messages are used by the following services:Messages are used by the following services:

SETMSGSETMSG - Show a message on the next display. - Show a message on the next display.

DISPLAYDISPLAY - Show a message as part of - Show a message as part of displaying a panel.displaying a panel.

TBDISPL -TBDISPL - Show a message as part of Show a message as part of displaying a table.displaying a table.

LOGLOG - Write a message to the ISPF log. - Write a message to the ISPF log.



®®®®

You can also read a message into a program You can also read a message into a program with the with the GETMSGGETMSG service. service.

This is an easy way to get simple national This is an easy way to get simple national language translation capability for small amounts language translation capability for small amounts of translatable data.of translatable data.

ISPF Messages




ISPF Messages have:ISPF Messages have:

Short message:Short message:Up to 24 charactersUp to 24 characters

Long message:Long message:Up to 512 characters Up to 512 characters

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

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




ContinuationContinuation

Continue long messages with a Continue long messages with a SPACE-PLUS after the line to be continued. SPACE-PLUS after the line to be continued.

'This is line one followed by ' + 'This is line one followed by ' + 'line two.' 'line two.'



®®®®ISPF Messages - Example

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.




Examples:Examples:

ISPEXEC ISPEXEC SETMSGSETMSG MSG(EJG331)MSG(EJG331)

ISPEXEC ISPEXEC DISPLAYDISPLAY PANEL(MYPAN) MSG(EED001)PANEL(MYPAN) MSG(EED001)

ISPEXEC ISPEXEC LOGLOG MSG(EJD331L)MSG(EJD331L)



®®®®ISPF Panels - Overview

Panels define what your users will see on the Panels define what your users will see on the screen.screen.

Output fieldsOutput fieldsInput fieldsInput fieldsColorsColorsVariables displayed or used for inputVariables displayed or used for input

Panel logic provides some 'smarts'Panel logic provides some 'smarts'



®®®®ISPF Panels - Four types of panels

Selection panel Selection panel

Can invoke programs, TSO commands, or other Can invoke programs, TSO commands, or other selection panels. Usually used for primary panels.selection panels. Usually used for primary panels.

Invoked via ISPEXEC SELECT serviceInvoked via ISPEXEC SELECT service(Always have an assignment to (Always have an assignment to &ZSEL&ZSEL))

ISPEXEC SELECT PANEL(ISR@PRIM)ISPEXEC SELECT PANEL(ISR@PRIM)




Display panelsDisplay panels

Used for basic input and output operations. Used for basic input and output operations.

An example is the Option 2 edit input panel.An example is the Option 2 edit input panel.

Displayed via the DISPLAY serviceDisplayed via the DISPLAY service

ISPEXEC DISPLAY PANEL(EDITINP)ISPEXEC DISPLAY PANEL(EDITINP)




Table Display PanelsTable Display Panels

Used to display formatted ISPF Tables.Used to display formatted ISPF Tables.

An example is the Option 3.9 display (Command An example is the Option 3.9 display (Command tables).tables).

Displayed via the TBDISPL serviceDisplayed via the TBDISPL service

ISPEXEC TBDISPL TABLE(MYTABLE) PANEL(MYTBPANL)ISPEXEC TBDISPL TABLE(MYTABLE) PANEL(MYTBPANL)




Tutorial PanelsTutorial Panels

Used to display Help panels.Used to display Help panels.

Displayed when the HELP key is pressed. Specified in Displayed when the HELP key is pressed. Specified in Panels or on Messages.Panels or on Messages.

Basically the same as Display panels with a few extra Basically the same as Display panels with a few extra keywords.keywords.

Tip: You can view a specific help panel by typing TUTOR Tip: You can view a specific help panel by typing TUTOR panelpanel on any ISPF command line.on any ISPF command line.



®®®®ISPF Panels

Panels reside in DD name Panels reside in DD name ISPPLIBISPPLIB

Each panel is a member.Each panel is a member.

Services use the member name to refer to the Services use the member name to refer to the panel.panel.

Input on panels ends up in ISPF Variables.Input on panels ends up in ISPF Variables.



®®®®ISPF Panels - The basic sections

Panels have several sections:Panels have several sections:

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

colorscolors

)BODY)BODYDefines what the panel will look likeDefines what the panel will look like

)INIT)INIT, )REINIT)REINIT, )PROC )PROCPanel Logic (simple setup, verifications, etc.)Panel Logic (simple setup, verifications, etc.)

)END)ENDDefines the end of the panel definition (required)Defines the end of the panel definition (required)



®®®®ISPF Panels - )ATTR

The The )ATTR)ATTR section defines section defines Attribute bytesAttribute bytes

Attribute bytes, used in the Attribute bytes, used in the )BODY)BODY section, section, indicate what follows:indicate what follows:

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

@ @ TYPE(INPUT)TYPE(INPUT) CAPS(ON)CAPS(ON) means an input field is beginning and the means an input field is beginning and the

field will translate input to upper case.field will translate input to upper case.



®®®®ISPF Panels - )ATTR

Many different TYPEs:Many different TYPEs:

TYPE(TYPE(TEXTTEXT)) - Text follows - may include - Text follows - may include variables, e.g.: Hello &ZUSER variables, e.g.: Hello &ZUSER

TYPE(TYPE(INPUTINPUT) - Input field) - Input fieldTYPE(TYPE(OUTPUTOUTPUT) - Output field (variable name)) - Output field (variable name)

CUA Types define colors based on the field type, CUA Types define colors based on the field type, such as panel title or normal entry field.such as panel title or normal entry field.



®®®®

The )BODY section is the 'WYSIWYG' section.The )BODY section is the 'WYSIWYG' section.(what you see is what you get)(what you see is what you get)

Use attribute bytes, plain text and variables.Use attribute bytes, plain text and variables.

)ATTR % type(text) intens(high) + type(text) intens(low) _ type(input))BODY%------- Panel Title -----%Command ===>_MYVAR %)END

ISPF Panels - )BODY

%, + and _ are preset by ISPF.They are shown here as an example only.

This indicates the beginning of an input field. What the user types will be stored in variable MYVAR.



®®®®

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

)INIT)INIT section - Run before panel display section - Run before panel display

)REINIT)REINIT section - run before redisplay (usually section - run before redisplay (usually before an error message set in the )PROC section is before an error message set in the )PROC section is shown).shown).

)PROC)PROC section - Run after the panel is displayed. section - Run after the panel is displayed. Usually contains field verifications.Usually contains field verifications.

ISPF Panels - Panel Logic



®®®®ISPF Panels - Panel Logic

Assignment statement Assignment statement

&MYVAR = &ZUSER &MYVAR = &ZUSER

&MYVAR = 'Johnny is a &NICEGUY'&MYVAR = 'Johnny is a &NICEGUY'

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

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



®®®®ISPF Panels

Some control variablesSome control variables

.CURSOR.CURSOR - Field name where cursor is. - Field name where cursor is.

.CSRPOS.CSRPOS - Cursor offset into field. - Cursor offset into field.

.HELP.HELP - Help panel associated with this panel - Help panel associated with this panel

.MSG.MSG - Next message to display - Next message to display

.RESP.RESP - - User or simulated response - END or ENTER.User or simulated response - END or ENTER.

.TRAIL.TRAIL - What remained after a TRUNC() operation- What remained after a TRUNC() operation (TRUNC is a common function to pull options of the command (TRUNC is a common function to pull options of the command

line).line).



®®®®

IF - ELSEIF - ELSE

Indentation sensitiveIndentation sensitive IFIF (&A = 1,2,3) /* if a is 1, 2 or 3 */ (&A = 1,2,3) /* if a is 1, 2 or 3 */ &B = 2 &B = 2 .MSG = XGG001 .MSG = XGG001ELSEELSE &B = 4 /* can be on same line as else */ &B = 4 /* can be on same line as else */&C= 'This is outside of the IF/ELSE logic */&C= 'This is outside of the IF/ELSE logic */

ISPF Panels

Comments use /* */

Clause on same or next line(s)



®®®®ISPF Panels

IF - ELSEIF - ELSE

The expression can includeThe expression can include Simple comparison : IF (&A = 3)Simple comparison : IF (&A = 3)List if comparisons : IF (&A NE 4,5,6)List if comparisons : IF (&A NE 4,5,6)

Use of control variables: IF (.MSG = &Z)Use of control variables: IF (.MSG = &Z)Imbedded verify: IF (VER (&DSN,NB))Imbedded verify: IF (VER (&DSN,NB))



®®®®ISPF Panels

IF - ELSEIF - 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)



®®®®ISPF Panels

VER - The VERIFY statementVER - The VERIFY statement

Used to Verify input fields:Used to Verify input fields:

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

VER (&A,NB)VER (&A,NB)

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

VER (&PROJECT,DSNAME)VER (&PROJECT,DSNAME)



®®®®ISPF Panels

ALPHA LEN,relational-operator,expected-length

ALPHAB LIST,value1[value2...]BIT LISTV,varlistDBCS LISTVX,varlistDSNAME LISTX,value1,value2,...EBCDIC MIXENUM NAMEFILEID NUMHEX PICT,stringINCLUDE[IMBLK] value1[,value2] RANGE,lower,upper

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



®®®®ISPF Panels

)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) SHAREDIF (&SHOWDATE NE &Z) &SHOWDATE = '/'IF (.MSG EQ &Z) .CURSOR = MEMNAME /*set cursor */

)REINITREFRESH (*)

)PROCIF (&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



®®®®ISPF Panels



®®®®ISPF Panels - Testing

Use Dialog TestUse Dialog Test

Option 7.2 - displays panels and messagesOption 7.2 - displays panels and messages

Start ISPF in TEST mode from the TSO READY prompt Start ISPF in TEST mode from the TSO READY prompt to insure that you get the latest copy of each panel.to insure that you get the latest copy of each panel.

ISPF TESTISPF TEST



®®®®More information

ISPF Dialog Developers Guide and ReferenceISPF Dialog Developers Guide and Reference

Use ISRDDN to find existing panelsUse ISRDDN to find existing panels

Use the ISUse the ISRRDTLCV edit macro to make DTL DTLCV edit macro to make DTL generated panels more readable.generated panels more readable.

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



®®®®Internet Resources...

List Servers:ISPF-L list server

send note to [email protected] withSUBSCRIBE 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 serversend note to [email protected] with

SUBSCRIBE IBM-MAIN yournamein the body of the note.

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




Newsgroups:On news.software.ibm.com

ISPF newsgroupibm.software.ispf

SCLM newsgroup ibm.software.sclm




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.orgThe CBT tape, maintained by Sam Golob

http://planetmvs.comA good starting point for everything OS/390...

maintained by Dave Alcock

introduction to panels, messages and variables

Documents