FLD Control Statement -- Define or Modify a Panel Definition Field Character
This control statement tailors the operational characteristics of a panel.
nwmsol
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 } ]
- c| X'xx'
- Specifies the field character that is used in the panel definition to identify the start of the field.
- c
- Specifies asinglecharacter that isnotalphanumeric. Any special character (for example, an exclamation mark) can be used, except an ampersand (&), which is reserved for use with variables.
- X'xx'
- 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.
- TYPE=OUTPUT INTENS=LOW
- No special attributes or internal validation apply.
- BLANKS={ TRAIL | NONE | ANY }
- 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.
- CAPS={ YES | NO }
- (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.
- 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.
- { 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.
- 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).
- CSET={ ALT | 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 |_ (rotated 180 degrees)
- M is displayed as _|
- N is displayed as _| (rotated 180 degrees)
- F is displayed as |
- G is displayed as _|_
- O is displayed as _|_ (rotated 90 degrees counter-clockwise)
- P is displayed as _|_ (rotated 180 degrees)
- L is displayed as +
- CSET=ALT supersedes CSET=ASM in version 3.1
- EDIT={ ALPHA | ALPHANUM | DATEn| DSN | HEX | NAME | NAME* | NUM | REAL | SIGNNUM | TIMEn}
- (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.
- ALPHA
- Accepts A to Z only.
- ALPHANUM
- Accepts A to Z, 0 through 9, #, @, and $ only.
- DATEn
- Field must be a valid date. The DATEnkeyword must correspond to one of the &DATEnsystem 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).
- DSN
- 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.
- HEX
- Accepts 0 through 9 and A to F only.
- NAME
- Commences with alpha (A to Z, #, @, or $) and followed by alphanumerics (A to Z, 0 through 9, #, @, or $).
- NAME*
- 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.
- NUM
- Accepts 0 through 9 only.
- REAL
- Input in this field must conform to the syntax for integers, signed numbers or real numbers, including scientific notation.
- SIGNNUM
- Field must be numeric but can have a leading sign (+ or -).
- TIMEn
- Specifies a valid time. The TIMEnkeyword must correspond to one of the &ZTIMEnsystem 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.
- For EDIT=NUM, the panel is redisplayed with the &SYSMSG variable set to:
- FIELD NOT NUMERIC FIELD NOT REAL NUMBER INVALID VALUE INVALID DATE INVALID DATASET NAME INVALID MEMBER NAME INVALID TIME
- For EDIT=REAL, the panel is redisplayed with the message:
- For EDIT=ALPHA, ALPHANUM, HEX, or NAME, the panel is redisplayed with the &SYSMSG variable set to:
- For EDIT=DATEn, the panel is redisplayed with the &SYSMSG variable set to:
- For EDIT=DSN, the panel is redisplayed with the &SYSMSG variable set tooneof the following values:
- For EDIT=TIMEn, the panel is redisplayed 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.
- 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.
- { HLIGHT | HLITE }={ USCORE | REVERSE | BLINK | NONE }
- 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.
- INTENS={ HIGH | LOW | NON }
- Determines the intensity of the field when displayed.
- HIGH
- 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.
- LOW
- The field is displayed in low or standard intensity.
- NON
- The field is displayed in zero intensity, that is, any data within the field is not visible to the operator.
- JUST={ LEFT | RIGHT | ASIS | CENTER | CENTRE }
- 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.
- JUST=LEFT results in padding to the right
- JUST=RIGHT results in padding to the left
- JUST=ASIS is treated as JUST=LEFT for output fields
- JUST=CENTER results in padding to both the left and the right.
- The data is justified to the left and padded to the right for JUST=LEFT.
- The data is justified to the right and padded to the left for JUST=RIGHT.
- The data is aligned for JUST=CENTER as the data is aligned for JUST=LEFT.
- The data is positioned exactly as defined in the variable and padding to the right is performed for JUST=ASIS.
- For JUST=RIGHT, leading blanks and pads are also stripped (including numerics). Use of JUST=RIGHT for input fields can inconvenience terminal operators because it is necessary to cursor across 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 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.
- NCLKEYWD={ YES | NO }
- 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.
- 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 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.
- PAD={ NULL | BLANK |char}
- 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.
- NULL
- 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.
- char
- 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.
- PSKIP={ NO | PMENU }
- (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, wherem.mis a menu selection. When this request is 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 action taken in response.
- RANGE=(min,max)
- (Numeric field) Specifies the range of acceptable values. The range includes all numbers, from the minimum number (min) to the maximum number (max). Bothminandmaxmust 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 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.
- SKIP={ YES | NO }
- (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.
- SUB={ YES | NO }
- (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.
- TYPE={ OUTPUT | INPUT | OUTVAR | SPD | NULL }
- 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).
- OUTPUT
- 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.
- INPUT
- 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.
- OUTVAR
- 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.
- SPD
- 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.
- NULL
- 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.
- VALIGN={ NO | LEFT | RIGHT | CENTER | CENTRE }
- (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.
- 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 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
- If insufficient space is available on a single statement, multiple #FLD statements can be used for the same field character.
- Symbolic variables can be included in a #FLD statement. Variable substitution is performed before the statement is processed, using variables available to the NCL procedure at the time the &PANEL statement is issued.
- You can alter the default field characters by using the DEFAULT operand of the #OPT control statement.
- You can use the #ERR control statement to simplify redisplaying 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 issue (from the &SYSMSG variable). With this information, it can alter its processing accordingly, including altering the text of the error message in the &SYSMSG variable if necessary.