Designing Panels

12-1
This section describes what to put in a panel definition: how to define constant data, and input and output fields. The panel control statements can be used to embed comments in panel definitions, to define fields, and to interact with NCL processes.
For information about how NCL processes use panel definitions, see Network Control Language Programming.
Panel Control Statements
Optional control statements can precede a panel to specify the particular requirements for that panel. These are as follows:
#ALIAS
Defines an alternative name for an input variable.
#OPT
Defines optional operational requirements.
#FLD
Defines or modifies a field character’s attributes.
#ERR
Defines the action to be taken for an error condition.
#NOTE
Provides installation documentation (this is ignored during processing).
#TRAILER
Provides a means of placing specified panel lines at the end of the panel (regardless of screen size).
Control statements included within panel definitions must precede the displayable portion of the panel (as determined from the first non-control statement encountered). Control statements must start in column 1 of the lines on which they appear.
Before a panel is displayed, its associated control statements are parsed and any variable substitution performed. This lets you tailor control statements dynamically.
Data in Panels
Panels contain a combination of fixed data and variable output data:
  • Fixed data is the screen captions, field identification text, and other static screen information defined when the panel is created. This does not change when the panel is displayed.
  • Variable output data is data generated by the system while the panel is being displayed. It replaces variables positioned within the panel created by the editor. Data is extracted from NCL variables available at the time the panel is invoked.
Variable output data can be displayed in:
  • Protected output-only fields (where the data comprises either system or user variables), or
  • Unprotected input fields, for any user variables. Once displayed, you can enter data into the unprotected input fields. Panel Services then inserts this data into the user variable for each field, so it is available for further processing by NCL procedures.
Panel Design
A panel design contains a series of lines, each of which can contain one or more fields.
Each field is preceded by a field character that identifies the attributes for that field. These attributes specify:
  • The field type (input, output, selector pen detectable (SPD), or null)
  • The intensity (brightness) of the display
  • Optional formatting rules
  • Optional editing rules
  • The color and extended highlighting used when the field is displayed (for appropriate terminals)
Field Characters
Each panel line has one or more fields, starting with a field character that specifies the field attributes.
Within the #FLD control statement at the top of the panel definition, you must specify which characters are required for different types of field.
You can use the following methods to define field characters:
Character mode
-- To specify character mode, use any special character other than an alpha or numeric character, and excluding ampersand (&), blank, or null.
Hexadecimal mode
-- To specify hexadecimal mode, enter the hexidecimal value for the character (for example, as X‘FA’). Use any hexidecimal value in the range X‘00’ to X‘FF’, excluding the values X‘00’ (null), X‘40’ (blank), X‘50’ (ampersand -- &), X‘0E’, and X‘0F’. Hexadecimal mode is used when you need a very large number of field types within one panel and there are insufficient special keyboard characters available to accommodate all of the field characters you require.
Field Types
Each field is allocated a field type that specifies the method for processing the field. The following field types are supported:
OUTPUT
Display only -- no data can be entered from the screen.
INPUT
You can both display and enter data.
SPD
Selector pen detectable -- data cannot be typed in.
NULL
Display only -- although unprotected, any data entered is ignored.
Any mixture of the above field types can be defined to suit the requirements for a panel you are designing.
The field character that precedes each field determines:
  • The field type.
  • The display characteristics of the field (such as intensity, color, highlighting, justification, and capitalization).
  • For input fields, the internal validation rules that must be obeyed for data entered in that field. Such rules can specify, for example, that a field is mandatory, must be numeric, cannot contain imbedded blanks, or must be a valid date.
Each field character that you define occupies the equivalent screen position when the panel is displayed, but appears as a blank character (the attribute byte).
The field proper starts from the next position after the field character, and continues to the next attribute byte on the same line, or to the end of that line where there is no intervening field. Fields do not wrap round from one line to the next.
Field characters can be specified either in character, in which case they are always special characters (non-alpha, and non-numeric; for example, *, %), or in hexadecimal.
The standard default field characters are as follows:
%
High-intensity, protected (no input)
+
Low-intensity, protected (no input)
_
High-intensity, unprotected (input, no validation)
These standard default field characters do not require definition by a #FLD Statement statement.
Define any additional field characters you need using the #FLD Statement statement. The attributes for the above default field characters can be modified. You can use the #OPT statement to nominate alternative standard field characters, so that %, +, and _ can be used within the panel and not processed as field characters, if required.
Column 1 of each line of a panel must be a valid field character; if one is not defined, then the attributes for the second standard field character (normally +, for low-intensity, protected) are used to replace any data incorrectly placed in that column.
In the figure below, all fields preceded by a percent sign (%) display in high-intensity and are protected from data entry. All fields preceded by a plus sign (+) display in low-intensity and are also protected. The only field available for input is on line 16 of the text data, preceded by an underline (_). The word newpanel identifies the NCL variable that receives the data that the user enters in this field once the Enter key is pressed.
By default, the cursor is placed at the beginning of the
cmd
field, as this is the first field requiring input -- no other cursor position has been specified.
 The ampersand (&) that precedes a variable is omitted when specifying an input field. 
LIB: PANLUSR------------------ MODS : Edit Panel ----------------NAME: PANEL001  Command ===>                                                   Scroll ===> CSR                                                                                                                                                                     LINE <---+----10---+----20---+----30---+----40---+----50---+----60---+----70-->  **** ****************************** TOP OF DATA *******************************                                    %MODS : Rename Panel                                +Command ===>_cmd                                                                                                                                                                                                                                                                                                                   %   Current Panel Definition                                                                                                                                      +   Path ....................%&path      +                                                                                                                        +   Library .................%&lib  +                                                                                                                             +   Panel Name ..............%&oldpanel +                                                                                                                         %   Enter New Panel Name                                                                                                                                          +   New Panel Name .........._newpanel +
When a panel is displayed, field characters are removed and the required terminal attribute characters substituted. The following figure shows how the panel is displayed.
 In all figures, the underline symbol (_) designates the cursor location.
                              MODS : Rename Panel  Command ===> _     Current Panel Definition     Path ....................______________     Library ................._______     Panel Name ..............__________     Enter New Panel Name     New Panel Name ..........________
Allowing Long Field Names in Short Fields
An input field is defined on a panel by inserting an appropriate attribute character followed by the name of the NCL variable that contains the input data. Unfortunately this means that input fields cannot be any shorter than the variable name that contains the input data.
The #ALIAS control statement lets you define an alias name for a variable. The alias can be used where the variable would have been used. A range or list of variables can be defined and referred to by the same alias name in the panel definition.
Output Padding and Justification
Careful use of padding and justification greatly enhances the look and effectiveness of panels for end-users.
Panel Services includes extensive facilities to manipulate displayed data. Padding and justification qualities are specified by the #FLD Statement statement. There are two justification categories -- field-level justification, and variable-level justification. Both can be used concurrently.
Field-Level Justification
This is performed on an entire field as delimited by defined field characters. Field justification analyzes the entire field, strips trailing blanks, and pads and justifies the remaining data. The #FLD Statement operands controlling field-level justification are JUST and PAD.
The various ways data can be manipulated are best described by a series of examples. These examples show a mix of fields each defined with a different field character and each showing a different display format. Study the #FLD Statement statements and observe the results achieved.
#NOTE   This sample panel definition gives examples of the #NOTE   use of field level justification and padding. #FLD   # #FLD   $   JUST=RIGHT #FLD   @   JUST=LEFT PAD=< #FLD   ?   JUST=RIGHT PAD=> #FLD   /   JUST=CENTER PAD=. #&VAR01                                 + @&VAR03                                 + ?&VAR04                                 + /&VAR05                                 +
Assume the following variable assignment statements are executed by the NCL procedure before displaying the sample panel:
&VAR01 = &STR Left justified null padding &VAR02 = &STR Right justified null padding  &VAR03 = &STR Left justified with padding  &VAR04 = &STR Right justified with padding  &VAR05 = &STR Center justified with padding
The default values are JUST=LEFT and PAD=NULL, as shown by the first line in the example below, where field character # is used with no attributes other than the defaults. The sample panel is displayed as follows:
Left justified null padding          Right justified null padding Left justified with padding<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<< >>>>>>>>>>>>>>>>>>>>>>>>>>>>>>Right justified with padding ..............Center justified with padding............... 
Variable-Level Justification
This operates independently of field-level justification, and applies to the data substituted for field variables defined as requiring variable-level justification. Variable-level justification is designed to help tabulated output, where data of differing lengths is substituted for a series of variables and where the normal substitution process disrupts display formats. The #FLD Statement operands that control variable-level justification are VALIGN and PAD.
The substitution process substitutes data in place of the &variable without creating additional characters. Thus, if a variable (for instance, &VARIABLE) is replaced by data (for example, Data), any characters following this are moved left to occupy any spaces remaining after substitution (this occurs if spaces are freed going from a long variable name to a shorter data length).
#NOTE   This sample panel definition gives examples of the #NOTE   use of variable justification, padding, and field #NOTE   justification. #FLD # VALIGN=LEFT #FLD $ VALIGN=RIGHT #FLD @ VALIGN=CENTER #FLD ? VALIGN=LEFT PAD=. #FLD / VALIGN=RIGHT PAD=. #FLD } VALIGN=CENTER PAD=. #FLD ! VALIGN=LEFT JUST=RIGHT PAD=. #&VARIABLE other data               + $&VARIABLE other data               + @&VARIABLE other data               + ?&VARIABLE other data               + /&VARIABLE other data               + }&VARIABLE other data               + !&VARIABLE other data               +
Variable-level justification, controlled by the VALIGN operand of the #FLD statement, lets you influence the way substitution is performed.
 Variable-level justification is only performed if the length of the data being substituted is less than the length of the variable name being replaced, including the ampersand (&).
Assume the following variable assignment statement has been executed by the NCL procedure before displaying the sample panel:
&VARIABLE = Data
&VARIABLE is the only variable within a field that contains the words ‘other data’. Where both field justification and variable alignment are used, the padding character applies to both, as shown by the last line of the example for the field character !. The sample panel is displayed as follows:
Data    other data Data other data Data  other data Data..... other data .....Data other data ..Data... other data .................................Data..... other data
Input Padding and Justification
Fields to which the PAD and JUST operands of the #FLD statement are applied can be defined as input fields. If an input field is primed with data during the display process, the alignment of data within that field when displayed is similar to output padding and justification, except that JUST=CENTER is treated as JUST=LEFT.
When Panel Services processes input from the screen, input fields defined using the PAD and JUST operands are specially processed using the following rules:
  • Trailing blanks and pad characters are stripped off, unless the pad character is numeric.
  • If JUST=RIGHT is specified for the field, leading blanks and pads are stripped off (including numeric pads).
  • If JUST=ASIS is specified for the field, trailing blanks and pads are stripped off, but leading blanks and pads remain intact.
#NOTE   This sample panel definition gives examples of the #NOTE   use of input padding and justification. #FLD # TYPE=INPUT #FLD $ TYPE=INPUT JUST=RIGHT #FLD @ TYPE=INPUT PAD=< JUST=LEFT #FLD ? TYPE=INPUT PAD=> JUST=RIGHT #FLD / TYPE=INPUT PAD=0 JUST=LEFT #FLD } TYPE=INPUT PAD=1 JUST=RIGHT #VAR01                                 + $VAR02                                 + @VAR03                                 + ?VAR04                                 + /VAR05                                 + }VAR06                                 +
Assume the following variable assignment statements are executed by the NCL procedure before displaying the sample panel:
&VAR01 = Walt &VAR02 = Tom &VAR03 = Dick &VAR04 = Harry &VAR05 = John &VAR06 = Vicky
The sample panel is displayed as:
WALT                                      TOM DICK<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<< >>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>HARRY JOHN000000000000000000000000000000000000 11111111111111111111111111111111111VICKY
If control is passed back to the NCL procedure without any data entered into the input fields, the variables are set to the following values:
&VAR01 = WALT &VAR02 = TOM &VAR03 = DICK &VAR04 = HARRY &VAR05 = JOHN &VAR06 = VICKY
 If the line JOHN000... is modified, it is padded to the right with zeros. The variable values are translated to uppercase because the default for input fields is CAPS=YES.
Displaying Function Key Prompts
The SAA Common User Access (CUA) standards require that a list of function keys and their functions be displayed at the bottom of a panel. These function key prompts are displayed on the last lines of the physical screen.
The #TRAILER control statement can be used by NCL procedures to nominate lines that appear at the bottom of the panel. The function key prompts are then always displayed at the bottom of the panel regardless of the screen size.
Panel Statements
This section describes the panel statements.
ALIAS Statement
This statement defines an alternative name for input variables and allows the panel definition to contain alternative names for variable names in TYPE=INPUT and TYPE=OUTVAR fields.
This facility is useful if you require short fields with long variable names. Each reference to
name
in the panel definition is regarded as a reference to the next name from the list of VARS specified.
This statement has the following format:
#ALIAS 
name
     { VARS=
prefix
*[ RANGE=(
start,end
) ] |        VARS={ 
vname
 | (
vname,vname
,…,
vname
) } }
name
Specifies the alias name that appears in the panel definition. Whenever this name occurs in a field declared as TYPE=INPUT or TYPE=OUTVAR
on the #FLD statement, panel services logically replaces it with the next available name from the VARS list.
The name can be from one to eight characters in length. The first character must be an alphabetic or national character. The remaining characters, if any, must be alphanumeric or national characters.
The same name can be used on multiple #ALIAS statements. The variable names are added to the end of the list of names to which the alias name refers.
VARS=
prefix
* [ RANGE=(
start,end
) ] |VARS=(
vname,vname, ..., vname
)  }
Specifies the list of names that replaces the alias name in the panel definition. Each time the alias name is encountered in the panel definition it is replaced by the next available name from this list. The format of the operands associated with VARS= is:
VARS=
prefix
* denotes that the variable names used are
prefix
1,
prefix
2, and so on. The RANGE= operand can be specified to indicate a starting and ending suffix number. The default is RANGE=(1,64). The format
prefix
* cannot be used in conjunction with other variable names on the same #ALIAS statement.
VARS=
vname
is the name of a variable excluding the ampersand (&).
Examples:
#ALIAS Z VARS=LONGNAME #ALIAS Z123 VARS=(SATURDAY,SUNDAY) #ALIAS AVAR VARS=LINE* RANGE=(10,20)
Notes:
  • Multiple #ALIAS statements can be used for the same alias name if insufficient space is available on a single statement
    .
  • If an alias name appears in the panel definition after all the variable names in the alias list have been used up, the alias name itself appears in the panel.
  • Symbolic variables can be included in the #ALIAS statement. Variable substitution is performed prior to processing the statement, using variables available to the NCL procedure at the time the &PANEL statement is issued.
ERR Statement
This statement defines action to be taken during error processing.
The #ERR statement is a panel control statement that determines the processing required when a panel is being redisplayed following an error condition.
An error condition can be detected either by Panel Services internal validation or by the processing NCL procedure. If detected by internal validation (and &CONTROL PANELRC is not in effect), error processing is automatically invoked by Panel Services. If detected by the processing NCL procedure, error processing is invoked in one of two ways:
  • Using the &ASSIGN OPT=SETERR verb
  • By nominating the name of the variable that identifies the invalid input field on the ERRFLD operand of the #OPT statement. This is dynamically invoked by using a symbolic variable with the ERRFLD operand and setting this variable to the name of the variable (minus the ampersand) that identifies the field in error.
For information about using this technique, see Network Control Language Programming.
When #ERR processing is initiated, the cursor is positioned to the first field in error and the panel is redisplayed, applying the attributes defined on the #ERR statement to the fields in error. This technique provides the panel user with a simple means of drawing the terminal operator’s attention to the field in error. This is particularly effective on color terminals where the color of any field in error can be altered for the duration of the error, and reverts to normal when the error condition is rectified.
One or more #ERR statements can be defined in any order. However, as with #OPT, #FLD, and #NOTE statements, any #ERR statement must precede the start of the panel, which is determined by the first line that is not a control statement.
This statement has the following format:
#ERR [ INTENS={ HIGH | LOW } ]    [ { COLOR | COLOUR }={ BLUE | RED | PINK | GREEN |                         TURQUOISE | YELLOW | WHITE | DEFAULT } ]    [ { HLIGHT | HLITE }={ USCORE | REVERSE | BLINK | NONE } ]      [  ALARM={ YES | NO } ]
INTENS={ HIGH | LOW }
Determines the intensity of the error field when displayed. The INTENS operand is ignored for terminals with extended color and highlighting when either the COLOR or HLIGHT operands are specified.
HIGH specifies that the field is displayed in double intensity.
LOW specifies that the field is displayed in low or standard intensity.
{ COLOR | COLOUR }={ BLUE | RED | PINK | GREEN | TURQUOISE |                                                YELLOW | WHITE| DEFAULT }
Determines the color of the field. It applies only to IBM terminals with seven-color support and Fujitsu terminals with three- or seven-color support.
The COLOR operand is ignored if the terminal does not support extended color. This enables COLOR to be specified on panels that are displayed on both color and non-color terminals. COLOR can be used in conjunction with the HLIGHT operand.
For Fujitsu terminals that support extended color data streams, but support only three colors, the following color relationships are used:
GREEN
When GREEN is specified, it produces a result of GREEN on a Fujitsu three-color terminal.
RED
When RED is specified, it produces a result of RED on a Fujitsu three-color terminal.
PINK
When PINK is specified, it produces a result of RED on a Fujitsu three-color terminal.
BLUE
When BLUE is specified, it produces a result of GREEN on a Fujitsu three-color terminal.
TURQUOISE
When TURQUOISE is specified, it produces a result of GREEN on a Fujitsu three-color terminal.
YELLOW
When YELLOW is specified, it produces a result of WHITE on a Fujitsu three-color terminal.
WHITE
When WHITE is specified, it produces a result of WHITE on a Fujitsu three-color terminal.
DEFAULT
When DEFAULT is specified, it produces a result of GREEN on a Fujitsu three-color terminal.
Fujitsu seven-color terminals are treated the same as IBM seven-color terminals.
The DEFAULT keyword indicates that the color of the field is determined from the INTENS operand. This is particularly useful if you want to set the color from an NCL procedure (that is, COLOR=&COLOR is specified and the NCL procedure can set the &COLOR variable to DEFAULT).
{ HLIGHT | HLITE } = { USCORE | REVERSE | BLINK | NONE  }
Applies only to terminals with extended highlighting support, and determines the highlighting to be used for the field.
Because the HLIGHT operand is ignored if the terminal does not support extended highlighting, HLIGHT can be specified on panels that are displayed on terminals that do not support extended highlighting. HLIGHT can be used with the COLOR operand.
When NONE is specified, the HLIGHT operand is ignored and no extended highlighting is performed for this field.
ALARM={ YES | NO }
Turns the terminal alarm on or off if the panel is displayed with an error condition. This works independently of the ALARM operand on the #OPT control statement.
Examples:
#ERR COLOR=RED HLIGHT=REVERSE ALARM=YES #ERR COLOR=YELLOW HLIGHT=BLINK INTENS=HIGH
Notes:
  • Only those attributes defined on the #ERR statement are modified for the field in error. All other attributes associated with the original field, such as internal validation, remain intact
  • Symbolic variables can be included in a #ERR statement. Variable substitution is performed before processing the statement, by using variables available to the NCL procedure at the time the &PANEL statement is issued.
  • When &CONTROL PANELRC is in effect, internal validation does not automatically reshow the panel with the error message, and so on. In this case, the procedure regains control following the &PANEL statement with the &RETCODE system variable set to 8 to indicate that an error has occurred. The &SYSMSG variable contains the text of the error message that describes the error and the &SYSFLD variable contains the name of the field in error. This name is the name of the variable in an input field that receives the data entered into that field.
  • The &ASSIGN statement SETERR option provides a mechanism for assigning #ERR field attributes to multiple (input field) variables before displaying a panel. This lets you accept input from a number of different fields on a panel, validate all the fields and then redisplay the panel with all incorrect fields displayed with the #ERR attributes. This shows the user all the errors at one time, rather than field by field.
FLD Statement
This statement defines or modifies a panel definition field character.
The #FLD statement is a panel control statement used to tailor the operational characteristics of a panel.
When a panel is defined, it is constructed of a number of lines that, in turn, are made up of a number of fields. Each field commences with a field character that appears as a blank on the panel when displayed. Each field character determines the attributes that are to be associated with the field following the field character itself. A field is delimited by the next field character or the end of the panel line. Fields cannot wrap from one line to the next.
The first field on a line always starts in column 1. If no field character is defined in the first position of the line, the attributes of the second of the three standard field characters (usually a plus sign (+), TYPE=OUTPUT, INTENS=LOW) are forced and replace any non-field character incorrectly placed in this position.
Before parsing, the #FLD statement is scanned and variable substitution is performed. This makes it possible to dynamically tailor any of the options or operands on the statement.
As many #FLD statements as required can be specified. They can be defined in any order. However, as with #OPT, #ERR and #NOTE statements, all #FLD statements must precede the start of the panel, which is determined by the first line that is not a control statement.
This statement has the following format:
#FLD {
c
 | X‘
xx
’ }      [ BLANKS={ TRAIL | NONE | ANY } ]      [ CAPS={ YES | NO } ]    [ { COLOR | COLOUR }={ BLUE | RED | PINK | GREEN |                    TURQUOISE | YELLOW | WHITE | DEFAULT } ]      [ CSET={ ALT | DEFAULT } ]      [ EDIT={ ALPHA | ALPHANUM | DATE
n
 | DSN | HEX |               NAME | NAME* | NUM | REAL | SIGNNUM | TIME
n
 } ]    [ { HLIGHT | HLITE }={ USCORE | REVERSE | BLINK | NONE } ]      [ INTENS={ HIGH | LOW | NON } ]      [ JUST={ LEFT | RIGHT | ASIS | CENTER | CENTRE } ]      [ MODE={ SBCS | MIXED } ]      [ NCLKEYWD={ YES | NO } ]      [ OUTLINE={  {L R T B} | BOX } ]      [ PAD={ NULL | BLANK | 
char
 } ]      [ PSKIP={ NO | PMENU } ]      [ RANGE=(
min,max
) ]      [ REQUIRED={ YES | NO } ]      [ SKIP={ YES | NO } ]      [ SUB={ YES | NO } ]      [ TYPE={ OUTPUT | INPUT | OUTVAR | SPD | NULL } ]      [ VALIGN={ NO | LEFT | RIGHT | CENTER | CENTRE } ]
c
| X‘
xx
The field character:
c
is the character that is used in the panel definition to identify the start of the field. This is known as a field character. This must be a single non-alpha and non-numeric character. Any special character (for example, an exclamation mark) can be used, with the exception of an ampersand (&), which is reserved for use with variables.
X‘
xx
’ is the hexadecimal value of the field character. Use this notation to specify any value in the range X‘01’ to X’3F’. Do not use values that correspond to alphanumeric characters, or X‘0E’ (shift in) or X‘0F’(shift out).
Although the panel editor does not let you enter non-displayable hexadecimal attributes (X’01’ to X’3F’) in the body of the panel, you can use the preparse option to prime the field character value in the panel before issuing the &PANEL statement.
The first #FLD statement to reference a particular field character defines a new character. Subsequent statements referencing that same field character modify or extend the attributes of the field character. Three standard field characters (%, +, _ unless altered by the #OPT statement) are provided. If a default field character (usually % + or _) is referenced, it is the same as extending or modifying the attributes of an existing field character.
If no additional operands are defined following a new field character, the following defaults apply:
TYPE=OUTPUT INTENS=LOW
No special attributes or internal validation apply.
BLANKS={  TRAIL | NONE | ANY  }
This determines the format for entering data in input fields. By default, a field can contain imbedded blanks (BLANKS=ANY). Specification of this operand ensures that the entered data does not contain imbedded blanks and contains only trailing blanks (TRAIL) or no blanks at all (NONE). This operand works independently of the REQUIRED operand. For optional fields this operand can still be specified to ensure that when data is entered, it is in the correct format. If &CONTROL PANELRC is not in effect, BLANKS=TRAIL is specified, and the data is in error, Panel Services redisplays the panel with the &SYSMSG variable set to:
INVALID IMBEDDED BLANKS
If BLANKS=NONE is specified and the data is in error, Panel Services redisplays the panel with the &SYSMSG variable set to:
INCOMPLETE FIELD
If &CONTROL PANELRC is in effect, control is returned to the NCL procedure for error handling instead of being handled totally by Panel Services. In this case, &SYSFLD contains the name of the field in error and &SYSMSG the error message text.
CAPS={  YES | NO  }
Applies to input fields only and determines if entered data is converted to upper case before passing it to the NCL procedure in the nominated variable. Conversion to upper case is also performed for the data associated with an input variable before displaying the panel. This does not impact the current contents of the variable unless the data is modified and entered by the operator. Output fields are displayed exactly as defined and are not subject to upper case conversion.
The effect of CAPS=NO can be negated if the variable that receives the data is used in an assignment statement (for example, &A = &DATA) within the processing NCL procedure, as data can be converted to upper case before performing the assignment; see the &CONTROL UCASE option. The CAPS operand is ignored when operating in a system executing with SYSPARMS DBCS=YES.
{ COLOR | COLOUR } = { BLUE | RED | PINK | GREEN |                                          TURQUOISE | YELLOW | WHITE | DEFAULT }
Applies only to IBM terminals with seven-color support and Fujitsu terminals with three- or seven-color support, and determines the color of the field.
Because the COLOR operand is ignored if the terminal does not support extended color, COLOR can be specified on panels that are displayed on both color and non-color terminals. COLOR can be used in conjunction with the HLIGHT operand.
For Fujitsu terminals that support extended color data streams where only three colors are available, the following color relationships are used:
GREEN
When GREEN is specified, it produces a result of GREEN on a Fujitsu three-color terminal.
RED
When RED is specified, it produces a result of RED on a Fujitsu three-color terminal.
PINK
When PINK is specified, it produces a result of RED on a Fujitsu three-color terminal.
BLUE
When BLUE is specified, it produces a result of GREEN on a Fujitsu three-color terminal.
TURQUOISE
When TURQUOISE is specified, it produces a result of GREEN on a Fujitsu three-color terminal.
YELLOW
When YELLOW is specified, it produces a result of WHITE on a Fujitsu three-color terminal.
WHITE
When WHITE is specified, it produces a result of WHITE on a Fujitsu three-color terminal.
DEFAULT
When DEFAULT is specified, it produces a result of GREEN on a Fujitsu three-color terminal.
Fujitsu seven-color terminals are treated the same as IBM seven-color terminals.
The DEFAULT keyword indicates that the color of the field is determined from the INTENS operand. This is particularly useful if you want to set the color from an NCL procedure (that is, COLOR=&COLOR is specified and the NCL procedure can set the &COLOR variable to DEFAULT).
CSET={  ALT | DEFAULT  }
Applies to output fields only. The operand determines which terminal character set to use to display the field. If you specify CSET=ALT (or ALTERNATE), you can draw box shapes using the following characters:
Designing Panels
Designing Panels
CSET=ALT supersedes CSET=ASM in Version 3.1.
EDIT={  ALPHA | ALPHANUM | DATE
n
| DSN | HEX | NAME |                NAME* | NUM | REAL | SIGNNUM | TIME
n
  }
For input fields this determines additional internal editing to be performed by Panel Services. By default no editing is performed. Specification of this operand ensures that the entered data conforms to the nominated type. If a field is mandatory, then REQ=YES should also be specified.
ALPHA
Only accept A to Z.
ALPHANUM
Only accept A to Z, 0 to 9, #, @ and $.
DATE
n
Field must be a valid date. The DATE
n
keyword must correspond to one of the &DATEn system variables, and indicates that the input field must contain date in the format associated with that system variable. For example, EDIT=DATE5 indicates that the input field must always contain a date in the format corresponding to the &DATE5 system variable (MM/DD/YY).
DSN
Field must be a valid OS/VS format data set name. If required, a partitioned data set (PDS) member name or Generation Data Group (GDG) number can be specified in brackets as part of the name.
HEX
Only accept 0 to 9 and A to F.
NAME
Field must commence with alpha (A to Z, #, @ or $) and be followed by alphanumerics (A to Z, 0 to 9, #, @ or $).
NAME*
Field must commence with alpha (A to Z, #, @ or $) and be followed by alphanumerics (A to Z, 0 to 9, #, @ or $) but can be terminated with a single asterisk (*). This allows a value to be entered that can be interpreted as a generic request by the receiving procedure.
NUM
Only accept 0 to 9. Specifying EDIT=NUM, in addition to internal Edit validity checking, sets a hardware flag to inhibit alpha input. This flag is display system dependent for its implementation; either in hardware or emulation software.
REAL
Input in this field must conform to the syntax for integers, signed numbers or real numbers, including scientific notation. For information about real number support, see Network Control Language Programming..
SIGNNUM
Field must be numeric but can have a leading sign (+ or -).
TIME
n
Field must be a valid time. The TIME
n
keyword must correspond to one of the &ZTIME
n
system variables and indicates that the input field must be in the format associated with that system variable.
When invalid data is detected and &CONTROL PANELRC is not in effect, standard error processing is invoked by Panel Services and control is not returned to the NCL procedure until the error is corrected.
For EDIT=NUM the panel is redisplayed with the &SYSMSG variable set to:
FIELD NOT NUMERIC
For EDIT=REAL the panel is redisplayed with the message:
FIELD NOT REAL NUMBER
For EDIT=ALPHA, ALPHANUM, HEX or NAME the panel is redisplayed with the &SYSMSG variable set to:
INVALID VALUE
For EDIT=DATE
n
the panel is redisplayed with the &SYSMSG variable set to:
INVALID DATE
For EDIT=DSN the panel is redisplayed with the &SYSMSG variable set to:
INVALID DATASET NAME  or INVALID MEMBER NAME
For EDIT=TIME
n
the panel is redisplayed with the &SYSMSG variable set to:
INVALID TIME
In all cases the terminal alarm sounds and the cursor is positioned to the field in error. If a #ERR statement has been included in the panel definition, processing of the error condition is performed as defined in that statement.
If &CONTROL PANELRC is in effect, control is returned to the NCL procedure for error handling instead of being handled totally by Panel Services. In this case, &SYSFLD contains the name of the field in error and &SYSMSG the error message text.
Use of the EDIT operand might also require the use of the BLANKS operand to ensure that entered data does not include imbedded blanks. Regardless, editing is performed only for the length of the data entered and not for the length of the input field. If the entire field must be entered, the BLANKS=NONE operand should be specified.
{ HLIGHT | HLITE } = {  USCORE | REVERSE | BLINK | NONE  }
Applies only to terminals with extended highlighting support, and determines the highlighting to be used for the field.
Because the HLIGHT operand is ignored if the terminal does not support extended highlighting, HLIGHT can be specified on panels that are displayed on terminals that do not support extended highlighting. HLIGHT can be used with the COLOR operand.
The NONE keyword is provided as a no-impact value that can be used when the highlighting of a field is being dynamically determined from the NCL procedure and set using variable substitution of the #FLD statement. When NONE is specified, the HLIGHT operand is ignored.
INTENS={  HIGH | LOW | NON  }
Determines the intensity of the field when displayed.
HIGH
The field is displayed in double intensity. High intensity is normally associated with input fields and other important data and its use minimized to maintain its effectiveness.
LOW
The field is displayed in low or standard intensity.
NON
The field is displayed in zero intensity. Any data within the field is not visible to the operator. This is normally used for input fields where sensitive data such as passwords are entered. Use of this attribute for output fields is meaningless. Color or extended high-lighting attributes are ignored when used in conjunction with this attribute.
JUST={  LEFT | RIGHT | ASIS | CENTER | CENTRE  }
For output fields, this determines the alignment of the data within the field after trailing blanks have been stripped. Justification is applied at a field level and should not be confused with VALIGN, which applies to the individual variable only:
  • LEFT results in padding to the right
  • RIGHT results in padding to the left
  • ASIS is treated as JUST=LEFT for output fields
  • CENTER results in padding to both the left and the right.
  • For input fields justification occurs both when the data is being displayed and when the data is being processed on subsequent entry. When an input field is formatted for display (the value currently assigned to the variable defined in the input field is substituted in place of the variable’s name) the data is justified to the left and padded to the right for JUST=LEFT or justified to the right and padded to the left for JUST=RIGHT. JUST=CENTER is treated like JUST=LEFT. For JUST=ASIS data is positioned exactly as defined in the variable and padding to the right is performed.
  • On subsequent re-entry, trailing blanks and pad characters are stripped, unless the trailing pad character is a numeric, in which case it is not stripped:
  • For JUST=RIGHT leading blanks and pads are also stripped (including numerics). Use of JUST=RIGHT for input fields can inconvenience terminal operators, as it is necessary to move the cursor to the commencement of the data in the field.
  • For JUST=ASIS trailing blanks and pads are stripped, but leading blanks and pads remain intact.
MODE={  SBCS | MIXED  }
Applies to IBM terminals capable of supporting DBCS data streams. If a panel is sent to such a device, input fields on the panel that use this #FLD character let the operator enter DBCS characters if MODE=MIXED is specified. IBM DBCS terminals do not allow DBCS character entry in input fields that specify MODE=SBCS (single byte character stream).
This operand does not apply to Fujitsu or Hitachi terminals, which allow DBCS character entry at any time.
NCLKEYWD={  YES | NO  }
Specifies whether fields that use this FLD character accept input of words that conflict with NCL keywords. The default is YES. NO causes an attempt to enter any NCL reserved keyword to be rejected.
OUTLINE={  { L R T B  } | BOX  }
Specifies the extended highlighting outlining option required for this field. Any combination of L (left) R (right) T (top) or B (bottom) can be coded. The field is outlined at the top or bottom with a horizontal line and at the left and right border with a vertical line according to the options specified. Alternatively the BOX option can be specified, which is equivalent to specifying LRTB. This option is terminal dependent.
PAD={  NULL | BLANK |
char
  }
Applies to INPUT, OUTPUT, and SPD fields.
For output fields PAD works in conjunction with both the JUST and VALIGN operands, one of which must be specified for PAD to take effect. Determines the pad or fill character to be used when the field is displayed.
The variable substitution process substitutes the data currently assigned to any variables within the field being processed. Having completed substitution, any difference between the length of the field defined on the panel and the length after substitution (after stripping trailing blanks) is padded with the specified PAD character.
For input fields, use of the NULL character ensures that the terminal operator can use keyboard insert mode when entering data. Padding is performed either to the left or the right as specified in the JUST operand.
char
Specifies a single character that is to be the pad character (for example, PAD=-). There is no restriction on the character used including the use of any of the field characters defined on #FLD statements. Care should be taken when using numeric pad characters as their use impacts the pad character stripping process on subsequent entry.
Using PAD characters with input fields invokes special processing on subsequent input to ensure that unnecessary pad characters are stripped before returning the entered data in the nominated variable.
PSKIP={  NO | PMENU  }
Applies to input fields only and determines if panel skip requests are accepted in this field. A panel skip request is entered in an input field in the format =
m.m
, where
m.m
is a menu selection. When entered in an appropriate field a panel skip to the specified menu selection is performed.
NO
The input field is not scanned for panel skip requests.
PMENU
The input field is scanned for panel skip requests and actioned.
RANGE=(
min,max
)
For numeric fields, specifies the range of acceptable values. The range includes all numbers, from the minimum number (
min
) to the maximum number (
max
). Both
min
and
max
must be specified and
max
must be equal to or greater than
min
. Use of this operand forces EDIT=NUM. If the entered number falls outside the acceptable range, and &CONTROL PANELRC is not in effect, Panel Services redisplays the panel with the &SYSMSG variable set to:
NOT WITHIN RANGE
If &CONTROL PANELRC is in effect, control is returned to the NCL procedure for error handling instead of being handled totally by Panel Services. In this case, &SYSFLD contains the name of the field in error and &SYSMSG the error message text.
REQUIRED={  YES | NO  }
Specifies that this is a mandatory field that must be entered by the user. If &CONTROL PANELRC is not in effect, Panel services rejects any entry by the user unless this field has been entered. If not entered, Panel Services redisplays the panel with the &SYSMSG variable set to:
REQUIRED FIELD OMITTED
The terminal alarm sounds and the cursor is positioned to the omitted field. If a #ERR statement has been included in the panel definition, processing of the error condition is performed as defined by the #ERR statement. Failure to include the &SYSMSG variable on the panel suppresses this error message. This operand can be abbreviated to REQ=.
If &CONTROL PANELRC is in effect, control is returned to the NCL procedure for error handling instead of being handled totally by Panel Services. In this case, &SYSFLD contains the name of the field in error and &SYSMSG the error message text.
SKIP={  YES | NO  }
For output fields only, determines if the skip attribute is to be assigned to the field. The result of using this option is that the cursor skips to the next input field if the preceding input field is entered in full and the intervening output field is specified with the SKIP operand.
This operand is NO by default, as field skipping can unexpectedly place the cursor in the wrong screen window when operating in split screen mode.
SUB={  YES | NO  }
For output fields only, determines if variable substitution is to be performed. This operand can be used for fields where data contains the & character. This results in the current value of that variable being substituted, or the variable being eliminated if no value was assigned. This operand is ignored for both INPUT and SPD fields.
TYPE={  OUTPUT | INPUT | OUTVAR | SPD | NULL  }
Determines if the field is to be processed as an output-only field (OUTPUT and OUTVAR), input field (INPUT), Selector Pen Detectable (SPD) field or pseudo input field (NULL).
OUTPUT
A protected field is created that does not allow keyboard entry. This field can contain a mixture of fixed data and variables. Each variable must commence with an ampersand (&). Substitution of variables is performed using the variables available to the invoking NCL procedure at the time the &PANEL statement is issued. Global variables can be referenced in an output field. Alignment and padding is performed according to the rules defined for the field.
INPUT
An unprotected field is created that allows keyboard entry. This field must contain a single variable name (without the ampersand). This single variable must immediately follow the field character. System variables and global variables cannot be used in an input field. Subsequent data entered into this field is made available to the invoking NCL procedure in this variable on return from the &PANEL statement. Specification of multiple variables or a mixture of variables and fixed data in an input field results in an error.
OUTVAR
The same as TYPE=OUTPUT except that an & is inserted by Panel Services between the field attribute and the next character. This means that you can follow a TYPE=OUTVAR field character with a variable name without the ampersand. This facility makes it easy to create fields that switch between input and output under NCL control. For example, a panel could contain the statements:
#FLD $ TYPE=&INOUT + Record Key .....$RKEY +
An NCL procedure then sets the variable &INOUT to control if the data in the variable &RKEY is output only, or if it can be modified by an operator:
&INOUT = OUTVAR   -* the value is output only. &INOUT = INPUT    -* the Operator can modify the                     -* field.
A similar effect can be achieved using &ASSIGN OPT=SETOUT.
SPD
A protected field is created in selector pen detectable format. This enables the terminal operator to select the field using either a LIGHT PEN or the CURSOR SELECT key. SPD field characters must be immediately followed by one of the three designator characters (?, &, or a blank), which can in turn optionally be followed by one or more blanks. A single variable with no other fixed data must also be defined within the field. This single variable must be defined omitting the ampersand (&) and cannot be a system or global variable. If selected by the user, the variable nominated in the SPD field is set to the value SELECTED on return to the NCL procedure. If not selected, the variable is set to a null value.
NULL
An unprotected field is created that allows keyboard entry. However, the field need not contain the name of an input variable to receive data entered in the field as any data entered by the terminal operator in a
TYPE=NULL
field is ignored. Display data in this field can be in any format. The NULL option is supplied to accommodate 4 color terminals where the field attribute byte is used to determine the color in which the field is displayed (7 color terminals utilize an extended data stream to set the color). The NULL option indicates that Panel Services is to use an unprotected field attribute in conjunction with the INTENS operand value, to determine the color of the field.
VALIGN={  NO | LEFT | RIGHT | CENTER | CENTRE  }
Applies to output fields only and is ignored if specified for an input field. Determines the alignment of data for an individual variable only. This should not be confused with the JUST operand, which applies to field alignment after all variable substitution has been completed. The VALIGN operand is designed to facilitate tabular output without the need to specify many individual field characters on the panel.
The substitution process substitutes the data assigned to a variable in place of the variable name. No additional blanks are created or removed during this process. Thus, if the data being substituted is shorter than the name of the variable itself (for example, the variable &OUTPUTDATA is currently set to 5678) then data following the variable name is shifted left to occupy the area remaining after the removal of the variable name. This destroys any tabular alignment where the length of the data for each variable differs. The VALIGN option ensures that the data to the right of the variable is not shifted to the left if the data being substituted is shorter than the variable name. The length of the variable name (including the ampersand) is the important factor and determines the number of character positions to be preserved during the substitution process.
However, data truncation is not performed and if the data being substituted is longer than the variable name, the data to the right is moved to accommodate all the substituted data. VALIGN works in conjunction with the pad character specified on the PAD operand. The pad character is used to fill any differences between the data being substituted and the length of the variable name being replaced.
VALIGN=NO
No alignment or padding is performed.
VALIGN=LEFT
Data is aligned to the left and padded to the right. An abbreviation of L is acceptable.
VALIGN=RIGHT
Data is aligned to the right and padded to the left. An abbreviation of R is acceptable.
VALIGN=CENTER
Data is centered (or one position to the left for an odd number of characters) and padded both to the left and to the right. An abbreviation of C is acceptable.
Examples:
#FLD   #   TYPE=INPUT REQ=YES EDIT=NUM COLOR=RED RANGE=(1,3) #FLD   #   BLANKS=TRAIL PAD=_ #FLD   #   TYPE=OUTPUT COLOR=&COLOR HLIGHT=&HLIGHT #FLD   (   TYPE=INPUT INTENS=HIGH EDIT=DATE4 #FLD   @   HLIGHT=BLINK #FLD   /   TYPE=SPD #FLD   %   JUST=R PAD=- -* supplementing default output char #FLD   _   JUST=ASIS    -* supplementing default input char  #FLD + VALIGN=RIGHT JUST=CENTER          -* null pad assumed
Notes:
  • Multiple #FLD statements can be used for the same field character if insufficient space is available on a single statement.
  • Symbolic variables can be included in a #FLD statement. Variable substitution is performed prior to processing the statement, using variables available to the NCL procedure at the time the &PANEL statement is issued.
  • The default field characters can be altered using the DEFAULT operand of the #OPT control statement.
  • The #ERR control statement can be used to greatly simplify the redisplay of a panel to indicate a field in error.
  • The &CONTROL PANELRC operand can be used to specify that the NCL procedure receives control for further processing when internal validation detects an error in data entered by the operator. When this technique is used the procedure can determine the field in error (from the &SYSFLD variable) and the error message to be issued (from the &SYSMSG variable) and alter its processing accordingly, including altering the text of the error message in the &SYSMSG variable if required.
NOTE Statement
The #NOTE statement provides a means of placing documentation within a panel definition. The #NOTE statement is not processed and is ignored. Multiple #NOTE statements can be specified. However, as with #FLD, #ERR, and #OPT statements, all #NOTE statements must precede the start of the panel. The start of the panel is determined by the first line that is not a control statement or #NOTE statement.
This statement has the following format:
#NOTE 
any
 
text
any text
Any free form user text.
Examples:
#NOTE This panel is used by the Network Error Log System #NOTE INWAIT=60 CURSOR=&CURSORFLD
 As shown in the example above the #NOTE statement can provide a simple means of temporarily nullifying another control statement allowing for easy reinstatement when required.
OPT Statement
This statement defines panel processing options.
Before parsing, the #OPT statement is scanned and any variables are substituted. This makes it possible to dynamically tailor any of the operands on the statement.
Multiple #OPT statements can be specified. However, as with #FLD, #ERR and #NOTE statements, all #OPT statements must precede the start of the panel, which is determined by the first line that is not a control statement.
This statement has the following format:
#OPT [ ALARM={ YES | NO } ]      [ BCAST={ YES | NO } ]      [ CURSOR={ 
varname
 |
row,column
 } ]      [ DEFAULT={ 
hlu
 | X‘
xxxxxx
’ } ]      [ ERRFLD=
varname
 ]      [ FMTINPUT={ YES | NO } ]      [ IPANULL={ YES | NO } ]      [ INWAIT=
ss.th
 ]      [ PREPARSE={ (
c
,S) | (
c
,D) } ]      [ UNLOCK={ YES | NO } ]      [ MAXWIDTH={ YES | NO } ]
ALARM={  YES | NO  }
Determines whether the terminal alarm is to be rung when the panel is displayed. Dynamic control of the alarm can be achieved by changing the value of the ALARM operand using a variable set prior to issuing the &PANEL statement.
If internal validation has detected an error, and the panel is being redisplayed to indicate the error, this operand is ignored and the terminal alarm rung. The #ERR statement can be used to alter the processing performed when an error condition is detected.
BCAST={  YES | NO  }
Specifies that the panel is to be redisplayed automatically if a broadcast is scheduled. By default, the only panels that are redisplayed automatically are those that contain one or more of the special broadcast variables, &BROLINE
n
. If BCAST=YES is coded, a broadcast causes the panel to be redisplayed even if it does not contain any of the &BROLINE
n
variables.
CURSOR={ 
varname
|
row,column }
Specifies the name of a variable in either an INPUT or SPD field where the cursor is to be positioned. Alternatively, the precise co-ordinates for the cursor can be defined as
row,column
.
The value of
varname
should be the variable name WITHOUT the ampersand, just as used in the INPUT or SPD field (for example, CURSOR=FIELD5).
Where co-ordinates are specified,
row
must be specified in the range 1 to 62 and column in the range 1 to 80. The row and column values are always relative to the start of the current window and therefore remain unchanged when operating in split screen mode. The &CURSROW and &CURSCOL system variables can be used to determine the location of the cursor on input to the system.
Dynamic positioning of the cursor can be achieved by using a variable or variables (including the ampersand) in place of
varname
or
row
,
column
. The invoking NCL procedure can set the variables to the name of the field to contain the cursor or the coordinates prior to issuing the &PANEL statement.
If internal validation detects an error, and the panel is being redisplayed to indicate the error, the CURSOR operand is ignored and the cursor is positioned to the field in error.
Specifying varname with a name other than the name of a variable used in an INPUT or SPD field results in an error. If coordinates are used, and they lie outside the dimensions of the window currently displayed, the cursor is positioned in the upper left corner of the window.
DEFAULT={ 
hlu
| X‘
xxxxxx
’  }
This operand alters the three standard default field characters. If the #OPT statement is omitted, or the DEFAULT operand not used, three standard field characters are provided for use when defining the panel. They are as follows:
%
protected, high-intensity
+
protected, low-intensity
_
unprotected, high-intensity
It might be necessary to select alternative field characters, for example if the underline character is required within the body of the panel for some reason.
The DEFAULT=
hlu
operand must always specify three characters. The characters chosen must be non-alpha and non-numeric, that is, any special character except ampersand (&), which is reserved for variables. They must not duplicate another field character, except one already defined as a default. The order of the characters is significant, as the attributes of the standard default characters apply in the order described above.
Therefore specification of DEFAULT=*+/ results in:
*
protected, high-intensity
+
protected, low-intensity
/
unprotected, high-intensity
You can also specify the default field characters in hexadecimal in the following format:
DEFAULT=X’
xxxxxx
Each
xx
pair represents a hexadecimal number in the range X‘00’ to X‘FF’. All numbers except X‘00’ (null), and X‘40’ (blank) or X‘50’ (ampersand), are valid. This even allows alphanumeric characters to be used as field characters. For example, if you specify X‘C1’, any occurrence of the letter A in the panel definition is treated as the default character. (It is advisable to use hexadecimal values that do not correspond to alphanumeric characters.)
For example, specification of DEFAULT=‘010203’ results in the following:
X‘01’
protected, high-intensity
X‘02’
protected, low-intensity
X‘03’
unprotected, high-intensity
ERRFLD=
varname
Specifies the name of a variable in an INPUT field that is in error and for which error processing is to be invoked as defined on a #ERR statement. Use of this operand without including a #ERR statement within the panel definition results in an error. The ERRFLD operand provides a simple way of informing Panel Services that the field identified by varname is in error. Panel Services displays the panel using the options defined on the #ERR statement. The #ERR statement could indicate that the error field is to be displayed in reverse-video, colored red and the terminal alarm sounded. Use of the ERRFLD operand can be accompanied by the assignment of some error text into a variable appearing on the screen that identifies the nature of the error.
The operand can be specified with the name of a variable (including the &) that is set to null unless an error occurs, in which case the NCL procedure sets the variable to the name of the field in error prior to issuing the &PANEL statement to display the panel.
ERRFLD provides the panel designer with a simple means of changing the attributes of a field (such as color and high-lighting) without the need to resort to dynamic substitution of #FLD statements.
Consider the case where an input field &INPUT1 is found to be in error and the #OPT statement has been defined with ERRFLD=&INERROR. The NCL procedure assigns the name of the variable used to identify the input field, in this case INPUT1 (minus the &), into &INERROR, and then redisplays the panel.
&INERROR = INPUT1 &SYSMSG  = &STR THIS FIELD IS WRONG &PANEL  MYPANEL
In this example, the text that identifies the nature of the error has been assigned into the variable &SYSMSG, which is defined somewhere on the panel.The same effect can be achieved by using the &ASSIGN OPT=SETERR verb. This allows more than one field to be marked as in error.
ASSIGN OPT=SETERR is only effective if &CONTROL FLDCTL is in effect.
FMTINPUT={  YES | NO  }
Determines if input fields are to be formatted when a panel is displayed. This is a specialized option that is designed to be used in conjunction with INWAIT. When processing with INWAIT, the time interval might expire at the instant when data is being entered by the operator. If the same panel is redisplayed to update the screen contents, the data entered by the operator is lost as the new panel is written. FMTINPUT can be used to bypass formatting of input fields and hence when the panel is redisplayed only output fields are written. The value of this operand can be assigned to a variable from within the NCL procedure and changed between YES and NO as required (#OPT FMTINPUT =&YESNO). Care must taken when using this facility, as incorrect use of FMTINPUT=NO can result in validation errors. Ideally, a panel should be displayed initially with FMTINPUT=YES and only when the INWAIT timer expires is it redisplayed with FMTINPUT=NO.
IPANULL={  YES | NO )
The default YES, specifies that if the panel is displayed with the INWAIT option and the time specified on the INWAIT expires so that control is returned to the procedure without any panel input, or input is caused by a PA key, all variables associated with the panel input fields are to be set to null value.
If you do not want input field variables to be erased, if INWAIT completes, or a PA key is pressed, specify IPANULL=NO.
INWAIT=
ss.th
Specifies the time in seconds and/or parts of seconds that Panel Services is to wait for input from the terminal prior to returning control to the NCL procedure following the &PANEL statement. By default the system waits indefinitely for input having displayed a panel. This might not always be desirable, as is the case where a terminal is performing a monitoring function where input might be infrequent or never occur. If INWAIT is utilized and the specified time elapses, control is returned to the NCL procedure with all input or SPD variables set to null. Should input be made during the time interval, the time period is canceled and standard processing will proceed.
The maximum value that can be specified for INWAIT is 86400.00 seconds (24 hours).
Specification of part seconds is possible. For example:
INWAIT=.5 INWAIT=20.5 INWAIT=.75
Any redisplay of a panel, for example, by using the clear key, causes the panel to be redisplayed and the time interval reset.
Specification of internal validation options, such as REQUIRED=YES are ignored if the time interval expires before input is received.
Specification of INWAIT=0 or INWAIT=0.00 indicates that no input is to be accepted and control is returned to the NCL procedure immediately after the panel has been displayed. In this case the period that the panel remains displayed is determined by subsequent action taken by the procedure.
The invoking NCL procedure can determine if the INWAIT time elapsed or if data was entered by testing the &INKEY system variable. &INKEY is set to the character value of the key pressed by the operator to enter the data (for example, Enter or F1). If the INWAIT time interval elapsed, and no entry was made, the &INKEY variable is set to null. If processing with &CONTROL PANELRC is in effect, &RETCODE is set to 12 to indicate that the INWAIT timer has expired.
INWAIT is ignored for asynchronous panels.
PREPARSE={  (c,S) | (c,D)  }
Preparsing provides a means for dynamically modifying the location of field characters in a panel. The position of field characters (as defined by the #FLD control statement) is determined when the panel is created by Panel Services and remains fixed until the panel is modified.
Although the attributes of each field character (such as the color of the field) can be modified by the use of variables in the #FLD statement, this technique is limited in the number of variations that can be achieved.
The PREPARSE operand requests that Panel Services perform a preliminary substitution scan of each panel line prior to processing the line for field characters. The PREPARSE operand specifies a substitution character
c
that is to be used to determine where substitution is to take place. This character is processed in exactly the same manner as an ampersand (&) is processed during standard substitution.
The ability to specify a character other than an ampersand means that preparsing does not impact standard substitution when it is performed following preparsing. Preparsing can be used to alter a field character that appears in a particular position, thereby allocating a new set of attributes to the field or to create entire new fields (or complete lines) that in themselves contain the required field characters.
(
c
,S)
Indicates that the character c is to be used as the preparse character for the panel, but that the Static Preparse Option is to apply during preparse processing. This prevents the movement of preparse or field characters during the substitution process. This option is useful when panels are being dynamically modified to hold data that can vary in length but is to be displayed in columns. If necessary, substituted data can be truncated if it is too long to fit into its target field without overwriting the next occurrence of a preparse or field character on the same line.
(c,D)
Indicates that the character c is to be used as the preparse character for the panel, but that the Dynamic Preparse Option is to apply during preparse processing. The dynamic option allows the movement of preparse or field characters to left or right of their original position to accommodate differing lengths of data being substituted into the panel.
UNLOCK={  YES | NO  }
Determines if the terminal keyboard is to be unlocked when the panel is displayed. Specification of UNLOCK=NO prevents entry of data by the terminal operator, and can be used in conjunction with the INWAIT operand where a panel was being displayed for a short period, prior to progressing to some other function.
MAXWIDTH={ YES | NO }
Specify MAXWIDTH=YES to indicate the display is to be wider than the standard 80 character width. MAXWIDTH=YES means that panel services will use the number of columns available on the terminal (&ZCOLS).
Examples:
#OPT DEFAULT=#$%  #OPT INWAIT=60 CURSOR=&CURSORFLD #OPT CURSOR=IN1 ALARM=YES #OPT ALARM=&ALARM PREPARSE=($,D) #OPT ERRFLD=&INERROR #OPT INWAIT=.5 UNLOCK=NO PREPARSE=($,S)  #OPT CURSOR=5,75 #OPT CURSOR=&ROW,&COLUMN FMTINPUT=&FMT
Notes:
  • Multiple #OPT statements can be used if required.
  • Symbolic variables can be included in a #OPT statement. Variable substitution is performed prior to processing the statement.
  • Panel redisplay following use of the CLEAR key is automatic. Control is not returned to the invoking NCL procedure. The attributes of the standard default characters can be modified using a #FLD statement that adds additional attributes (such as color) or alters existing attributes.
TRAILER Statement
This statement provides a means of placing specified lines at the end of the screen, regardless of screen size.
The #TRAILER statement can be used to position function key prompts at the bottom of the screen.
Indicate the start of the trailer lines with a #TRAILER START statement. Then enter the lines to appear at the bottom of the screen, followed by a #TRAILER END statement.
This statement has the following format:
#TRAILER [ START | END ]          [ POSITION={ YES | NO } ]
START
Indicates the start of the lines to be placed in the trailer. Each line following this line until a #TRAILER END statement or another control statement such as #FLD is placed in the trailer.
END
Indicates that this is the end of the lines to be placed into the trailer. There must have been a #TRAILER START statement earlier in the panel definition. No other operands can be specified on a #TRAILER END statement.
POSITION={ YES | NO }
Specifies if the trailer lines are to be displayed. The values available are as follows:
YES
The trailer lines are displayed on the final lines of the physical screen.
NO
This value can be used to suppress the display of the trailer lines, even though they remain in the panel definition.
Examples:
#TRAILER START %This appears on the last line of the panel #TRAILER END
Notes:
  • The #TRAILER statements must appear before the first panel line in the definition. If you want to preparse the lines, you must place the #TRAILER statements after the #OPT PREPARSE= statement.
  • The field attribute characters that you use in the trailer lines can be defined before or after the trailer lines in the panel.
  • The trailer lines cover any panel lines that would otherwise have been displayed.
  • The trailer lines are positioned so that they end at the bottom of the physical screen if the window starts at the top of the screen.