PANEL RUNTIME

The format of the PANEL RUNTIME commands follow.

Read syntax diagramSkip visual syntax diagram>>-PANEL--+-Send-----+--panel_name------------------------------>
          +-Receive--+
          +-Converse-+
          +-Test-----+
          +-End------+
          '-Generate-'
 
>--+----------------------------+------------------------------->
   '-FIle--(--directory_name--)-'
 
>--+-------------------------------+---------------------------->
   '-CUrsor--(--+-field_id----+--)-'
                '-row--column-'
 
>--+-----------------------------------+--+-------+------------->
   '-ATtrib(field_id attribute_values)-'  '-ALarm-'
 
>--+---------+--+-----------------------------+--+--------+----->
   '-NOErase-'  '-POsition--(--row--column--)-'  +-FReekb-+
                                                 '-LOckkb-'
 
                               .-UNProtect-.  .-NORmal----.
>--+----------+--| options: |--+-----------+--+-----------+----->
   '-CLrinput-'                +-PRotect---+  +-BRight----+
                               '-SKip------'  '-INVisible-'
 
                                 .-NOJustify-.
>--+-GReen-----+--+-BLInk-----+--+-----------+------------------>
   +-RED-------+  +-REVerse---+  +-LEft------+
   +-BLUe------+  '-UNDerline-'  '-RIght-----'
   +-TUrquoise-+
   +-WHite-----+
   +-YEllow----+
   +-PInk------+
   '-DEfcolor--'
 
           .-NULls--.
>--PAd--(--+--------+--)--NUMeric--CUrsor--MDT-----------------><
           +-BLAnks-+
           '-char---'
 

Operands

Send
is the panel command that sends a panel.
Receive
is the panel command that receives a panel.
Converse
is the panel command that sends a panel and waits for operator input.
Test
is the panel command that displays a panel. An intermediate file (panel object) is not created and variable substitutions are not attempted.
End
is a command that terminates the panel session. Command releases all storage held by the panel facility. This command does not have arguments and any arguments supplied are ignored.
Generate
is an explicit command that creates a panel object. The panel is not displayed.
panel_name
specifies the name of the panel to input/output or generate.
FIle()
specifies the name of the RFS directory (directory_name) containing this panel. (Specified for all panel commands except END.)
CUrsor()
(specified for SEND and CONVERSE only) positions the cursor on the panel.
field_id
specifies the REXX variable name where the cursor should be positioned on the panel.
row
specifies the row within the panel where the cursor should be positioned. The row value is relative to the starting row of the panel. The default starting row of the panel is 1, but may be changed using the POSITION() keyword.
column
specifies the column within the panel where the cursor should be positioned. The column value is relative to the starting column of the panel. The default starting column of the panel is 1, but may be changed using the POSITION() keyword.
ATtrib(field_id attribute_values)
(specified for SEND and CONVERSE only)
field_id
specifies the field whose attributes are dynamically set. It must be a variable name associated with the field. The field list must be enclosed with parenthesis. Only the attributes stated are changed and the other attributes default to what was statically defined. A field defined originally as RED and UNDERLINE remains underlined if only blue is stated dynamically.
ALarm
(specified for SEND and CONVERSE only) sounds the bell when displaying panel. (The default is no alarm).
NOErase
(specified for SEND and CONVERSE only) do not erase the screen before displaying this one. (The default is erase before a panel write).
POsition()
(specified for SEND, CONVERSE, and RECEIVE only) positions the panel on the output screen. Row (row) and column (column) specifies where the top left corner of the panel should begin. (The default is row 1 col 1). For example, POS(5 10) means to have the panel start in row 5 and column 10, the actual movement is 4 rows down and 9 columns to the right.
FReekb
(specified for SEND and CONVERSE only) frees the keyboard, allowing operator input. (This is the default.)
LOckkb
(specified for SEND and CONVERSE only) locks the keyboard.
CLrinput
(specified for SEND and CONVERSE only) clears all input fields before displaying the panel. Variable substitution is not attempted and pad characters fill the input area.

Options

UNProtect
specifies that the field is not protected from operator input.
PRotect
specifies that the field is protected from operator input.
SKip
specifies a protected field with the auto-skip feature. Operator entering a character in the last position of the previous unprotected field causes the cursor to skip over this field.
NORmal
specifies that the field is not highlighted.
BRight
specifies that the field is highlighted.
INVisible
specifies that the field is invisible.
GReen
RED
BLUe
TUrquoise
WHite
YEllow
PInk
DEfcolor
are the choices for the color.
Notes:
  1. When you do not specify a default color, the color is based on the field type and intensity values: protect/normal displays blue, protect/bright displays white, unprotect/normal displays green, and unprotect/bright displays red.
  2. If any field on a panel has explicitly specified a color (including DEFCOLOR), all bright fields with DEFCOLOR or no color specified are displayed white and all normal fields with DEFCOLOR or no color specified are displayed green. This is a 3270 hardware limitation and not the panel facility.
BLInk
specifies that the field blinks.
REVerse
specifies that the field is in reverse video.
UNDerline
specifies that the field is underlined.
NOJustify
specifies that no justification is done (left justified but blanks are not stripped).
LEft
specifies that the field is left justified (leading blanks will be stripped).
RIght
specifies that the field is right justified (trailing blanks will be stripped).
PAd()
specified only in context of fields having variables. In an unprotected field the pad character fills the character positions that are not occupied by a variable value. In a protected field, the pad character is similar but the scope of the fill area is not the whole field as in the unprotected field. It is bound by where the variable starts, within the protected field to either the end of the field or the start of the next variable or text.
NULls
specifies that a field will be padded with the null character.
BLanks
specifies that a field will be padded with blanks.
char
specifies a single character to be used to pad a field.
NUMeric
specifies a field is numeric (unprotected field only).
CUrsor
specifies that the cursor is positioned at the beginning of this field. If multiple cursor fields are defined, then the last one defined contains the cursor. The cursor is placed in the top left corner if a cursor field is not defined.
MDT
(specified for SEND and CONVERSE only) sets the modify bit tag for all input fields on the panel.

PANEL Variables

The implicitly defined PANEL variables that can be used by the REXX program follow.

PAN.AID
Attention identifier that last caused panel input.
ENTER   ENTER
CLEAR   CLEAR
CLRP    CLEAR PARTITION
PEN     SELECTOR PEN
OPID    OPERATOR ID
MSRE    MAGNETIC READER
STRF    STRUCTURE FIELD
TRIG    TRIGGER
PA1
PA2
PA3
PF1
PF2
PF3
PF4
PF5
PF6
PF7
PF8
PF9
PF10
PF11
PF12
PF13
PF14
PF15
PF16
PF17
PF18
PF19
PF20
PF21
PF22
PF23
PF24
PAN.CURS
Position of cursor in last panel input. This is in the form of row column separated by a blank. For example, '10 5' would be row 10 and column 5. The row and column values are absolute to the start of the screen and are unaffected by the POSITION() keyword.
PAN.CNAM
REXX variable name (field ID) associated with the cursor position. If the field has no associated variable then PAN_CNAM is not updated.

The PANEL error related variables follow.

PAN.REA
Reason code if warning or error occurs. REXX return code, RC, should be examined first. If the RC is 10, PAN.REA contains state codes and input codes to help in error determination. See section State Codes and Input Codes for more information.
PAN.LOC
Internal location code. Three to four-digit number used by IBM support. If the REXX variable RC contains the value 10, the PAN.LOC should be used in conjunction with PAN.REA for error determination.
PAN.LINE
Line number in the source panel definition where an error was detected, if error occurred during panel object generation.

Panel Facility Return Code Information

The main return code for the panel command is set in the REXX variable, RC. Each level of return code is accompanied by additional information in the form of a reason code and a line number (if applicable). When an error is detected while processing panel source code (location code of 11xx or 12xx) and RC is not 12 or 16, the REXX variable PAN.LINE contains the number of the line in error.

Return Codes

4
Warning. Panel facility continues processing. Processing stops for other return code values.
8
Programmer error
10
Programmer error, PAN.REA contains more information to help determine the cause of the error. See section State Codes and Input Codes for more information.
12
CICS command error; the CICS EIBRESP is returned in the panel reason code. If the error is not programmer resolvable, save and collect as much information as needed to recreate the error and contact IBM support.
14
RFS errors; reason code contains the RFS return code
16
Internal system error; save and collect as much information as needed to recreate the error and contact IBM support.

System Error Reason Codes

401
Panel facility ran out of storage space while processing the command
402
Internal control character identifier table and control character informational table are out of synchronization
403
Panel object data has been corrupted. First check to see the file is correct and that it is a panel object.
404
CICS receive buffer corrupted
405
Bad validation request
406
Storage free request failed
407
Storage get request failed
408
Attempt to get/put REXX variable failed
409
Aid is unknown
410
Dynamic match error

Programmer Introduced Warning/Error Reason Codes

101
Keyword repeated or keyword within a like category was repeated. For example, RED and BLUE; UNDERLINE and REVERSE.
102
Keywords are incompatible. For example, PROTECT and NUMERIC
103
Missing keyword or panel name
104
The control character being defined is invalid or missing
105
Panel is too large for the screen
108
Parenthesis missing
109
Pad character invalid
110
Task has no associated terminal
111
Panel has no input fields defined during a receive
112
Panel name is invalid
115
REXX variable name (or field ID) is invalid
116
Number is specified incorrectly. Explicit length value in panel source or row col value
117
Variable value was too long and was truncated to fit output field
118
Text field was truncated. Check to see if explicit length did not force a subsequent field to overlay another field.
119
Bad or missing panel command. It should be SEND, RECEIVE, CONVERSE, TEST, or END.
122
A modified field was received but it had no corresponding input field definition.
124
Empty received buffer. Clear, ENTER, and the PA keys will cause this.
125
File name is invalid
126
Field identifier for the ATTRIBUTE keyword was not found in the panel.
129
Too many arguments supplied with the command
130
SEND must be performed before a RECEIVE
131
Panel source has no panel definition. '.PANEL' was probably not in column 1 or did not have a space after.
132
Keyword encountered is unknown
133
DROP asked for a control character not presently active
136
Continuation is in effect but end of source was encountered
137
Row or column specified is too large for the current display CURSOR() or POSITION() the likely source of error.
138
Variable identifier control character was being defined and more than one stem name was listed.
139
More variable fields defined than listed in the control character definition.
140
Explicit input field value caused field to go past screen end
143
Panel name in file does not match the panel name in the panel runtime command.
144
Panel has more rows than the present screen allows
145
Panel has more columns than the present screen allows

State Codes and Input Codes

For return code 10 the reason code (in PAN.REA) has a special meaning. It consists of two 2-digit numeric codes, the first number stating what keyword is being processed (state code) and the second number stating the input that caused the error condition (input code). Use the location code (in PAN.LOC) to determine which state code list and input code list to use.

For example:

RC = 10
PAN.REA = 0199
PAN.LOC = 1177

When you use the state code and input code lists for the 11xx location codes, the keyword being processed was .DEFINE for state code 01 and the input code contained an unknown symbol for input code 99.

State codes

State codes for 11xx location codes:

01
.DEFINE and control char
02
field type (protect/skip/unprotect)
03
color (red/blue/green/...)
04
Intensity (bright/normal/invisible)
05
Justify (left/right/nojustify)
06
Numeric
07
extended highlight (blink/reverse/underline)
08
MDT
09
Cursor
10
Pad()
11
Variable
12
Drop

State codes

State codes for 20xx location codes:

01
panel commands (send/receive/converse/...)
02
File()
03
Cursor()
04
Position()
05
Alarm
06
Noerase
07
Keyboard lock (lockkb/freekb)
08
Clrinput
09
Attribute
10
field type (protect/skip/unprotect)
11
color (red/blue/green/...)
12
Intensity (bright/normal/invisible)
13
Justify (left/right/nojustify)
14
Numeric
15
extended highlight (blink/reverse/underline)
16
MDT
17
Cursor
18
Pad()
19
closing parenthesis of the ATTRIBUTE argument

Input codes

Input codes for 11xx and 20xx location codes:

01
field type (protect/skip/unprotect)
02
color (red/blue/green/...)
03
Intensity (bright/normal/invisible)
04
Justify (left/right/nojustify)
05
Numeric
06
extended highlight (blink/reverse/underline)
07
MDT
08
Cursor
09
Pad()
10
Variable
11
Drop
12
(not used)
13
File()
14
Cursor()
15
Position()
16
Alarm
17
Noerase
18
Keyboard lock (lockkb/freekb)
19
Clrinput
20
Attribute
21
closing parenthesis of the ATTRIBUTE argument
98
End of command; more operands were expected
99
Unknown symbol; keyword or control character was expected

State Codes

State codes for 12xx location codes:

01
panel name
02
protect/skip field
03
unprotect field
04
text within a protect/skip field
05
(not implemented yet)
06
explicit input field length number
07
unprotect variable
08
protect/skip variable

Input codes

Input codes for 12xx location codes:

01
Plain displayable text
02
Explicit length number
03
Protect field control character
04
Unprotect field control character
05
Variable control character
07
End of panel
08
Invalid or unknown input

Location Codes

Numbers under 1000 are in the mainline processor.

10xx
Panel generator common processor
11xx
.DEFINE verb processor
12xx
.PANEL verb processor
20xx
Panel runtime command processor
21xx
Dynamic attribute resolution processor
30xx
Output 3270 data stream processor
40xx
Input 3270 data stream and REXX variable assignment processor
90xx
CICS interface processor