|
|
|
This control statement tailors 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 to associate 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 are forced. These attributes are usually a plus sign (+), TYPE=OUTPUT, and INTENS=LOW. They replace any non-field character incorrectly placed in this position.
Before parsing, the #FLD statement is scanned and variable substitution is performed. This process makes it possible to tailor dynamically 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, as 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 } ]
Specifies the field character that is used in the panel definition to identify the start of the field.
Specifies a single character that is not alphanumeric. Any special character (for example, an exclamation mark) can be used, except an ampersand (&), which is reserved for use with variables.
Specifies 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 prevents you from entering 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:
TYPE=OUTPUT INTENS=LOW
No special attributes or internal validation apply.
For input fields, this operand determines the format the entered data must take. By default, a field can contain embedded blanks (BLANKS=ANY). Specification of this operand helps ensure that the entered data does not contain embedded 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 help 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:
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.
(Input fields only) Determines whether to convert entered data to uppercase before passing it to the NCL procedure in the nominated variable. Conversion to uppercase 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 uppercase conversion.
Uppercasing data 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: Because data can be converted to uppercase before performing the assignment, 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. 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.
If the terminal does not support extended color, the COLOR operand is ignored. This feature enables COLOR to be specified on panels that are displayed on both color and non-color terminals. COLOR can be used 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:
|
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 feature is 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).
(Output fields only) Determines which terminal character set to use to display the field. If you specify CSET=ALT (or ALTERNATE), you can draw boxes 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
(Input field) Determines additional internal editing that Panel Services perform. By default no editing is performed. Specification of this operand helps ensure that the entered data conforms to the nominated type. If a field is mandatory, then also specify REQ=YES.
Accepts A to Z only.
Accepts A to Z, 0 through 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).
Specifies a valid OS/VS format data set name. If necessary, a partitioned data set (PDS) member name or Generation Data Group (GDG) number can be specified in brackets as part of the name.
Accepts 0 through 9 and A to F only.
Commences with alpha (A to Z, #, @, or $) and followed by alphanumerics (A to Z, 0 through 9, #, @, or $).
Commences with alpha (A to Z, #, @, or $) and followed by alphanumerics (A to Z, 0 through 9, #, @, or $), but can be terminated with a single asterisk (*). This asterisk allows a value to be entered that can be interpreted as a generic request by the receiving procedure.
Accepts 0 through 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 -).
Specifies 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, Panel Services invokes standard error processing. 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
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 help ensure that entered data does not include embedded blanks. Regardless, editing is performed only for the length of the data entered and not for the length of the input field. If you want to enter the entire field, specify the BLANKS=NONE operand.
Applies only to terminals with extended highlighting support, and determines the highlighting to be used for the field.
If the terminal does not support extended highlighting, the HLIGHT operand is ignored. This feature enables HLIGHT to be specified on panels that are displayed on terminals that do not support extended highlighting. HLIGHT can be used with the COLOR operand.
You can use NONE as a no-impact value 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 typically associated with input fields and other important data. Minimize its use 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 operand is typically used for input fields for entering sensitive data such as passwords. Use of this attribute for output fields is meaningless. Color or extended highlighting attributes are ignored when used with this attribute.
For output fields, this operand determines the alignment of the data within the field after trailing blanks have been stripped. Justification is applied at a field level. Do not confuse with VALIGN that 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):
On subsequent reentry, 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 data streams. 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 with both the JUST and VALIGN operands, one of which must be specified for PAD to take effect. The operand determines the pad or fill character to use 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.
Helps ensure 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=-).
You can use any character, including the use of any of the field characters defined on #FLD statements. Take care when using numeric pad characters because their use affects the pad character stripping process on subsequent entry.
Using PAD characters with input fields invokes special processing on subsequent input to help ensure that unnecessary pad characters are stripped before returning the entered data in the nominated variable.
(Input fields only) 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 request 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 action taken in response.
(Numeric field) 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 a field is mandatory and the user must complete it. 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.
(Output field only) Determines whether to assign the skip attribute to the field. If the preceding input field is entered in full and the intervening output field is specified with the SKIP operand, this option causes the cursor to skip to the next input field.
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.
(Output field only) Determines whether to perform variable substitution. This operand is typically used only for fields where data contains the & character. Substitution results in the current value of that variable being substituted or, if no value is assigned, the variable being eliminated. This operand is ignored for both INPUT and SPD fields.
Determines whether to process the field 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.
Is the same as TYPE=OUTPUT, except that Panel Services inserts an & between the field attribute and the next character. This feature 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 contains the statements:
#FLD $ TYPE=&INOUT + Record Key .....$RKEY +
An NCL procedure would then set the variable &INOUT to control whether the data in the variable &RKEY is output only or an operator can modify it:
&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 value 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 name of an input variable to receive data entered in the field is not required because 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 accommodates four-color terminals where the field attribute byte is used to determine the color in which the field is displayed. (Seven-color terminals use an extended data stream to set the color). The NULL option indicates that Panel Services is to use an unprotected field attribute with the INTENS operand value to determine the color of the field.
(Output fields only) Determines the alignment of data for an individual variable only. Do not confuse 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. If specified for an input field, the operand is ignored.
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 (for example, variable &OUTPUTDATA 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 shift would destroy any tabular alignment where the length of the data for each variable differed. If the data being substituted is shorter than the variable name, the VALIGN option helps ensure that the data to the right of the variable is not shifted to the left. The length of the variable name (including the ampersand) is the important factor and determines the number of character positions to preserve 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 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:
| Copyright © 2011 CA. All rights reserved. | Tell Technical Publications how we can improve this information |