Use this control statement to tailor the operational characteristics of a panel.
When a panel is defined, it is made up of a number of lines, which in turn are made up of a number of fields. Each field commences with a field character, which 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 they 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.
You can specify as many #FLD statements as required, and you can define them 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 control 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 | DATEn | DSN | HEX |
NAME | NAME* | NUM | REAL | SIGNNUM | TIMEn } ]
[ { 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 } ]
The field character:
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, except an ampersand (&), which is reserved for use with variables.
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 which correspond to alphanumeric characters , or X'0E' (shift in ) or X'0F'(shift out).
Although the panel editor does not allow you to 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, then the following defaults apply:
No special attributes or internal validation apply.
For input fields this determines the format the entered data must take. 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 any data entered 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:
If BLANKS=NONE is specified and the data is in error, Panel Services redisplays the panel with the &SYSMSG variable set to:
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.
Applies to input fields only and determines if entered data is to be 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 affect 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.
Uppercasing for CAPS=YES fields uses the language code of the user region to select the character set that is used as the basis of the translation. Where the language code of the user is not one of the supported values, the language code of the system is used. Where the language code of the system is not one of the supported values, a translation based on EBCDIC codes is performed.
Note: 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.
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.
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 datastreams where only three colors are available, the following color relationships are used:
|
Specified |
Result (on Fujitsu three-color terminals) |
|
GREEN |
GREEN |
|
RED |
RED |
|
PINK |
RED |
|
BLUE |
GREEN |
|
TURQUOISE |
GREEN |
|
YELLOW |
WHITE |
|
WHITE |
WHITE |
|
DEFAULT |
GREEN |
Fujitsu seven-color terminals are treated the same as IBM seven-color terminals.
The DEFAULT keyword indicates that the color of the field is to be 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).
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:
e is displayed as ç
s is displayed as ¾
D is displayed as ë
E is displayed a é
M is displayed as û
N is displayed as ù
F is displayed as ú
G is displayed as ^
O is displayed as ^ (rotated 90° counter-clockwise)
P is displayed as ^ (rotated 180°)
L is displayed as +
Note: CSET=ALT supersedes CSET=ASM in version 3.1
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.
Accept A to Z only.
Accept A to Z, 0 to 9, #, @, and $ only.
Field must be a valid date. The DATEn keyword must correspond to one of the &DATEn system variables, and 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).
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.
Accept 0 to 9 and A to F only.
Field must commence with alpha (A to Z, #, @, or $) and be followed by alphanumerics (A to Z, 0 to 9, #, @, or $).
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.
Accept 0 to 9 only.
Input in this field must conform to the syntax for integers, signed numbers or real numbers, including scientific notation.
Field must be numeric but can have a leading sign (+ or -).
Field must be a valid time. The TIMEn keyword must correspond to one of the &ZTIMEn system variables, and 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.
FIELD NOT NUMERIC
FIELD NOT REAL NUMBER
INVALID VALUE
INVALID DATE
INVALID DATASET NAME or INVALID MEMBER NAME
INVALID TIME
In all cases the terminal alarm is rung 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 on 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.
Note: 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 is to be entered, the BLANKS=NONE operand should be specified.
Applies only to terminals with extended highlighting support, and determines the highlighting to be used for the field.
The HLIGHT operand is ignored if the terminal does not support extended highlighting. This enables HLIGHT to be specified on panels that are displayed on terminals that do not support extended highlighting. HLIGHT can be used in conjunction 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.
Determines the intensity of the field when displayed.
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.
The field is displayed in low or standard intensity.
The field is displayed in zero intensity, that is, 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 to be entered. Use of this attribute for output fields is meaningless. Color or extended highlighting attributes are ignored when used in conjunction with this attribute.
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:
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:
Applies to IBM terminals capable of supporting DBCS datastreams. If a panel is sent to such a device, input fields on the panel that use this #FLD character allow the operator to 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 terminals, which allow DBCS character entry at any time.
Specifies whether fields that use this FLD character accept input of words that conflict with NCL keywords. The default is YES. If you attempt to enter any NCL reserved keyword NO causes it to be rejected.
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 or right border with a vertical line, according to the options specified. Alternatively, you can specify the BOX option, which is equivalent to specifying LRTB. This option is terminal-dependent.
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. When substitution is complete, 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.
Ensures that the terminal operator can use keyboard insert mode when entering data. Padding is performed either to the left or to the right, as specified in the JUST operand.
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.
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 this is entered in an appropriate field, a panel skip to the specified menu selection is performed.
The input field is not scanned for panel skip requests.
The input field is scanned for panel skip requests and actioned.
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.
Specifies whether 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 the mandatory field has been entered. If it is not entered, Panel Services redisplays the panel with the &SYSMSG variable set to:
REQUIRED FIELD OMITTED
The terminal alarm is rung 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 contains the error message text.
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, because field skipping can unexpectedly place the cursor in the wrong screen window when operating in split screen mode.
For output fields only, determines if variable substitution is to be performed. This operand is normally used only for fields where data contains the & character, which normally results in the current value of that variable being substituted or the variable being eliminated if no value is assigned. This operand is ignored for both INPUT and SPD fields.
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).
A protected field is created, which 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 are performed according to the rules defined for the field.
An unprotected field is created, which 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.
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 which switch between input and output under NCL control. For example, a panel might contain the statements:
#FLD $ TYPE=&INOUT + Record Key .....$RKEY +
An NCL procedure would then set 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.
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. The 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 without 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.
An unprotected field is created, which 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 four-color terminals where the field attribute byte is used to determine the color in which the field is displayed (seven-color terminals utilize an extended datastream 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.
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 normally 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 would of course destroy any tabular alignment where the length of the data for each variable differed. 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 is not truncated and, if the data being substituted is longer than the variable name, then 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 difference between the data being substituted and the length of the variable name being replaced.
No alignment or padding is performed.
Data is aligned to the left and padded to the right. An abbreviation of L is acceptable.
Data is aligned to the right and padded to the left. An abbreviation of R is acceptable.
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 Control Statement
#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: