After completing this chapter, you will be able to describe the Rexx Panels.
ISPF panels are used for data entry and display. If the number of arguments to the REXX EXECs becomes large, users will be unable to remember the proper sequence and format of those arguments. A better solution would be to provide the user with a full screen entry panel.
Panel definitions reside in a PDS that must contain fixed (LRECL of 80) or variable (maximum record size of 160) blocked size. The block size can be determined by the application. Panel definitions can be created using the ISPF editor. Each line in the dataset can be either a header or a section statement.
Each header statement begins in column one with a left parenthesis followed by a control word. Unlike skeletons, the panel definition is divided into sections, which must be in rather strict order.
Lines that do not start with a left parenthesis are considered to be section statements and do not have to start with column one.
The following commands when included in a REXX program display a Panel:
"ispexec libdef ispplib dataset id('panels.dataset')"
"ispexec display panel(pnlname)" |
Here, panels.dataset is the dataset where the panel definitions are stored.pnlname is the panel name.
The following describes the ISPF panel sections:
The )PANEL section.
The )ATTR section.
The )BODY section.
The Executable sections.
The )END section.
This section controls common user access display characteristics, KEYLIST options, images displayed in GUI mode, and placement for the upper left-hand corner of the image in GUI mode.
The )panel section is optional and relatively new to the ISPF panel definition process and to document its maintenance history and purpose. It is also used to add some descriptive comments to our panel definition. Without the )panel statement the comments following it will cause errors.
)PANEL /*Panel generated by IBMMainframer*/ /*At 21:29 on 2021/06/26*/ |
This section which is optional also, defines character to be used to define the text in the )BODY section. By default the following attribute characters are defined.
%: TYPE (TEXT) INTENS (HIGH).
+: TYPE (TEXT) INTENS (LOW).
_: TYPE (INPUT) INTENS (HIGH).
It defines the special characters in the body of the panel definition that represent attribute (start of field) bytes. Following the attribute character a list of keyword parameters that define the characteristics of the panel fields
TYPE (TEXT/INPUT/OUTPUT): Specifies the type of the field as – TEXT (protected), INPUT (unprotected), and OUTPUT (protected). INPUT and OUTPUT fields must be followed immediately by a dialog variable name.
INTENS (HIGH/LOW): Defines whether the field is high or low intensity.
CAPS (ON/OFF): Specifies whether the field is translated to upper-case before being displayed (ON), or left as it appears in the variable pool (OFF). ON is the default in most cases, unless the field is defined in a table display panel.
SKIP (YES/NO): Defines whether an automatic skip of the cursor to the next unprotected field should be made when the last character location of the preceding unprotected field is entered.
)ATTR DEFAULT(%+_) |
This section defines the physical screen layout that the user will see when the panel is displayed.
The syntax is as follows:
)BODY [WINDOW (width, depth)] [CMD (field-name)] [SMSG (field-name)] [LMSG (field-name)] [ASIS] [EXPAND (xy)] [DEFAULT (def1def2def3)]. |
The WINDOW keyword is used in conjunction with the ADDPOP service request to determine the size of the pop-up window. The width and depth (height) specified do not include the pop-up panel borders; the dialog manager adds them outside the width and depth values.
When defining the fields, it is easier to use "Z" placeholders for dialog variable names. The corresponding dialog variables are defined in the )INIT section using the .ZVARS control variable. The use of "Z" placeholders becomes necessary if you have variable names that will not fit into their corresponding field definitions.
The Executable sections, )INIT, )PROC, and )REINIT, contain executable statements following the section headers. Both the )INIT and )REINIT sections contain statements that are processed before panel display. The )PROC section contains statements processed after panel display.
The Executable statements that follow these section headers can be assignment, IF / ELSE, REFRESH, VER, VGET, and VPUT. Dialog variables (names proceeded by &), control variables (preceded by .) and literal values (character string not beginning with . or & and possibly enclosed in quotes) may be referenced in these statements. Several built-in functions like TRANS and TRUNC are also defined.
The Assignment statement allows the panel designer to set dialog variables to specific values. It can be used in the )INIT section to initialize variables before display, in the )REINIT section prior to redisplay, and in the )PROC statement to set variables in the panel body.
The format of Assignment statement is as follows:
&Variable = value |
The VER (verify) statement is used to check that the current value of a variable meets some criteria. Input variable value verification is performed after the value is stored in the variable pool. The VER statement is used in the )PROC section to verify panel input.
The syntax of VER Executable statement is as follows:
(Variable [, NONBLANK], keyword [value, value,…]) |
The first parameter is the variable to be checked. The second parameter NONBLANK (NB) is used to specify that the variable is required and may be omitted. The next parameter is optional if the NONBLANK parameter was specified and may or may not be followed by further parameters depending on the keywords used.
The keyword and parameter must be one of the following.
ALPHA: Variable must contain A through Z, a through z, #, $, or @.
NUM: Variable must contain 0 through 9.
ENUM: Variable must contain 0 through 9, +, -, delimiter symbols, decimal points or commas.
PICT, string: Variable must match a picture string (which follows the PICT keyword) and allow checking for alphabetic, numeric, hexadecimal and special character value format.
NAME: Variable must be a valid member name.
DSNAME: Variable must be a valid dataset name, including quotes and periods.
HEX/BIT: Variable must be a valid hexadecimal or binary string.
LEN, relation-operator, expected-length: Variable length must satisfy the condition expressed by relation-operator, expected-length. Valid operators that should be enclosed in quotes are EQ, LT, GT, LE, GE, NE, NG, or NL. The expected length operand should be a positive integer or a dialog variable containing the value.
RANGE, lower, higher: Variable must be numeric with optional leading sign and fall within the range specified.
LIST, value1, value2, …: Variable must be one of the listed values.
DBCS | EBCDIC | MIX: Variable must be all valid DBCS | EBCDIC | MIXED DBCS / EBCDIC characters.
Every panel definition must end with an )END section header. This section header has no keywords, and the panel display process ignores anything following it.
To display panels in a REXX EXEC, we use the ISPEXEC service to invoke functions as with other ISPF services. The display services are categorized as follows:
DISPLAY PANEL (panel): This displays the panel.
ADDPOP: This allows subsequent panels to be displayed in a pop-up window.
REMPOP: This removes the pop-up window display.
SETMSG MSG (message-id): This displays a message.
The following sequence of commands displays the panel pnlname whose definition is stored in panels.dataset as a pop-up window.
"Ispexec libdef ispplib dataset id ('panels.dataset')"
"ADDPOP"
"Ispexec display panel (pnlname)"
"REMPOP" |
/* A simple Panel Definition */
)ATTR DEFAULT (%+_)
% TYPE (TEXT) INTENS (HIGH)
+ TYPE (TEXT) INTENS (LOW)
_ TYPE (INPUT) INTENS (HIGH) CAPS (ON) JUST (LEFT)
)BODY
+ A Sample panel - REXX Training
+ -------------------------------------
+
+ %Enter your name please ==>_urname +
+
+ %Name cannot exceed more than 15 chars +
+
+ +Press ENTER to continue,PF3 to exit +
+
+
+
)INIT
)PROC
VER (&URNAME,NB,ALPHAB)
)END |
Write a panel definition which gets the input of name and age of the user. And write a sample code to call the panel and to display the panel inputs like name and age of the user.
Panel Definition:
)ATTR
% TYPE (TEXT) INTENS (HIGH) COLOR (GREEN)
# TYPE (TEXT) INTENS (HIGH) COLOR (YELLOW)
¢ TYPE (TEXT) INTENS (HIGH) COLOR (WHITE) CAPS (OFF)
_ TYPE (INPUT) INTENS (LOW) COLOR (GREEN) PAD (_)
$ TYPE (OUTPUT) INTENS (HIGH) COLOR (BLUE)
)BODY
*--------------------------------------------------------------------*
#WELCOME TO ELT TRAINEE PAGE
*--------------------------------------------------------------------*
TIME:$TIM %
DATE:$DAT %
ENTER YOUR NAME: _Z
ENTER YOUR AGE: _Z %
*--------------------------------------------------------------------*
)INIT
.ZVARS = '(NAME AGE)' &NAME = ''
&AGE = ''
)PROC
)END
Main Program:
/******************************** REXX ********************************/
INITIATE:
TIM = TIME ()
DAT = DATE ()
ADDRESS ISPEXEC
"DISPLAY PANEL (PDISPLAY)"
SAY 'YOUR NAME:' NAME
SAY 'YOUR AGE:' AGE
SAY 'ALL THE BEST FOR YOUR FUTURE'
EXIT |
This code will call the panel pdisplay the panel.
The panel gets the input from the user and displays it.
For panel display return code may be evaluated. Successful operation is denoted by RC of 0 while a non-zero return code suggests failure.
For better understanding of the code, proper comments must be given.
ISPF panels can be used for data entry and display. The use of ISPF tables and Panels has made many applications user-friendly and easy to maintain.
Various sections that make up a Panel Definition are )PANEL, )ATTR, )BODY, )INIT, )PROC, )END. ADDPOP and REMPOP services can be used to display the panel as a pop-up.
The panels are displayed using
ADDPOP
REMPOP
Both
If you have any doubts or queries related to this chapter, get them clarified from our Mainframe experts on ibmmainframer Community!